<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :
! EDITOR NOTES
!
! Adding a new element involves editing the following sections:
! - section for the element itself
! - descriptions of the element's categories
! - images/content-venn.svg
! - syntax, if it's void or otherwise special
! - parser, if it's not phrasing-level
! - rendering
! - obsolete section
! - element, attribute, content model, and interface indices
!
! Adding a new attribute involves editing the following sections:
! - The IDL and content attributes for the relevant elements
! - element and attribute indices
!-->
<!--
! https://lists.w3.org/Archives/Public/www-archive/2014Apr/0034.html
!-->
<!DOCTYPE html> <!-- Note: This file is NOT HTML, it's a proprietary language that is then post-processed into HTML. -->
<html lang="en-US-x-hixie">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title w-nodev>HTML Standard</title>
<title w-dev>HTML Standard, Edition for Web Developers</title>
<meta name="theme-color" content="#3c790a">
<meta name="color-scheme" content="light dark">
<link w-noreview rel="stylesheet" crossorigin href="https://resources.whatwg.org/standard-shared-with-dev.css">
<link w-nodev w-noreview crossorigin rel="stylesheet" href="https://resources.whatwg.org/standard.css">
<link w-nodev crossorigin rel="stylesheet" href="https://resources.whatwg.org/spec.css">
<link w-nohtml w-nodev w-nosnap rel="stylesheet" crossorigin href="https://resources.whatwg.org/review-draft.css">
<link w-nosnap w-noreview rel="icon" crossorigin href="https://resources.whatwg.org/logo.svg">
<link w-nohtml w-nodev rel="icon" crossorigin href="https://resources.whatwg.org/logo-snapshot.svg">
<link w-dev rel="stylesheet" crossorigin href="/dev/styles.css">
<link w-nodev rel="stylesheet" crossorigin href="/styles.css">
<script>
function toggleStatus(div) {
div.parentNode.classList.toggle('wrapped');
}
function setLinkFragment(link) {
link.hash = location.hash;
}
</script>
</head>
<body>
<script w-dev src="/dev/search.js" async></script>
<script w-nodev w-noreview crossorigin src="/html-dfn.js" defer></script>
<script w-nodev w-noreview w-nosplit crossorigin src="https://resources.whatwg.org/commit-snapshot-shortcut-key.js" defer></script>
<header class="head with-buttons" id="head">
<a href="https://whatwg.org/" class="logo"><img crossorigin width="100" height="100" alt="WHATWG" src="https://resources.whatwg.org/logo.svg" class="darkmode-aware"></a>
<hgroup w-nodev>
<h1 class="allcaps">HTML</h1>
<p w-nosnap w-noreview id="living-standard">Living Standard — Last Updated <span class="pubdate">[DATE: 01 Jan 1901]</span></p>
<p w-nohtml w-noreview id="living-standard">Commit Snapshot — Last Updated <span class="pubdate">[DATE: 01 Jan 1901]</span></p>
<p w-nohtml w-nosnap id="living-standard">Review Draft — Published <span class="pubdate">[DATE: 01 Jan 1901]</span></p>
</hgroup>
<hgroup w-dev>
<h1><a href="/dev/" rel=home>HTML: The Living Standard</a></h1>
<p id="dev-edition-h2">Edition for Web Developers — Last Updated <span class="pubdate">[DATE: 01 Jan 1901]</span></p>
</hgroup>
<nav w-nosplit w-nodev w-noreview>
<!-- Note: be sure to keep an even number of <a>s, for small screens where they appear in two columns. -->
<div>
<a w-nohtml href="/" id="commit-snapshot-link"><span data-x=""><strong>One-Page Version</strong> <code data-x="">html.spec.whatwg.org</code></span></a>
<a w-nosnap href="/"><span data-x=""><strong>One-Page Version</strong> <code data-x="">html.spec.whatwg.org</code></span></a>
<a href="/multipage/" id="multipage-link" onclick="setLinkFragment(this);"><span data-x=""><strong>Multipage Version</strong> <code data-x="">/multipage</code></span></a>
<a href="/dev/" onclick="setLinkFragment(this);"><span data-x=""><strong>Version for Web Devs</strong> <code data-x="">/dev</code></span></a>
<a href="/print.pdf"><span data-x=""><strong>PDF Version</strong> <code data-x="">/print.pdf</code></span></a>
<a href="https://github.com/whatwg/html/wiki/Translations"><span data-x=""><strong>Translations</strong> <code data-x="">日本語 • 简体中文</code></span></a>
</div>
<div>
<a class="misc" href="https://github.com/whatwg/html/blob/main/FAQ.md"><span data-x=""><strong>FAQ</strong> <code data-x="">on GitHub</code></span></a>
<a class="comms" href="https://whatwg.org/chat"><span data-x=""><strong>Chat</strong> <code data-x="">on Matrix</code></span></a>
</div>
<div>
<a class="changes" href="https://github.com/whatwg/html"><span data-x=""><strong>Contribute on GitHub</strong> <code data-x="">whatwg/html repository</code></span></a>
<a class="changes" href="https://github.com/whatwg/html/commits"><span data-x=""><strong>Commits</strong> <code data-x="">on GitHub</code></span></a>
<a w-nosnap class="changes" href="/commit-snapshots/[SHA]" id="commit-snapshot-link"><span data-x=""><strong>Snapshot</strong> <code data-x="">as of this commit</code></span></a>
<a class="changes" href="https://twitter.com/htmlstandard"><span data-x=""><strong>Twitter Updates</strong> <code data-x="">@htmlstandard</code></span></a>
</div>
<div>
<a class="feedback" href="https://github.com/whatwg/html/issues"><span data-x=""><strong>Open Issues</strong> <code data-x="">filed on GitHub</code></span></a>
<a class="feedback" href="https://whatwg.org/newbug"><span data-x=""><strong>Open an Issue</strong> <code data-x="">whatwg.org/newbug</code></span></a>
<a class="feedback" href="https://github.com/web-platform-tests/wpt/tree/master/html"><span data-x=""><strong>Tests</strong> <code data-x="">web-platform-tests html/</code></span></a>
<a class="feedback" href="https://github.com/web-platform-tests/wpt/labels/html"><span data-x=""><strong>Issues for Tests</strong> <code data-x="">ongoing work</code></span></a>
</div>
</nav>
<div id="search" w-dev>
<input name="query" type="search" placeholder="Search. Press '/'" autocomplete="off" id="query">
<ol id="results"></ol>
</div>
</header>
<details w-nohtml w-nodev w-noreview class="annoying-warning" open="">
<summary>This is a Commit Snapshot of the standard</summary>
<p>This document contains the contents of the standard as of the <a class="sha-link"></a>, and
should only be used as a historical reference. This commit may not even have been merged into the
main branch.</p>
<p>Do not attempt to implement this version of the standard. Do not reference this version as
authoritative in any way. Instead, see <a
href="https://html.spec.whatwg.org/">https://html.spec.whatwg.org/</a> for the living
standard.</p>
</details>
<details w-nohtml w-nodev w-nosnap class="annoying-warning" open>
<summary>This is a Review Draft of the standard</summary>
<p>This is a Review Draft. It is published primarily for purposes of patent review by Workstream
Participants; it mirrors the <a href="https://html.spec.whatwg.org/">Living Standard</a> closely,
redacting only text that is identified as "Objection Pending" or "Confirmation Pending".
Developers should refer to the <a href="https://html.spec.whatwg.org/">Living Standard</a> for
the most current error corrections and other developments.</p>
<p>For information regarding patent commitments, please see the <a
href="https://whatwg.org/ipr-policy">IPR Policy</a> and <a
href="https://github.com/whatwg/html/labels/exclusion%20notices">exclusion notices</a>.</p>
<p>Do not attempt to implement this version of the standard. Do not reference this version as
authoritative in any way. Instead, see <a
href="https://html.spec.whatwg.org/">https://html.spec.whatwg.org/</a> for the Living
Standard.</p>
</details>
<hr w-nodev w-nosplit>
<h2 class="no-num no-toc" w-nosplit>Table of contents</h2>
<!--smalltoc-->
<h2 class="no-num no-toc" id="contents" w-nosplit w-nodev>Full table of contents</h2>
<!--toc-->
<div w-dev w-nosplit>
<h2 class="no-num no-toc" id="about-dev-edition">About this specification</h2>
<p>This specification is like no other — it has been processed with <em>you</em>, the humble web
developer, in mind.</p>
<p>The focus of this specification is readability and ease of access. Unlike the <a
href="/multipage/">full HTML Standard</a>, 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.</p>
<p>To read about its conception, construction, and future, read the <a
href="https://web.archive.org/web/20150220020906/http://archive.germanforblack.com:80/articles/html5-for-web-developers">original
press release</a>, and the <a href="https://blog.whatwg.org/developers-edition-comeback">blog post
about its relaunch</a>.</p>
<p>Finally, feel free to <a href="https://github.com/whatwg/html/labels/dev%20edition">contribute
on GitHub</a> to make this edition better for everyone!</p>
</div>
<h2 split-filename="introduction" id="introduction">Introduction</h2>
<div w-nodev>
<h3 id="abstract">Where does this specification fit?</h3>
<p>This specification defines a big part of the web platform, in lots of detail. Its place in the
web platform specification stack relative to other specifications can be best summed up as
follows:</p>
<svg viewBox="0 0 398 359" width=398 height=359 role=img aria-label="It consists of everything else, above such core technologies as HTTP, TLS, DOM, Unicode, Web IDL, MIME, URL, XML, JavaScript, and Encoding; below higher-level technologies like CSS, SVG, MathML, and Service Workers; and to the side of technologies like IndexedDB, Fetch, CSP, AV1, Opus, and PNG." id="abstractimg">
<rect width=398 height=80 />
<text x=199 y=45 class=horizontal>CSS SVG MathML Service Workers</text>
<rect width=67 height=177 y=85 />
<text transform="translate(25 173.5) rotate(-90)" class="left">IDB Fetch CSP</text>
<text transform="translate(50 173.5) rotate(-90)" class="left">AV1 Opus PNG</text>
<!-- https://www.flickr.com/photos/wonderlane/2986252088/ -->
<image x=72 y=85 width=326 height=177 xlink:href="/images/abstract.jpeg"/>
<text x=130 y=250 class=right>THIS SPECIFICATION</text>
<rect width=398 height=92 y=267 />
<text x=199 y=300 class=horizontal>HTTP TLS DOM Unicode Web IDL</text>
<text x=199 y=330 class=horizontal>MIME URL XML JavaScript Encoding</text>
</svg>
</div>
<h3 id="is-this-html5?">Is this HTML5?</h3>
<!-- NON-NORMATIVE SECTION -->
<p>In short: Yes.</p>
<p>In more length: the term "HTML5" is widely used as a buzzword to refer to modern web
technologies, many of which (though by no means all) are developed at the WHATWG. This document is
one such; others are available from <a href="https://spec.whatwg.org/">the WHATWG Standards
overview</a>.</p>
<h3>Background</h3>
<!-- NON-NORMATIVE SECTION -->
<p>HTML is the World Wide Web's core markup language. Originally, HTML was primarily designed as a
language for semantically describing scientific documents. Its general design, however, has
enabled it to be adapted, over the subsequent years, to describe a number of other types of
documents and even applications.</p>
<h3>Audience</h3>
<!-- NON-NORMATIVE SECTION -->
<p>This specification is intended for authors of documents and scripts that use the features
defined in this specification<span w-nodev>, implementers of tools that operate on pages that
use the features defined in this specification, and individuals wishing to establish the
correctness of documents or implementations with respect to the requirements of this
specification</span>.</p>
<p>This document is probably not suited to readers who do not already have at least a passing
familiarity with web technologies, as in places it sacrifices clarity for precision, and brevity
for completeness. More approachable tutorials and authoring guides can provide a gentler
introduction to the topic.</p>
<p>In particular, familiarity with the basics of DOM is necessary for a complete understanding of
some of the more technical parts of this specification. An understanding of Web IDL, HTTP, XML,
Unicode, character encodings, JavaScript, and CSS will also be helpful in places but is not
essential.</p>
<h3>Scope</h3>
<!-- NON-NORMATIVE SECTION -->
<p>This specification is limited to providing a semantic-level markup language and associated
semantic-level scripting APIs for authoring accessible pages on the web ranging from static
documents to dynamic applications.</p>
<p>The scope of this specification does not include providing mechanisms for media-specific
customization of presentation (although default rendering rules for web browsers are included at
the end of this specification, and several mechanisms for hooking into CSS are provided as part of
the language).</p>
<p>The scope of this specification is not to describe an entire operating system. In particular,
hardware configuration software, image manipulation tools, and applications that users would be
expected to use with high-end workstations on a daily basis are out of scope. In terms of
applications, this specification is targeted specifically at applications that would be expected
to be used by users on an occasional basis, or regularly but from disparate locations, with low
CPU requirements. Examples of such applications include online purchasing systems, searching
systems, games (especially multiplayer online games), public telephone books or address books,
communications software (email clients, instant messaging clients, discussion software), document
editing software, etc.</p>
<h3>History</h3>
<!-- NON-NORMATIVE SECTION -->
<p>For its first five years (1990-1995), HTML went through a number of revisions and experienced a
number of extensions, primarily hosted first at CERN, and then at the IETF.</p>
<p>With the creation of the W3C, HTML's development changed venue again. A first abortive attempt
at extending HTML in 1995 known as HTML 3.0 then made way to a more pragmatic approach known as
HTML 3.2, which was completed in 1997. HTML4 quickly followed later that same year.</p>
<p>The following year, the W3C membership decided to stop evolving HTML and instead begin work on
an XML-based equivalent, called XHTML. <!-- https://www.w3.org/MarkUp/future/#summary --> This
effort started with a reformulation of HTML4 in XML, known as XHTML 1.0, which added no new
features except the new serialization, and which was completed in 2000. After XHTML 1.0, the W3C's
focus turned to making it easier for other working groups to extend XHTML, under the banner of
XHTML Modularization. In parallel with this, the W3C also worked on a new language that was not
compatible with the earlier HTML and XHTML languages, calling it XHTML2.</p>
<p>Around the time that HTML's evolution was stopped in 1998, parts of the API for HTML developed
by browser vendors were specified and published under the name DOM Level 1 (in 1998) and DOM Level
2 Core and DOM Level 2 HTML (starting in 2000 and culminating in 2003). These efforts then petered
out, with some DOM Level 3 specifications published in 2004 but the working group being closed
before all the Level 3 drafts were completed.</p>
<p>In 2003, the publication of XForms, a technology which was positioned as the next generation of
web forms, sparked a renewed interest in evolving HTML itself, rather than finding replacements
for it. This interest was borne from the realization that XML's deployment as a web technology was
limited to entirely new technologies (like RSS and later Atom), rather than as a replacement for
existing deployed technologies (like HTML).</p>
<p>A proof of concept to show that it was possible to extend HTML4's forms to provide many of the
features that XForms 1.0 introduced, without requiring browsers to implement rendering engines
that were incompatible with existing HTML web pages, was the first result of this renewed
interest. At this early stage, while the draft was already publicly available, and input was
already being solicited from all sources, the specification was only under Opera Software's
copyright.</p>
<p>The idea that HTML's evolution should be reopened was tested at a W3C workshop in 2004, where
some of the principles that underlie the HTML5 work (described below), as well as the
aforementioned early draft proposal covering just forms-related features, were presented to the
W3C jointly by Mozilla and Opera. The proposal was rejected on the grounds that the proposal
conflicted with the previously chosen direction for the web's evolution; the W3C staff and
membership voted to continue developing XML-based replacements instead.</p>
<p>Shortly thereafter, Apple, Mozilla, and Opera jointly announced their intent to continue
working on the effort under the umbrella of a new venue called the WHATWG. A public mailing list
was created, and the draft was moved to the WHATWG site. The copyright was subsequently amended to
be jointly owned by all three vendors, and to allow reuse of the specification.</p>
<p>The WHATWG was based on several core principles, in particular that technologies need to be
backwards compatible, that specifications and implementations need to match even if this means
changing the specification rather than the implementations, and that specifications need to be
detailed enough that implementations can achieve complete interoperability without
reverse-engineering each other.</p>
<p>The latter requirement in particular required that the scope of the HTML5 specification include
what had previously been specified in three separate documents: HTML4, XHTML1, and DOM2 HTML. It
also meant including significantly more detail than had previously been considered the norm.</p>
<p>In 2006, the W3C indicated an interest to participate in the development of HTML5 after all,
and in 2007 formed a working group chartered to work with the WHATWG on the development of the
HTML5 specification. Apple, Mozilla, and Opera allowed the W3C to publish the specification under
the W3C copyright, while keeping a version with the less restrictive license on the WHATWG
site.</p>
<p>For a number of years, both groups then worked together. In 2011, however, the groups came to
the conclusion that they had different goals: the W3C wanted to publish a "finished" version of
"HTML5", while the WHATWG wanted to continue working on a Living Standard for HTML, continuously
maintaining the specification rather than freezing it in a state with known problems, and adding
new features as needed to evolve the platform.</p>
<p>In 2019, the WHATWG and W3C <a href="https://www.w3.org/blog/news/archives/7753">signed an
agreement</a> to collaborate on a single version of HTML going forward: this document.</p>
<h3>Design notes</h3>
<!-- NON-NORMATIVE SECTION -->
<p>It must be admitted that many aspects of HTML appear at first glance to be nonsensical and
inconsistent.</p>
<p>HTML, its supporting DOM APIs, as well as many of its supporting technologies, have been
developed over a period of several decades by a wide array of people with different priorities
who, in many cases, did not know of each other's existence.</p>
<p>Features have thus arisen from many sources, and have not always been designed in especially
consistent ways. Furthermore, because of the unique characteristics of the web, implementation
bugs have often become de-facto, and now de-jure, standards, as content is often unintentionally
written in ways that rely on them before they can be fixed.</p>
<p>Despite all this, efforts have been made to adhere to certain design goals. These are described
in the next few subsections.</p>
<div w-nodev>
<!--en-GB--><h4 id="serialisability-of-script-execution">Serializability of script execution</h4>
<!-- NON-NORMATIVE SECTION -->
<p>To avoid exposing web authors to the complexities of multithreading, the HTML and DOM APIs are
designed such that no script can ever detect the simultaneous execution of other scripts. Even
with <span data-x="Worker">workers</span>, the intent is that the behavior of implementations can
be thought of as completely serializing the execution of all scripts in all globals.</p>
<p>The exception to this general design principle is the JavaScript <code>SharedArrayBuffer</code>
class. Using <code>SharedArrayBuffer</code> objects, it can in fact be observed that scripts in
other <span data-x="agent">agents</span> are executing simultaneously. Furthermore, due to the
JavaScript memory model, there are situations which not only are un-representable via serialized
<em>script</em> execution, but also un-representable via serialized <em>statement</em> execution
among those scripts.</p>
</div>
<h4>Extensibility</h4>
<!-- NON-NORMATIVE SECTION -->
<p>HTML has a wide array of extensibility mechanisms that can be used for adding semantics in a
safe manner:</p>
<ul>
<li><p>Authors can use the <code data-x="attr-class">class</code> attribute to extend elements,
effectively creating their own elements, while using the most applicable existing "real" HTML
element, so that browsers and other tools that don't know of the extension can still support it
somewhat well. This is the tack used by microformats, for example.</p></li>
<li><p>Authors can include data for inline client-side scripts or server-side site-wide scripts
to process using the <code data-x="attr-data-*">data-*=""</code> attributes. These are guaranteed
to never be touched by browsers, and allow scripts to include data on HTML elements that scripts
can then look for and process.</p></li>
<li><p>Authors can use the <code data-x="meta"><meta name="" content=""></code> mechanism to
include page-wide metadata.</p></li>
<li><p>Authors can use the <code data-x="attr-hyperlink-rel">rel=""</code> mechanism to annotate
links with specific meanings by registering <span data-x="concept-rel-extensions">extensions to
the predefined set of link types</span>. This is also used by microformats.</p></li>
<li><p>Authors can embed raw data using the <code data-x="script"><script type=""></code>
mechanism with a custom type, for further handling by inline or server-side scripts.</p></li>
<li><p>Authors can extend APIs using the JavaScript prototyping mechanism. This is widely used by
script libraries, for instance.</p></li>
<li><p>Authors can use the microdata feature (the <code
data-x="attr-itemscope">itemscope=""</code> and <code data-x="attr-itemprop">itemprop=""</code>
attributes) to embed nested name-value pairs of data to be shared with other applications and
sites.</p></li>
<li><p>Authors can define, share, and use <span data-x="custom element">custom elements</span>
to extend the vocabulary of HTML. The requirements of <span data-x="valid custom element
name">valid custom element names</span> ensure forward compatibility (since no elements will be
added to HTML, SVG, or MathML with hyphen-containing local names in the future).</p></li>
</ul>
<h3 id="html-vs-xhtml">HTML vs XML syntax</h3>
<!-- NON-NORMATIVE SECTION -->
<p>This specification defines an abstract language for describing documents and applications, and
some APIs for interacting with in-memory representations of resources that use this language.</p>
<p>The in-memory representation is known as "DOM HTML", or "the DOM" for short.</p>
<p>There are various concrete syntaxes that can be used to transmit resources that use this
abstract language, two of which are defined in this specification.</p>
<p>The first such concrete syntax is the HTML syntax. This is the format suggested for most
authors. It is compatible with most legacy web browsers. If a document is transmitted with the
<code>text/html</code> <span>MIME type</span>, then it will be processed as an HTML document by
web browsers. This specification defines the latest HTML syntax, known simply as "HTML".</p>
<p>The second concrete syntax is XML. When a document is transmitted with an <span>XML MIME
type</span>, such as <code>application/xhtml+xml</code>, then it is treated as an XML document by
web browsers, to be parsed by an XML processor. Authors are reminded that the processing for XML
and HTML differs; in particular, even minor syntax errors will prevent a document labeled as XML
from being rendered fully, whereas they would be ignored in the HTML syntax.</p>
<p class="note">The XML syntax for HTML was formerly referred to as "XHTML", but this
specification does not use that term (among other reasons, because no such term is used for the
HTML syntaxes of MathML and SVG).</p>
<p>The DOM, the HTML syntax, and the XML syntax cannot all represent the same content. For
example, namespaces cannot be represented using the HTML syntax, but they are supported in the DOM
and in the XML syntax. Similarly, documents that use the <code>noscript</code> feature can be
represented using the HTML syntax, but cannot be represented with the DOM or in the XML syntax.
Comments that contain the string "<code data-x="">--></code>" can only be represented in the
DOM, not in the HTML and XML syntaxes.</p>
<h3>Structure of this specification</h3>
<!-- NON-NORMATIVE SECTION -->
<p>This specification is divided into the following major sections:</p>
<dl>
<dt><a href="#introduction">Introduction</a></dt>
<dd>Non-normative materials providing a context for the HTML standard.</dd>
<dt><a href="#infrastructure">Common infrastructure</a></dt>
<dd>The conformance classes, algorithms, definitions, and the common underpinnings of the rest of
the specification.</dd>
<dt><a href="#dom">Semantics, structure, and APIs of HTML documents</a></dt>
<dd>Documents are built from elements. These elements form a tree using the DOM. This section
defines the features of this DOM, as well as introducing the features common to all elements, and
the concepts used in defining elements.</dd>
<dt><a href="#semantics">The elements of HTML</a></dt>
<dd>Each element has a predefined meaning, which is explained in this section. Rules for authors
on how to use the element<span w-nodev>, along with user agent requirements for how to
handle each element,</span> are also given. This includes large signature features of HTML such
as video playback and subtitles, form controls and form submission, and a 2D graphics API known
as the HTML canvas.</dd>
<dt><a href="#microdata">Microdata</a></dt>
<dd>This specification introduces a mechanism for adding machine-readable annotations to
documents, so that tools can extract trees of name-value pairs from the document. This section
describes this mechanism<span w-nodev> and some algorithms that can be used to convert HTML
documents into other formats</span>. This section also defines some sample Microdata vocabularies
for contact information, calendar events, and licensing works.</dd>
<dt><a href="#editing">User interaction</a></dt>
<dd>HTML documents can provide a number of mechanisms for users to interact with and modify
content, which are described in this section, such as how focus works, and drag-and-drop.</dd>
<dt><a href="#browsers">Loading web pages</a></dt>
<dd>HTML documents do not exist in a vacuum — this section defines many of the features
that affect environments that deal with multiple pages, such as web browsers.</dd>
<dt><a href="#webappapis">Web application APIs</a></dt>
<dd>This section introduces basic features for scripting of applications in HTML.</dd>
<dt><a href="#workers">Web workers</a></dt>
<dd>This section defines an API for background threads in JavaScript.</dd>
<dt><a href="#worklets">Worklets</a></dt>
<dd>This section defines infrastructure for APIs that need to run JavaScript separately from the
main JavaScript execution environment.</dd>
<dt><a href="#comms">The communication APIs</a></dt>
<dd>This section describes some mechanisms that applications written in HTML can use to
communicate with other applications from different domains running on the same client. It also
introduces a server-push event stream mechanism known as Server Sent Events or
<code>EventSource</code>, and a two-way full-duplex socket protocol for scripts known as Web
Sockets.</dd>
<dt><a href="#webstorage">Web storage</a></dt>
<dd>This section defines a client-side storage mechanism based on name-value pairs.</dd>
<dt><a href="#syntax">The HTML syntax</a></dt>
<dt><a href="#xhtml">The XML syntax</a></dt>
<dd>All of these features would be for naught if they couldn't be represented in a serialized
form and sent to other people, and so these sections define the syntaxes of HTML and XML<span
w-nodev>, along with rules for how to parse content using those syntaxes</span>.</dd>
<dt w-nodev><a href="#rendering">Rendering</a></dt>
<dd w-nodev>This section defines the default rendering rules for web browsers.</dd>
</dl>
<p>There are also some appendices, listing <a href="#obsolete">obsolete features</a> and <a
href="#iana">IANA considerations</a>, and several indices.</p>
<div w-nodev>
<h4>How to read this specification</h4>
<p>This specification should be read like all other specifications. First, it should be read
cover-to-cover, multiple times. Then, it should be read backwards at least once. Then it should be
read by picking random sections from the contents list and following all the cross-references.</p>
<p>As described in the conformance requirements section below, this specification describes
conformance criteria for a variety of conformance classes. In particular, there are conformance
requirements that apply to <em>producers</em>, for example authors and the documents they create,
and there are conformance requirements that apply to <em>consumers</em>, for example web browsers.
They can be distinguished by what they are requiring: a requirement on a producer states what is
allowed, while a requirement on a consumer states how software is to act.</p>
<div class="example">
<p>For example, "the <code data-x="">foo</code> attribute's value must be a <span>valid
integer</span>" is a requirement on producers, as it lays out the allowed values; in contrast,
the requirement "the <code data-x="">foo</code> attribute's value must be parsed using the
<span>rules for parsing integers</span>" is a requirement on consumers, as it describes how to
process the content.</p>
</div>
<p><strong>Requirements on producers have no bearing whatsoever on consumers.</strong></p>
<div class="example">
<p>Continuing the above example, a requirement stating that a particular attribute's value is
constrained to being a <span>valid integer</span> emphatically does <em>not</em> imply anything
about the requirements on consumers. It might be that the consumers are in fact required to treat
the attribute as an opaque string, completely unaffected by whether the value conforms to the
requirements or not. It might be (as in the previous example) that the consumers are required to
parse the value using specific rules that define how invalid (non-numeric in this case) values
are to be processed.</p>
</div>
</div>
<h4>Typographic conventions</h4>
<p>This is a definition, requirement, or explanation.</p>
<p class="note">This is a note.</p>
<p class="example">This is an example.</p>
<p class="XXX">This is an open issue.</p>
<p class="warning">This is a warning.</p>
<pre class="extract" w-nodev><code class="idl">[Exposed=Window]
interface <dfn data-x="">Example</dfn> {
// this is an IDL definition
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>variable</var> = <var>object</var>.<span data-x="x-that">method</span>([<var>optionalArgument</var>])</code></dt>
<dd><p>This is a note to authors describing the usage of an interface.</p></dd>
</dl>
<pre><code class="css">/* this is a CSS fragment */</code></pre>
<p>The defining instance of a term is marked up like <dfn data-x="x-this">this</dfn>. Uses of that
term are marked up like <span data-x="x-this">this</span> or like <i data-x="x-this">this</i>.</p>
<p>The defining instance of an element, attribute, or API is marked up like <dfn><code
data-x="x-that">this</code></dfn>. References to that element, attribute, or API are marked up
like <code data-x="x-that">this</code>.</p>
<p>Other code fragments are marked up <code data-x="">like this</code>.</p>
<p>Variables are marked up like <var>this</var>.</p>
<p w-nodev>In an algorithm, steps in <span data-x="synchronous section">synchronous
sections</span> are marked with ⌛.</p>
<p>In some cases, requirements are given in the form of lists with conditions and corresponding
requirements. In such cases, the requirements that apply to a condition are always the first set
of requirements that follow the condition, even in the case of there being multiple sets of
conditions for those requirements. Such cases are presented as follows:</p>
<dl class="switch">
<dt>This is a condition
<dt>This is another condition
<dd>This is the requirement that applies to the conditions above.
<dt>This is a third condition
<dd>This is the requirement that applies to the third condition.
</dl>
<h3>A quick introduction to HTML</h3>
<!-- NON-NORMATIVE SECTION -->
<p>A basic HTML document looks like this:</p>
<pre id="intro-early-example"><code class="html"><!DOCTYPE html>
<html lang="en">
<head>
<title>Sample page</title>
</head>
<body>
<h1>Sample page</h1>
<p>This is a <a href="demo.html">simple</a> sample.</p>
<!-- this is a comment -->
</body>
</html></code></pre>
<p>HTML documents consist of a tree of elements and text. Each element is denoted in the source by
a <span data-x="syntax-start-tag">start tag</span>, such as "<code data-x=""><body></code>", and
an <span data-x="syntax-end-tag">end tag</span>, such as "<code data-x=""></body></code>".
(Certain start tags and end tags can in certain cases be <span
data-x="syntax-tag-omission">omitted</span> and are implied by other tags.)</p>
<p>Tags have to be nested such that elements are all completely within each other, without
overlapping:</p>
<pre class="bad"><code class="html"><p>This is <em>very <strong>wrong</em>!</strong></p></code></pre>
<pre><code class="html"><p>This <em>is <strong>correct</strong>.</em></p></code></pre>
<p>This specification defines a set of elements that can be used in HTML, along with rules about
the ways in which the elements can be nested.</p>
<p>Elements can have attributes, which control how the elements work. In the example below, there
is a <span>hyperlink</span>, formed using the <code>a</code> element and its <code
data-x="attr-hyperlink-href">href</code> attribute:</p>
<pre><code class="html"><a href="demo.html">simple</a></code></pre>
<p><span data-x="syntax-attributes">Attributes</span> are placed inside the start tag, and consist
of a <span data-x="syntax-attribute-name">name</span> and a <span
data-x="syntax-attribute-value">value</span>, separated by an "<code data-x="">=</code>" character.
The attribute value can remain <a href="#unquoted">unquoted</a> if it doesn't contain <span>ASCII
whitespace</span> or any of <code data-x="">"</code> <code data-x="">'</code> <code
data-x="">`</code> <code data-x="">=</code> <code data-x=""><</code> or <code
data-x="">></code>. Otherwise, it has to be quoted using either single or double quotes. The
value, along with the "<code data-x="">=</code>" character, can be omitted altogether if the value
is the empty string.</p>
<pre><code class="html"><!-- empty attributes -->
<input name=address disabled>
<input name=address disabled="">
<!-- attributes with a value -->
<input name=address maxlength=200>
<input name=address maxlength='200'>
<input name=address maxlength="200"></code></pre>
<p>HTML user agents (e.g., web browsers) then <i>parse</i> this markup, turning it into a DOM
(Document Object Model) tree. A DOM tree is an in-memory representation of a document.</p>
<p>DOM trees contain several kinds of nodes, in particular a <code>DocumentType</code> node,
<code>Element</code> nodes, <code>Text</code> nodes, <code>Comment</code> nodes, and in some cases
<code>ProcessingInstruction</code> nodes.</p>
<p>The <a href="#intro-early-example">markup snippet at the top of this section</a> would be
turned into the following DOM tree:</p>
<ul class="domTree"><li class="t10">DOCTYPE: <code data-x="">html</code></li><li class="t1"><code>html</code> <span data-x="" class="t2"><code class="attribute name" data-x="attr-lang">lang</code>="<code class="attribute value" data-x="">en</code>"</span><ul><li class="t1"><code>head</code><ul><li class="t3"><code>#text</code>: <span data-x="">⏎␣␣</span></li><li class="t1"><code>title</code><ul><li class="t3"><code>#text</code>: <span data-x="">Sample page</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">⏎␣</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">⏎␣</span></li><li class="t1"><code>body</code><ul><li class="t3"><code>#text</code>: <span data-x="">⏎␣␣</span></li><li class="t1"><code>h1</code><ul><li class="t3"><code>#text</code>: <span data-x="">Sample page</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">⏎␣␣</span></li><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">This is a <!--grammar-check-override--></span></li><li class="t1"><code>a</code> <span data-x="" class="t2"><code class="attribute name" data-x="attr-hyperlink-href">href</code>="<code class="attribute value" data-x="">demo.html</code>"</span><ul><li class="t3"><code>#text</code>: <span data-x="">simple</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x=""> sample.</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">⏎␣␣</span></li><li class="t8"><code>#comment</code>: <span data-x=""> this is a comment </span></li><li class="t3"><code>#text</code>: <span data-x="">⏎␣⏎</span></li></ul></li></ul></li></ul>
<p>The <span>document element</span> of this tree is the <code>html</code> element, which is the
element always found in that position in HTML documents. It contains two elements,
<code>head</code> and <code>body</code>, as well as a <code>Text</code> node between them.</p>
<p>There are many more <code>Text</code> nodes in the DOM tree than one would initially expect,
because the source contains a number of spaces (represented here by "␣") and line breaks
("⏎") that all end up as <code>Text</code> nodes in the DOM. However, for historical
reasons not all of the spaces and line breaks in the original markup appear in the DOM. In
particular, all the whitespace before <code>head</code> start tag ends up being dropped silently,
and all the whitespace after the <code>body</code> end tag ends up placed at the end of the
<code>body</code>.</p>
<p>The <code>head</code> element contains a <code>title</code> element, which itself contains a
<code>Text</code> node with the text "Sample page". Similarly, the <code>body</code> element
contains an <code>h1</code> element, a <code>p</code> element, and a comment.</p>
<hr>
<p>This DOM tree can be manipulated from scripts in the page. Scripts (typically in JavaScript)
are small programs that can be embedded using the <code>script</code> element or using <span>event
handler content attributes</span>. For example, here is a form with a script that sets the value
of the form's <code>output</code> element to say "Hello World":</p>
<pre><code class="html"><<span>form</span> <span data-x="attr-form-name">name</span>="main">
Result: <<span>output</span> <span data-x="attr-fe-name">name</span>="result"></output>
<<span>script</span>>
<span data-x="Document">document</span>.<span data-x="dom-document-forms">forms</span>.main.<span data-x="dom-form-elements">elements</span>.result.<span data-x="dom-output-value">value</span> = 'Hello World';
</script>
</form></code></pre>
<p>Each element in the DOM tree is represented by an object, and these objects have APIs so that
they can be manipulated. For instance, a link (e.g. the <code>a</code> element in the tree above)
can have its "<code data-x="attr-hyperlink-href">href</code>" attribute changed in several
ways:</p>
<pre><code class="js">var a = <span data-x="Document">document</span>.<span data-x="dom-document-links">links</span>[0]; // obtain the first link in the document
a.<span data-x="dom-hyperlink-href">href</span> = 'sample.html'; // change the destination URL of the link
a.<span data-x="dom-hyperlink-protocol">protocol</span> = 'https'; // change just the scheme part of the URL
a.setAttribute('href', 'https://example.com/'); // change the content attribute directly</code></pre>
<p>Since DOM trees are used as the way to represent HTML documents when they are processed and
presented by implementations (especially interactive implementations like web browsers), this
specification is mostly phrased in terms of DOM trees, instead of the markup described above.</p>
<hr>
<p>HTML documents represent a media-independent description of interactive content. HTML documents
might be rendered to a screen, or through a speech synthesizer, or on a braille display. To
influence exactly how such rendering takes place, authors can use a styling language such as
CSS.</p>
<p>In the following example, the page has been made yellow-on-blue using CSS.</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<head>
<title>Sample styled page</title>
<style>
body { background: navy; color: yellow; }
</style>
</head>
<body>
<h1>Sample styled page</h1>
<p>This page is just a demo.</p>
</body>
</html></code></pre>
<p>For more details on how to use HTML, authors are encouraged to consult tutorials and guides.
Some of the examples included in this specification might also be of use, but the novice author is
cautioned that this specification, by necessity, defines the language with a level of detail that
might be difficult to understand at first.</p>
<h4>Writing secure applications with HTML</h4>
<!-- NON-NORMATIVE SECTION -->
<p>When HTML is used to create interactive sites, care needs to be taken to avoid introducing
vulnerabilities through which attackers can compromise the integrity of the site itself or of the
site's users.</p>
<p>A comprehensive study of this matter is beyond the scope of this document, and authors are
strongly encouraged to study the matter in more detail. However, this section attempts to provide
a quick introduction to some common pitfalls in HTML application development.</p>
<p>The security model of the web is based on the concept of "origins", and correspondingly many of
the potential attacks on the web involve cross-origin actions. <ref>ORIGIN</ref></p>
<dl>
<dt>Not validating user input</dt>
<dt>Cross-site scripting (XSS)</dt>
<dt>SQL injection</dt>
<dd>
<p>When accepting untrusted input, e.g. user-generated content such as text comments, values in
URL parameters, messages from third-party sites, etc, it is imperative that the data be
validated before use, and properly escaped when displayed. Failing to do this can allow a
hostile user to perform a variety of attacks, ranging from the potentially benign, such as
providing bogus user information like a negative age, to the serious, such as running scripts
every time a user looks at a page that includes the information, potentially propagating the
attack in the process, to the catastrophic, such as deleting all data in the server.</p>
<p>When writing filters to validate user input, it is imperative that filters always be
safelist-based, allowing known-safe constructs and disallowing all other input. Blocklist-based
filters that disallow known-bad inputs and allow everything else are not secure, as not
everything that is bad is yet known (for example, because it might be invented in the
future).</p>
<div class="example">
<p>For example, suppose a page looked at its URL's query string to determine what to display,
and the site then redirected the user to that page to display a message, as in:</p>
<pre><code class="html"><ul>
<li><a href="message.cgi?say=Hello">Say Hello</a>
<li><a href="message.cgi?say=Welcome">Say Welcome</a>
<li><a href="message.cgi?say=Kittens">Say Kittens</a>
</ul></code></pre>
<p>If the message was just displayed to the user without escaping, a hostile attacker could
then craft a URL that contained a script element:</p>
<pre>https://example.com/message.cgi?say=%3Cscript%3Ealert%28%27Oh%20no%21%27%29%3C/script%3E</pre>
<p>If the attacker then convinced a victim user to visit this page, a script of the attacker's
choosing would run on the page. Such a script could do any number of hostile actions, limited
only by what the site offers: if the site is an e-commerce shop, for instance, such a script
could cause the user to unknowingly make arbitrarily many unwanted purchases.</p>
<p>This is called a cross-site scripting attack.</p>
</div>
<p>There are many constructs that can be used to try to trick a site into executing code. Here
are some that authors are encouraged to consider when writing safelist filters:</p>
<ul>
<li>When allowing harmless-seeming elements like <code>img</code>, it is important to safelist
any provided attributes as well. If one allowed all attributes then an attacker could, for
instance, use the <code data-x="handler-onload">onload</code> attribute to run arbitrary
script.</li>
<li>When allowing URLs to be provided (e.g. for links), the scheme of each URL also needs to be
explicitly safelisted, as there are many schemes that can be abused. The most prominent
example is "<code data-x="javascript protocol">javascript:</code>", but user agents can
implement (and indeed, have historically implemented) others.</li> <!-- IE had vbscript:,
Netscape had livescript:, etc. -->
<li>Allowing a <code>base</code> element to be inserted means any <code>script</code> elements
in the page with relative links can be hijacked, and similarly that any form submissions can
get redirected to a hostile site.</li>
</ul>
</dd>
<dt>Cross-site request forgery (CSRF)</dt>
<dd>
<p>If a site allows a user to make form submissions with user-specific side-effects, for example
posting messages on a forum under the user's name, making purchases, or applying for a passport,
it is important to verify that the request was made by the user intentionally, rather than by
another site tricking the user into making the request unknowingly.</p>
<p>This problem exists because HTML forms can be submitted to other origins.</p>
<p>Sites can prevent such attacks by populating forms with user-specific hidden tokens, or by
checking `<code data-x="http-origin">Origin</code>` headers on all requests.</p>
</dd>
<dt>Clickjacking</dt>
<dd>
<p>A page that provides users with an interface to perform actions that the user might not wish
to perform needs to be designed so as to avoid the possibility that users can be tricked into
activating the interface.</p>
<p>One way that a user could be so tricked is if a hostile site places the victim site in a
small <code>iframe</code> and then convinces the user to click, for instance by having the user
play a reaction game. Once the user is playing the game, the hostile site can quickly position
the iframe under the mouse cursor just as the user is about to click, thus tricking the user
into clicking the victim site's interface.</p>
<p>To avoid this, sites that do not expect to be used in frames are encouraged to only enable
their interface if they detect that they are not in a frame (e.g. by comparing the <code
data-x="dom-window">window</code> object to the value of the <code data-x="dom-top">top</code>
attribute).</p>
</dd>
</dl>
<h4>Common pitfalls to avoid when using the scripting APIs</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Scripts in HTML have "run-to-completion" semantics, meaning that the browser will generally run
the script uninterrupted before doing anything else, such as firing further events or continuing
to parse the document.</p>
<p>On the other hand, parsing of HTML files happens incrementally, meaning that
the parser can pause at any point to let scripts run. This is generally a good thing, but it does
mean that authors need to be careful to avoid hooking event handlers after the events could have
possibly fired.</p>
<p>There are two techniques for doing this reliably: use <span>event handler content
attributes</span>, or create the element and add the event handlers in the same script. The latter
is safe because, as mentioned earlier, scripts are run to completion before further events can
fire.</p>
<div class="example">
<p>One way this could manifest itself is with <code>img</code> elements and the <code
data-x="event-load">load</code> event. The event could fire as soon as the element has been
parsed, especially if the image has already been cached (which is common).</p>
<p>Here, the author uses the <code data-x="handler-onload">onload</code> handler on an
<code>img</code> element to catch the <code data-x="event-load">load</code> event:</p>
<pre><code class="html"><img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)"></code></pre>
<p>If the element is being added by script, then so long as the event handlers are added in the
same script, the event will still not be missed:</p>
<pre><code class="html"><script>
var img = new Image();
img.src = 'games.png';
img.alt = 'Games';
img.onload = gamesLogoHasLoaded;
// img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
</script></code></pre>
<p>However, if the author first created the <code>img</code> element and then in a separate
script added the event listeners, there's a chance that the <code data-x="event-load">load</code>
event would be fired in between, leading it to be missed:</p>
<pre class="bad"><code class="html"><!-- Do not use this style, it has a race condition! -->
<img id="games" src="games.png" alt="Games">
<!-- the 'load' event might fire here while the parser is taking a
break, in which case you will not see it! -->
<script>
var img = document.getElementById('games');
img.onload = gamesLogoHasLoaded; // might never fire!
</script></code></pre>
</div>
<h4>How to catch mistakes when writing HTML: validators and conformance checkers</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Authors are encouraged to make use of conformance checkers (also known as <i>validators</i>) to
catch common mistakes. The WHATWG maintains a list of such tools at: <a
href="https://whatwg.org/validator/">https://whatwg.org/validator/</a></p>
<h3>Conformance requirements for authors</h3>
<!-- NON-NORMATIVE SECTION -->
<p>Unlike previous versions of the HTML specification, this specification defines in some detail
the required processing for invalid documents as well as valid documents.</p> <!-- This has led to
some questioning the purpose of conformance criteria: if there is no ambiguity in how something
will be processed, why disallow it? -->
<p>However, even though the processing of invalid content is in most cases well-defined,
conformance requirements for documents are still important: in practice, interoperability (the
situation in which all implementations process particular content in a reliable and identical or
equivalent way) is not the only goal of document conformance requirements. This section details
some of the more common reasons for still distinguishing between a conforming document and one
with errors.</p>
<h4>Presentational markup</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The majority of presentational features from previous versions of HTML are no longer allowed.
Presentational markup in general has been found to have a number of problems:</p>
<dl>
<dt>The use of presentational elements leads to poorer accessibility</dt>
<dd>
<p>While it is possible to use presentational markup in a way that provides users of assistive
technologies (ATs) with an acceptable experience (e.g. using ARIA), doing so is significantly
more difficult than doing so when using semantically-appropriate markup. Furthermore, even using
such techniques doesn't help make pages accessible for non-AT non-graphical users, such as users
of text-mode browsers.</p>
<p>Using media-independent markup, on the other hand, provides an easy way for documents to be
authored in such a way that they work for more users (e.g. users of text browsers).</p>
</dd>
<dt>Higher cost of maintenance</dt>
<dd>
<p>It is significantly easier to maintain a site written in such a way that the markup is
style-independent. For example, changing the color of a site that uses <code
data-x=""><font color=""></code> throughout requires changes across the entire site,
whereas a similar change to a site based on CSS can be done by changing a single file.</p>
</dd>
<dt>Larger document sizes</dt>
<dd>
<p>Presentational markup tends to be much more redundant, and thus results in larger document
sizes.</p>
</dd>
</dl>
<p>For those reasons, presentational markup has been removed from HTML in this version. This
change should not come as a surprise; HTML4 deprecated presentational markup many years ago and
provided a mode (HTML4 Transitional) to help authors move away from presentational markup; later,
XHTML 1.1 went further and obsoleted those features altogether.</p>
<p>The only remaining presentational markup features in HTML are the <code
data-x="attr-style">style</code> attribute and the <code>style</code> element. Use of the <code
data-x="attr-style">style</code> attribute is somewhat discouraged in production environments, but
it can be useful for rapid prototyping (where its rules can be directly moved into a separate
style sheet later) and for providing specific styles in unusual cases where a separate style sheet
would be inconvenient. Similarly, the <code>style</code> element can be useful in syndication or
for page-specific styles, but in general an external style sheet is likely to be more convenient
when the styles apply to multiple pages.</p>
<p>It is also worth noting that some elements that were previously presentational have been
redefined in this specification to be media-independent: <code>b</code>, <code>i</code>,
<code>hr</code>, <code>s</code>, <code>small</code>, and <code>u</code>.</p>
<h4>Syntax errors</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The syntax of HTML is constrained to avoid a wide variety of problems.</p>
<dl>
<dt>Unintuitive error-handling behavior</dt>
<dd>
<p>Certain invalid syntax constructs, when parsed, result in DOM trees that are highly
unintuitive.</p>
<div class="example">
<p>For example, the following markup fragment results in a DOM with an <code>hr</code> element
that is an <em>earlier</em> sibling of the corresponding <code>table</code> element:</p>
<pre class="bad"><code class="html"><table><hr>...</code></pre>
</div>
</dd>
<dt>Errors with optional error recovery</dt>
<dd>
<p>To allow user agents to be used in controlled environments without having to implement the
more bizarre and convoluted error handling rules, user agents are permitted to fail whenever
encountering a <span>parse error</span>.</p>
</dd>
<dt>Errors where the error-handling behavior is not compatible with streaming user agents</dt>
<dd>
<p>Some error-handling behavior, such as the behavior for the <code
data-x=""><table><hr>...</code> example mentioned above, are incompatible with streaming
user agents (user agents that process HTML files in one pass, without storing state). To avoid
interoperability problems with such user agents, any syntax resulting in such behavior is
considered invalid.</p>
</dd>
<dt>Errors that can result in infoset coercion</dt>
<dd>
<p>When a user agent based on XML is connected to an HTML parser, it is possible that certain
invariants that XML enforces, such as element or attribute names never contain multiple colons,
will be violated by an HTML file. Handling this can require that the parser coerce the HTML DOM
into an XML-compatible infoset. Most syntax constructs that require such handling are considered
invalid. (Comments containing two consecutive hyphens, or ending with a hyphen, are exceptions
that are allowed in the HTML syntax.)</p>
</dd>
<dt>Errors that result in disproportionately poor performance</dt>
<dd>
<p>Certain syntax constructs can result in disproportionately poor performance. To discourage the
use of such constructs, they are typically made non-conforming.</p>
<div class="example">
<p>For example, the following markup results in poor performance, since all the unclosed
<code>i</code> elements have to be reconstructed in each paragraph, resulting in progressively
more elements in each paragraph:</p>
<pre class="bad"><code class="html"><p><i>She dreamt.
<p><i>She dreamt that she ate breakfast.
<p><i>Then lunch.
<p><i>And finally dinner.</code></pre>
<p>The resulting DOM for this fragment would be:</p>
<ul class="domTree"><li class="t1"><code>p</code><ul><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">She dreamt.</span></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">She dreamt that she ate breakfast.</span></li></ul></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">Then lunch.</span></li></ul></li></ul></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">And finally dinner.</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
</div>
</dd>
<dt>Errors involving fragile syntax constructs</dt>
<dd>
<p>There are syntax constructs that, for historical reasons, are relatively fragile. To help
reduce the number of users who accidentally run into such problems, they are made
non-conforming.</p>
<div class="example">
<p>For example, the parsing of certain named character references in attributes happens even
with the closing semicolon being omitted. It is safe to include an ampersand followed by
letters that do not form a named character reference, but if the letters are changed to a
string that <em>does</em> form a named character reference, they will be interpreted as that
character instead.</p>
<p>In this fragment, the attribute's value is "<code data-x="">?bill&ted</code>":</p>
<pre class="bad"><code class="html"><a href="?bill&ted">Bill and Ted</a></code></pre>
<p>In the following fragment, however, the attribute's value is actually "<code
data-x="">?art©</code>", <em>not</em> the intended "<code data-x="">?art&copy</code>",
because even without the final semicolon, "<code data-x="">&copy</code>" is handled the same
as "<code data-x="">&copy;</code>" and thus gets interpreted as "<code
data-x="">©</code>":</p>
<pre class="bad"><code class="html"><a href="?art&copy">Art and Copy</a></code></pre>
<p>To avoid this problem, all named character references are required to end with a semicolon,
and uses of named character references without a semicolon are flagged as errors.</p>
<p>Thus, the correct way to express the above cases is as
follows:</p>
<pre><code class="html"><a href="?bill&ted">Bill and Ted</a> <!-- &ted is ok, since it's not a named character reference --></code></pre>
<pre><code class="html"><a href="?art&amp;copy">Art and Copy</a> <!-- the & has to be escaped, since &copy <em>is</em> a named character reference --></code></pre>
</div>
</dd>
<dt>Errors involving known interoperability problems in legacy user agents</dt>
<dd>
<p>Certain syntax constructs are known to cause especially subtle or serious problems in legacy
user agents, and are therefore marked as non-conforming to help authors avoid them.</p>
<div class="example">
<p>For example, this is why the U+0060 GRAVE ACCENT character (`) is not allowed in unquoted
attributes. In certain legacy user agents, <!-- namely IE --> it is sometimes treated as a
quote character.</p>
</div>
<div class="example">
<p>Another example of this is the DOCTYPE, which is required to trigger <span>no-quirks
mode</span>, because the behavior of legacy user agents in <span>quirks mode</span> is often
largely undocumented.</p>
</div>
</dd>
<dt>Errors that risk exposing authors to security attacks</dt>
<dd>
<p>Certain restrictions exist purely to avoid known security problems.</p>
<div class="example">
<p>For example, the restriction on using UTF-7 exists purely to avoid authors falling prey to a
known cross-site-scripting attack using UTF-7. <ref>UTF7</ref></p>
</div>
</dd>
<dt>Cases where the author's intent is unclear</dt>
<dd>
<p>Markup where the author's intent is very unclear is often made non-conforming. Correcting
these errors early makes later maintenance easier.</p>
<div class="example">
<p>For example, it is unclear whether the author intended the following to be an
<code>h1</code> heading or an <code>h2</code> heading:</p>
<pre class="bad"><code class="html"><h1>Contact details</h2></code></pre>
</div>
</dd>
<dt>Cases that are likely to be typos</dt>
<dd>
<p>When a user makes a simple typo, it is helpful if the error can be caught early, as this can
save the author a lot of debugging time. This specification therefore usually considers it an
error to use element names, attribute names, and so forth, that do not match the names defined
in this specification.</p>
<div class="example">
<p>For example, if the author typed <code data-x=""><capton></code> instead of <code
data-x=""><caption></code>, this would be flagged as an error and the author could correct
the typo immediately.</p>
</div>
</dd>
<dt>Errors that could interfere with new syntax in the future</dt>
<dd>
<p>In order to allow the language syntax to be extended in the future, certain otherwise
harmless features are disallowed.</p>
<div class="example">
<p>For example, "attributes" in end tags are ignored currently, but they are invalid, in case a
future change to the language makes use of that syntax feature without conflicting with
already-deployed (and valid!) content.</p>
</div>
</dd>
</dl>
<p>Some authors find it helpful to be in the practice of always quoting all attributes and always
including all optional tags, preferring the consistency derived from such custom over the minor
benefits of terseness afforded by making use of the flexibility of the HTML syntax. To aid such
authors, conformance checkers can provide modes of operation wherein such conventions are
enforced.</p>
<h4>Restrictions on content models and on attribute values</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Beyond the syntax of the language, this specification also places restrictions on how elements
and attributes can be specified. These restrictions are present for similar reasons:</p>
<dl>
<dt>Errors involving content with dubious semantics</dt>
<dd>
<p>To avoid misuse of elements with defined meanings, content models are defined that restrict
how elements can be nested when such nestings would be of dubious value.</p>
<p class="example">For example, this specification disallows nesting a <code>section</code>
element inside a <code>kbd</code> element, since it is highly unlikely for an author to indicate
that an entire section <!--non-normative-->should be keyed in.</p>
</dd>
<dt>Errors that involve a conflict in expressed semantics</dt>
<dd>
<p>Similarly, to draw the author's attention to mistakes in the use of elements, clear
contradictions in the semantics expressed are also considered conformance errors.</p>
<div class="example">
<p>In the fragments below, for example, the semantics are nonsensical: a separator cannot
simultaneously be a cell, nor can a radio button be a progress bar.</p>
<pre class="bad"><code class="html"><hr role="cell"></code></pre>
<pre class="bad"><code class="html"><input type=radio role=progressbar></code></pre>
</div>
<p class="example">Another example is the restrictions on the content models of the
<code>ul</code> element, which only allows <code>li</code> element children. Lists by definition
consist just of zero or more list items, so if a <code>ul</code> element contains something
other than an <code>li</code> element, it's not clear what was meant.</p>
</dd>
<dt>Cases where the default styles are likely to lead to confusion</dt>
<dd>
<p>Certain elements have default styles or behaviors that make certain combinations likely to
lead to confusion. Where these have equivalent alternatives without this problem, the confusing
combinations are disallowed.</p>
<p class="example">For example, <code>div</code> elements are rendered as <span
data-x="block box">block boxes</span>, and <code>span</code> elements as <span
data-x="inline box">inline boxes</span>. Putting a <span>block box</span> in an
<span>inline box</span> is unnecessarily confusing; since either nesting just <code>div</code>
elements, or nesting just <code>span</code> elements, or nesting <code>span</code> elements
inside <code>div</code> elements all serve the same purpose as nesting a <code>div</code>
element in a <code>span</code> element, but only the latter involves a <span>block box</span> in
an <span>inline box</span>, the latter combination is disallowed.</p>
<p class="example">Another example would be the way <span>interactive content</span> cannot be
nested. For example, a <code>button</code> element cannot contain a <code>textarea</code>
element. This is because the default behavior of such nesting interactive elements would be
highly confusing to users. Instead of nesting these elements, they can be placed side by
side.</p>
</dd>
<dt>Errors that indicate a likely misunderstanding of the specification</dt>
<dd>
<p>Sometimes, something is disallowed because allowing it would likely cause author
confusion.</p>
<p class="example">For example, setting the <code data-x="attr-fe-disabled">disabled</code>
attribute to the value "<code data-x="">false</code>" is disallowed, because despite the
appearance of meaning that the element is enabled, it in fact means that the element is
<em>disabled</em> (what matters for implementations is the presence of the attribute, not its
value).</p>
</dd>
<dt>Errors involving limits that have been imposed merely to simplify the language</dt>
<dd>
<p>Some conformance errors simplify the language that authors need to learn.</p>
<p class="example">For example, the <code>area</code> element's <code
data-x="attr-area-shape">shape</code> attribute, despite accepting both <code
data-x="attr-area-shape-keyword-circ">circ</code> and <code
data-x="attr-area-shape-keyword-circle">circle</code> values in practice as synonyms, disallows
the use of the <code data-x="attr-area-shape-keyword-circ">circ</code> value, so as to simplify
tutorials and other learning aids. There would be no benefit to allowing both, but it would
cause extra confusion when teaching the language.</p>
</dd>
<dt>Errors that involve peculiarities of the parser</dt>
<dd>
<p>Certain elements are parsed in somewhat eccentric ways (typically for historical reasons),
and their content model restrictions are intended to avoid exposing the author to these
issues.</p>
<div class="example">
<p>For example, a <code>form</code> element isn't allowed inside <span>phrasing content</span>,
because when parsed as HTML, a <code>form</code> element's start tag will imply a
<code>p</code> element's end tag. Thus, the following markup results in two <span
data-x="paragraph">paragraphs</span>, not one:</p>
<pre><code class="html"><p>Welcome. <form><label>Name:</label> <input></form></code></pre>
<p>It is parsed exactly like the following:</p>
<pre><code class="html"><p>Welcome. </p><form><label>Name:</label> <input></form></code></pre>
</div>
</dd>
<dt>Errors that would likely result in scripts failing in hard-to-debug ways</dt>
<dd>
<p>Some errors are intended to help prevent script problems that would be hard to debug.</p>
<p class="example">This is why, for instance, it is non-conforming to have two <code
data-x="attr-id">id</code> attributes with the same value. Duplicate IDs lead to the wrong
element being selected, with sometimes disastrous effects whose cause is hard to determine.</p>
</dd>
<dt>Errors that waste authoring time</dt>
<dd>
<p>Some constructs are disallowed because historically they have been the cause of a lot of
wasted authoring time, and by encouraging authors to avoid making them, authors can save time in
future efforts.</p>
<p class="example">For example, a <code>script</code> element's <code
data-x="attr-script-src">src</code> attribute causes the element's contents to be ignored.
However, this isn't obvious, especially if the element's contents appear to be executable script
— which can lead to authors spending a lot of time trying to debug the inline script
without realizing that it is not executing. To reduce this problem, this specification makes it
non-conforming to have executable script in a <code>script</code> element when the <code
data-x="attr-script-src">src</code> attribute is present. This means that authors who are
validating their documents are less likely to waste time with this kind of mistake.</p>
</dd>
<dt>Errors that involve areas that affect authors migrating between the HTML and XML
syntaxes</dt>
<dd>
<p>Some authors like to write files that can be interpreted as both XML and HTML with similar
results. Though this practice is discouraged in general due to the myriad of subtle
complications involved (especially when involving scripting, styling, or any kind of automated
serialization), this specification has a few restrictions intended to at least somewhat mitigate
the difficulties. This makes it easier for authors to use this as a transitionary step when
migrating between the HTML and XML syntaxes.</p>
<p class="example">For example, there are somewhat complicated rules surrounding the <code
data-x="attr-lang">lang</code> and <code data-x="attr-xml-lang">xml:lang</code> attributes
intended to keep the two synchronized.</p>
<p class="example">Another example would be the restrictions on the values of <code
data-x="">xmlns</code> attributes in the HTML serialization, which are intended to ensure that
elements in conforming documents end up in the same namespaces whether processed as HTML or
XML.</p>
</dd>
<dt>Errors that involve areas reserved for future expansion</dt>
<dd>
<p>As with the restrictions on the syntax intended to allow for new syntax in future revisions
of the language, some restrictions on the content models of elements and values of attributes
are intended to allow for future expansion of the HTML vocabulary.</p>
<p class="example">For example, limiting the values of the <code
data-x="attr-hyperlink-target">target</code> attribute that start with an U+005F LOW LINE
character (_) to only specific predefined values allows new predefined values to be introduced
at a future time without conflicting with author-defined values.</p>
</dd>
<dt>Errors that indicate a mis-use of other specifications</dt>
<dd>
<p>Certain restrictions are intended to support the restrictions made by other
specifications.</p>
<p class="example">For example, requiring that attributes that take media query lists use only
<em>valid</em> media query lists reinforces the importance of following the conformance rules of
that specification.</p>
</dd>
</dl>
<h3>Suggested reading</h3>
<!-- NON-NORMATIVE SECTION -->
<p>The following documents might be of interest to readers of this specification.</p>
<dl>
<dt><cite>Character Model for the World Wide Web 1.0: Fundamentals</cite> <ref>CHARMOD</ref></dt>
<dd><blockquote><p>This Architectural Specification provides authors of specifications, software
developers, and content developers with a common reference for interoperable text manipulation on
the World Wide Web, building on the Universal Character Set, defined jointly by the Unicode
Standard and ISO/IEC 10646. Topics addressed include use of the terms 'character', 'encoding' and
'string', a reference processing model, choice and identification of character encodings,
character escaping, and string indexing.</p></blockquote></dd>
<dt><cite>Unicode Security Considerations</cite> <ref>UTR36</ref></dt>
<dd><blockquote><p>Because Unicode contains such a large number of characters and incorporates
the varied writing systems of the world, incorrect usage can expose programs or systems to
possible security attacks. This is especially important as more and more products are
internationalized. This document describes some of the security considerations that programmers,
system analysts, standards developers, and users should take into account, and provides specific
recommendations to reduce the risk of problems.</p></blockquote></dd>
<dt><cite>Web Content Accessibility Guidelines (WCAG)</cite> <ref>WCAG</ref></dt>
<dd><blockquote><p>Web Content Accessibility Guidelines (WCAG) covers a wide range of
recommendations for making web content more accessible. Following these guidelines will make
content accessible to a wider range of people with disabilities, including blindness and low
vision, deafness and hearing loss, learning disabilities, cognitive limitations, limited
movement, speech disabilities, photosensitivity and combinations of these. Following these
guidelines will also often make your web content more usable to users in
general.</p></blockquote></dd>
<dt w-nodev><cite>Authoring Tool Accessibility Guidelines (ATAG) 2.0</cite> <ref>ATAG</ref></dt>
<dd w-nodev><blockquote><p>This specification provides guidelines for designing web content
authoring tools that are more accessible for people with disabilities. An authoring tool that
conforms to these guidelines will promote accessibility by providing an accessible user interface
to authors with disabilities as well as by enabling, supporting, and promoting the production of
accessible web content by all authors.</p></blockquote></dd>
<dt w-nodev><cite>User Agent Accessibility Guidelines (UAAG) 2.0</cite> <ref>UAAG</ref></dt>
<dd w-nodev><blockquote><p>This document provides guidelines for designing user agents that
lower barriers to web accessibility for people with disabilities. User agents include browsers
and other types of software that retrieve and render web content. A user agent that conforms to
these guidelines will promote accessibility through its own user interface and through other
internal facilities, including its ability to communicate with other technologies (especially
assistive technologies). Furthermore, all users, not just users with disabilities, should find
conforming user agents to be more usable.</p></blockquote></dd>
</dl>
<h2 split-filename="infrastructure" id="infrastructure">Common infrastructure</h2>
<p>This specification depends on <cite>Infra</cite>. <ref>INFRA</ref></p>
<h3>Terminology</h3>
<p>This specification refers to both HTML and XML attributes and IDL attributes, often in the same
context. When it is not clear which is being referred to, they are referred to as <dfn
data-x="" data-lt="content attribute" export>content attributes</dfn> for HTML and XML attributes,
and <dfn data-x="">IDL attributes</dfn> for those defined on IDL interfaces. Similarly, the term
"properties" is used for both JavaScript object properties and CSS properties. When these are
ambiguous they are qualified as <dfn data-x="">object properties</dfn> and <dfn data-x="">CSS properties</dfn> respectively.</p>
<p>Generally, when the specification states that a feature applies to <span>the HTML syntax</span>
or <span>the XML syntax</span>, it also includes the other. When a feature specifically only
applies to one of the two languages, it is called out by explicitly stating that it does not apply
to the other format, as in "for HTML, ... (this does not apply to XML)".</p>
<p>This specification uses the term <dfn data-x="">document</dfn> to refer to any use of HTML,
ranging from short static documents to long essays or reports with rich multimedia, as well as to
fully-fledged interactive applications. The term is used to refer both to <code>Document</code>
objects and their descendant DOM trees, and to serialized byte streams using the <span data-x="the
HTML syntax">HTML syntax</span> or the <span data-x="the XML syntax">XML syntax</span>, depending
on context.</p>
<p>In the context of the DOM structures, the terms <span data-x="HTML documents">HTML
document</span> and <span data-x="XML documents">XML document</span> are used as defined in
<cite>DOM</cite>, and refer specifically to two different modes that <code>Document</code> objects
can find themselves in. <ref>DOM</ref> (Such uses are always hyperlinked to their
definition.)</p>
<p>In the context of byte streams, the term HTML document refers to resources labeled as
<code>text/html</code>, and the term XML document refers to resources labeled with an <span>XML
MIME type</span>.</p>
<hr>
<p>For simplicity, terms such as <dfn data-x="">shown</dfn>, <dfn data-x="">displayed</dfn>, and
<dfn data-x="">visible</dfn> might sometimes be used when referring to the way a document is
rendered to the user. These terms are not meant to imply a visual medium; they must be considered
to apply to other media in equivalent ways.</p>
<div w-nodev>
<h4>Parallelism</h4>
<p>To run steps <dfn export>in parallel</dfn> means those steps are to be run, one after another,
at the same time as other logic in the standard (e.g., at the same time as the <span>event
loop</span>). This standard does not define the precise mechanism by which this is achieved, be it
time-sharing cooperative multitasking, fibers, threads, processes, using different hyperthreads,
cores, CPUs, machines, etc. By contrast, an operation that is to run <dfn>immediately</dfn> must
interrupt the currently running task, run itself, and then resume the previously running task.</p>
<p class="note">For guidance on writing specifications that leverage parallelism, see <a
href="#event-loop-for-spec-authors">Dealing with the event loop from other specifications</a>.</p>
<p>To avoid race conditions between different <span>in parallel</span> algorithms that operate on
the same data, a <span>parallel queue</span> can be used.</p>
<p>A <dfn export>parallel queue</dfn> represents a queue of algorithm steps that must be run in
series.</p>
<p>A <span>parallel queue</span> has an <dfn>algorithm queue</dfn> (a <span>queue</span>),
initially empty.</p>
<p>To <dfn data-x="enqueue the following steps" data-lt="enqueue steps|enqueue the following
steps" export for="parallel queue">enqueue steps</dfn> to a <span>parallel queue</span>,
<span>enqueue</span> the algorithm steps to the <span>parallel queue</span>'s <span>algorithm
queue</span>.</p>
<p>To <dfn data-x="starting a new parallel queue" data-lt="start a new parallel queue|starting a
new parallel queue" export>start a new parallel queue</dfn>, run the following steps:</p>
<ol>
<li><p>Let <var>parallelQueue</var> be a new <span>parallel queue</span>.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li>
<p>While true:</p>
<ol>
<li><p>Let <var>steps</var> be the result of <span data-x="dequeue">dequeueing</span> from
<var>parallelQueue</var>'s <span>algorithm queue</span>.</p></li>
<li><p>If <var>steps</var> is not nothing, then run <var>steps</var>.</p></li>
<li><p><span>Assert</span>: running <var>steps</var> did not throw an exception, as steps
running <span>in parallel</span> are not allowed to throw.</p></li>
</ol>
<p class="note">Implementations are not expected to implement this as a continuously running
loop. Algorithms in standards are to be easy to understand and are not necessarily great for
battery life or performance.</p>
</li>
</ol>
</li>
<li><p>Return <var>parallelQueue</var>.</p></li>
</ol>
<p class="note">Steps running <span>in parallel</span> can themselves run other steps in <span>in
parallel</span>. E.g., inside a <span>parallel queue</span> it can be useful to run a series of
steps in parallel with the queue.</p>
<div class="example">
<p>Imagine a standard defined <var>nameList</var> (a <span>list</span>), along with a method to
add a <var>name</var> to <var>nameList</var>, unless <var>nameList</var> already <span
data-x="list contains">contains</span> <var>name</var>, in which case it rejects.</p>
<p>The following solution suffers from race conditions:</p>
<ol>
<li><p>Let <var>p</var> be a new promise created in <span>this</span>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Let <var>global</var> be <span>this</span>'s <span>relevant global
object</span>.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li><p>If <var>nameList</var> <span data-x="list contains">contains</span> <var>name</var>,
then <span>queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to reject <var>p</var> with a <code>TypeError</code>, and abort these
steps.</p></li>
<li><p>Do some potentially lengthy work.</p></li>
<li><p><span data-x="list append">Append</span> <var>name</var> to
<var>nameList</var>.</p></li>
<li><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to resolve <var>p</var> with undefined.</p></li>
</ol>
</li>
<li><p>Return <var>p</var>.</p></li>
</ol>
<p>Two invocations of the above could run simultaneously, meaning <var>name</var> isn't in
<var>nameList</var> during step 2.1, but it <em>might be added</em> before step 2.3 runs,
meaning <var>name</var> ends up in <var>nameList</var> twice.</p>
<p>Parallel queues solve this. The standard would let <var>nameListQueue</var> be the result of
<span>starting a new parallel queue</span>, then:</p>
<ol>
<li><p>Let <var>p</var> be a new promise created in <span>this</span>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Let <var>global</var> be <span>this</span>'s <span>relevant global
object</span>.</p></li>
<li>
<p><mark><span>Enqueue the following steps</span> to <var>nameListQueue</var>:</mark></p>
<ol>
<li><p>If <var>nameList</var> <span data-x="list contains">contains</span> <var>name</var>,
then <span>queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to reject <var>p</var> with a <code>TypeError</code>, and abort these
steps.</p></li>
<li><p>Do some potentially lengthy work.</p></li>
<li><p><span data-x="list append">Append</span> <var>name</var> to
<var>nameList</var>.</p></li>
<li><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to resolve <var>p</var> with undefined.</p></li>
</ol>
</li>
<li><p>Return <var>p</var>.</p></li>
</ol>
<p>The steps would now queue and the race is avoided.</p>
</div>
</div>
<h4>Resources</h4>
<p>The specification uses the term <dfn data-x="">supported</dfn> when referring to whether a user
agent has an implementation capable of decoding the semantics of an external resource. A format or
type is said to be <i>supported</i> if the implementation can process an external resource of that
format or type without critical aspects of the resource being ignored. Whether a specific resource
is <i>supported</i> can depend on what features of the resource's format are in use.</p>
<p class="example">For example, a PNG image would be considered to be in a supported format if its
pixel data could be decoded and rendered, even if, unbeknownst to the implementation, the image
also contained animation data.</p>
<p class="example">An MPEG-4 video file would not be considered to be in a supported format if the
compression format used was not supported, even if the implementation could determine the
dimensions of the movie from the file's metadata.</p>
<p>What some specifications, in particular the HTTP specifications, refer to as a
<i>representation</i> is referred to in this specification as a <dfn data-x="">resource</dfn>.
<ref>HTTP</ref></p>
<p>A resource's <dfn>critical subresources</dfn> are those that the resource needs to have
available to be correctly processed. Which resources are considered critical or not is defined by
the specification that defines the resource's format.</p>
<p>For <span data-x="CSS style sheet">CSS style sheets</span>, we tentatively define here that
their critical subresources are other style sheets imported via <code data-x="">@import</code>
rules, including those indirectly imported by other imported style sheets.</p>
<p class="XXX">This definition is not fully interoperable; furthermore, some user agents seem to
count resources like background images or web fonts as critical subresources. Ideally, the CSS
Working Group would define this; see <a
href="https://github.com/w3c/csswg-drafts/issues/1088">w3c/csswg-drafts issue #1088</a> to track
progress on that front.</p>
<h4 id="xml">XML compatibility</h4>
<p id="html-namespace">To ease migration from HTML to XML, user agents conforming to this
specification will place elements in HTML in the <code data-x="HTML
namespace">http://www.w3.org/1999/xhtml</code> namespace, at least for the purposes of the DOM and
CSS. The term "<dfn export>HTML elements</dfn>" refers to any element in that namespace, even in
XML documents.</p>
<p>Except where otherwise stated, all elements defined or mentioned in this specification are in
the <span>HTML namespace</span> ("<code data-x="">http://www.w3.org/1999/xhtml</code>"), and all
attributes defined or mentioned in this specification have no namespace.</p>
<p>The term <dfn>element type</dfn> is used to refer to the set of elements that have a given
local name and namespace. For example, <code>button</code> elements are elements with the element
type <code>button</code>, meaning they have the local name "<code data-x="">button</code>" and
(implicitly as defined above) the <span>HTML namespace</span>.</p>
<p>Attribute names are said to be <dfn>XML-compatible</dfn> if they match the <code
data-x="xml-Name">Name</code> production defined in XML and they contain no U+003A COLON
characters (:). <ref>XML</ref></p>
<h4>DOM trees</h4>
<p>When it is stated that some element or attribute is <dfn data-x="ignore">ignored</dfn>, or
treated as some other value, or handled as if it was something else, this refers only to the
processing of the node after it is in the DOM. <span w-nodev>A user agent must not mutate the
DOM in such situations.</span></p>
<p>A content attribute is said to <dfn data-x="">change</dfn> value only if its new value is
different than its previous value; setting an attribute to a value it already has does not change
it.</p>
<p>The term <dfn data-x="">empty</dfn>, when used for an attribute value, <code>Text</code> node,
or string, means that the <span>length</span> of the text is zero (i.e., not even containing <span
data-x="control">controls</span> or U+0020 SPACE).</p>
<p>An HTML element can have specific <dfn>HTML element insertion steps</dfn>, <dfn>HTML element
post-connection steps</dfn>, <dfn>HTML element removing steps</dfn>, and <dfn>HTML element moving
steps</dfn> all defined for the element's <span data-x="concept-element-local-name">local
name</span>.</p>
<p>The <span data-x="concept-node-insert-ext">insertion steps</span> for the HTML Standard, given
<var>insertedNode</var>, are defined as the following:</p>
<ol>
<li><p>If <var>insertedNode</var> is an element whose <span
data-x="concept-element-namespace">namespace</span> is the <span>HTML namespace</span>, and this
standard defines <span data-x="html element insertion steps">HTML element insertion steps</span>
for <var>insertedNode</var>'s <span data-x="concept-element-local-name">local name</span>, then
run the corresponding <span>HTML element insertion steps</span> given
<var>insertedNode</var>.</p></li>
<li>
<p>If <var>insertedNode</var> is a <span>form-associated element</span> or the ancestor of a
<span>form-associated element</span>, then:</p>
<ol>
<li><p>If the <span>form-associated element</span>'s <span>parser inserted flag</span> is set,
then return.</p></li>
<li><p><span>Reset the form owner</span> of the <span>form-associated element</span>.</p></li>
</ol>
</li>
<li><p>If <var>insertedNode</var> is an <code>Element</code> that is not on the
<span>stack of open elements</span> of an <span>HTML parser</span>, then
<span>process internal resource links</span> given <var>insertedNode</var>'s
<span>node document</span>.</p></li>
</ol>
<p>The <span data-x="concept-node-post-connection-ext">post-connection steps</span> for the HTML
Standard, given <var>insertedNode</var>, are defined as the following:</p>
<ol>
<li><p>If <var>insertedNode</var> is an element whose <span
data-x="concept-element-namespace">namespace</span> is the <span>HTML namespace</span>, and this
standard defines <span data-x="html element post-connection steps">HTML element post-connection
steps</span> for <var>insertedNode</var>'s <span data-x="concept-element-local-name">local
name</span>, then run the corresponding <span>HTML element post-connection steps</span> given
<var>insertedNode</var>.</p></li>
</ol>
<p>The <span data-x="concept-node-remove-ext">removing steps</span> for the HTML Standard, given
<var>removedNode</var> and <var>oldParent</var>, are defined as the following:</p>
<ol>
<li><p>Let <var>document</var> be <var>removedNode</var>'s <span>node document</span>.</p></li>
<li id="node-remove-focus-fixup">
<p>If <var>document</var>'s <span data-x="focused area of the document">focused area</span> is
<var>removedNode</var>, then set <var>document</var>'s <span data-x="focused area of the
document">focused area</span> to <var>document</var>'s <span>viewport</span>, and set
<var>document</var>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>'s <span>focus changed during ongoing
navigation</span> to false.</p>
<p class="note">This does <em>not</em> perform the <span>unfocusing steps</span>,
<span>focusing steps</span>, or <span>focus update steps</span>, and thus no <code
data-x="event-blur">blur</code> or <code data-x="event-change">change</code> events are
fired.</p>
</li>
<li><p>If <var>removedNode</var> is an element whose <span
data-x="concept-element-namespace">namespace</span> is the <span>HTML namespace</span>, and this
standard defines <span data-x="html element removing steps">HTML element removing steps</span>
for <var>removedNode</var>'s <span data-x="concept-element-local-name">local name</span>, then
run the corresponding <span>HTML element removing steps</span> given <var>removedNode</var> and
<var>oldParent</var>.</p></li>
<li>
<p>If <var>removedNode</var> is a <span>form-associated element</span> or the ancestor of a
<span>form-associated element</span>, then:</p>
<ol>
<li><p>If the <span>form-associated element</span> has a <span>form owner</span> and the
<span>form-associated element</span> and its <span>form owner</span> are no longer in the same
<span>tree</span>, then <span>reset the form owner</span> of the <span>form-associated
element</span>.</p></li>
</ol>
</li>
<li><p>If <var>removedNode</var>'s <code data-x="attr-popover">popover</code> attribute is not in
the <span data-x="attr-popover-none-state">no popover state</span>, then run the <span>hide
popover algorithm</span> given <var>removedNode</var>, false, false, and false.</p></li>
</ol>
<p>The <span data-x="concept-node-move-ext">moving steps</span> for the HTML Standard, given
<var>movedNode</var>, are defined as the following:</p>
<ol>
<li><p>If <var>movedNode</var> is an element whose <span
data-x="concept-element-namespace">namespace</span> is the <span>HTML namespace</span>, and this
standard defines <span>HTML element moving steps</span> for <var>movedNode</var>'s <span
data-x="concept-element-local-name">local name</span>, then run the corresponding <span>HTML
element moving steps</span> given <var>movedNode</var>.</p></li>
<li>
<p>If <var>movedNode</var> is a <span>form-associated element</span> or the ancestor of a
<span>form-associated element</span>, then:</p>
<ol>
<li><p>If the <span>form-associated element</span> has a <span>form owner</span> and the
<span>form-associated element</span> and its <span>form owner</span> are no longer in the same
<span>tree</span>, then <span>reset the form owner</span> of the <span>form-associated
element</span>.</p></li>
</ol>
</li>
</ol>
<p>A <dfn id="insert-an-element-into-a-document" data-x="node is inserted into a document"
data-lt="inserted into a document|node is inserted into a document" export>node is inserted into a
document</dfn> when the <span data-x="concept-node-insert-ext">insertion steps</span> are invoked
with it as the argument and it is now <span>in a document tree</span>. Analogously, a <dfn
id="remove-an-element-from-a-document" data-x="node is removed from a document" data-lt="removed
from a document|node is removed from a document" export>node is removed from a document</dfn> when
the <span data-x="concept-node-remove-ext">removing steps</span> are invoked with it as the
argument and it is now no longer <span>in a document tree</span>.</p>
<p>A node <dfn export>becomes connected</dfn> when the <span
data-x="concept-node-insert-ext">insertion steps</span> are invoked with it as the argument and it
is now <span>connected</span>. Analogously, a node <dfn data-lt="become disconnected"
export>becomes disconnected</dfn> when the <span data-x="concept-node-remove-ext">removing
steps</span> are invoked with it as the argument and it is now no longer
<span>connected</span>.</p>
<p>A node is <dfn export>browsing-context connected</dfn> when it is <span>connected</span> and
its <span data-x="shadow-including root">shadow-including root</span>'s <span
data-x="concept-document-bc">browsing context</span> is non-null. A node <dfn data-lt="become
browsing-context connected" export>becomes browsing-context connected</dfn> when the <span
data-x="concept-node-insert-ext">insertion steps</span> are invoked with it as the argument and it
is now <span>browsing-context connected</span>. A node <dfn data-lt="become browsing-context
disconnected" export>becomes browsing-context disconnected</dfn> either when the <span
data-x="concept-node-remove-ext">removing steps</span> are invoked with it as the argument and it
is now no longer <span>browsing-context connected</span>, or when its <span>shadow-including
root</span>'s <span data-x="concept-document-bc">browsing context</span> becomes null.
<h4>Scripting</h4>
<p>The construction "a <code data-x="">Foo</code> object", where <code data-x="">Foo</code> is
actually an interface, is sometimes used instead of the more accurate "an object implementing the
interface <code data-x="">Foo</code>".</p>
<p>An IDL attribute is said to be <dfn data-x="">getting</dfn> when its value is being retrieved
(e.g. by author script), and is said to be <dfn data-x="">setting</dfn> when a new value is
assigned to it.</p>
<p>If a DOM object is said to be <dfn>live</dfn>, then the attributes and methods on that object
<span w-nodev>must</span> operate on the actual underlying data, not a snapshot of the
data.</p>
<h4>Plugins</h4>
<p>The term <dfn>plugin</dfn> refers to an <span>implementation-defined</span> set of content
handlers used by the user agent that can take part in the user agent's rendering of a
<code>Document</code> object, but that neither act as <span data-x="child navigable">child
navigables</span> of the <code>Document</code> nor introduce any <code>Node</code> objects to the
<code>Document</code>'s DOM.</p>
<p>Typically such content handlers are provided by third parties, though a user agent can also
designate built-in content handlers as plugins.</p>
<div w-nodev>
<p>A user agent must not consider the types <code>text/plain</code> and
<code>application/octet-stream</code> as having a registered <span>plugin</span>.</p> <!-- because
of the way <object> elements handles those types, if nothing else (it also doesn't make any sense
to have a plugin registered for those types, of course) -->
</div>
<p class="example">One example of a plugin would be a PDF viewer that is instantiated in a
<span>navigable</span> when the user navigates to a PDF file. This would count as a plugin
regardless of whether the party that implemented the PDF viewer component was the same as that
which implemented the user agent itself. However, a PDF viewer application that launches separate
from the user agent (as opposed to using the same interface) is not a plugin by this
definition.</p>
<p class="note">This specification does not define a mechanism for interacting with plugins, as it
is expected to be user-agent- and platform-specific. Some UAs might opt to support a plugin
mechanism such as the Netscape Plugin API; others might use remote content converters or have
built-in support for certain types. Indeed, this specification doesn't require user agents to
support plugins at all. <ref>NPAPI</ref></p>
<div w-nodev>
<p class="warning">Browsers should take extreme care when interacting with external content
intended for <span data-x="plugin">plugins</span>. When third-party software is run with the same
privileges as the user agent itself, vulnerabilities in the third-party software become as
dangerous as those in the user agent.</p>
<p>
<!--INSERT TRACKING-->
Since different users having different sets of <span data-x="plugin">plugins</span> provides a
tracking vector that increases the chances of users being uniquely identified, user agents are
encouraged to support the exact same set of <span data-x="plugin">plugins</span> for each
user.</p>
</div>
<h4 id="encoding-terminology">Character encodings</h4>
<p>A <dfn data-x="encoding" data-x-href="https://encoding.spec.whatwg.org/#encoding">character
encoding</dfn>, or just <i>encoding</i> where that is not ambiguous, is a defined way to convert
between byte streams and Unicode strings, as defined in <cite>Encoding</cite>. An
<span>encoding</span> has an <dfn data-x-href="https://encoding.spec.whatwg.org/#name">encoding
name</dfn> and one or more <dfn data-x="encoding label"
data-x-href="https://encoding.spec.whatwg.org/#label">encoding labels</dfn>, referred to as the
encoding's <i>name</i> and <i>labels</i> in the Encoding standard. <ref>ENCODING</ref></p>
<div w-nodev>
<h4>Conformance classes</h4>
<p>This specification describes the conformance criteria for <span w-nodev>user agents
(relevant to implementers) and</span> documents<span w-nodev> (relevant to authors and
authoring tool implementers)</span>.</p>
<p><dfn>Conforming documents</dfn> are those that comply with all the conformance criteria for
documents. For readability, some of these conformance requirements are phrased as conformance
requirements on authors; such requirements are implicitly requirements on documents: by
definition, all documents are assumed to have had an author. (In some cases, that author may
itself be a user agent — such user agents are subject to additional rules, as explained
below.)</p>
<p class="example">For example, if a requirement states that "authors <!--non-normative-->must not
use the <code data-x="">foobar</code> element", it would imply that documents are not allowed to
contain elements named <code data-x="">foobar</code>.</p>
<p class="note impl">There is no implied relationship between document conformance requirements
and implementation conformance requirements. User agents are not free to handle non-conformant
documents as they please; the processing model described in this specification applies to
implementations regardless of the conformity of the input documents.</p>
<p>User agents fall into several (overlapping) categories with different conformance
requirements.</p>
<dl>
<dt id="interactive">Web browsers and other interactive user agents</dt>
<dd>
<p>Web browsers that support <span>the XML syntax</span> must process elements and attributes
from the <span>HTML namespace</span> found in XML documents as described in this specification,
so that users can interact with them, unless the semantics of those elements have been
overridden by other specifications.</p>
<p class="example">A conforming web browser would, upon finding a <code>script</code> element in
an XML document, execute the script contained in that element. However, if the element is found
within a transformation expressed in XSLT (assuming the user agent also supports XSLT), then the
processor would instead treat the <code>script</code> element as an opaque element that forms
part of the transform.</p>
<p>Web browsers that support <span>the HTML syntax</span> must process documents labeled with an
<span>HTML MIME type</span> as described in this specification, so that users can interact with
them.</p>
<p>User agents that support scripting must also be conforming implementations of the IDL
fragments in this specification, as described in <cite>Web IDL</cite>. <ref>WEBIDL</ref></p>
<p class="note">Unless explicitly stated, specifications that override the semantics of HTML
elements do not override the requirements on DOM objects representing those elements. For
example, the <code>script</code> element in the example above would still implement the
<code>HTMLScriptElement</code> interface.</p>
</dd>
<dt id="non-interactive">Non-interactive presentation user agents</dt>
<dd>
<p>User agents that process HTML and XML documents purely to render non-interactive versions of
them must comply to the same conformance criteria as web browsers, except that they are exempt
from requirements regarding user interaction.</p>
<p class="note">Typical examples of non-interactive presentation user agents are printers
(static UAs) and overhead displays (dynamic UAs). It is expected that most static
non-interactive presentation user agents will also opt to <a href="#non-scripted">lack scripting
support</a>.</p>
<p class="example">A non-interactive but dynamic presentation UA would still execute scripts,
allowing forms to be dynamically submitted, and so forth. However, since the concept of "focus"
is irrelevant when the user cannot interact with the document, the UA would not need to support
any of the focus-related DOM APIs.</p>
</dd>
<dt id="renderingUA">Visual user agents that support the suggested default rendering</dt>
<dd>
<p>User agents, whether interactive or not, may be designated (possibly as a user option) as
supporting the suggested default rendering defined by this specification.</p>
<p>This is not required. In particular, even user agents that do implement the suggested default
rendering are encouraged to offer settings that override this default to improve the experience
for the user, e.g. changing the color contrast, using different focus styles, or otherwise
making the experience more accessible and usable to the user.</p>
<p>User agents that are designated as supporting the suggested default rendering must, while so
designated, implement the rules <a href="#rendering">the Rendering section</a> defines as the
behavior that user agents are <em>expected</em> to implement.</p>
</dd>
<dt id="non-scripted">User agents with no scripting support</dt>
<dd>
<p>Implementations that do not support scripting (or which have their scripting features
disabled entirely) are exempt from supporting the events and DOM interfaces mentioned in this
specification. For the parts of this specification that are defined in terms of an events model
or in terms of the DOM, such user agents must still act as if events and the DOM were
supported.</p>
<p class="note">Scripting can form an integral part of an application. Web browsers that do not
support scripting, or that have scripting disabled, might be unable to fully convey the author's
intent.</p>
</dd>
<dt>Conformance checkers</dt>
<dd id="conformance-checkers">
<p>Conformance checkers must verify that a document conforms to the applicable conformance
criteria described in this specification. Automated conformance checkers are exempt from
detecting errors that require interpretation of the author's intent (for example, while a
document is non-conforming if the content of a <code>blockquote</code> element is not a quote,
conformance checkers running without the input of human judgement do not have to check that
<code>blockquote</code> elements only contain quoted material).</p>
<p>Conformance checkers must check that the input document conforms when parsed without a
<span data-x="concept-document-bc">browsing context</span> (meaning that no scripts are run, and
that the parser's <span>scripting flag</span> is disabled), and should also check that the input
document conforms when parsed with a <span data-x="concept-document-bc">browsing context</span>
in which scripts execute, and that the scripts never cause non-conforming states to occur other
than transiently during script execution itself. (This is only a "SHOULD" and not a "MUST"
requirement because it has been proven to be impossible. <ref>COMPUTABLE</ref>)</p>
<p>The term "HTML validator" can be used to refer to a conformance checker that itself conforms
to the applicable requirements of this specification.</p>
<div class="note">
<p>XML DTDs cannot express all the conformance requirements of this specification. Therefore, a
validating XML processor and a DTD cannot constitute a conformance checker. Also, since neither
of the two authoring formats defined in this specification are applications of SGML, a
validating SGML system cannot constitute a conformance checker either.</p>
<p>To put it another way, there are three types of conformance criteria:</p>
<ol>
<li>Criteria that can be expressed in a DTD.</li>
<li>Criteria that cannot be expressed by a DTD, but can still be checked by a machine.</li>
<li>Criteria that can only be checked by a human.</li>
</ol>
<p>A conformance checker must check for the first two. A simple DTD-based validator only checks
for the first class of errors and is therefore not a conforming conformance checker according
to this specification.</p>
</div>
</dd>
<dt>Data mining tools</dt>
<dd id="data-mining">
<p>Applications and tools that process HTML and XML documents for reasons other than to either
render the documents or check them for conformance should act in accordance with the semantics
of the documents that they process.</p>
<p class="example">A tool that generates <span data-x="outline">document outlines</span> but
increases the nesting level for each paragraph and does not increase the nesting level for
<span data-x="concept-heading">headings</span> would not be conforming.</p>
</dd>
<dt id="editors">Authoring tools and markup generators</dt>
<dd>
<p>Authoring tools and markup generators must generate <span>conforming documents</span>.
Conformance criteria that apply to authors also apply to authoring tools, where appropriate.</p>
<p>Authoring tools are exempt from the strict requirements of using elements only for their
specified purpose, but only to the extent that authoring tools are not yet able to determine
author intent. However, authoring tools must not automatically misuse elements or encourage
their users to do so.</p>
<p class="example">For example, it is not conforming to use an <code>address</code> element for
arbitrary contact information; that element can only be used for marking up contact information
for its nearest <code>article</code> or <code>body</code> element ancestor. However, since an
authoring tool is likely unable to determine the difference, an authoring tool is exempt from
that requirement. This does not mean, though, that authoring tools can use <code>address</code>
elements for any block of italics text (for instance); it just means that the authoring tool
doesn't have to verify that when the user uses a tool for inserting contact information for an
<code>article</code> element, that the user really is doing that and not inserting something
else instead.</p>
<p class="note">In terms of conformance checking, an editor has to output documents that conform
to the same extent that a conformance checker will verify.</p>
<p>When an authoring tool is used to edit a non-conforming document, it may preserve the
conformance errors in sections of the document that were not edited during the editing session
(i.e. an editing tool is allowed to round-trip erroneous content). However, an authoring tool
must not claim that the output is conformant if errors have been so preserved.</p>
<p>Authoring tools are expected to come in two broad varieties: tools that work from structure
or semantic data, and tools that work on a What-You-See-Is-What-You-Get media-specific editing
basis (WYSIWYG).</p>
<p>The former is the preferred mechanism for tools that author HTML, since the structure in the
source information can be used to make informed choices regarding which HTML elements and
attributes are most appropriate.</p>
<p>However, WYSIWYG tools are legitimate. WYSIWYG tools should use elements they know are
appropriate, and should not use elements that they do not know to be appropriate. This might in
certain extreme cases mean limiting the use of flow elements to just a few elements, like
<code>div</code>, <code>b</code>, <code>i</code>, and <code>span</code> and making liberal use
of the <code data-x="attr-style">style</code> attribute.</p>
<p>All authoring tools, whether WYSIWYG or not, should make a best effort attempt at enabling
users to create well-structured, semantically rich, media-independent content.</p>
</dd>
</dl>
<p>For compatibility with existing content and prior specifications, this specification describes
two authoring formats: one based on <span data-x="the XML syntax">XML</span>, and one using a <a
href="#writing">custom format</a> inspired by SGML (referred to as <span>the HTML syntax</span>).
Implementations must support at least one of these two formats, although supporting both is
encouraged.</p>
<p>Some conformance requirements are phrased as requirements on elements, attributes, methods or
objects. Such requirements fall into two categories: those describing content model restrictions,
and those describing implementation behavior. Those in the former category are requirements on
documents and authoring tools. Those in the second category are requirements on user agents.
Similarly, some conformance requirements are phrased as requirements on authors; such requirements
are to be interpreted as conformance requirements on the documents that authors produce. (In other
words, this specification does not distinguish between conformance criteria on authors and
conformance criteria on documents.)</p>
</div>
<h4>Dependencies</h4>
<!--
data-noexport="" is used here to avoid the definition scraper (Shepherd) from picking up any of the terms found
within this section. This is *not* used in accordance to the Bikeshed data model, which requires data-noexport=""
to exist only on <dfn> or <hN> elements. (That is why we use data-noexport="" instead of noexport=""; Wattsi will
only translate noexport="" according to the Bikeshed data model.)
We may be able to remove this once all definitions are sufficiently marked up and Shepherd stops trying to infer
definitions by scraping HTML.
-->
<div data-noexport="">
<p>This specification relies on several other underlying specifications.</p>
<dl>
<dt>Infra</dt>
<dd>
<p>The following terms are defined in <cite>Infra</cite>: <ref>INFRA</ref></p>
<ul class="brief">
<li>The general iteration terms <dfn data-x-href="https://infra.spec.whatwg.org/#iteration-while">while</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#iteration-continue">continue</dfn>, and
<dfn data-x-href="https://infra.spec.whatwg.org/#iteration-break">break</dfn>.</li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#assert">Assert</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#implementation-defined">implementation-defined</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#willful-violation">willful violation</dfn></li>
<li id="fingerprint"><span id="fingerprinting-vector"></span>
<!-- INSERT TRACKING -->
<dfn data-x-href="https://infra.spec.whatwg.org/#tracking-vector">tracking vector</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#code-point">code point</dfn> and its synonym
<dfn data-x-href="https://infra.spec.whatwg.org/#code-point">character</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#surrogate">surrogate</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#scalar-value">scalar value</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#tuple">tuple</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#noncharacter">noncharacter</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#string">string</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#code-unit">code unit</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#code-unit-prefix">code unit prefix</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#code-unit-less-than">code unit less than</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#string-starts-with">starts with</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#string-ends-with">ends with</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#string-length">length</dfn>, and
<dfn data-x-href="https://infra.spec.whatwg.org/#string-code-point-length">code point length</dfn></li>
<li id="case-sensitive">The string equality operations <dfn data-x-href="https://infra.spec.whatwg.org/#string-is">is</dfn> and
<dfn data-x-href="https://infra.spec.whatwg.org/#string-is">identical to</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#scalar-value-string">scalar value string</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#javascript-string-convert">convert</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#ascii-string">ASCII string</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#ascii-tab-or-newline">ASCII tab or newline</dfn></li>
<li><dfn id="space-characters" data-x-href="https://infra.spec.whatwg.org/#ascii-whitespace">ASCII whitespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#control">control</dfn></li>
<li><dfn data-x="ASCII digits" data-x-href="https://infra.spec.whatwg.org/#ascii-digit">ASCII digit</dfn></li>
<li><dfn id="uppercase-ascii-hex-digits" data-x-href="https://infra.spec.whatwg.org/#ascii-upper-hex-digit">ASCII upper hex digit</dfn></li>
<li><dfn id="lowercase-ascii-hex-digits" data-x-href="https://infra.spec.whatwg.org/#ascii-lower-hex-digit">ASCII lower hex digit</dfn></li>
<li><dfn data-x="ASCII hex digits" data-x-href="https://infra.spec.whatwg.org/#ascii-hex-digit">ASCII hex digit</dfn></li>
<li><dfn id="uppercase-ascii-letters" data-x-href="https://infra.spec.whatwg.org/#ascii-upper-alpha">ASCII upper alpha</dfn></li>
<li><dfn id="lowercase-ascii-letters" data-x-href="https://infra.spec.whatwg.org/#ascii-lower-alpha">ASCII lower alpha</dfn></li>
<li><dfn id="ascii-letters" data-x-href="https://infra.spec.whatwg.org/#ascii-alpha">ASCII alpha</dfn></li>
<li><dfn id="alphanumeric-ascii-characters" data-x-href="https://infra.spec.whatwg.org/#ascii-alphanumeric">ASCII alphanumeric</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#isomorphic-decode">isomorphic decode</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#isomorphic-encode">isomorphic encode</dfn></li>
<li><dfn data-x="converted to ASCII lowercase" data-x-href="https://infra.spec.whatwg.org/#ascii-lowercase">ASCII lowercase</dfn></li>
<li><dfn data-x="converted to ASCII uppercase" data-x-href="https://infra.spec.whatwg.org/#ascii-uppercase">ASCII uppercase</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#ascii-case-insensitive">ASCII case-insensitive</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#strip-newlines">strip newlines</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#normalize-newlines">normalize newlines</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#strip-leading-and-trailing-ascii-whitespace">strip leading and trailing ASCII whitespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace">strip and collapse ASCII whitespace</dfn></li>
<li><dfn id="split-a-string-on-spaces" data-x-href="https://infra.spec.whatwg.org/#split-on-ascii-whitespace">split a string on ASCII whitespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#split-on-commas">split a string on commas</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#collect-a-sequence-of-code-points">collect a sequence of code points</dfn> and its associated
<dfn data-x-href="https://infra.spec.whatwg.org/#string-position-variable">position variable</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#skip-ascii-whitespace">skip ASCII whitespace</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#ordered-map">ordered map</dfn> data structure and the associated definitions for
<dfn data-x="map key" data-x-href="https://infra.spec.whatwg.org/#map-key">key</dfn>,
<dfn data-x="map value" data-x-href="https://infra.spec.whatwg.org/#map-value">value</dfn>,
<dfn data-x="map empty" data-x-href="https://infra.spec.whatwg.org/#map-is-empty">empty</dfn>,
<dfn data-x="map entry" data-x-href="https://infra.spec.whatwg.org/#map-entry">entry</dfn>,
<dfn data-x="map exists" data-x-href="https://infra.spec.whatwg.org/#map-exists">exists</dfn>,
<dfn data-x="map get" data-x-href="https://infra.spec.whatwg.org/#map-get">getting the value of an entry</dfn>,
<dfn data-x="map set" data-x-href="https://infra.spec.whatwg.org/#map-set">setting the value of an entry</dfn>,
<dfn data-x="map remove" data-x-href="https://infra.spec.whatwg.org/#map-remove">removing an entry</dfn>,
<dfn data-x="map clear" data-x-href="https://infra.spec.whatwg.org/#map-clear">clear</dfn>,
<dfn data-x="map get the keys" data-x-href="https://infra.spec.whatwg.org/#map-getting-the-keys">getting the keys</dfn>,
<dfn data-x="map get the values" data-x-href="https://infra.spec.whatwg.org/#map-getting-the-values">getting the values</dfn>,
<dfn data-x="map sort descending" data-x-href="https://infra.spec.whatwg.org/#map-sort-in-descending-order">sorting in descending order</dfn>,
<dfn data-x="map size" data-x-href="https://infra.spec.whatwg.org/#map-size">size</dfn>, and
<dfn data-x="map iterate" data-x-href="https://infra.spec.whatwg.org/#map-iterate">iterate</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#list">list</dfn> data structure and the associated definitions for
<dfn data-x="list append" data-x-href="https://infra.spec.whatwg.org/#list-append">append</dfn>,
<dfn data-x="list extend" data-x-href="https://infra.spec.whatwg.org/#list-extend">extend</dfn>,
<dfn data-x="list prepend" data-x-href="https://infra.spec.whatwg.org/#list-prepend">prepend</dfn>,
<dfn data-x="list replace" data-x-href="https://infra.spec.whatwg.org/#list-replace">replace</dfn>,
<dfn data-x="list remove" data-x-href="https://infra.spec.whatwg.org/#list-remove">remove</dfn>,
<dfn data-x="list empty" data-x-href="https://infra.spec.whatwg.org/#list-empty">empty</dfn>,
<dfn data-x="list contains" data-x-href="https://infra.spec.whatwg.org/#list-contain">contains</dfn>,
<dfn data-x="list size" data-x-href="https://infra.spec.whatwg.org/#list-size">size</dfn>,
<dfn data-x-href="https://infra.spec.whatwg.org/#list-get-the-indices">indices</dfn>,
<dfn data-x="list is empty" data-x-href="https://infra.spec.whatwg.org/#list-is-empty">is empty</dfn>,
<dfn data-x="list item" data-x-href="https://infra.spec.whatwg.org/#list-item">item</dfn>,
<dfn data-x="list iterate" data-x-href="https://infra.spec.whatwg.org/#list-iterate">iterate</dfn>, and
<dfn data-x="list clone" data-x-href="https://infra.spec.whatwg.org/#list-clone">clone</dfn>
<dfn data-x="list sort" data-x-href="https://infra.spec.whatwg.org/#list-sort-in-ascending-order">sort in ascending order</dfn>
<dfn data-x="list sort descending" data-x-href="https://infra.spec.whatwg.org/#list-sort-in-descending-order">sort in descending order</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#stack">stack</dfn> data structure and the associated definitions for
<dfn data-x="stack push" data-x-href="https://infra.spec.whatwg.org/#stack-push">push</dfn> and
<dfn data-x="stack pop" data-x-href="https://infra.spec.whatwg.org/#stack-pop">pop</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#queue">queue</dfn> data structure and the associated definitions for
<dfn data-x-href="https://infra.spec.whatwg.org/#queue-enqueue">enqueue</dfn> and
<dfn data-x-href="https://infra.spec.whatwg.org/#queue-dequeue">dequeue</dfn></li>
<li>The <dfn data-x="set" data-x-href="https://infra.spec.whatwg.org/#ordered-set">ordered set</dfn> data structure and the associated definition for
<dfn data-x="set append" data-x-href="https://infra.spec.whatwg.org/#set-append">append</dfn> and
<dfn data-x="set union" data-x-href="https://infra.spec.whatwg.org/#set-union">union</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#struct">struct</dfn> specification type and the associated definition for
<dfn data-x="struct item" data-x-href="https://infra.spec.whatwg.org/#struct-item">item</dfn></li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#byte-sequence">byte sequence</dfn> data structure</li>
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#forgiving-base64-encode">forgiving-base64 encode</dfn> and
<dfn data-x-href="https://infra.spec.whatwg.org/#forgiving-base64-decode">forgiving-base64 decode</dfn> algorithms</li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#the-exclusive-range">exclusive range</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#parse-a-json-string-to-an-infra-value">parse a JSON string to an Infra value</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#html-namespace">HTML namespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#mathml-namespace">MathML namespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#svg-namespace">SVG namespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#xlink-namespace">XLink namespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#xml-namespace">XML namespace</dfn></li>
<li><dfn data-x-href="https://infra.spec.whatwg.org/#xmlns-namespace">XMLNS namespace</dfn></li>
</ul>
</dd>
<dt>Unicode and Encoding</dt>
<dd>
<p>The Unicode character set is used to represent textual data, and <cite>Encoding</cite>
defines requirements around <span data-x="encoding">character encodings</span>.
<ref>UNICODE</ref></p>
<p class="note">This specification <a href="#encoding-terminology">introduces terminology</a>
based on the terms defined in those specifications, as described earlier.</p>
<p>The following terms are used as defined in <cite>Encoding</cite>: <ref>ENCODING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://encoding.spec.whatwg.org/#concept-encoding-get">Getting an
encoding</dfn></li>
<li><dfn data-x-href="https://encoding.spec.whatwg.org/#get-an-output-encoding">Get an output
encoding</dfn></li>
<li>The generic <dfn data-x-href="https://encoding.spec.whatwg.org/#decode">decode</dfn>
algorithm which takes a byte stream and an encoding and returns a character stream</li>
<li>The <dfn data-x-href="https://encoding.spec.whatwg.org/#utf-8-decode">UTF-8 decode</dfn>
algorithm which takes a byte stream and returns a character stream, additionally stripping one
leading UTF-8 Byte Order Mark (BOM), if any</li>
<li>The <dfn data-x-href="https://encoding.spec.whatwg.org/#utf-8-decode-without-bom">UTF-8
decode without BOM</dfn> algorithm which is identical to <span>UTF-8 decode</span> except that
it does not strip one leading UTF-8 Byte Order Mark (BOM)</li>
<li>The <dfn data-x-href="https://encoding.spec.whatwg.org/#encode">encode</dfn> algorithm
which takes a character stream and an encoding and returns a byte stream</li>
<li>The <dfn data-x-href="https://encoding.spec.whatwg.org/#utf-8-encode">UTF-8 encode</dfn>
algorithm which takes a character stream and returns a byte stream</li>
<li>The <dfn data-x-href="https://encoding.spec.whatwg.org/#bom-sniff">BOM sniff</dfn>
algorithm which takes a byte stream and returns an encoding or null.</li>
</ul>
</dd>
<dt>XML and related specifications</dt>
<dd>
<p>Implementations that support <span>the XML syntax</span> for HTML must support some version
of XML, as well as its corresponding namespaces specification, because that syntax uses an XML
serialization with namespaces. <ref>XML</ref> <ref>XMLNS</ref></p>
<p>Data mining tools and other user agents that perform operations on content without running
scripts, evaluating CSS or XPath expressions, or otherwise exposing the resulting DOM to
arbitrary content, may "support namespaces" by just asserting that their DOM node analogues are
in certain namespaces, without actually exposing the namespace strings.</p>
<p class="note">In <span>the HTML syntax</span>, namespace prefixes and namespace declarations
do not have the same effect as in XML. For instance, the colon has no special meaning in HTML
element names.</p>
<hr>
<p>The attribute with the name <dfn
data-x-href="https://www.w3.org/TR/xml/#sec-white-space"><code
data-x="attr-xml-space">space</code></dfn> in the <span>XML namespace</span> is defined by
<cite>Extensible Markup Language</cite> (<cite>XML</cite>). <ref>XML</ref></p>
<p>The <dfn data-x-href="https://www.w3.org/TR/xml/#NT-Name"><code
data-x="xml-Name">Name</code></dfn> production is defined in <cite>XML</cite>.
<ref>XML</ref></p>
<p>This specification also references the <dfn
data-x-href="https://www.w3.org/TR/xml-stylesheet/#the-xml-stylesheet-processing-instruction"><code><?xml-stylesheet?></code></dfn>
processing instruction, defined in <cite>Associating Style Sheets with XML documents</cite>.
<ref>XMLSSPI</ref></p>
<p>This specification also non-normatively mentions the <dfn><code>XSLTProcessor</code></dfn>
interface and its <dfn><code
data-x="dom-XSLTProcessor-transformToFragment">transformToFragment()</code></dfn> and <dfn><code
data-x="dom-XSLTProcessor-transformToDocument">transformToDocument()</code></dfn> methods.
<ref>XSLTP</ref></p>
</dd>
<dt>URLs</dt>
<dd>
<p>The following terms are defined in <cite>URL</cite>: <ref>URL</ref></p>
<ul class="brief">
<li><dfn data-x="concept-host" data-x-href="https://url.spec.whatwg.org/#concept-host">host</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#host-public-suffix">public suffix</dfn></li>
<li><dfn data-x="concept-domain" data-x-href="https://url.spec.whatwg.org/#concept-domain">domain</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#ip-address">IP address</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#concept-url">URL</dfn></li>
<li><dfn data-x="concept-url-origin" data-x-href="https://url.spec.whatwg.org/#concept-url-origin">Origin</dfn> of URLs</li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#syntax-url-absolute">Absolute URL</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#syntax-url-relative">Relative URL</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#host-registrable-domain">registrable domain</dfn></li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#concept-url-parser">URL parser</dfn>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#concept-basic-url-parser">basic URL parser</dfn> and its
<dfn data-x="basic url parser url" data-x-href="https://url.spec.whatwg.org/#basic-url-parser-url"><var>url</var></dfn> and
<dfn data-x="basic url parser state override" data-x-href="https://url.spec.whatwg.org/#basic-url-parser-state-override"><var>state override</var></dfn>
arguments, as well as these parser states:
<ul class="brief">
<li><dfn data-x-href="https://url.spec.whatwg.org/#scheme-start-state">scheme start state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#host-state">host state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#hostname-state">hostname state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#port-state">port state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#path-start-state">path start state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#query-state">query state</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#fragment-state">fragment state</dfn></li>
</ul>
<li>
<dfn data-x-href="https://url.spec.whatwg.org/#concept-url">URL record</dfn>, as well as its
individual components:
<ul class="brief">
<li><dfn data-x="concept-url-scheme" data-x-href="https://url.spec.whatwg.org/#concept-url-scheme">scheme</dfn></li>
<li><dfn data-x="concept-url-username" data-x-href="https://url.spec.whatwg.org/#concept-url-username">username</dfn></li>
<li><dfn data-x="concept-url-password" data-x-href="https://url.spec.whatwg.org/#concept-url-password">password</dfn></li>
<li><dfn data-x="concept-url-host" data-x-href="https://url.spec.whatwg.org/#concept-url-host">host</dfn></li>
<li><dfn data-x="concept-url-port" data-x-href="https://url.spec.whatwg.org/#concept-url-port">port</dfn></li>
<li><dfn data-x="concept-url-path" data-x-href="https://url.spec.whatwg.org/#concept-url-path">path</dfn></li>
<li><dfn data-x="concept-url-query" data-x-href="https://url.spec.whatwg.org/#concept-url-query">query</dfn></li>
<li><dfn data-x="concept-url-fragment" data-x-href="https://url.spec.whatwg.org/#concept-url-fragment">fragment</dfn></li>
<li><dfn data-x="concept-url-blob-entry" data-x-href="https://url.spec.whatwg.org/#concept-url-blob-entry">blob URL entry</dfn></li>
</ul>
</li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#valid-url-string">valid URL string</dfn></li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#cannot-have-a-username-password-port">cannot have a username/password/port</dfn> concept</li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#url-opaque-path">opaque path</dfn> concept</li>
<li><dfn data-x="concept-url-serializer" data-x-href="https://url.spec.whatwg.org/#concept-url-serializer">URL serializer</dfn> and its
<dfn data-x="url serializer exclude fragment" data-x-href="https://url.spec.whatwg.org/#url-serializer-exclude-fragment">exclude fragment</dfn> argument</li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#url-path-serializer">URL path serializer</dfn></li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#concept-host-parser">host parser</dfn></li>
<li>The <dfn data-x="host serializer" data-x-href="https://url.spec.whatwg.org/#concept-host-serializer">host serializer</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#concept-host-equals">Host equals</dfn></li>
<li><dfn data-x="concept-url-equals" data-x-href="https://url.spec.whatwg.org/#concept-url-equals">URL equals</dfn> and its
<dfn data-x="url equals exclude fragments" data-x-href="https://url.spec.whatwg.org/#url-equals-exclude-fragments">exclude fragments</dfn> argument</li>
<li><dfn data-x="serialize an integer" data-x-href="https://url.spec.whatwg.org/#serialize-an-integer">serialize an integer</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#default-encode-set">Default encode set</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#component-percent-encode-set">component percent-encode set</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#string-utf-8-percent-encode">UTF-8 percent-encode</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#string-percent-decode">percent-decode</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#set-the-username">set the username</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#set-the-password">set the password</dfn></li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#concept-urlencoded"><code>application/x-www-form-urlencoded</code></dfn> format</li>
<li>The <dfn data-x-href="https://url.spec.whatwg.org/#concept-urlencoded-serializer"><code>application/x-www-form-urlencoded</code> serializer</dfn></li>
<li><dfn data-x-href="https://url.spec.whatwg.org/#is-special">is special</dfn></li>
</ul>
<p>A number of schemes and protocols are referenced by this specification also:</p>
<ul class="brief">
<li>The <dfn data-x="about protocol"
data-x-href="https://www.rfc-editor.org/rfc/rfc6694#section-2"><code>about:</code></dfn> scheme
<ref>ABOUT</ref></li>
<li>The <dfn data-x="blob protocol"
data-x-href="https://w3c.github.io/FileAPI/#DefinitionOfScheme"><code>blob:</code></dfn> scheme
<ref>FILEAPI</ref></li>
<li>The <dfn data-x="data protocol"
data-x-href="https://www.rfc-editor.org/rfc/rfc2397#section-2"><code>data:</code></dfn> scheme
<ref>RFC2397</ref></li>
<li>The <dfn data-x="http protocol"
data-x-href="https://httpwg.org/specs/rfc7230.html#http.uri"><code>http:</code></dfn> scheme
<ref>HTTP</ref></li>
<li>The <dfn data-x="https protocol"
data-x-href="https://httpwg.org/specs/rfc7230.html#https.uri"><code>https:</code></dfn> scheme
<ref>HTTP</ref></li>
<li>The <dfn data-x="mailto protocol"
data-x-href="https://www.rfc-editor.org/rfc/rfc6068#section-2"><code>mailto:</code></dfn>
scheme <ref>MAILTO</ref></li>
<li>The <dfn data-x="sms protocol"
data-x-href="https://www.rfc-editor.org/rfc/rfc5724#section-2"><code>sms:</code></dfn> scheme
<ref>SMS</ref></li>
<li>The <dfn data-x="urn protocol"
data-x-href="https://www.rfc-editor.org/rfc/rfc2141#section-2"><code>urn:</code></dfn> scheme
<ref>URN</ref></li>
</ul>
<p><dfn data-x-href="https://www.w3.org/TR/media-frags/#media-fragment-syntax">Media fragment
syntax</dfn> is defined in <cite>Media Fragments URI</cite>. <ref>MEDIAFRAG</ref></p>
</dd>
<dt>HTTP and related specifications</dt>
<dd>
<p>The following terms are defined in the HTTP specifications: <ref>HTTP</ref></p>
<ul class="brief">
<li>`<dfn data-x="http-accept" data-x-href="https://httpwg.org/specs/rfc7231.html#header.accept"><code>Accept</code></dfn>` header</li>
<li>`<dfn data-x="http-accept-language" data-x-href="https://httpwg.org/specs/rfc7231.html#header.accept-language"><code>Accept-Language</code></dfn>` header</li>
<li>`<dfn data-x="http-cache-control" data-x-href="https://httpwg.org/specs/rfc7234.html#header.cache-control"><code>Cache-Control</code></dfn>` header</li>
<li>`<dfn data-x="http-content-disposition" data-x-href="https://httpwg.org/specs/rfc6266.html"><code>Content-Disposition</code></dfn>` header</li>
<li>`<dfn data-x="http-content-language" data-x-href="https://httpwg.org/specs/rfc7231.html#header.content-language"><code>Content-Language</code></dfn>` header</li>
<li>`<dfn data-x="http-content-range" data-x-href="https://httpwg.org/specs/rfc7233.html#header.content-range"><code>Content-Range</code></dfn>` header</li>
<li>`<dfn data-x="http-last-modified" data-x-href="https://httpwg.org/specs/rfc7232.html#header.last-modified"><code>Last-Modified</code></dfn>` header</li>
<li>`<dfn data-x="http-range" data-x-href="https://httpwg.org/specs/rfc7233.html#header.range"><code>Range</code></dfn>` header</li>
<li>`<dfn data-x="http-referer" data-x-href="https://httpwg.org/specs/rfc7231.html#header.referer"><code>Referer</code></dfn>` header</li>
</ul>
<p>The following terms are defined in <cite>HTTP State Management Mechanism</cite>:
<ref>COOKIES</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://httpwg.org/specs/rfc6265.html#sane-cookie-syntax">cookie-string</dfn></li>
<li><dfn data-x-href="https://httpwg.org/specs/rfc6265.html#storage-model">receives a set-cookie-string</dfn></li>
<li>`<dfn data-x="http-cookie" data-x-href="https://httpwg.org/specs/rfc6265.html#cookie"><code>Cookie</code></dfn>` header</li>
</ul>
<p>The following term is defined in <cite>Web Linking</cite>: <ref>WEBLINK</ref></p>
<ul class="brief">
<li>`<dfn data-x="http-link" data-x-href="https://httpwg.org/specs/rfc8288.html#header"><code>Link</code></dfn>` header</li>
<li><dfn data-x="parsing a link field value" data-x-href="https://httpwg.org/specs/rfc8288.html#parse-fv">Parsing a `<code>Link</code>` field value</dfn></li>
</ul>
<p>The following terms are defined in <cite>Structured Field Values for HTTP</cite>:
<ref>STRUCTURED-FIELDS</ref></p>
<ul class="brief">
<li><dfn data-x="http-structured-header" data-x-href="https://httpwg.org/specs/rfc8941.html">structured header</dfn></li>
<li><dfn data-x="http-structured-header-boolean" data-x-href="https://httpwg.org/specs/rfc8941.html#boolean">boolean</dfn></li>
<li><dfn data-x="http-structured-header-token" data-x-href="https://httpwg.org/specs/rfc8941.html#token">token</dfn></li>
<li><dfn data-x="http-structured-header-parameters" data-x-href="https://httpwg.org/specs/rfc8941.html#param">parameters</dfn></li>
</ul>
<p>The following terms are defined in <cite>MIME Sniffing</cite>: <ref>MIMESNIFF</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#mime-type">MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#mime-type-essence">MIME type essence</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#valid-mime-type">valid MIME type string</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#valid-mime-type-with-no-parameters">valid MIME type string with no parameters</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#html-mime-type">HTML MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#javascript-mime-type">JavaScript MIME type</dfn> and
<dfn data-x-href="https://mimesniff.spec.whatwg.org/#javascript-mime-type-essence-match">JavaScript MIME type essence match</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#json-mime-type">JSON MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#xml-mime-type">XML MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#image-mime-type">image MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#audio-or-video-mime-type">audio or video MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#font-mime-type">font MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#parse-a-mime-type">parse a MIME type</dfn></li>
<li><dfn data-x-href="https://mimesniff.spec.whatwg.org/#supported-by-the-user-agent">is MIME type supported by the user agent?</dfn></li>
</ul>
</dd>
<dt>Fetch</dt>
<dd>
<p>The following terms are defined in <cite>Fetch</cite>: <ref>FETCH</ref></p>
<ul class="brief">
<li><dfn data-x="header-abnf" data-x-href="https://fetch.spec.whatwg.org/#abnf">ABNF</dfn></li>
<li><dfn><code>about:blank</code></dfn></li>
<li>An <dfn data-x-href="https://fetch.spec.whatwg.org/#http-scheme">HTTP(S) scheme</dfn></li>
<li>A URL which <dfn data-x="is-local" data-x-href="https://fetch.spec.whatwg.org/#is-local">is local</dfn></li>
<li>A <dfn data-x-href="https://fetch.spec.whatwg.org/#local-scheme">local scheme</dfn></li>
<li>A <dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-scheme">fetch scheme</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#http-cors-protocol">CORS protocol</dfn></li>
<li><dfn data-x="default-user-agent-value" data-x-href="https://fetch.spec.whatwg.org/#default-user-agent-value">default `<code>User-Agent</code>` value</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-header-extract-mime-type">extract a MIME type</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#legacy-extract-an-encoding">legacy extract an encoding</dfn></li>
<li><dfn data-x="concept-fetch" data-x-href="https://fetch.spec.whatwg.org/#concept-fetch">fetch</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-controller">fetch controller</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-controller-process-the-next-manual-redirect">process the next manual redirect</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#ok-status">ok status</dfn></li>
<li><dfn data-x="navigation-request" data-x-href="https://fetch.spec.whatwg.org/#navigation-request">navigation request</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-network-error">network error</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-aborted-network-error">aborted network error</dfn></li>
<li>`<dfn data-x="http-origin" data-x-href="https://fetch.spec.whatwg.org/#http-origin"><code>Origin</code></dfn>` header</li>
<li>`<dfn data-x-href="https://fetch.spec.whatwg.org/#http-cross-origin-resource-policy"><code>Cross-Origin-Resource-Policy</code></dfn>` header</li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-header-list-get-structured-header">getting a structured field value</dfn></li>
<li><dfn data-x="concept-header-list" data-x-href="https://fetch.spec.whatwg.org/#concept-header-list">header list</dfn></li>
<li><dfn data-x="concept-header-list-set" data-x-href="https://fetch.spec.whatwg.org/#concept-header-list-set">set</dfn></li>
<li><dfn data-x="concept-header-list-get-decode-split" data-x-href="https://fetch.spec.whatwg.org/#concept-header-list-get-decode-split">get, decode, and split</dfn></li>
<li><dfn data-x="fetch-controller-abort" data-x-href="https://fetch.spec.whatwg.org/#fetch-controller-abort">abort</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#cross-origin-resource-policy-check">cross-origin resource policy check</dfn></li>
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestcredentials"><code>RequestCredentials</code></dfn> enumeration</li>
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestdestination"><code>RequestDestination</code></dfn> enumeration</li>
<li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#dom-global-fetch"><code>fetch()</code></dfn> method</li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#finalize-and-report-timing">report timing</dfn></li>
<li><dfn data-x="serialize-a-response-url-for-reporting" data-x-href="https://fetch.spec.whatwg.org/#serialize-a-response-url-for-reporting">serialize a response URL for reporting</dfn></li>
<li><dfn data-x="body safely extract" data-x-href="https://fetch.spec.whatwg.org/#bodyinit-safely-extract">safely extracting a body</dfn></li>
<li><dfn data-x="body-incrementally-read" data-x-href="https://fetch.spec.whatwg.org/#body-incrementally-read">incrementally reading a body</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#process-response-end-of-body">processResponseConsumeBody</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-processresponseendofbody">processResponseEndOfBody</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#process-response">processResponse</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-useparallelqueue">useParallelQueue</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#fetch-processearlyhintsresponse">processEarlyHintsResponse</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-connection-pool">connection pool</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-connection-obtain">obtain a connection</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#determine-the-network-partition-key">determine the network partition key</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#extract-full-timing-info">extract full timing info</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#byte-sequence-as-a-body">as a body</dfn></li>
<li><dfn data-x="response-body-info" data-x-href="https://fetch.spec.whatwg.org/#response-body-info">response body info</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#resolve-an-origin">resolve an origin</dfn></li>
<li>
<dfn data-x="concept-response"
data-x-href="https://fetch.spec.whatwg.org/#concept-response">response</dfn> and its
associated:
<ul class="brief">
<li><dfn data-x="concept-response-type" data-x-href="https://fetch.spec.whatwg.org/#concept-response-type">type</dfn></li>
<li><dfn data-x="concept-response-url" data-x-href="https://fetch.spec.whatwg.org/#concept-response-url">URL</dfn></li>
<li><dfn data-x="concept-response-url-list" data-x-href="https://fetch.spec.whatwg.org/#concept-response-url-list">URL list</dfn></li>
<li><dfn data-x="concept-response-status" data-x-href="https://fetch.spec.whatwg.org/#concept-response-status">status</dfn></li>
<li><dfn data-x="concept-response-header-list" data-x-href="https://fetch.spec.whatwg.org/#concept-response-header-list">header list</dfn></li>
<li><dfn data-x="concept-response-body" data-x-href="https://fetch.spec.whatwg.org/#concept-response-body">body</dfn></li>
<li><dfn data-x="concept-response-body-info" data-x-href="https://fetch.spec.whatwg.org/#concept-response-body-info">body info</dfn></li>
<li><dfn data-x="concept-internal-response" data-x-href="https://fetch.spec.whatwg.org/#concept-internal-response">internal response</dfn></li>
<li><dfn data-x="concept-response-location-url" data-x-href="https://fetch.spec.whatwg.org/#concept-response-location-url">location URL</dfn></li>
<li><dfn data-x="concept-response-timing-info" data-x-href="https://fetch.spec.whatwg.org/#concept-response-timing-info">timing info</dfn></li>
<li><dfn data-x="concept-response-service-worker-timing-info" data-x-href="https://fetch.spec.whatwg.org/#response-service-worker-timing-info">service worker timing info</dfn></li>
<li><dfn data-x="concept-response-has-cross-origin-redirects" data-x-href="https://fetch.spec.whatwg.org/#response-has-cross-origin-redirects">has-cross-origin-redirects</dfn></li>
<li><dfn data-x="concept-response-timing-allow-passed" data-x-href="https://fetch.spec.whatwg.org/#concept-response-timing-allow-passed">timing allow passed</dfn></li>
<li>
<dfn data-x-href="https://wicg.github.io/background-fetch/#extract-content-range-values">extract content-range values</dfn>
<!-- TODO: move this to FETCH -->
</li>
</ul>
</li>
<li>
<dfn data-x="concept-request"
data-x-href="https://fetch.spec.whatwg.org/#concept-request">request</dfn> and its associated:
<ul class="brief">
<li><dfn data-x="concept-request-url" data-x-href="https://fetch.spec.whatwg.org/#concept-request-url">URL</dfn></li>
<li><dfn data-x="concept-request-method" data-x-href="https://fetch.spec.whatwg.org/#concept-request-method">method</dfn></li>
<li><dfn data-x="concept-request-header-list" data-x-href="https://fetch.spec.whatwg.org/#concept-request-header-list">header list</dfn></li>
<li><dfn data-x="concept-request-body" data-x-href="https://fetch.spec.whatwg.org/#concept-request-body">body</dfn></li>
<li><dfn data-x="concept-request-client" data-x-href="https://fetch.spec.whatwg.org/#concept-request-client">client</dfn></li>
<li><dfn data-x="concept-request-url-list" data-x-href="https://fetch.spec.whatwg.org/#concept-request-url-list">URL list</dfn></li>
<li><dfn data-x="concept-request-current-url" data-x-href="https://fetch.spec.whatwg.org/#concept-request-current-url">current URL</dfn></li>
<li><dfn data-x="concept-request-reserved-client" data-x-href="https://fetch.spec.whatwg.org/#concept-request-reserved-client">reserved client</dfn></li>
<li><dfn data-x="concept-request-replaces-client-id" data-x-href="https://fetch.spec.whatwg.org/#concept-request-replaces-client-id">replaces client id</dfn></li>
<li><dfn data-x="concept-request-initiator" data-x-href="https://fetch.spec.whatwg.org/#concept-request-initiator">initiator</dfn></li>
<li><dfn data-x="concept-request-destination" data-x-href="https://fetch.spec.whatwg.org/#concept-request-destination">destination</dfn></li>
<li><dfn data-x="concept-potential-destination" data-x-href="https://fetch.spec.whatwg.org/#concept-potential-destination">potential destination</dfn></li>
<li><dfn data-x="concept-potential-destination-translate" data-x-href="https://fetch.spec.whatwg.org/#concept-potential-destination-translate">translating</dfn> a <span data-x="concept-potential-destination">potential destination</span></li>
<li><dfn data-x="concept-script-like-destination" data-x-href="https://fetch.spec.whatwg.org/#request-destination-script-like">script-like</dfn> <span data-x="concept-request-destination">destinations</span></li>
<li><dfn data-x="concept-request-priority" data-x-href="https://fetch.spec.whatwg.org/#request-priority">priority</dfn></li>
<li><dfn data-x="concept-request-origin" data-x-href="https://fetch.spec.whatwg.org/#concept-request-origin">origin</dfn></li>
<li><dfn data-x="concept-request-referrer" data-x-href="https://fetch.spec.whatwg.org/#concept-request-referrer">referrer</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#synchronous-flag">synchronous flag</dfn></li>
<li><dfn data-x="concept-request-mode" data-x-href="https://fetch.spec.whatwg.org/#concept-request-mode">mode</dfn></li>
<li><dfn data-x="concept-request-credentials-mode" data-x-href="https://fetch.spec.whatwg.org/#concept-request-credentials-mode">credentials mode</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-request-use-url-credentials-flag">use-URL-credentials flag</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#unsafe-request-flag">unsafe-request flag</dfn></li>
<li><dfn data-x="concept-request-cache-mode" data-x-href="https://fetch.spec.whatwg.org/#concept-request-cache-mode">cache mode</dfn></li>
<li><dfn data-x="concept-request-redirect-count" data-x-href="https://fetch.spec.whatwg.org/#concept-request-redirect-count">redirect count</dfn></li>
<li><dfn data-x="concept-request-redirect-mode" data-x-href="https://fetch.spec.whatwg.org/#concept-request-redirect-mode">redirect mode</dfn></li>
<li><dfn data-x="concept-request-policy-container" data-x-href="https://fetch.spec.whatwg.org/#concept-request-policy-container">policy container</dfn></li>
<li><dfn data-x="concept-request-referrer-policy" data-x-href="https://fetch.spec.whatwg.org/#concept-request-referrer-policy">referrer policy</dfn></li>
<li><dfn data-x="concept-request-nonce-metadata" data-x-href="https://fetch.spec.whatwg.org/#concept-request-nonce-metadata">cryptographic nonce metadata</dfn></li>
<li><dfn data-x="concept-request-integrity-metadata" data-x-href="https://fetch.spec.whatwg.org/#concept-request-integrity-metadata">integrity metadata</dfn></li>
<li><dfn data-x="concept-request-parser-metadata" data-x-href="https://fetch.spec.whatwg.org/#concept-request-parser-metadata">parser metadata</dfn></li>
<li><dfn data-x="concept-request-reload-navigation-flag" data-x-href="https://fetch.spec.whatwg.org/#concept-request-reload-navigation-flag">reload-navigation flag</dfn></li>
<li><dfn data-x="concept-request-history-navigation-flag" data-x-href="https://fetch.spec.whatwg.org/#concept-request-history-navigation-flag">history-navigation flag</dfn></li>
<li><dfn data-x="concept-request-user-activation" data-x-href="https://fetch.spec.whatwg.org/#request-user-activation">user-activation</dfn></li>
<li><dfn data-x="concept-request-render-blocking" data-x-href="https://fetch.spec.whatwg.org/#request-render-blocking">render-blocking</dfn></li>
<li><dfn data-x="concept-request-initiator-type" data-x-href="https://fetch.spec.whatwg.org/#request-initiator-type">initiator type</dfn></li>
<li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-request-add-range-header">add a range header</dfn></li>
</ul>
</li>
<li>
<dfn data-x="fetch-timing-info"
data-x-href="https://fetch.spec.whatwg.org/#fetch-timing-info">fetch timing info</dfn> and its
associated:
<ul class="brief">
<li><dfn data-x="fetch-timing-info-start-time" data-x-href="https://fetch.spec.whatwg.org/#fetch-timing-info-start-time">start time</dfn></li>
<li><dfn data-x="fetch-timing-info-end-time" data-x-href="https://fetch.spec.whatwg.org/#fetch-timing-info-end-time">end time</dfn></li>
</ul>
</li>
</ul>
<p>The following terms are defined in <cite>Referrer Policy</cite>:
<ref>REFERRERPOLICY</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy">referrer policy</dfn></li>
<li>The `<dfn data-x="http-referrer-policy" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-header-dfn"><code>Referrer-Policy</code></dfn>` HTTP header</li>
<li>The <dfn data-x="parse-referrer-policy-header" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#parse-referrer-policy-from-header">parse a referrer policy from a `<code>Referrer-Policy</code>` header</dfn> algorithm</li>
<li>The "<dfn data-x="referrer-policy-no-referrer" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-no-referrer"><code>no-referrer</code></dfn>",
"<dfn data-x="referrer-policy-no-referrer-when-downgrade" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-no-referrer-when-downgrade"><code>no-referrer-when-downgrade</code></dfn>",
"<dfn data-x="referrer-policy-origin-when-cross-origin" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-origin-when-cross-origin"><code>origin-when-cross-origin</code></dfn>", and
"<dfn data-x="referrer-policy-unsafe-url" data-x-href="https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-unsafe-url"><code>unsafe-url</code></dfn>" referrer policies</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-referrer-policy/#default-referrer-policy">default referrer policy</dfn></li>
</ul>
<p>The following terms are defined in <cite>Mixed Content</cite>: <ref>MIX</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-mixed-content/#a-priori-authenticated-url"><i>a priori</i> authenticated URL</dfn></li>
</ul>
<p>The following terms are defined in <cite>Subresource Integrity</cite>: <ref>SRI</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-subresource-integrity/#parse-metadata">parse integrity metadata</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-subresource-integrity/#the-integrity-attribute">the requirements of the integrity attribute</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-subresource-integrity/#get-the-strongest-metadata">get the strongest metadata from set</dfn></li>
</ul>
</dd>
<dt>Paint Timing</dt>
<dd>
<p>The following terms are defined in <cite>Paint Timing</cite>: <ref>PAINTTIMING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/paint-timing/#mark-paint-timing">mark paint timing</dfn></li>
</ul>
</dd>
<dt>Navigation Timing</dt>
<dd>
<p>The following terms are defined in <cite>Navigation Timing</cite>:
<ref>NAVIGATIONTIMING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/navigation-timing/#dfn-create-the-navigation-timing-entry">create the navigation timing entry</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/navigation-timing/#dfn-queue-the-navigation-timing-entry">queue the navigation timing entry</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/navigation-timing/#dom-navigationtimingtype"><code>NavigationTimingType</code></dfn> and its
"<dfn data-x="dom-navigationtimingtype-navigate" data-x-href="https://w3c.github.io/navigation-timing/#dom-navigationtimingtype-navigate"><code>navigate</code></dfn>",
"<dfn data-x="dom-navigationtimingtype-reload" data-x-href="https://w3c.github.io/navigation-timing/#dom-navigationtimingtype-reload"><code>reload</code></dfn>", and
"<dfn data-x="dom-navigationtimingtype-back_forward" data-x-href="https://w3c.github.io/navigation-timing/#dom-navigationtimingtype-back_forward"><code>back_forward</code></dfn>" values.</li>
</ul>
</dd>
<dt>Resource Timing</dt>
<dd>
<p>The following terms are defined in <cite>Resource Timing</cite>:
<ref>RESOURCETIMING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/resource-timing/#dfn-mark-resource-timing">Mark resource timing</dfn></li>
</ul>
<dt>Performance Timeline</dt>
<dd>
<p>The following terms are defined in <cite>Performance Timeline</cite>:
<ref>PERFORMANCETIMELINE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry"><code>PerformanceEntry</code></dfn> and its
<dfn data-x="PerformanceEntry-name" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-name"><code>name</code></dfn>,
<dfn data-x="PerformanceEntry-entryType" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-entrytype"><code>entryType</code></dfn>,
<dfn data-x="PerformanceEntry-startTime" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-starttime"><code>startTime</code></dfn>, and
<dfn data-x="PerformanceEntry-duration" data-x-href="https://w3c.github.io/performance-timeline/#dom-performanceentry-duration"><code>duration</code></dfn> attributes.</li>
<li><dfn data-x-href="https://w3c.github.io/performance-timeline/#queue-a-performanceentry">Queue a performance entry</dfn></li>
</ul>
</dd>
<dt>Long Animation Frames</dt>
<dd>
<p>The following terms are defined in <cite>Long Animation Frames</cite>: <ref>LONGANIMATIONFRAMES</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-task-start-time">record task start time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-task-end-time">record task end time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-rendering-time">record rendering time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-classic-script-creation-time">record classic script creation time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-classic-script-execution-start-time">record classic script execution start time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-module-script-execution-start-time">record module script execution start time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-pause-duration">Record pause duration</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-timing-info-for-timer-handler">record timing info for timer handler</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/long-animation-frames/#record-timing-info-for-microtask-checkpoint">record timing info for microtask checkpoint</dfn></li>
</ul>
</dd>
<dt>Long Tasks</dt>
<dd>
<p>The following terms are defined in <cite>Long Tasks</cite>: <ref>LONGTASKS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/longtasks/#report-long-tasks">report long tasks</dfn></li>
</ul>
</dd>
<dt>Web IDL</dt>
<dd>
<p>The IDL fragments in this specification must be interpreted as required for conforming IDL
fragments, as described in <cite>Web IDL</cite>. <ref>WEBIDL</ref></p>
<p>The following terms are defined in <cite>Web IDL</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#this">this</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-extended-attribute">extended attribute</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-named-constructor">named constructor</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#idl-constructors">constructor operation</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#overridden-constructor-steps">overridden constructor steps</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#internally-create-a-new-object-implementing-the-interface">internally create a new object implementing the interface</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-array-index-property-name">array index property name</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-support-indexed-properties">supports indexed properties</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-supported-property-indices">supported property indices</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-determine-the-value-of-an-indexed-property">determine the value of an indexed property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-set-the-value-of-an-existing-indexed-property">set the value of an existing indexed property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-set-the-value-of-a-new-indexed-property">set the value of a new indexed property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-support-named-properties">support named properties</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-supported-property-names">supported property names</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-determine-the-value-of-a-named-property">determine the value of a named property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-set-the-value-of-an-existing-named-property">set the value of an existing named property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-set-the-value-of-a-new-named-property">set the value of a new named property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-delete-an-existing-named-property">delete an existing named property</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-perform-a-security-check">perform a security check</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-platform-object">platform object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-legacy-platform-object">legacy platform object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-primary-interface">primary interface</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-interface-object">interface object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-named-properties-object">named properties object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#include">include</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-inherit">inherit</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-interface-prototype-object">interface prototype object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#implements">implements</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-associated-realm">associated realm</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#es-platform-objects">[[Realm]] field of a platform object</dfn></li>
<li><dfn data-x="named-properties-object-getownproperty" data-x-href="https://webidl.spec.whatwg.org/#named-properties-object-getownproperty">[[GetOwnProperty]] internal method of a named properties object</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-callback-context">callback context</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-frozen-array-type">frozen array</dfn> and
<dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-create-frozen-array">creating a frozen array</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#new" data-x="new">create a new object implementing the interface</dfn></li>
<li><dfn data-x="dfn-callback-this-value" data-x-href="https://webidl.spec.whatwg.org/#dfn-callback-this-value">callback this value</dfn></li>
<li><dfn data-x="concept-idl-convert" data-x-href="https://webidl.spec.whatwg.org/#es-type-mapping">converting</dfn> between Web IDL types and JS types</li>
<li><dfn data-x="es-invoking-callback-functions" data-x-href="https://webidl.spec.whatwg.org/#invoke-a-callback-function">invoking</dfn> and
<dfn data-x="es-constructing-callback-functions" data-x-href="https://webidl.spec.whatwg.org/#construct-a-callback-function">constructing</dfn> callback functions</li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-overload-resolution-algorithm">overload resolution algorithm</dfn></li>
<li><dfn data-x="idl-exposed" data-x-href="https://webidl.spec.whatwg.org/#dfn-exposed">exposed</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#a-promise-resolved-with">a promise resolved with</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#a-promise-rejected-with">a promise rejected with</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#wait-for-all">wait for all</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#upon-rejection">upon rejection</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#upon-fulfillment">upon fulfillment</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#mark-a-promise-as-handled">mark as handled</dfn></li>
<li><dfn data-x="Global" data-x-href="https://webidl.spec.whatwg.org/#Global"><code>[Global]</code></dfn></li>
<li><dfn data-x="LegacyFactoryFunction" data-x-href="https://webidl.spec.whatwg.org/#LegacyFactoryFunction"><code>[LegacyFactoryFunction]</code></dfn></li>
<li><dfn data-x="LegacyLenientThis" data-x-href="https://webidl.spec.whatwg.org/#LegacyLenientThis"><code>[LegacyLenientThis]</code></dfn></li>
<li><dfn data-x="LegacyNullToEmptyString" data-x-href="https://webidl.spec.whatwg.org/#LegacyNullToEmptyString"><code>[LegacyNullToEmptyString]</code></dfn></li>
<li><dfn data-x="LegacyOverrideBuiltIns" data-x-href="https://webidl.spec.whatwg.org/#LegacyOverrideBuiltIns"><code>[LegacyOverrideBuiltIns]</code></dfn></li>
<li><dfn data-x="LegacyPlatformObjectGetOwnProperty" data-x-href="https://webidl.spec.whatwg.org/#LegacyPlatformObjectGetOwnProperty">LegacyPlatformObjectGetOwnProperty</dfn></li>
<li><dfn data-x="LegacyTreatNonObjectAsNull" data-x-href="https://webidl.spec.whatwg.org/#LegacyTreatNonObjectAsNull"><code>[LegacyTreatNonObjectAsNull]</code></dfn></li>
<li><dfn data-x="LegacyUnenumerableNamedProperties" data-x-href="https://webidl.spec.whatwg.org/#LegacyUnenumerableNamedProperties"><code>[LegacyUnenumerableNamedProperties]</code></dfn></li>
<li><dfn data-x="LegacyUnforgeable" data-x-href="https://webidl.spec.whatwg.org/#LegacyUnforgeable"><code>[LegacyUnforgeable]</code></dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-set-entries">set entries</dfn></li>
</ul>
<p><cite>Web IDL</cite> also defines the following types that are used in Web IDL fragments in
this specification:</p>
<ul class="brief">
<li><dfn data-x="idl-ArrayBuffer" data-x-href="https://webidl.spec.whatwg.org/#idl-ArrayBuffer"><code>ArrayBuffer</code></dfn></li>
<li><dfn data-x="idl-ArrayBufferView" data-x-href="https://webidl.spec.whatwg.org/#common-ArrayBufferView"><code>ArrayBufferView</code></dfn></li>
<li><dfn data-x="idl-boolean" data-x-href="https://webidl.spec.whatwg.org/#idl-boolean"><code>boolean</code></dfn></li>
<li><dfn data-x="idl-DOMString" data-x-href="https://webidl.spec.whatwg.org/#idl-DOMString"><code>DOMString</code></dfn></li>
<li><dfn data-x="idl-double" data-x-href="https://webidl.spec.whatwg.org/#idl-double"><code>double</code></dfn></li>
<li><dfn data-x="IDL enumeration" data-x-href="https://webidl.spec.whatwg.org/#idl-enums">enumeration</dfn></li>
<li><dfn data-x="idl-Function" data-x-href="https://webidl.spec.whatwg.org/#common-Function"><code>Function</code></dfn></li>
<li><dfn data-x="idl-long" data-x-href="https://webidl.spec.whatwg.org/#idl-long"><code>long</code></dfn></li>
<li><dfn data-x="idl-object" data-x-href="https://webidl.spec.whatwg.org/#idl-object"><code>object</code></dfn></li>
<li><dfn data-x="idl-Promise" data-x-href="https://webidl.spec.whatwg.org/#idl-promise"><code>Promise</code></dfn></li>
<li><dfn data-x="idl-Uint8ClampedArray" data-x-href="https://webidl.spec.whatwg.org/#idl-Uint8ClampedArray"><code>Uint8ClampedArray</code></dfn></li>
<li><dfn data-x="idl-unrestricted-double" data-x-href="https://webidl.spec.whatwg.org/#idl-unrestricted-double"><code>unrestricted double</code></dfn></li>
<li><dfn data-x="idl-unsigned-long" data-x-href="https://webidl.spec.whatwg.org/#idl-unsigned-long"><code>unsigned long</code></dfn></li>
<li><dfn data-x="idl-USVString" data-x-href="https://webidl.spec.whatwg.org/#idl-USVString"><code>USVString</code></dfn></li>
<li><dfn data-x="idl-VoidFunction" data-x-href="https://webidl.spec.whatwg.org/#VoidFunction"><code>VoidFunction</code></dfn></li>
</ul>
<p>The term <dfn data-x-href="https://webidl.spec.whatwg.org/#dfn-throw">throw</dfn> in this
specification is used as defined in <cite>Web IDL</cite>. The <dfn
data-x-href="https://webidl.spec.whatwg.org/#dfn-DOMException"><code>DOMException</code></dfn>
type and the following exception names are defined by Web IDL and used by this
specification:</p>
<ul class="brief">
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#indexsizeerror">"<code>IndexSizeError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#hierarchyrequesterror">"<code>HierarchyRequestError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#invalidcharactererror">"<code>InvalidCharacterError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#nomodificationallowederror">"<code>NoModificationAllowedError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#notfounderror">"<code>NotFoundError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#notsupportederror">"<code>NotSupportedError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#invalidstateerror">"<code>InvalidStateError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#syntaxerror">"<code>SyntaxError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#invalidaccesserror">"<code>InvalidAccessError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#securityerror">"<code>SecurityError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#networkerror">"<code>NetworkError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#aborterror">"<code>AbortError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#quotaexceedederror">"<code>QuotaExceededError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#datacloneerror">"<code>DataCloneError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#encodingerror">"<code>EncodingError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#notallowederror">"<code>NotAllowedError</code>"</dfn></li>
</ul>
<p>When this specification requires a user agent to <dfn>create a <code>Date</code> object</dfn>
representing a particular time (which could be the special value Not-a-Number), the milliseconds
component of that time, if any, must be truncated to an integer, and the time value of the newly
created <code>Date</code> object must represent the resulting truncated time.</p>
<p class="example">For instance, given the time 23045 millionths of a second after 01:00 UTC on
January 1st 2000, i.e. the time 2000-01-01T00:00:00.023045Z, then the <code>Date</code> object
created representing that time would represent the same time as that created representing the
time 2000-01-01T00:00:00.023Z, 45 millionths earlier. If the given time is NaN, then the result
is a <code>Date</code> object that represents a time value NaN (indicating that the object does
not represent a specific instant of time).</p>
</dd>
<dt>JavaScript</dt>
<dd>
<p>Some parts of the language described by this specification only support JavaScript as the
underlying scripting language. <ref>JAVASCRIPT</ref></p>
<p class="note">The term "JavaScript" is used to refer to ECMA-262, rather than the official
term ECMAScript, since the term JavaScript is more widely known.</p>
<p>The following terms are defined in the JavaScript specification and used in this
specification:</p>
<ul class="brief">
<li><dfn data-x-href="https://tc39.es/ecma262/#active-function-object">active function object</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-agents">agent</dfn> and
<dfn data-x-href="https://tc39.es/ecma262/#sec-agent-clusters">agent cluster</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-automatic-semicolon-insertion">automatic semicolon insertion</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-candidate-executions">candidate execution</dfn></li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#current-realm">current realm</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#clamping">clamping</dfn> a mathematical value</li>
<li><dfn data-x-href="https://tc39.es/ecma262/#early-error-rule">early error</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-forward-progress">forward progress</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-invariants-of-the-essential-internal-methods">invariants of the essential internal methods</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-execution-contexts">JavaScript execution context</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#execution-context-stack">JavaScript execution context stack</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-code-realms">realm</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-jobcallback-records">JobCallback Record</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-built-in-function-objects">NewTarget</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#running-execution-context">running JavaScript execution context</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#surrounding-agent">surrounding agent</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-abstract-closure">abstract closure</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#immutable-prototype-exotic-object">immutable prototype exotic object</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-well-known-symbols">Well-Known Symbols</dfn>, including
<dfn>%Symbol.hasInstance%</dfn>,
<dfn>%Symbol.isConcatSpreadable%</dfn>,
<dfn>%Symbol.toPrimitive%</dfn>, and
<dfn>%Symbol.toStringTag%</dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-well-known-intrinsic-objects">Well-Known Intrinsic Objects</dfn>, including
<dfn data-x-href="https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object">%Array.prototype%</dfn>,
<dfn data-x-href="https://tc39.es/ecma262/#sec-properties-of-the-error-prototype-object">%Error.prototype%</dfn>,
<dfn>%EvalError.prototype%</dfn>,
<dfn data-x-href="https://tc39.es/ecma262/#sec-properties-of-the-function-prototype-object">%Function.prototype%</dfn>,
<dfn data-x-href="https://tc39.es/ecma262/#sec-properties-of-the-object-prototype-object">%Object.prototype%</dfn>,
<dfn data-x-href="https://tc39.es/ecma262/#sec-object.prototype.valueof">%Object.prototype.valueOf%</dfn>,
<dfn>%RangeError.prototype%</dfn>,
<dfn>%ReferenceError.prototype%</dfn>,
<dfn>%SyntaxError.prototype%</dfn>,
<dfn>%TypeError.prototype%</dfn>, and
<dfn>%URIError.prototype%</dfn></li>
<li>The <dfn data-x="js-prod-FunctionBody" data-x-href="https://tc39.es/ecma262/#prod-FunctionBody"><i>FunctionBody</i></dfn> production</li>
<li>The <dfn data-x="js-prod-Module" data-x-href="https://tc39.es/ecma262/#prod-Module"><i>Module</i></dfn> production</li>
<li>The <dfn data-x="js-prod-Pattern" data-x-href="https://tc39.es/ecma262/#prod-Pattern"><i>Pattern</i></dfn> production</li>
<li>The <dfn data-x="js-prod-Script" data-x-href="https://tc39.es/ecma262/#prod-Script"><i>Script</i></dfn> production</li>
<li>The
<dfn data-x="js-BigInt" data-x-href="https://tc39.es/ecma262/#sec-ecmascript-language-types-bigint-type">BigInt</dfn>,
<dfn data-x="js-Boolean" data-x-href="https://tc39.es/ecma262/#sec-ecmascript-language-types-boolean-type">Boolean</dfn>,
<dfn data-x="js-Number" data-x-href="https://tc39.es/ecma262/#sec-ecmascript-language-types-number-type">Number</dfn>,
<dfn data-x="js-String" data-x-href="https://tc39.es/ecma262/#sec-ecmascript-language-types-string-type">String</dfn>,
<dfn data-x="js-Symbol" data-x-href="https://tc39.es/ecma262/#sec-ecmascript-language-types-symbol-type">Symbol</dfn>,
and <dfn data-x="js-Object" data-x-href="https://tc39.es/ecma262/#sec-object-type">Object</dfn> ECMAScript language types</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-completion-record-specification-type">Completion Record</dfn> specification type</li>
<li>The <dfn data-x="js-List" data-x-href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">List</dfn> and
<dfn data-x-href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">Record</dfn> specification types</li>
<li>The <dfn data-x="PropertyDescriptor" data-x-href="https://tc39.es/ecma262/#sec-property-descriptor-specification-type">Property Descriptor</dfn> specification type</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#modulerequest-record">ModuleRequest Record</dfn> specification type</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-script-records">Script Record</dfn> specification type</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-synthetic-module-records">Synthetic Module Record</dfn> specification type</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-cyclic-module-records">Cyclic Module Record</dfn> specification type</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-source-text-module-records">Source Text Module Record</dfn> specification type and its
<dfn data-x="js-Evaluate" data-x-href="https://tc39.es/ecma262/#sec-moduleevaluation">Evaluate</dfn>,
<dfn data-x="js-Link" data-x-href="https://tc39.es/ecma262/#sec-moduledeclarationlinking">Link</dfn> and
<dfn data-x="js-LoadRequestedModules" data-x-href="https://tc39.es/ecma262/#sec-LoadRequestedModules">LoadRequestedModules</dfn> methods</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-arraycreate">ArrayCreate</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-call">Call</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-clear-kept-objects">ClearKeptObjects</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-cleanup-finalization-registry">CleanupFinalizationRegistry</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-construct">Construct</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-copydatablockbytes">CopyDataBlockBytes</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-createbuiltinfunction">CreateBuiltinFunction</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-createbytedatablock">CreateByteDataBlock</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-createdataproperty">CreateDataProperty</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-create-default-export-synthetic-module">CreateDefaultExportSyntheticModule</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-definepropertyorthrow">DefinePropertyOrThrow</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-detacharraybuffer">DetachArrayBuffer</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-enumerableownproperties">EnumerableOwnProperties</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-FinishLoadingImportedModule">FinishLoadingImportedModule</dfn> abstract operation</li>
<li>The <dfn data-x="js-OrdinaryFunctionCreate" data-x-href="https://tc39.es/ecma262/#sec-ordinaryfunctioncreate">OrdinaryFunctionCreate</dfn> abstract operation</li>
<li>The <dfn data-x="js-Get" data-x-href="https://tc39.es/ecma262/#sec-get-o-p">Get</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-getactivescriptormodule">GetActiveScriptOrModule</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-getfunctionrealm">GetFunctionRealm</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-hasownproperty">HasOwnProperty</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostCallJobCallback" data-x-href="https://tc39.es/ecma262/#sec-hostcalljobcallback">HostCallJobCallback</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueueFinalizationRegistryCleanupJob" data-x-href="https://tc39.es/ecma262/#sec-host-cleanup-finalization-registry">HostEnqueueFinalizationRegistryCleanupJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueueGenericJob" data-x-href="https://tc39.es/ecma262/#sec-hostenqueuegenericjob">HostEnqueueGenericJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueuePromiseJob" data-x-href="https://tc39.es/ecma262/#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueueTimeoutJob" data-x-href="https://tc39.es/ecma262/#sec-hostenqueuetimeoutjob">HostEnqueueTimeoutJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnsureCanAddPrivateElement" data-x-href="https://tc39.es/ecma262/#sec-hostensurecanaddprivateelement">HostEnsureCanAddPrivateElement</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostGetSupportedImportAttributes" data-x-href="https://tc39.es/ecma262/#sec-hostgetsupportedimportattributes">HostGetSupportedImportAttributes</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostLoadImportedModule" data-x-href="https://tc39.es/ecma262/#sec-HostLoadImportedModule">HostLoadImportedModule</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostMakeJobCallback" data-x-href="https://tc39.es/ecma262/#sec-hostmakejobcallback">HostMakeJobCallback</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostPromiseRejectionTracker" data-x-href="https://tc39.es/ecma262/#sec-host-promise-rejection-tracker">HostPromiseRejectionTracker</dfn> abstract operation</li>
<li>The <dfn data-x="js-InitializeHostDefinedRealm" data-x-href="https://tc39.es/ecma262/#sec-initializehostdefinedrealm">InitializeHostDefinedRealm</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-isarraybufferviewoutofbounds">IsArrayBufferViewOutOfBounds</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-isaccessordescriptor">IsAccessorDescriptor</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-iscallable">IsCallable</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-isconstructor">IsConstructor</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-isdatadescriptor">IsDataDescriptor</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-isdetachedbuffer">IsDetachedBuffer</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-issharedarraybuffer">IsSharedArrayBuffer</dfn> abstract operation</li>
<li>The <dfn data-x="js-NewObjectEnvironment" data-x-href="https://tc39.es/ecma262/#sec-newobjectenvironment">NewObjectEnvironment</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-normalcompletion">NormalCompletion</dfn> abstract operation</li>
<!-- the next set of Ordinary* abstract operations are in order of appearance -->
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarygetprototypeof">OrdinaryGetPrototypeOf</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarysetprototypeof">OrdinarySetPrototypeOf</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinaryisextensible">OrdinaryIsExtensible</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarypreventextensions">OrdinaryPreventExtensions</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarygetownproperty">OrdinaryGetOwnProperty</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarydefineownproperty">OrdinaryDefineOwnProperty</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinaryget">OrdinaryGet</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinaryset">OrdinarySet</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinarydelete">OrdinaryDelete</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-ordinaryownpropertykeys">OrdinaryOwnPropertyKeys</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-objectcreate">OrdinaryObjectCreate</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-parse-json-module">ParseJSONModule</dfn> abstract operation</li>
<li>The <dfn data-x="js-ParseModule" data-x-href="https://tc39.es/ecma262/#sec-parsemodule">ParseModule</dfn> abstract operation</li>
<li>The <dfn data-x="js-ParseScript" data-x-href="https://tc39.es/ecma262/#sec-parse-script">ParseScript</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-newpromisereactionjob">NewPromiseReactionJob</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-newpromiseresolvethenablejob">NewPromiseResolveThenableJob</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-regexpbuiltinexec">RegExpBuiltinExec</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-regexpcreate">RegExpCreate</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-runjobs">RunJobs</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-samevalue">SameValue</dfn> abstract operation</li>
<li>The <dfn data-x="js-ScriptEvaluation" data-x-href="https://tc39.es/ecma262/#sec-runtime-semantics-scriptevaluation">ScriptEvaluation</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-setsyntheticmoduleexport">SetSyntheticModuleExport</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-set-immutable-prototype">SetImmutablePrototype</dfn> abstract operation</li>
<li>The <dfn data-x="js-ToBoolean" data-x-href="https://tc39.es/ecma262/#sec-toboolean">ToBoolean</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-tostring">ToString</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-touint32">ToUint32</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#typedarray-create">TypedArrayCreate</dfn> abstract operation</li>
<li>The <dfn data-x="js-abstract-equality" data-x-href="https://tc39.es/ecma262/#sec-islooselyequal">IsLooselyEqual</dfn> abstract operation</li>
<li>The <dfn data-x="js-strict-equality" data-x-href="https://tc39.es/ecma262/#sec-isstrictlyequal">IsStrictlyEqual</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-atomics-object"><code>Atomics</code></dfn> object</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-atomics.waitasync"><code>Atomics.waitAsync</code></dfn> object</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-date-objects"><code>Date</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-finalization-registry-objects"><code>FinalizationRegistry</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-regexp-regular-expression-objects"><code>RegExp</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-sharedarraybuffer-objects"><code>SharedArrayBuffer</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-syntaxerror"><code>SyntaxError</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-typeerror"><code>TypeError</code></dfn> class</li>
<li>The <dfn data-x="js-RangeError" data-x-href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-rangeerror"><code>RangeError</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-weak-ref-objects"><code>WeakRef</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-eval-x"><code>eval()</code></dfn> function</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-weak-ref.prototype.deref"><code>WeakRef.prototype.deref()</code></dfn> function</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-IsHTMLDDA-internal-slot">[[IsHTMLDDA]]</dfn> internal slot</li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-import-calls"><code>import()</code></dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-meta-properties"><code>import.meta</code></dfn></li>
<li>The <dfn data-x="js-HostGetImportMetaProperties" data-x-href="https://tc39.es/ecma262/#sec-hostgetimportmetaproperties">HostGetImportMetaProperties</dfn> abstract operation</li>
<li>The <dfn data-x="js-typeof" data-x-href="https://tc39.es/ecma262/#sec-typeof-operator"><code>typeof</code></dfn> operator</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-delete-operator"><code>delete</code></dfn> operator</li>
<li><dfn data-x-href="https://tc39.es/ecma262/#table-49">The <var>TypedArray</var> Constructors</dfn> table</li>
</ul>
<p>Users agents that support JavaScript must also implement the <cite>Dynamic Code Brand
Checks</cite> proposal. The following terms are defined there, and used in this specification:
<ref>JSDYNAMICCODEBRANDCHECKS</ref></p>
<ul class="brief">
<li>The <dfn data-x="js-HostEnsureCanCompileStrings" data-x-href="https://tc39.es/proposal-dynamic-code-brand-checks/#sec-hostensurecancompilestrings">HostEnsureCanCompileStrings</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostGetCodeForEval" data-x-href="https://tc39.es/proposal-dynamic-code-brand-checks/#sec-hostgetcodeforeval">HostGetCodeForEval</dfn> abstract operation</li>
</ul>
<p>Users agents that support JavaScript must also implement <cite>ECMAScript
Internationalization API</cite>. <ref>JSINTL</ref></p>
<p>User agents that support JavaScript must also implement the <cite>Temporal</cite> proposal.
The following terms are defined there, and used in this specification: <ref>JSTEMPORAL</ref></p>
<ul class="brief">
<li>The <dfn data-x="js-HostSystemUTCEpochNanoseconds" data-x-href="https://tc39.es/proposal-temporal/#sec-hostsystemutcepochnanoseconds">HostSystemUTCEpochNanoseconds</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/proposal-temporal/#eqn-nsMaxInstant">nsMaxInstant</dfn> and
<dfn data-x-href="https://tc39.es/proposal-temporal/#eqn-nsMinInstant">nsMinInstant</dfn> values</li>
</ul>
</dd>
<dt>WebAssembly</dt>
<dd>
<p>The following term is defined in <cite>WebAssembly JavaScript Interface</cite>:
<ref>WASMJS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://webassembly.github.io/spec/js-api/#module"><code>WebAssembly.Module</code></dfn></li>
</ul>
</dd>
<dt>DOM</dt>
<dd>
<p>The Document Object Model (DOM) is a representation — a model — of a document and
its content. The DOM is not just an API; the conformance criteria of HTML implementations are
defined, in this specification, in terms of operations on the DOM. <ref>DOM</ref></p>
<p>Implementations must support DOM and the events defined in UI Events, because this
specification is defined in terms of the DOM, and some of the features are defined as extensions
to the DOM interfaces. <ref>DOM</ref> <ref>UIEVENTS</ref></p>
<p>In particular, the following features are defined in <cite>DOM</cite>: <ref>DOM</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-attr"><code>Attr</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-characterdata"><code>CharacterData</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-comment"><code>Comment</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-domimplementation"><code>DOMImplementation</code></dfn> interface</li>
<li><dfn data-x="DOM Document" data-x-href="https://dom.spec.whatwg.org/#interface-document"><code>Document</code></dfn> interface and its
<dfn data-x="dom-Document-doctype" data-x-href="https://dom.spec.whatwg.org/#dom-document-doctype"><code>doctype</code></dfn> attribute
</li>
<li><dfn data-x="DOM DocumentOrShadowRoot" data-x-href="https://dom.spec.whatwg.org/#documentorshadowroot"><code>DocumentOrShadowRoot</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-documentfragment"><code>DocumentFragment</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-documenttype"><code>DocumentType</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-childnode"><code>ChildNode</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-element"><code>Element</code></dfn> interface</li>
<li><dfn data-x="dom-Element-attachShadow" data-x-href="https://dom.spec.whatwg.org/#dom-element-attachshadow"><code>attachShadow()</code></dfn> method.</li>
<li>An element's <dfn data-x="concept-element-shadow-root" data-x-href="https://dom.spec.whatwg.org/#concept-element-shadow-root">shadow root</dfn></li>
<li>A <span data-x="concept-element-shadow-root">shadow root</span>'s <dfn data-x="concept-shadow-root-mode" data-x-href="https://dom.spec.whatwg.org/#shadowroot-mode">mode</dfn></li>
<li>A <span data-x="concept-element-shadow-root">shadow root</span>'s <dfn data-x="concept-shadow-root-declarative" data-x-href="https://dom.spec.whatwg.org/#shadowroot-declarative">declarative</dfn> member</li>
<li>The <dfn data-x="concept-attach-a-shadow-root" data-x-href="https://dom.spec.whatwg.org/#concept-attach-a-shadow-root">attach a shadow root</dfn> algorithm</li>
<li>The <dfn data-x="dom-retarget" data-x-href="https://dom.spec.whatwg.org/#retarget">retargeting algorithm</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-node"><code>Node</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-nodelist"><code>NodeList</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-processinginstruction"><code>ProcessingInstruction</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-shadowroot"><code>ShadowRoot</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-text"><code>Text</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-range"><code>Range</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-document">node document</dfn> concept</li>
<li><dfn data-x="concept-document-type" data-x-href="https://dom.spec.whatwg.org/#concept-document-type">document type</dfn> concept</li>
<li><dfn data-x="concept-DocumentFragment-host" data-x-href="https://dom.spec.whatwg.org/#concept-documentfragment-host">host</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-root">shadow root</dfn> concept, and its <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-delegates-focus">delegates focus</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-available-to-element-internals">available to element internals</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-clonable">clonable</dfn>, and <dfn data-x="shadow-serializable" data-x-href="https://dom.spec.whatwg.org/#shadowroot-serializable">serializable</dfn>.</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#element-shadow-host">shadow host</dfn> concept</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-htmlcollection"><code>HTMLCollection</code></dfn> interface, its
<dfn data-x="dom-HTMLCollection-length" data-x-href="https://dom.spec.whatwg.org/#dom-htmlcollection-length"><code>length</code></dfn> attribute, and its
<dfn data-x="dom-HTMLCollection-item" data-x-href="https://dom.spec.whatwg.org/#dom-htmlcollection-item"><code>item()</code></dfn> and
<dfn data-x="dom-HTMLCollection-namedItem" data-x-href="https://dom.spec.whatwg.org/#dom-htmlcollection-nameditem"><code>namedItem()</code></dfn> methods</li>
<li>The terms <dfn data-x="concept-collection" data-x-href="https://dom.spec.whatwg.org/#concept-collection">collection</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#represented-by-the-collection">represented by the collection</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-domtokenlist"><code>DOMTokenList</code></dfn> interface, and its
<dfn data-x="dom-DOMTokenList-value" data-x-href="https://dom.spec.whatwg.org/#dom-domtokenlist-value"><code>value</code></dfn> attribute and
<dfn data-x="dom-DOMTokenList-supports" data-x-href="https://dom.spec.whatwg.org/#dom-domtokenlist-supports"><code>supports</code></dfn> operation</li>
<li><dfn data-x="dom-DOMImplementation-createDocument" data-x-href="https://dom.spec.whatwg.org/#dom-domimplementation-createdocument"><code>createDocument()</code></dfn> method</li>
<li><dfn data-x="dom-DOMImplementation-createHTMLDocument" data-x-href="https://dom.spec.whatwg.org/#dom-domimplementation-createhtmldocument"><code>createHTMLDocument()</code></dfn> method</li>
<li><dfn data-x="dom-Document-createElement" data-x-href="https://dom.spec.whatwg.org/#dom-document-createelement"><code>createElement()</code></dfn> method</li>
<li><dfn data-x="dom-Document-createElementNS" data-x-href="https://dom.spec.whatwg.org/#dom-document-createelementns"><code>createElementNS()</code></dfn> method</li>
<li><dfn data-x="dom-Document-getElementById" data-x-href="https://dom.spec.whatwg.org/#dom-nonelementparentnode-getelementbyid"><code>getElementById()</code></dfn> method</li>
<li><dfn data-x="dom-document-getElementsByClassName" data-x-href="https://dom.spec.whatwg.org/#dom-document-getelementsbyclassname"><code>getElementsByClassName()</code></dfn> method</li>
<li><dfn data-x="dom-Node-append" data-x-href="https://dom.spec.whatwg.org/#dom-node-append"><code>append()</code></dfn> method</li>
<li><dfn data-x="dom-Node-appendChild" data-x-href="https://dom.spec.whatwg.org/#dom-node-appendchild"><code>appendChild()</code></dfn> method</li>
<li><dfn data-x="dom-Node-cloneNode" data-x-href="https://dom.spec.whatwg.org/#dom-node-clonenode"><code>cloneNode()</code></dfn> method</li>
<li><dfn data-x="dom-ParentNode-moveBefore" data-x-href="https://dom.spec.whatwg.org/#dom-parentnode-movebefore"><code>moveBefore()</code></dfn> method</li>
<li><dfn data-x="dom-Document-importNode" data-x-href="https://dom.spec.whatwg.org/#dom-document-importnode"><code>importNode()</code></dfn> method</li>
<li><dfn data-x="dom-Event-preventDefault" data-x-href="https://dom.spec.whatwg.org/#dom-event-preventdefault"><code>preventDefault()</code></dfn> method</li>
<li><dfn data-x="dom-Element-id" data-x-href="https://dom.spec.whatwg.org/#dom-element-id"><code>id</code></dfn> attribute</li>
<li><dfn data-x="dom-Element-setAttribute" data-x-href="https://dom.spec.whatwg.org/#dom-element-setattribute"><code>setAttribute()</code></dfn> method</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#dom-node-textcontent"><code>textContent</code></dfn> attribute</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree">tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-tree">shadow tree</dfn>, and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-tree">node tree</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-order">tree order</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-tree-order">shadow-including tree order</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-element" data-x="concept-element">element</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-child" data-x="concept-tree-child">child</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-root">root</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-root">shadow-including root</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</dfn>,
<dfn data-x="concept-shadow-including-ancestor" data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-ancestor">shadow-including ancestor</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-descendant">shadow-including descendant</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-inclusive-descendant">shadow-including inclusive descendant</dfn>, and
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-inclusive-ancestor">shadow-including inclusive ancestor</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-first-child">first child</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-next-sibling">next sibling</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-previous-sibling">previous sibling</dfn>, and
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-parent">parent</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#parent-element">parent element</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#document-element">document element</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document">in a document</dfn> (legacy), and <dfn data-x-href="https://dom.spec.whatwg.org/#connected">connected</dfn> concepts</li>
<li>The <dfn data-x="concept-slot" data-x-href="https://dom.spec.whatwg.org/#concept-slot">slot</dfn> concept, and its <dfn data-x="slot-name" data-x-href="https://dom.spec.whatwg.org/#slot-name">name</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#slot-assigned-nodes">assigned nodes</dfn></li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slotable-assigned-slot">assigned slot</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#dom-shadowroot-slot-assignment">slot assignment</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-slotable">slottable</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#assign-slotables-for-a-tree">assign slottables for a tree</dfn> algorithm</li>
<li>The <dfn data-x="event-slotchange" data-x-href="https://dom.spec.whatwg.org/#eventdef-htmlslotelement-slotchange"><code>slotchange</code></dfn> event</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-descendant">inclusive descendant</dfn> concept</li>
<li>The <dfn data-x="finding flattened slottables" data-x-href="https://dom.spec.whatwg.org/#find-flattened-slotables">find flattened slottables</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slottable-manual-slot-assignment">manual slot assignment</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#assign-a-slot">assign a slot</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-x="concept-node-replace-all" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace-all">replace all</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#string-replace-all">string replace all</dfn>, <dfn data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-x="concept-tree-descendant" data-x-href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</dfn> concept</li>
<li>The <dfn data-x="concept-node-insert-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert-ext">insertion steps</dfn>,
<li>The <dfn data-x="concept-node-post-connection-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-post-connection-ext">post-connection steps</dfn>,
<dfn data-x="concept-node-remove-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove-ext">removing steps</dfn>,
<dfn data-x="concept-node-move-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-move-ext">moving steps</dfn>,
<dfn data-x="concept-node-adopt-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt-ext">adopting steps</dfn>, and
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-children-changed-ext">children changed steps</dfn> hooks for elements</li>
<li>The <dfn data-x="concept-element-attributes-change" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-change">change</dfn>, <dfn data-x="concept-element-attributes-append" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-append">append</dfn>, <dfn data-x="concept-element-attributes-remove" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-remove">remove</dfn>, <dfn data-x="concept-element-attributes-replace" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-replace">replace</dfn>, <dfn data-x="concept-element-attributes-get-by-namespace" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-get-by-namespace">get an attribute by namespace and local name</dfn>, <dfn data-x="concept-element-attributes-set-value" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-set-value">set value</dfn>, and <dfn data-x="concept-element-attributes-remove-by-namespace" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-remove-by-namespace">remove an attribute by namespace and local name</dfn> algorithms for attributes</li>
<li>The <dfn data-x="concept-element-attributes-change-ext" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-change-ext">attribute change steps</dfn> hook for attributes</li>
<li>The <dfn data-x="concept-attribute-value" data-x-href="https://dom.spec.whatwg.org/#concept-attribute-value">value</dfn> concept for attributes</li>
<li>The <dfn data-x="concept-attribute-local-name" data-x-href="https://dom.spec.whatwg.org/#concept-attribute-local-name">local name</dfn> concept for attributes</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-element-attribute">attribute list</dfn> concept</li>
<li>The <dfn data-x="concept-cd-data" data-x-href="https://dom.spec.whatwg.org/#concept-cd-data">data</dfn> of a <code>CharacterData</code> node and its
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-cd-replace">replace data</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-child-text-content">child text content</dfn> of a node</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-descendant-text-content">descendant text content</dfn> of a node</li>
<li>The <dfn data-x="concept-doctype-name" data-x-href="https://dom.spec.whatwg.org/#concept-doctype-name">name</dfn>,
<dfn data-x="concept-doctype-publicid" data-x-href="https://dom.spec.whatwg.org/#concept-doctype-publicid">public ID</dfn>, and
<dfn data-x="concept-doctype-systemid" data-x-href="https://dom.spec.whatwg.org/#concept-doctype-systemid">system ID</dfn> of a doctype</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-event"><code>Event</code></dfn> interface</li>
<li><dfn data-x="dom-Event-constructor" data-x-href="https://dom.spec.whatwg.org/#concept-event-constructor"><code>Event</code> and derived interfaces constructor behavior</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-eventtarget"><code>EventTarget</code></dfn> interface</li>
<li>The <!--en-GB--><dfn id="activation-behaviour" data-x-href="https://dom.spec.whatwg.org/#eventtarget-activation-behavior">activation behavior</dfn> hook</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#eventtarget-legacy-pre-activation-behavior">legacy-pre-activation behavior</dfn> hook</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#eventtarget-legacy-canceled-activation-behavior">legacy-canceled-activation behavior</dfn> hook</li>
<li>The <dfn data-x="creating an event" data-x-href="https://dom.spec.whatwg.org/#concept-event-create">create an event</dfn> algorithm</li>
<li>The <dfn data-x="concept-event-fire" data-x-href="https://dom.spec.whatwg.org/#concept-event-fire">fire an event</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#canceled-flag">canceled flag</dfn></li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#dispatch-flag">dispatch flag</dfn></li>
<li>The <dfn data-x="concept-event-dispatch" data-x-href="https://dom.spec.whatwg.org/#concept-event-dispatch">dispatch</dfn> algorithm</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#dictdef-eventinit"><code>EventInit</code></dfn> dictionary type</li>
<li><dfn data-x="dom-Event-type" data-x-href="https://dom.spec.whatwg.org/#dom-event-type"><code>type</code></dfn> attribute</li>
<li>An event's <dfn data-x="concept-event-target" data-x-href="https://dom.spec.whatwg.org/#concept-event-target">target</dfn></li>
<li><dfn data-x="dom-Event-currentTarget" data-x-href="https://dom.spec.whatwg.org/#dom-event-currenttarget"><code>currentTarget</code></dfn> attribute</li>
<li><dfn data-x="dom-Event-bubbles" data-x-href="https://dom.spec.whatwg.org/#dom-event-bubbles"><code>bubbles</code></dfn> attribute</li>
<li><dfn data-x="dom-Event-cancelable" data-x-href="https://dom.spec.whatwg.org/#dom-event-cancelable"><code>cancelable</code></dfn> attribute</li>
<li><dfn data-x="dom-Event-composed" data-x-href="https://dom.spec.whatwg.org/#dom-event-composed"><code>composed</code></dfn> attribute</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#composed-flag">composed flag</dfn></li>
<li><dfn data-x="dom-Event-isTrusted" data-x-href="https://dom.spec.whatwg.org/#dom-event-istrusted"><code>isTrusted</code></dfn> attribute</li>
<li><dfn data-x="dom-Event-initEvent" data-x-href="https://dom.spec.whatwg.org/#dom-event-initevent"><code>initEvent()</code></dfn> method</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#add-an-event-listener">add an event listener</dfn></li>
<li><dfn data-x="dom-EventTarget-addEventListener" data-x-href="https://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener"><code>addEventListener()</code></dfn> method</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#remove-an-event-listener">remove an event listener</dfn> and
<dfn data-x-href="https://dom.spec.whatwg.org/#remove-all-event-listeners">remove all event listeners</dfn> algorithms</li>
<li><dfn data-x="dom-EventListener" data-x-href="https://dom.spec.whatwg.org/#callbackdef-eventlistener"><code>EventListener</code></dfn> callback interface</li>
<li>The <dfn data-x="concept-event-type" data-x-href="https://dom.spec.whatwg.org/#dom-event-type">type</dfn> of an event</li>
<li>An <dfn data-x-href="https://dom.spec.whatwg.org/#concept-event-listener">event listener</dfn> and its
<dfn data-x="event listener type" data-x-href="https://dom.spec.whatwg.org/#event-listener-type">type</dfn> and
<dfn data-x="event listener callback" data-x-href="https://dom.spec.whatwg.org/#event-listener-callback">callback</dfn></li>
<li>The <dfn data-x="document's character encoding" data-x-href="https://dom.spec.whatwg.org/#concept-document-encoding">encoding</dfn> (herein the <i>character encoding</i>),
<dfn data-x="concept-document-mode" data-x-href="https://dom.spec.whatwg.org/#concept-document-mode">mode</dfn>,
<dfn data-x="concept-document-allow-declarative-shadow-roots" data-x-href="https://dom.spec.whatwg.org/#concept-document-allow-declarative-shadow-roots">allow declarative shadow roots</dfn>, and
<dfn data-x="concept-document-content-type" data-x-href="https://dom.spec.whatwg.org/#concept-document-content-type">content type</dfn> of a <code>Document</code></li>
<li>The distinction between <dfn data-x-href="https://dom.spec.whatwg.org/#xml-document">XML documents</dfn> and
<dfn data-x-href="https://dom.spec.whatwg.org/#html-document">HTML documents</dfn></li>
<li>The terms <dfn data-x-href="https://dom.spec.whatwg.org/#concept-document-quirks">quirks mode</dfn>,
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-document-limited-quirks">limited-quirks mode</dfn>, and
<dfn data-x-href="https://dom.spec.whatwg.org/#concept-document-no-quirks">no-quirks mode</dfn></li>
<li>The algorithm <dfn data-x="concept-node-clone" data-x-href="https://dom.spec.whatwg.org/#concept-node-clone">clone a node</dfn> with its arguments
<dfn data-x="concept-node-clone-document" data-x-href="https://dom.spec.whatwg.org/#clone-a-node-document"><var>document</var></dfn>,
<dfn data-x="concept-node-clone-subtree" data-x-href="https://dom.spec.whatwg.org/#clone-a-node-subtree"><var>subtree</var></dfn>, and
<dfn data-x="concept-node-clone-parent" data-x-href="https://dom.spec.whatwg.org/#clone-a-node-parent"><var>parent</var></dfn>, and the concept of
<dfn data-x="concept-node-clone-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-clone-ext">cloning steps</dfn></li>
<li>The concept of <dfn>base URL change steps</dfn> and the definition of what happens when an element is <dfn>affected by a base URL change</dfn></li>
<li>The concept of an element's <dfn data-x="concept-id" data-x-href="https://dom.spec.whatwg.org/#concept-id">unique identifier (ID)</dfn></li>
<li>The concept of an element's <dfn data-x="concept-class" data-x-href="https://dom.spec.whatwg.org/#concept-class">classes</dfn></li>
<li>The term <dfn data-x="concept-supported-tokens" data-x-href="https://dom.spec.whatwg.org/#concept-supported-tokens">supported tokens</dfn></li>
<li>The concept of a DOM <dfn data-x="concept-range" data-x-href="https://dom.spec.whatwg.org/#concept-range">range</dfn>, and the terms
<dfn data-x="concept-range-start-node" data-x-href="https://dom.spec.whatwg.org/#concept-range-start-node">start node</dfn>,
<dfn data-x="concept-range-start" data-x-href="https://dom.spec.whatwg.org/#concept-range-start">start</dfn>,
<dfn data-x="concept-range-end" data-x-href="https://dom.spec.whatwg.org/#concept-range-end">end</dfn>, and
<dfn data-x="concept-range-bp" data-x-href="https://dom.spec.whatwg.org/#concept-range-bp">boundary point</dfn> as applied to ranges.</li>
<li>The <dfn data-x="create an element" data-x-href="https://dom.spec.whatwg.org/#concept-create-element">create an element</dfn> algorithm</li>
<li>The <dfn data-x="element interface" data-x-href="https://dom.spec.whatwg.org/#concept-element-interface">element interface</dfn> concept</li>
<li>The concepts of <dfn data-x-href="https://dom.spec.whatwg.org/#concept-element-custom-element-state">custom element state</dfn>, and of
<dfn data-x="concept-element-defined" data-x-href="https://dom.spec.whatwg.org/#concept-element-defined">defined</dfn> and
<dfn data-x="concept-element-custom" data-x-href="https://dom.spec.whatwg.org/#concept-element-custom">custom</dfn> elements</li>
<li>An element's <dfn data-x="concept-element-namespace" data-x-href="https://dom.spec.whatwg.org/#concept-element-namespace">namespace</dfn>,
<dfn data-x="concept-element-namespace-prefix" data-x-href="https://dom.spec.whatwg.org/#concept-element-namespace-prefix">namespace prefix</dfn>,
<dfn data-x="concept-element-local-name" data-x-href="https://dom.spec.whatwg.org/#concept-element-local-name">local name</dfn>,
<dfn data-x="concept-element-custom-element-definition" data-x-href="https://dom.spec.whatwg.org/#concept-element-custom-element-definition">custom element definition</dfn>, and
<dfn data-x="concept-element-is-value" data-x-href="https://dom.spec.whatwg.org/#concept-element-is-value"><code data-x="">is</code> value</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#mutationobserver"><code>MutationObserver</code></dfn> interface and <dfn data-x-href="https://dom.spec.whatwg.org/#mutation-observers">mutation observers</dfn> in general</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortcontroller"><code>AbortController</code></dfn> and its
<dfn data-x="concept-AbortController-signal" data-x-href="https://dom.spec.whatwg.org/#abortcontroller-signal">signal</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortsignal"><code>AbortSignal</code></dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortsignal-aborted" data-x="AbortSignal-aborted">aborted</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortcontroller-signal-abort">signal abort</dfn></li>
<li><dfn data-x="AbortSignal-add" data-x-href="https://dom.spec.whatwg.org/#abortsignal-add">add</dfn></li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-get-by-name">get an attribute by name</dfn> algorithm</li>
</ul>
<p>The following features are defined in <cite>UI Events</cite>: <ref>UIEVENTS</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://w3c.github.io/uievents/#mouseevent"><code>MouseEvent</code></dfn> interface</li>
<li>The <code>MouseEvent</code> interface's <dfn data-x="dom-MouseEvent-relatedTarget" data-x-href="https://w3c.github.io/uievents/#dom-mouseevent-relatedtarget"><code>relatedTarget</code></dfn> attribute</li>
<li><dfn data-x-href="https://w3c.github.io/uievents/#dictdef-mouseeventinit"><code>MouseEventInit</code></dfn> dictionary type</li>
<li>The <dfn data-x-href="https://w3c.github.io/uievents/#focusevent"><code>FocusEvent</code></dfn> interface</li>
<li>The <code>FocusEvent</code> interface's <dfn data-x="dom-FocusEvent-relatedTarget" data-x-href="https://w3c.github.io/uievents/#dom-focusevent-relatedtarget"><code>relatedTarget</code></dfn> attribute</li>
<li>The <dfn data-x-href="https://w3c.github.io/uievents/#uievent"><code>UIEvent</code></dfn> interface</li>
<li>The <code>UIEvent</code> interface's <dfn data-x="dom-UIEvent-view" data-x-href="https://w3c.github.io/uievents/#dom-uievent-view"><code>view</code></dfn> attribute</li>
<li><dfn data-x="event-auxclick" data-x-href="https://w3c.github.io/uievents/#event-type-auxclick"><code>auxclick</code></dfn> event</li>
<li><dfn data-x="event-beforeinput" data-x-href="https://w3c.github.io/uievents/#event-type-beforeinput"><code>beforeinput</code></dfn> event</li>
<li><dfn data-x="event-click" data-x-href="https://w3c.github.io/uievents/#event-type-click"><code>click</code></dfn> event</li>
<li><dfn data-x="event-contextmenu" data-x-href="https://w3c.github.io/uievents/#event-type-contextmenu"><code>contextmenu</code></dfn> event</li>
<li><dfn data-x="event-dblclick" data-x-href="https://w3c.github.io/uievents/#event-type-dblclick"><code>dblclick</code></dfn> event</li>
<li><dfn data-x="event-input" data-x-href="https://w3c.github.io/uievents/#event-type-input"><code>input</code></dfn> event</li>
<li><dfn data-x="event-mousedown" data-x-href="https://w3c.github.io/uievents/#event-type-mousedown"><code>mousedown</code></dfn> event</li>
<li><dfn data-x="event-mouseenter" data-x-href="https://w3c.github.io/uievents/#event-type-mouseenter"><code>mouseenter</code></dfn> event</li>
<li><dfn data-x="event-mouseleave" data-x-href="https://w3c.github.io/uievents/#event-type-mouseleave"><code>mouseleave</code></dfn> event</li>
<li><dfn data-x="event-mousemove" data-x-href="https://w3c.github.io/uievents/#event-type-mousemove"><code>mousemove</code></dfn> event</li>
<li><dfn data-x="event-mouseout" data-x-href="https://w3c.github.io/uievents/#event-type-mouseout"><code>mouseout</code></dfn> event</li>
<li><dfn data-x="event-mouseover" data-x-href="https://w3c.github.io/uievents/#event-type-mouseover"><code>mouseover</code></dfn> event</li>
<li><dfn data-x="event-mouseup" data-x-href="https://w3c.github.io/uievents/#event-type-mouseup"><code>mouseup</code></dfn> event</li>
<li><dfn data-x="event-wheel" data-x-href="https://w3c.github.io/uievents/#event-type-wheel"><code>wheel</code></dfn> event</li>
<li><dfn data-x="event-keydown" data-x-href="https://w3c.github.io/uievents/#event-type-keydown"><code>keydown</code></dfn> event</li>
<li><dfn data-x="event-keypress" data-x-href="https://w3c.github.io/uievents/#event-type-keypress"><code>keypress</code></dfn> event</li>
<li><dfn data-x="event-keyup" data-x-href="https://w3c.github.io/uievents/#event-type-keyup"><code>keyup</code></dfn> event</li>
</ul>
<p>The following features are defined in <cite>Touch Events</cite>: <ref>TOUCH</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/touch-events/#touch-interface"><code>Touch</code></dfn> interface</li>
<li><dfn data-x-href="https://w3c.github.io/touch-events/#dfn-touch-point">Touch point</dfn> concept</li>
<li><dfn data-x="event-touchend" data-x-href="https://w3c.github.io/touch-events/#event-touchend"><code>touchend</code></dfn> event</li>
</ul>
<p>The following features are defined in <cite>Pointer Events</cite>:
<ref>POINTEREVENTS</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://w3c.github.io/pointerevents/#pointerevent-interface"><code>PointerEvent</code></dfn> interface</li>
<li>The <code>PointerEvent</code> interface's <dfn data-x-href="https://w3c.github.io/pointerevents/#dom-pointerevent-pointertype"><code>pointerType</code></dfn> attribute</li>
<li><dfn data-x-href="https://w3c.github.io/pointerevents/#dfn-fire-a-pointer-event">fire a pointer event</dfn></li>
<li><dfn data-x="event-pointerdown" data-x-href="https://w3c.github.io/pointerevents/#the-pointerdown-event"><code>pointerdown</code></dfn> event</li>
<li><dfn data-x="event-pointerup" data-x-href="https://w3c.github.io/pointerevents/#the-pointerup-event"><code>pointerup</code></dfn> event</li>
<li><dfn data-x="event-pointercancel" data-x-href="https://w3c.github.io/pointerevents/#the-pointercancel-event"><code>pointercancel</code></dfn> event</li>
</ul>
<p>The following events are defined in <cite>Clipboard API and events</cite>:
<ref>CLIPBOARD-APIS</ref></p>
<ul class="brief">
<li><dfn data-x="event-copy" data-x-href="https://w3c.github.io/clipboard-apis/#clipboard-event-copy"><code>copy</code></dfn> event</li>
<li><dfn data-x="event-cut" data-x-href="https://w3c.github.io/clipboard-apis/#clipboard-event-cut"><code>cut</code></dfn> event</li>
<li><dfn data-x="event-paste" data-x-href="https://w3c.github.io/clipboard-apis/#clipboard-event-paste"><code>paste</code></dfn> event</li>
</ul>
<p>This specification sometimes uses the term <dfn data-x="">name</dfn> to refer to the event's
<span data-x="concept-event-type">type</span>; as in, "an event named <code
data-x="">click</code>" or "if the event name is <code data-x="">keypress</code>". The terms
"name" and "type" for events are synonymous.</p>
<p>The following features are defined in <cite>DOM Parsing and Serialization</cite>:
<ref>DOMPARSING</ref></p>
<ul class="brief">
<li><dfn data-x="xml-serialization" data-x-href="https://w3c.github.io/DOM-Parsing/#dfn-xml-serialization"><code>XML serialization</code></dfn></li>
</ul>
<p>The following features are defined in <cite>Selection API</cite>: <ref>SELECTION</ref></p>
<ul class="brief">
<li><dfn data-x="document-selection" data-x-href="https://w3c.github.io/selection-api/#dfn-selection">selection</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/selection-api/#selection-interface"><code>Selection</code></dfn></li>
</ul>
<p class="note">User agents are encouraged to implement the features described in
<cite>execCommand</cite>. <ref>EXECCOMMAND</ref></p>
<p>The following features are defined in <cite>Fullscreen API</cite>: <ref>FULLSCREEN</ref></p>
<ul class="brief">
<li><dfn data-x="dom-element-requestFullscreen" data-x-href="https://fullscreen.spec.whatwg.org/#dom-element-requestfullscreen"><code>requestFullscreen()</code></dfn></li>
<li><dfn data-x="event-fullscreenchange" data-x-href="https://fullscreen.spec.whatwg.org/#eventdef-document-fullscreenchange"><code>fullscreenchange</code></dfn></li>
<li><dfn data-x-href="https://fullscreen.spec.whatwg.org/#run-the-fullscreen-steps">run the fullscreen steps</dfn></li>
<li><dfn data-x-href="https://fullscreen.spec.whatwg.org/#fully-exit-fullscreen">fully exit fullscreen</dfn></li>
<li><dfn data-x-href="https://fullscreen.spec.whatwg.org/#fullscreen-element">fullscreen element</dfn></li>
<li><dfn data-x-href="https://fullscreen.spec.whatwg.org/#fullscreen-flag">fullscreen flag</dfn></li>
</ul>
<p><cite>High Resolution Time</cite> provides the following features: <ref>HRT</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-current-high-resolution-time">current high resolution time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-relative-high-resolution-time">relative high resolution time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-unsafe-shared-current-time">unsafe shared current time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-shared-monotonic-clock">shared monotonic clock</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-unsafe-moment">unsafe moment</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-duration-from">duration from</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-coarsen-time">coarsen time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-current-wall-time">current wall time</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dfn-unix-epoch">Unix epoch</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/hr-time/#dom-domhighrestimestamp"><code>DOMHighResTimeStamp</code></dfn></li>
</ul>
</dd>
<dt>File API</dt>
<dd>
<p>This specification uses the following features defined in <cite>File API</cite>:
<ref>FILEAPI</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://w3c.github.io/FileAPI/#dfn-Blob"><code>Blob</code></dfn> interface and its
<dfn data-x="dom-Blob-type" data-x-href="https://w3c.github.io/FileAPI/#dfn-type"><code>type</code></dfn> attribute</li>
<li>The <dfn data-x-href="https://w3c.github.io/FileAPI/#dfn-file"><code>File</code></dfn> interface and its
<dfn data-x="dom-File-name" data-x-href="https://w3c.github.io/FileAPI/#dfn-name"><code>name</code></dfn> and
<dfn data-x="dom-File-lastModified" data-x-href="https://w3c.github.io/FileAPI/#dfn-lastModified"><code>lastModified</code></dfn> attributes</li>
<li>The <dfn data-x-href="https://w3c.github.io/FileAPI/#filelist-section"><code>FileList</code></dfn> interface</li>
<li>The concept of a <code>Blob</code>'s <dfn data-x-href="https://w3c.github.io/FileAPI/#snapshot-state">snapshot state</dfn></li>
<li>The concept of <dfn data-x="file-error-read">read errors</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/FileAPI/#BlobURLStore">Blob URL Store</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/FileAPI/#blob-url-entry">blob URL entry</dfn> and its
<dfn data-x="blob-url-entry-environment" data-x-href="https://w3c.github.io/FileAPI/#blob-url-entry-environment">environment</dfn></li>
<li>The <dfn data-x="blob-url-obtain-object" data-x-href="https://w3c.github.io/FileAPI/#blob-url-obtain-object">obtain a blob object</dfn> algorithm</li>
</ul>
</dd>
<dt>Indexed Database API</dt>
<dd>
<p>The following terms are defined in <cite>Indexed Database API</cite>:
<ref>INDEXEDDB</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/IndexedDB/#cleanup-indexed-database-transactions">cleanup Indexed Database transactions</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IndexedDB/#idbversionchangeevent"><code>IDBVersionChangeEvent</code></dfn></li>
</ul>
</dd>
<dt>Media Source Extensions</dt>
<dd>
<p>The following terms are defined in <cite>Media Source Extensions</cite>:
<ref>MEDIASOURCE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/media-source/#idl-def-mediasource"><code>MediaSource</code></dfn> interface</li>
<li><dfn data-x-href="https://w3c.github.io/media-source/#mediasource-detach">detaching from a media element</dfn></li>
</ul>
</dd>
<dt>Media Capture and Streams</dt>
<dd>
<p>The following terms are defined in <cite>Media Capture and Streams</cite>:
<ref>MEDIASTREAM</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/mediacapture-main/getusermedia.html#idl-def-mediastream"><code>MediaStream</code></dfn> interface</li>
<li><dfn data-x-href="https://w3c.github.io/mediacapture-main/getusermedia.html#mediastreamtrack"><code>MediaStreamTrack</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/mediacapture-main/getusermedia.html#idl-def-MediaStreamTrackState.live">live state</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/mediacapture-main/getusermedia.html#dom-mediadevices-getusermedia"><code>getUserMedia()</code></dfn></li>
</ul>
</dd>
<dt>Reporting</dt>
<dd>
<p>The following terms are defined in <cite>Reporting</cite>: <ref>REPORTING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/reporting/#queue-report">Queue a report</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/reporting/#report-type">report type</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/reporting/#visible-to-reportingobservers">visible to <code>ReportingObserver</code>s</dfn></li>
</ul>
</dd>
<dt>XMLHttpRequest</dt>
<dd>
<p>The following features and terms are defined in <cite>XMLHttpRequest</cite>:
<ref>XHR</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://xhr.spec.whatwg.org/#xmlhttprequest"><code>XMLHttpRequest</code></dfn> interface, and its
<dfn data-x="dom-XMLHttpRequest-responseXML" data-x-href="https://xhr.spec.whatwg.org/#dom-xmlhttprequest-responsexml"><code>responseXML</code></dfn> attribute</li>
<li>The <dfn data-x-href="https://xhr.spec.whatwg.org/#interface-progressevent"><code>ProgressEvent</code></dfn> interface, and its
<dfn data-x="dom-ProgressEvent-lengthComputable" data-x-href="https://xhr.spec.whatwg.org/#dom-progressevent-lengthcomputable"><code>lengthComputable</code></dfn>,
<dfn data-x="dom-ProgressEvent-loaded" data-x-href="https://xhr.spec.whatwg.org/#dom-progressevent-loaded"><code>loaded</code></dfn>, and
<dfn data-x="dom-ProgressEvent-total" data-x-href="https://xhr.spec.whatwg.org/#dom-progressevent-total"><code>total</code></dfn> attributes</li>
<li>The <dfn data-x-href="https://xhr.spec.whatwg.org/#formdata"><code>FormData</code></dfn> interface, and its associated
<dfn data-x="FormData entry list" data-x-href="https://xhr.spec.whatwg.org/#concept-formdata-entry-list">entry list</dfn></li>
</ul>
</dd>
<dt>Battery Status</dt>
<dd>
<p>The following features are defined in <cite>Battery Status API</cite>: <ref>BATTERY</ref></p>
<ul class="brief">
<li><dfn data-x="dom-navigator-getBattery" data-x-href="https://w3c.github.io/battery/#widl-Navigator-getBattery-Promise-BatteryManager"><code>getBattery()</code></dfn> method</li>
</ul>
</dd>
<dt>Media Queries</dt>
<dd>
<p>Implementations must support <cite>Media Queries</cite>. The <dfn
data-x-href="https://drafts.csswg.org/mediaqueries/#typedef-media-condition"><media-condition></dfn>
feature is defined therein. <ref>MQ</ref></p>
</dd>
<dt>CSS modules</dt>
<dd>
<p>While support for CSS as a whole is not required of implementations of this specification
(though it is encouraged, at least for web browsers), some features are defined in terms of
specific CSS requirements.</p>
<p>When this specification requires that something be <dfn data-x="parse something according to
a CSS grammar" data-x-href="https://drafts.csswg.org/css-syntax/#parse-grammar">parsed according
to a particular CSS grammar</dfn>, the relevant algorithm in <cite>CSS Syntax</cite> must be
followed, including error handling rules. <ref>CSSSYNTAX</ref></p>
<p class="example">For example, user agents are required to close all open constructs upon
finding the end of a style sheet unexpectedly. Thus, when parsing the string "<code
data-x="">rgb(0,0,0</code>" (with a missing close-parenthesis) for a color value, the close
parenthesis is implied by this error handling rule, and a value is obtained (the color 'black').
However, the similar construct "<code data-x="">rgb(0,0,</code>" (with both a missing
parenthesis and a missing "blue" value) cannot be parsed, as closing the open construct does not
result in a viable value.</p>
<p>The following terms and features are defined in <cite>Cascading Style Sheets</cite>
(<cite>CSS</cite>): <ref>CSS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css2/#viewport">viewport</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#line-box">line box</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#out-of-flow">out-of-flow</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#in-flow">in-flow</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#collapsing-margins">collapsing margins</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#containing-block-details">containing block</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#inline-box">inline box</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css2/#block-boxes%E2%91%A0">block box</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#propdef-top">'top'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css2/#propdef-bottom">'bottom'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css2/#propdef-left">'left'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css2/#propdef-right">'right'</dfn> properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#float-position">'float'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#flow-control">'clear'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#the-width-property">'width'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#the-height-property">'height'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#min-max-widths">'min-width'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#min-max-heights">'min-height'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#min-max-widths">'max-width'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#min-max-heights">'max-height'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#propdef-line-height">'line-height'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#propdef-vertical-align">'vertical-align'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#content%E2%91%A0">'content'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#value-def-inline-block">'inline-block'</dfn> value of the <span>'display'</span> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css2/#propdef-visibility">'visibility'</dfn> property</li>
</ul>
<p>The basic version of the <dfn
data-x-href="https://drafts.csswg.org/css2/#display-prop">'display'</dfn> property
is defined in <cite>CSS</cite>, and the property is extended by other CSS modules.
<ref>CSS</ref> <ref>CSSRUBY</ref> <ref>CSSTABLE</ref></p>
<p>The following terms and features are defined in <cite>CSS Box Model</cite>:
<ref>CSSBOX</ref></p>
<ul>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#content-area">content area</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#content-box">content box</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#border-box">border box</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#margin-box">margin box</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#border-edge">border edge</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-box/#margin-edge">margin edge</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-margin-top">'margin-top'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-margin-bottom">'margin-bottom'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-margin-left">'margin-left'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-margin-right">'margin-right'</dfn> properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-padding-top">'padding-top'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-padding-bottom">'padding-bottom'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-padding-left">'padding-left'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-box/#propdef-padding-right">'padding-right'</dfn> properties</li>
</ul>
<p>The following features are defined in <cite>CSS Logical Properties</cite>:
<ref>CSSLOGICAL</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-block">'margin-block'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-block-start">'margin-block-start'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-block-end">'margin-block-end'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-inline">'margin-inline'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-inline-start">'margin-inline-start'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-margin-inline-end">'margin-inline-end'</dfn> properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-block">'padding-block'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-block-start">'padding-block-start'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-block-end">'padding-block-end'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-inline">'padding-inline'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-inline-start">'padding-inline-start'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-padding-inline-end">'padding-inline-end'</dfn> properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-width">'border-block-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-start-width">'border-block-start-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-end-width">'border-block-end-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-width">'border-inline-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-start-width">'border-inline-start-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-end-width">'border-inline-end-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-style">'border-block-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-start-style">'border-block-start-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-end-style">'border-block-end-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-style">'border-inline-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-start-style">'border-inline-start-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-end-style">'border-inline-end-style'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-start-color">'border-block-start-color'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-block-end-color">'border-block-end-color'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-start-color">'border-inline-start-color'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-inline-end-color">'border-inline-end-color'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-start-start-radius">'border-start-start-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-start-end-radius">'border-start-end-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-end-start-radius">'border-end-start-radius'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-border-end-end-radius">'border-end-end-radius'</dfn>
properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-block-size">'block-size'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-inline-size">'inline-size'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-inset-block-start">'inset-block-start'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-logical/#propdef-inset-block-end">'inset-block-end'</dfn> property</li>
</ul>
<p>The following terms and features are defined in <cite>CSS Color</cite>:
<ref>CSSCOLOR</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#named-color">named color</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#typedef-color"><color></dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-color/#the-color-property">'color'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-color/#valdef-color-currentcolor" id="currentcolor">'currentcolor'</dfn> value</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#opaque-black">opaque black</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#transparent-black">transparent black</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#valdef-color-srgb">'srgb'</dfn> color space</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#valdef-color-display-p3">'display-p3'</dfn> color space</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color-5/#valdef-color-profile-rendering-intent-relative-colorimetric">'relative-colorimetric'</dfn> rendering intent</li>
<li><dfn id="parsed-as-a-css-color-value" data-x-href="https://drafts.csswg.org/css-color/#parse-a-css-color-value">parse a CSS <color> value</dfn></li>
<li><!--en-GB--><dfn id="serialisation-of-a-color" data-x-href="https://drafts.csswg.org/css-color/#serializing-color-values">serialize a CSS <color> value</dfn> including <dfn data-x-href="https://drafts.csswg.org/css-color/#color-serialization-html-compatible-serialization-is-requested">HTML-compatible serialization is requested</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color/#color-conversion">Converting Colors</dfn></li>
<li><dfn id="color-function" data-x-href="https://drafts.csswg.org/css-color/#color-function">'color()'</dfn></li>
</ul>
<p>The following terms are defined in <cite>CSS Images</cite>: <ref>CSSIMAGES</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-images/#default-object-size">default object size</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-images/#concrete-object-size">concrete object size</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-images/#natural-dimensions">natural dimensions</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-images/#natural-height">natural height</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-images/#natural-width">natural width</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-images-3/#the-image-orientation">'image-orientation'</dfn> property</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-images-4/#funcdef-conic-gradient">'conic-gradient'</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-images/#the-object-fit">'object-fit'</dfn> property</li>
</ul>
<p>The term <dfn data-x-href="https://drafts.csswg.org/css-images-4/#paint-source">paint
source</dfn> is used as defined in <cite>CSS Images Level 4</cite>
to define the interaction of certain HTML elements with the CSS 'element()' function.
<ref>CSSIMAGES4</ref></p>
<p>The following features are defined in <cite>CSS Backgrounds and Borders</cite>:
<ref>CSSBG</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-color">'background-color'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-image">'background-image'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-repeat">'background-repeat'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-attachment">'background-attachment'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-position">'background-position'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-clip">'background-clip'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-origin">'background-origin'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-background-size">'background-size'</dfn>
properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-radius">'border-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-top-left-radius">'border-top-left-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-top-right-radius">'border-top-right-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-bottom-right-radius">'border-bottom-right-radius'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-bottom-left-radius">'border-bottom-left-radius'</dfn>
properties</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-image-source">'border-image-source'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-image-slice">'border-image-slice'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-image-width">'border-image-width'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-image-outset">'border-image-outset'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-image-repeat">'border-image-repeat'</dfn>
properties</li>
</ul>
<p><cite>CSS Backgrounds and Borders</cite> also defines the following border properties:
<ref>CSSBG</ref></p>
<table>
<caption>Border properties
<tbody>
<tr>
<td>
<th>Top
<th>Bottom
<th>Left
<th>Right
<tr>
<th>Width
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-top-width">'border-top-width'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-bottom-width">'border-bottom-width'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-left-width">'border-left-width'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-right-width">'border-right-width'</dfn>
<tr>
<th>Style
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-top-style">'border-top-style'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-bottom-style">'border-bottom-style'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-left-style">'border-left-style'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-right-style">'border-right-style'</dfn>
<tr>
<th>Color
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-top-color">'border-top-color'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-bottom-color">'border-bottom-color'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-left-color">'border-left-color'</dfn>
<td><dfn data-x-href="https://drafts.csswg.org/css-backgrounds/#propdef-border-right-color">'border-right-color'</dfn>
</table>
<p>The following features are defined in <cite>CSS Box Alignment</cite>: <ref>CSSALIGN</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-align-content">'align-content'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-align-items">'align-items'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-align-self">'align-self'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-justify-self">'justify-self'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-propdef-justify-content">'justify-content'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-align/#propdef-propdef-justify-items">'justify-items'</dfn> property</li>
</ul>
<p>The following terms and features are defined in <cite>CSS Display</cite>:
<ref>CSSDISPLAY</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#outer-display-type">outer display type</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#inner-display-type">inner display type</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#block-level">block-level</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#block-container">block container</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#formatting-context">formatting context</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#block-formatting-context">block formatting context</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#inline-formatting-context">inline formatting context</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#replaced-element">replaced element</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-display/#css-box">CSS box</dfn></li>
</ul>
<p>The following features are defined in <cite>CSS Flexible Box Layout</cite>:
<ref>CSSFLEXBOX</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-flexbox/#propdef-flex-direction">'flex-direction'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-flexbox/#propdef-flex-wrap">'flex-wrap'</dfn> property</li>
</ul>
<p>The following terms and features are defined in <cite>CSS Fonts</cite>:
<ref>CSSFONTS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-fonts/#first-available-font">first available font</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#font-family-prop">'font-family'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#font-weight-prop">'font-weight'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#font-size-prop">'font-size'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#font-prop">'font'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#propdef-font-kerning">'font-kerning'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#propdef-font-stretch">'font-stretch'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#propdef-font-variant-caps">'font-variant-caps'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-small-caps">'small-caps'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-all-small-caps">'all-small-caps'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-petite-caps">'petite-caps'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-all-petite-caps">'all-petite-caps'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-unicase">'unicase'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-variant-caps-titling-caps">'titling-caps'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-ultra-condensed">'ultra-condensed'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-extra-condensed">'extra-condensed'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-condensed">'condensed'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-semi-condensed">'semi-condensed'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-semi-expanded">'semi-expanded'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-expanded">'expanded'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-extra-expanded">'extra-expanded'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-fonts/#valdef-font-stretch-ultra-expanded">'ultra-expanded'</dfn> value</li>
</ul>
<p>The following features are defined in <cite>CSS Grid Layout</cite>: <ref>CSSGRID</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-auto-columns">'grid-auto-columns'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-auto-flow">'grid-auto-flow'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-auto-rows">'grid-auto-rows'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-column-gap">'grid-column-gap'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-row-gap">'grid-row-gap'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-template-areas">'grid-template-areas'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-template-columns">'grid-template-columns'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-grid/#propdef-grid-template-rows">'grid-template-rows'</dfn> property</li>
</ul>
<p>The following terms are defined in <cite>CSS Inline Layout</cite>: <ref>CSSINLINE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#alphabetic-baseline">alphabetic baseline</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#ascent-metric">ascent metric</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#descent-metric">descent metric</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#em-over-baseline">em-over baseline</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#em-under-baseline">em-under baseline</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#hanging-baseline">hanging baseline</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-inline/#ideographic-under-baseline">ideographic-under baseline</dfn></li>
</ul>
<p>The following terms and features are defined in <cite>CSS Box Sizing</cite>:
<ref>CSSSIZING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-sizing/#fit-content-inline-size">fit-content inline size</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-sizing-4/#aspect-ratio">'aspect-ratio'</dfn> property</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-sizing/#intrinsic-size">intrinsic size</dfn></li>
</ul>
<p>The following features are defined in <cite>CSS Lists and Counters</cite>.
<ref>CSSLISTS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-lists/#list-item" data-x="css-list-item">list item</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-lists/#propdef-counter-reset">'counter-reset'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-lists/#propdef-counter-set">'counter-set'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-lists/#propdef-list-style-type">'list-style-type'</dfn> property</li>
</ul>
<p>The following features are defined in <cite>CSS Overflow</cite>. <ref>CSSOVERFLOW</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-overflow/#propdef-overflow">'overflow'</dfn> property and its <dfn data-x-href="https://drafts.csswg.org/css-overflow/#valdef-overflow-hidden">'hidden'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-overflow/#propdef-text-overflow">'text-overflow'</dfn> property</li>
<li>The term <dfn data-x-href="https://drafts.csswg.org/css-overflow/#scroll-container">scroll container</dfn>
</ul>
<p>The following terms and features are defined in <cite>CSS Positioned Layout</cite>:
<ref>CSSPOSITION</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-position/#absolute-position">absolutely-positioned</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-position/#position-property">'position'</dfn> property and its
<dfn data-x-href="https://drafts.csswg.org/css-position/#valdef-position-static">'static'</dfn> value</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-position-4/#document-top-layer">top layer</dfn>
(an <span data-x="set">ordered set</span>)</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-position-4/#add-an-element-to-the-top-layer">add an element to the top layer</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-position-4/#request-an-element-to-be-removed-from-the-top-layer">request an element to be removed from the top layer</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-position-4/#remove-an-element-from-the-top-layer-immediately">remove an element from the top layer immediately</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-position-4/#process-top-layer-removals">process top layer removals</dfn></li>
</ul>
<p>The following features are defined in <cite>CSS Multi-column Layout</cite>.
<ref>CSSMULTICOL</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-multicol/#propdef-column-count">'column-count'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-multicol/#propdef-column-fill">'column-fill'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-multicol/#propdef-column-gap">'column-gap'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-multicol/#propdef-column-rule">'column-rule'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-multicol/#propdef-column-width">'column-width'</dfn> property</li>
</ul>
<p>The <dfn
data-x-href="https://drafts.csswg.org/css-ruby/#valdef-display-ruby-base">'ruby-base'</dfn>
value of the <span>'display'</span> property is defined in <cite>CSS Ruby Layout</cite>.
<ref>CSSRUBY</ref></p>
<p>The following features are defined in <cite>CSS Table</cite>: <ref>CSSTABLE</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-tables/#propdef-border-spacing">'border-spacing'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-tables/#border-collapse-property">'border-collapse'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-tables/#table-cell">'table-cell'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-tables/#table-row">'table-row'</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-tables/#table-caption">'table-caption'</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-tables/#table">'table'</dfn> values of the <span>'display'</span> property</li>
</ul>
<p>The following features are defined in <cite>CSS Text</cite>: <ref>CSSTEXT</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text-4/#content-language">content language</dfn> concept</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text/#text-transform-property">'text-transform'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text/#white-space-property">'white-space'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text/#text-align-property">'text-align'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text/#letter-spacing-property">'letter-spacing'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-text/#propdef-word-spacing">'word-spacing'</dfn> property</li>
</ul>
<p>The following features are defined in <cite>CSS Writing Modes</cite>: <ref>CSSWM</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#direction">'direction'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#unicode-bidi">'unicode-bidi'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#propdef-writing-mode">'writing-mode'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#block-flow-direction">block flow direction</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#block-axis">block axis</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#inline-axis">inline axis</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#block-size">block size</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#inline-size">inline size</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#block-start">block-start</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#block-end">block-end</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#inline-start">inline-start</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#inline-end">inline-end</dfn>,
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#line-left">line-left</dfn>, and
<dfn data-x-href="https://drafts.csswg.org/css-writing-modes/#line-right">line-right</dfn> concepts</li>
</ul>
<p>The following features are defined in <cite>CSS Basic User Interface</cite>:
<ref>CSSUI</ref></p>
<ul class="brief">
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui/#outline">'outline'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui/#cursor">'cursor'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui/#appearance-switching">'appearance'</dfn> property, its
<dfn data-x-href="https://drafts.csswg.org/css-ui/#typedef-appearance-compat-auto"><compat-auto></dfn> non-terminal value type, its
<dfn data-x-href="https://drafts.csswg.org/css-ui/#valdef-appearance-textfield">'textfield'</dfn> value, and its
<dfn data-x-href="https://drafts.csswg.org/css-ui/#valdef-appearance-menulist-button">'menulist-button'</dfn> value.</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui/#field-sizing">'field-sizing'</dfn> property, and its
<dfn data-x-href="https://drafts.csswg.org/css-ui/#valdef-field-sizing-content" data-x="field-sizing-content">'content'</dfn> value.</li>
<li>The concept <dfn data-x-href="https://drafts.csswg.org/css-ui/#widget">widget</dfn></li>
<li>The concept <dfn data-x-href="https://drafts.csswg.org/css-ui/#native-appearance">native appearance</dfn></li>
<li>The concept <dfn data-x-href="https://drafts.csswg.org/css-ui/#primitive-appearance">primitive appearance</dfn></li>
<li>The concept <dfn data-x-href="https://drafts.csswg.org/css-ui/#element-with-default-preferred-size">element with default preferred size</dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui/#non-devolvable">non-devolvable widget</dfn> and
<dfn data-x-href="https://drafts.csswg.org/css-ui/#devolvable">devolvable widget</dfn> classification, and the related
<dfn data-x-href="https://drafts.csswg.org/css-ui/#devolved">devolved widget</dfn> state.</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui-4/#pointer-events-control">'pointer-events'</dfn> property</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-ui-4/#content-selection">'user-select'</dfn> property</li>
</ul>
<p>The algorithm to <dfn
data-x-href="https://drafts.csswg.org/web-animations-1/#update-animations-and-send-events">update
animations and send events</dfn> is defined in <cite>Web Animations</cite>.
<ref>WEBANIMATIONS</ref></p>
<p>Implementations that support scripting must support the CSS Object Model. The following
features and terms are defined in the CSSOM specifications: <ref>CSSOM</ref>
<ref>CSSOMVIEW</ref>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#the-screen-interface"><code>Screen</code></dfn> interface</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#the-linkstyle-interface"><code>LinkStyle</code></dfn> interface</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#the-cssstyledeclaration-interface"><code>CSSStyleDeclaration</code></dfn> interface</li>
<li><dfn data-x="dom-style" data-x-href="https://drafts.csswg.org/cssom/#dom-elementcssinlinestyle-style"><code>style</code></dfn> IDL attribute</li>
<li><dfn data-x="dom-CSSStyleDeclaration-cssText" data-x-href="https://drafts.csswg.org/cssom/#dom-cssstyledeclaration-csstext"><code>cssText</code></dfn> attribute of <code>CSSStyleDeclaration</code></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#the-stylesheet-interface"><code>StyleSheet</code></dfn> interface</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#the-cssstylesheet-interface"><code>CSSStyleSheet</code></dfn> interface</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#create-a-css-style-sheet">create a CSS style sheet</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#remove-a-css-style-sheet">remove a CSS style sheet</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#associated-css-style-sheet">associated CSS style sheet</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#create-a-constructed-cssstylesheet">create a constructed <code>CSSStyleSheet</code></dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#synchronously-replace-the-rules-of-a-cssstylesheet">synchronously replace the rules of a <code>CSSStyleSheet</code></dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#disable-a-css-style-sheet">disable a CSS style sheet</dfn></li>
<li>
<dfn data-x="CSS style sheet"
data-x-href="https://drafts.csswg.org/cssom/#css-style-sheet">CSS style sheets</dfn> and their
properties:
<ul class="brief">
<li><dfn data-x="concept-css-style-sheet-type" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-type">type</dfn></li>
<li><dfn data-x="concept-css-style-sheet-location" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-location">location</dfn></li>
<li><dfn data-x="concept-css-style-sheet-parent-CSS-style-sheet" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-parent-css-style-sheet">parent CSS style sheet</dfn></li>
<li><dfn data-x="concept-css-style-sheet-owner-node" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-owner-node">owner node</dfn></li>
<li><dfn data-x="concept-css-style-sheet-owner-CSS-rule" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-owner-css-rule">owner CSS rule</dfn></li>
<li><dfn data-x="concept-css-style-sheet-media" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-media">media</dfn></li>
<li><dfn data-x="concept-css-style-sheet-title" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-title">title</dfn></li>
<li><dfn data-x="concept-css-style-sheet-alternate-flag" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-alternate-flag">alternate flag</dfn></li>
<li><dfn data-x="concept-css-style-sheet-disabled-flag" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-disabled-flag">disabled flag</dfn></li>
<li><dfn data-x="concept-css-style-sheet-CSS-rules" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-css-rules">CSS rules</dfn></li>
<li><dfn data-x="concept-css-style-sheet-origin-clean-flag" data-x-href="https://drafts.csswg.org/cssom/#concept-css-style-sheet-origin-clean-flag">origin-clean flag</dfn></li>
</ul>
</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#css-style-sheet-set">CSS style sheet set</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#css-style-sheet-set-name">CSS style sheet set name</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#preferred-css-style-sheet-set-name">preferred CSS style sheet set name</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#change-the-preferred-css-style-sheet-set-name">change the preferred CSS style sheet set name</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom/#serialize-a-css-value">Serializing a CSS value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#document-run-the-resize-steps">run the resize steps</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#document-run-the-scroll-steps">run the scroll steps</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#evaluate-media-queries-and-report-changes">evaluate media queries and report changes</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#scroll-a-target-into-view">Scroll a target into view</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#scroll-to-the-beginning-of-the-document">Scroll to the beginning of the document</dfn></li>
<li>The <dfn data-x="event-resize" data-x-href="https://drafts.csswg.org/cssom-view/#eventdef-window-resize"><code>resize</code></dfn> event</li>
<li>The <dfn data-x="event-scroll" data-x-href="https://drafts.csswg.org/cssom-view/#eventdef-document-scroll"><code>scroll</code></dfn> event</li>
<li>The <dfn data-x="event-scrollend" data-x-href="https://drafts.csswg.org/cssom-view/#eventdef-document-scrollend"><code>scrollend</code></dfn> event</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#set-up-browsing-context-features">set up browsing context features</dfn></li>
<li>The <dfn data-x="mouseevent-clientx" data-x-href="https://drafts.csswg.org/cssom-view/#dom-mouseevent-clientx">clientX</dfn> and <dfn data-x="mouseevent-clienty" data-x-href="https://drafts.csswg.org/cssom-view/#dom-mouseevent-clienty">clientY</dfn> extension attributes of the <span>MouseEvent</span> interface</li>
</ul>
<p>The following features and terms are defined in <cite>CSS Syntax</cite>:
<ref>CSSSYNTAX</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#conform-classes">conformant style sheet</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#parse-a-list-of-component-values">parse a list of component values</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#parse-a-comma-separated-list-of-component-values">parse a comma-separated list of component values</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#component-value">component value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#environment-encoding">environment encoding</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-syntax/#typedef-whitespace-token"><whitespace-token></dfn></li>
</ul>
<p>The following terms are defined in <cite>Selectors</cite>: <ref>SELECTORS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/selectors/#type-selector">type selector</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/selectors/#attribute-selector">attribute selector</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/selectors/#pseudo-class">pseudo-class</dfn></li>
<li><dfn
data-x-href="https://drafts.csswg.org/selectors/#the-focus-visible-pseudo"><code>:focus-visible</code></dfn>
pseudo-class</li>
<li><dfn data-x-href="https://drafts.csswg.org/selectors/#indicate-focus">indicate focus</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/selectors/#pseudo-element">pseudo-element</dfn></li>
</ul>
<p>The following features are defined in <cite>CSS Values and Units</cite>:
<ref>CSSVALUES</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-values/#lengths"><length></dfn></li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#em">'em'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#ex">'ex'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#vw">'vw'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#in">'in'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#px">'px'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#pt">'pt'</dfn> unit</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#funcdef-attr">'attr()'</dfn> function</li>
<li>The <dfn data-x-href="https://drafts.csswg.org/css-values/#math-function">math functions</dfn></li>
</ul>
<p>The following features are defined in <cite>CSS View Transitions</cite>:
<ref>CSSVIEWTRANSITIONS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions/#perform-pending-transition-operations">perform pending transition operations</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions/#document-rendering-suppression-for-view-transitions">rendering suppression for view transitions</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions/#activate-view-transition">activate view transition</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions/#viewtransition"><code>ViewTransition</code></dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions/#view-transition-page-visibility-change-steps">view transition page visibility change steps</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions-2/#resolve-inbound-cross-document-view-transition">resolving inbound cross-document view-transition</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions-2/#setup-cross-document-view-transition">setting up a cross-document view-transition</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-view-transitions-2/#can-navigation-trigger-a-cross-document-view-transition">can navigation trigger a cross-document view-transition?</dfn>
</ul>
<p>The term <dfn data-x="css-styling-attribute"
data-x-href="https://drafts.csswg.org/css-style-attr/#style-attribute">style attribute</dfn> is
defined in <cite>CSS Style Attributes</cite>. <ref>CSSATTR</ref></p>
<p>The following terms are defined in the <cite>CSS Cascading and Inheritance</cite>:
<ref>CSSCASCADE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascaded-value">cascaded value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#specified-value">specified value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#computed-value">computed value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#used-value">used value</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#origin">cascade origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascade-origin-author">Author Origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascade-origin-user">User Origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascade-origin-ua">User Agent Origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascade-origin-animation">Animation Origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#cascade-origin-transition">Transition Origin</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-cascade/#initial-value">initial value</dfn></li>
</ul>
<p>The <code>CanvasRenderingContext2D</code> object's use of fonts depends on the features
described in the CSS <cite>Fonts</cite> and <cite>Font Loading</cite> specifications, including
in particular <dfn><code>FontFace</code></dfn> objects and the <dfn
data-x-href="https://drafts.csswg.org/css-font-loading/#font-source">font source</dfn> concept.
<ref>CSSFONTS</ref> <ref>CSSFONTLOAD</ref></p>
<p>The following interfaces and terms are defined in <cite>Geometry Interfaces</cite>:
<ref>GEOMETRY</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.fxtf.org/geometry/#dommatrix"><code>DOMMatrix</code></dfn> interface, and associated
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m11-element">m11 element</dfn>,
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m12-element">m12 element</dfn>,
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m21-element">m21 element</dfn>,
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m22-element">m22 element</dfn>,
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m41-element">m41 element</dfn>, and
<dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-m42-element">m42 element</dfn></li>
<li><dfn data-x-href="https://drafts.fxtf.org/geometry/#dictdef-dommatrix2dinit"><code>DOMMatrix2DInit</code></dfn> and
<dfn data-x-href="https://drafts.fxtf.org/geometry/#dictdef-dommatrixinit"><code>DOMMatrixInit</code></dfn> dictionaries</li>
<li>The <dfn data-x-href="https://drafts.fxtf.org/geometry/#create-a-dommatrix-from-the-dictionary">create a <code>DOMMatrix</code> from a dictionary</dfn>
and <dfn data-x-href="https://drafts.fxtf.org/geometry/#create-a-dommatrix-from-the-2d-dictionary">create a <code>DOMMatrix</code> from a 2D dictionary</dfn>
algorithms for <code>DOMMatrix2DInit</code> or <code>DOMMatrixInit</code></li>
<li>The <dfn data-x-href="https://drafts.fxtf.org/geometry/#dictdef-dompointinit"><code>DOMPointInit</code></dfn> dictionary, and associated
<dfn data-x="DOMPointInit-x" data-x-href="https://drafts.fxtf.org/geometry/#dom-dompointinit-x">x</dfn> and
<dfn data-x="DOMPointInit-y" data-x-href="https://drafts.fxtf.org/geometry/#dom-dompointinit-y">y</dfn> members</li>
<li><dfn data-x-href="https://drafts.fxtf.org/geometry/#matrix-multiply">Matrix multiplication</dfn></li>
</ul>
<p>The following terms are defined in the <cite>CSS Scoping</cite>: <ref>CSSSCOPING</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-scoping/#flat-tree">flat tree</dfn></li>
</ul>
<p>The following terms and features are defined in <cite>CSS Color Adjustment</cite>:
<ref>CSSCOLORADJUST</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-color-adjust/#color-scheme-prop">'color-scheme'</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-color-adjust/#pages-supported-color-schemes">page's supported color-schemes</dfn></li>
</ul>
<p>The following terms are defined in <cite>CSS Pseudo-Elements</cite>: <ref>CSSPSEUDO</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-pseudo/#details-content-pseudo">'::details-content'</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-pseudo/#file-selector-button-pseudo">'::file-selector-button'</dfn></li>
</ul>
<p>The following terms are defined in <cite>CSS Containment</cite>: <ref>CSSCONTAIN</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#skips-its-contents">skips its contents</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#relevant-to-the-user">relevant to the user</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#proximity-to-the-viewport">proximity to the viewport</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#containment-layout">layout containment</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#content-visibility">'content-visibility'</dfn> property</li>
<li><dfn data-x-href="https://drafts.csswg.org/css-contain/#propdef-content-visibility" data-x="content-visibility-auto">'auto'</dfn> value for <span>'content-visibility'</span></li>
</ul>
<p>The following terms are defined in <cite>CSS Anchor Positioning</cite>: <ref>CSSANCHOR</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-anchor-position/#implicit-anchor-element">implicit anchor element</dfn></li>
</ul>
</dd>
<dt>Intersection Observer</dt>
<dd>
<p>The following term is defined in <cite>Intersection Observer</cite>:
<ref>INTERSECTIONOBSERVER</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#run-the-update-intersection-observations-steps">run the update intersection observations steps</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#intersectionobserver"><code>IntersectionObserver</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#dictdef-intersectionobserverinit"><code>IntersectionObserverInit</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#dom-intersectionobserver-observe" data-x="dom-IntersectionObserver-observe"><code>observe</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#dom-intersectionobserver-unobserve" data-x="dom-IntersectionObserver-unobserve"><code>unobserve</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#dom-intersectionobserverentry-isintersecting" data-x="dom-IntersectionObserverEntry-isIntersecting"><code>isIntersecting</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/IntersectionObserver/#dom-intersectionobserverentry-target" data-x="dom-IntersectionObserverEntry-target"><code>target</code></dfn></li>
</ul>
</dd>
<dt>Resize Observer</dt>
<dd>
<p>The following terms are defined in <cite>Resize Observer</cite>:
<ref>RESIZEOBSERVER</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/resize-observer-1/#gather-active-observations-h">gather active resize observations at depth</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/resize-observer-1/#has-active-observations-h">has active resize observations</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/resize-observer-1/#has-skipped-observations-h">has skipped resize observations</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/resize-observer-1/#broadcast-resize-notifications-h">broadcast active resize observations</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/resize-observer-1/#deliver-resize-error">deliver resize loop error</dfn></li>
</ul>
</dd>
<dt>WebGL</dt>
<dd>
<p>The following interfaces are defined in the WebGL specifications: <ref>WEBGL</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext"><code>WebGLRenderingContext</code></dfn> interface</li>
<li><dfn data-x-href="https://www.khronos.org/registry/webgl/specs/latest/2.0/#WebGL2RenderingContext"><code>WebGL2RenderingContext</code></dfn> interface</li>
<li><dfn data-x-href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLContextAttributes"><code>WebGLContextAttributes</code></dfn> dictionary</li>
</ul>
</dd>
<dt>WebGPU</dt>
<dd>
<p>The following interfaces are defined in <cite>WebGPU</cite>: <ref>WEBGPU</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://gpuweb.github.io/gpuweb/#canvas-context"><code>GPUCanvasContext</code></dfn> interface</li>
</ul>
</dd>
<dt>WebVTT</dt>
<dd>
<p>Implementations may support WebVTT as a text track format for subtitles, captions, metadata,
etc., for media resources. <ref>WEBVTT</ref></p>
<p>The following terms, used in this specification, are defined in <cite>WebVTT</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webvtt/#webvtt-file">WebVTT file</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webvtt/#webvtt-file-using-cue-text">WebVTT file using cue text</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webvtt/#webvtt-file-using-only-nested-cues">WebVTT file using only nested cues</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webvtt/#webvtt-parser">WebVTT parser</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webvtt/#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the display of WebVTT text tracks</dfn></li>
<li>The WebVTT <dfn data-x-href="https://w3c.github.io/webvtt/#webvtt-cue-writing-direction">text track cue writing direction</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webvtt/#vttcue"><code>VTTCue</code></dfn> interface</li>
</ul>
</dd>
<dt>ARIA</dt>
<dd>
<p>The <dfn element-attr><code data-x="attr-aria-role">role</code></dfn> attribute is defined in
<cite>Accessible Rich Internet Applications</cite> (<cite>ARIA</cite>), as are the following
roles: <ref>ARIA</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/aria/#button"><code data-x="attr-aria-role-button">button</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#presentation"><code data-x="attr-aria-role-presentation">presentation</code></dfn></li>
</ul>
<p>In addition, the following <dfn><code data-x="attr-aria-*">aria-*</code></dfn> content
attributes are defined in <cite>ARIA</cite>: <ref>ARIA</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/aria/#aria-checked"><code data-x="attr-aria-checked">aria-checked</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#aria-describedby"><code data-x="attr-aria-describedby">aria-describedby</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#aria-disabled"><code data-x="attr-aria-disabled">aria-disabled</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#aria-label"><code data-x="attr-aria-label">aria-label</code></dfn></li>
</ul>
<p>Finally, the following terms are defined in <cite>ARIA</cite>: <ref>ARIA</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/aria/#dfn-role">role</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#dfn-accessible-name" data-x="concept-accessible-name">accessible name</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/aria/#ARIAMixin"><code>ARIAMixin</code></dfn> interface, with its associated
<dfn data-x-href="https://w3c.github.io/aria/#dfn-ariamixin-getter-steps"><code>ARIAMixin</code> getter steps</dfn> and
<dfn data-x-href="https://w3c.github.io/aria/#dfn-ariamixin-setter-steps"><code>ARIAMixin</code> setter steps</dfn> hooks, and its
<dfn data-x="dom-ARIAMixin-role" data-x-href="https://w3c.github.io/aria/#idl-def-ariamixin-role"><code>role</code></dfn> and
<dfn data-x="dom-ARIAMixin-aria*" data-x-href="https://w3c.github.io/aria/#idl-def-ariamixin-ariaactivedescendantelement"><code>aria*</code></dfn> attributes</li>
</ul>
</dd>
<dt>Content Security Policy</dt>
<dd>
<p>The following terms are defined in <cite>Content Security Policy</cite>: <ref>CSP</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-csp/#content-security-policy-object">Content Security Policy</dfn></li>
<li><dfn data-x="csp-disposition" data-x-href="https://w3c.github.io/webappsec-csp/#policy-disposition">disposition</dfn></li>
<li><dfn data-x="csp-directive-set" data-x-href="https://w3c.github.io/webappsec-csp/#policy-directive-set">directive set</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-csp/#directives">Content Security Policy directive</dfn></li>
<li><dfn data-x="concept-csp-list" data-x-href="https://w3c.github.io/webappsec-csp/#csp-list">CSP list</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#grammardef-serialized-policy">Content Security Policy syntax</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-csp/#enforced">enforce the policy</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#parse-serialized-policy">parse a serialized Content Security Policy</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#run-document-csp-initialization">Run CSP initialization for a Document</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#run-global-object-csp-initialization">Run CSP initialization for a global object</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#should-block-inline">Should element's inline behavior be blocked by Content Security Policy?</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#should-block-navigation-request">Should navigation request of type be blocked by Content Security Policy?</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#should-block-navigation-response">Should navigation response to navigation request of type in target be blocked by Content Security Policy?</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#report-uri"><code data-x="">report-uri</code> directive</dfn></li>
<li>The <dfn data-x="csp-EnsureCSPDoesNotBlockStringCompilation" data-x-href="https://w3c.github.io/webappsec-csp/#can-compile-strings">EnsureCSPDoesNotBlockStringCompilation</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#allow-base-for-document">Is base allowed for Document?</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#frame-ancestors"><code data-x="">frame-ancestors</code> directive</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#sandbox"><code data-x="">sandbox</code> directive</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-csp/#contains-a-header-delivered-content-security-policy">contains a header-delivered Content Security Policy</dfn> property.</li>
<li>The <dfn data-x="parse-response-csp" data-x-href="https://w3c.github.io/webappsec-csp/#parse-response-csp">Parse a response's Content Security Policies</dfn> algorithm.</li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-csp/#securitypolicyviolationevent"><code>SecurityPolicyViolationEvent</code></dfn> interface</li>
<li>The <dfn data-x="event-securitypolicyviolation" data-x-href="https://w3c.github.io/webappsec-csp/#eventdef-globaleventhandlers-securitypolicyviolation"><code>securitypolicyviolation</code></dfn> event</li>
</ul>
</dd>
<dt>Service Workers</dt>
<dd>
<p>The following terms are defined in <cite>Service Workers</cite>: <ref>SW</ref></p>
<ul class="brief">
<li><dfn data-x="dfn-active-worker" data-x-href="https://w3c.github.io/ServiceWorker/#dfn-active-worker">active worker</dfn></li>
<li><dfn data-x="dfn-client-message-queue" data-x-href="https://w3c.github.io/ServiceWorker/#dfn-client-message-queue">client message queue</dfn></li>
<li><dfn data-x="dfn-control" data-x-href="https://w3c.github.io/ServiceWorker/#dfn-control">control</dfn></li>
<li><dfn data-x="on-fetch-request-algorithm" data-x-href="https://w3c.github.io/ServiceWorker/#on-fetch-request-algorithm">handle fetch</dfn></li>
<li><dfn data-x="scope-match-algorithm" data-x-href="https://w3c.github.io/ServiceWorker/#scope-match-algorithm">match service worker registration</dfn></li>
<li><dfn data-x="dfn-service-worker" data-x-href="https://w3c.github.io/ServiceWorker/#dfn-service-worker">service worker</dfn></li>
<li><dfn data-x="serviceworkercontainer-service-worker-client" data-x-href="https://w3c.github.io/ServiceWorker/#serviceworkercontainer-service-worker-client">service worker client</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/service-workers/#dfn-service-worker-registration">service worker registration</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/ServiceWorker/#serviceworker"><code>ServiceWorker</code></dfn> interface</li>
<li><dfn data-x-href="https://w3c.github.io/ServiceWorker/#serviceworkercontainer"><code>ServiceWorkerContainer</code></dfn> interface</li>
<li><dfn data-x-href="https://w3c.github.io/ServiceWorker/#serviceworkerglobalscope"><code>ServiceWorkerGlobalScope</code></dfn> interface</li>
<li><dfn data-x="service-worker-unregister" data-x-href="https://w3c.github.io/service-workers/#navigator-service-worker-unregister"><code>unregister</code></dfn></li>
</ul>
</dd>
<dt>Secure Contexts</dt>
<dd>
<p>The following algorithms are defined in <cite>Secure Contexts</cite>:
<ref>SECURE-CONTEXTS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-secure-contexts/#potentially-trustworthy-url">Is url potentially trustworthy?</dfn></li>
</ul>
</dd>
<dt>Permissions Policy</dt>
<dd>
<p>The following terms are defined in <cite>Permissions Policy</cite>:
<ref>PERMISSIONSPOLICY</ref></p>
<ul class="brief">
<li><dfn data-x="concept-permissions-policy" data-x-href="https://w3c.github.io/webappsec-feature-policy/#permissions-policy">permissions policy</dfn></li>
<li><dfn data-x="concept-policy-controlled-feature" data-x-href="https://w3c.github.io/webappsec-feature-policy/#policy-controlled-feature">policy-controlled feature</dfn></li>
<li><dfn data-x="concept-container-policy" data-x-href="https://w3c.github.io/webappsec-feature-policy/#container-policy">container policy</dfn></li>
<li><dfn data-x="concept-serialized-permissions-policy" data-x-href="https://w3c.github.io/webappsec-feature-policy/#serialized-permissions-policy">serialized permissions policy</dfn></li>
<li><dfn data-x="concept-default-allowlist" data-x-href="https://w3c.github.io/webappsec-feature-policy/#default-allowlist">default allowlist</dfn></li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-feature-policy/#create-for-navigable">creating a permissions policy</dfn> algorithm</li>
<li>The <dfn data-x-href="https://w3c.github.io/webappsec-feature-policy/#create-from-response">creating a permissions policy from a response</dfn> algorithm</li>
<li>The <dfn data-x="is-feature-enabled" data-x-href="https://w3c.github.io/webappsec-feature-policy/#is-feature-enabled">is feature enabled by policy for origin</dfn> algorithm</li>
<li>The <dfn data-x="process-permissions-policy-attributes" data-x-href="https://w3c.github.io/webappsec-feature-policy/#process-permissions-policy-attributes">process permissions policy attributes</dfn> algorithm</li>
</ul>
</dd>
<dt>Payment Request API</dt>
<dd>
<p>The following feature is defined in <cite>Payment Request API</cite>:
<ref>PAYMENTREQUEST</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/payment-request/#dom-paymentrequest"><code>PaymentRequest</code></dfn> interface</li>
</ul>
</dd>
<dt>MathML</dt>
<dd>
<p>While support for MathML as a whole is not required by this specification (though it is
encouraged, at least for web browsers), certain features depend upon small parts of MathML being
implemented. <ref>MATHML</ref></p>
<p>The following features are defined in <cite>Mathematical Markup Language</cite>
(<cite>MathML</cite>):</p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#dfn-annotation-xml">MathML <code>annotation-xml</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#the-top-level-math-element">MathML <code>math</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#error-message-merror">MathML <code>merror</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#the-mi-element">MathML <code>mi</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#number-mn">MathML <code>mn</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#operator-fence-separator-or-accent-mo">MathML <code>mo</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#string-literal-ms">MathML <code>ms</code></dfn> element</li>
<li><dfn data-x-href="https://w3c.github.io/mathml-core/#text-mtext">MathML <code>mtext</code></dfn> element</li>
</ul>
</dd>
<dt>SVG</dt>
<dd>
<p>While support for SVG as a whole is not required by this specification (though it is
encouraged, at least for web browsers), certain features depend upon parts of SVG being
implemented.</p>
<p>User agents that implement SVG must implement the <cite>SVG 2</cite> specification, and not
any earlier revisions.</p>
<p>The following features are defined in the <cite>SVG 2</cite> specification:
<ref>SVG</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://svgwg.org/svg2-draft/types.html#InterfaceSVGElement"><code>SVGElement</code></dfn> interface</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/embedded.html#InterfaceSVGImageElement"><code>SVGImageElement</code></dfn> interface</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/interact.html#InterfaceSVGScriptElement"><code>SVGScriptElement</code></dfn> interface</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/struct.html#InterfaceSVGSVGElement"><code>SVGSVGElement</code></dfn> interface</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/linking.html#AElement">SVG <code>a</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/struct.html#DescElement">SVG <code>desc</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/embedded.html#ForeignObjectElement">SVG <code>foreignObject</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/embedded.html#ImageElement">SVG <code>image</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/interact.html#ScriptElement">SVG <code>script</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/struct.html#SVGElement">SVG <code>svg</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/struct.html#TitleElement">SVG <code>title</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/struct.html#UseElement">SVG <code>use</code></dfn> element</li>
<li><dfn data-x-href="https://svgwg.org/svg2-draft/painting.html#TextRendering">SVG <code>text-rendering</code></dfn> property</li>
</ul>
</dd>
<dt>Filter Effects</dt>
<dd>
<p>The following features are defined in <cite>Filter Effects</cite>: <ref>FILTERS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.fxtf.org/filter-effects/#typedef-filter-value-list"><filter-value-list></dfn></li>
</ul>
</dd>
<dt>Compositing</dt>
<dd>
<p>The following features are defined in <cite>Compositing and Blending</cite>:
<ref>COMPOSITE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://drafts.fxtf.org/compositing/#ltblendmodegt"><blend-mode></dfn></li>
<li><dfn data-x-href="https://drafts.fxtf.org/compositing/#compositemode"><composite-mode></dfn></li>
<li><dfn data-x-href="https://drafts.fxtf.org/compositing/#porterduffcompositingoperators_srcover" data-x="gcop-source-over">source-over</dfn></li>
<li><dfn data-x-href="https://drafts.fxtf.org/compositing/#porterduffcompositingoperators_src" data-x="gcop-copy">copy</dfn></li>
</ul>
</dd>
<dt>Cooperative Scheduling of Background Tasks</dt>
<dd>
<p>The following features are defined in <cite>Cooperative Scheduling of Background
Tasks</cite>: <ref>REQUESTIDLECALLBACK</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/requestidlecallback/#the-requestidlecallback-method"><code>requestIdleCallback()</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/requestidlecallback/#start-an-idle-period-algorithm">start an idle period algorithm</dfn></li>
</ul>
</dd>
<dt>Screen Orientation</dt>
<dd>
<p>The following terms are defined in <cite>Screen Orientation</cite>:
<ref>SCREENORIENTATION</ref></p>
<ul>
<li><dfn data-x-href="https://w3c.github.io/screen-orientation/#dfn-screen-orientation-change-steps">screen orientation change steps</dfn></li>
</ul>
</dd>
<dt>Storage</dt>
<dd>
<p>The following terms are defined in <cite>Storage</cite>: <ref>STORAGE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://storage.spec.whatwg.org/#obtain-a-local-storage-bottle-map">obtain a local storage bottle map</dfn></li>
<li><dfn data-x-href="https://storage.spec.whatwg.org/#obtain-a-session-storage-bottle-map">obtain a session storage bottle map</dfn></li>
<li><dfn data-x-href="https://storage.spec.whatwg.org/#obtain-a-storage-key-for-non-storage-purposes">obtain a storage key for non-storage purposes</dfn></li>
<li><dfn data-x-href="https://storage.spec.whatwg.org/#storage-key-equal">storage key equal</dfn></li>
<li><dfn data-x-href="https://storage.spec.whatwg.org/#storage-proxy-map">storage proxy map</dfn></li>
<li><dfn data-x-href="https://storage.spec.whatwg.org/#legacy-clone-a-traversable-storage-shed">legacy-clone a traversable storage shed</dfn></li>
</ul>
</dd>
<dt>Web App Manifest</dt>
<dd>
<p>The following features are defined in <cite>Web App Manifest</cite>: <ref>MANIFEST</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/manifest/#dfn-manifest">application manifest</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/manifest/#dfn-installed-web-application">installed web application</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/manifest/#dfn-processing-a-manifest">process the manifest</dfn></li>
</ul>
</dd>
<dt>WebAssembly JavaScript Interface: ESM Integration</dt>
<dd>
<p>The following terms are defined in <cite>WebAssembly JavaScript Interface: ESM Integration</cite>: <ref>WASMESM</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://webassembly.github.io/esm-integration/js-api/index.html#webassembly-module-record">WebAssembly Module Record</dfn></li>
<li><dfn data-x-href="https://webassembly.github.io/esm-integration/js-api/index.html#parse-a-webassembly-module">parse a WebAssembly module</dfn></li>
</ul>
</dd>
<dt>WebCodecs</dt>
<dd>
<p>The following features are defined in <cite>WebCodecs</cite>: <ref>WEBCODECS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webcodecs/#videoframe-interface"><code>VideoFrame</code></dfn> interface.</li>
<li><dfn data-x-href="https://w3c.github.io/webcodecs/#dom-videoframe-display-width-slot">[[display width]]</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webcodecs/#dom-videoframe-display-height-slot">[[display height]]</dfn></li>
</ul>
</dd>
<dt>WebDriver</dt>
<dd>
<p>The following terms are defined in <cite>WebDriver</cite>: <ref>WEBDRIVER</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-extension-commands">extension command</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-remote-end-steps">remote end steps</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-errors">WebDriver error</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-error-code">WebDriver error code</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-invalid-argument">invalid argument</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#dfn-getting-properties">getting a property</dfn></li>
<li><dfn data-x="success-value" data-x-href="https://w3c.github.io/webdriver/#dfn-success">success</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver/#security">WebDriver's security considerations</dfn></li>
<li><dfn data-x="webdriver-current-browsing-context" data-x-href="https://w3c.github.io/webdriver/#dfn-current-browsing-context">current browsing context</dfn></li>
</ul>
</dd>
<dt>WebDriver BiDi</dt>
<dd>
<p>The following terms are defined in <cite>WebDriver BiDi</cite>: <ref>WEBDRIVERBIDI</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-status">WebDriver BiDi navigation status</dfn></li>
<li><dfn data-x="navigation-status-id" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-id">navigation status id</dfn></li>
<li><dfn data-x="navigation-status-status" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-status">navigation status status</dfn></li>
<li><dfn data-x="navigation-status-canceled" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-canceled">navigation status canceled</dfn></li>
<li><dfn data-x="navigation-status-committed" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-committed">navigation status committed</dfn></li>
<li><dfn data-x="navigation-status-pending" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-pending">navigation status pending</dfn></li>
<li><dfn data-x="navigation-status-complete" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-complete">navigation status complete</dfn></li>
<li><dfn data-x="navigation-status-url" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-url">navigation status url</dfn></li>
<li><dfn data-x="navigation-status-suggested-filename" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-suggested-filename">navigation status suggested filename</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-aborted">WebDriver BiDi navigation aborted</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-committed">WebDriver BiDi navigation committed</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-failed">WebDriver BiDi navigation failed</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-started">WebDriver BiDi navigation started</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-download-started">WebDriver BiDi download started</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-fragment-navigated">WebDriver BiDi fragment navigated</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-dom-content-loaded">WebDriver BiDi DOM content loaded</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-load-complete">WebDriver BiDi load complete</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-history-updated">WebDriver BiDi history updated</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigable-created">WebDriver BiDi navigable created</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigable-destroyed">WebDriver BiDi navigable destroyed</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-user-prompt-closed">WebDriver BiDi user prompt closed</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-user-prompt-opened">WebDriver BiDi user prompt opened</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-file-dialog-opened">WebDriver BiDi file dialog opened</dfn></li>
</ul>
</dd>
<dt>Web Cryptography API</dt>
<dd>
<p>The following terms are defined in <cite>Web Cryptography API</cite>:
<ref>WEBCRYPTO</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webcrypto/#dfn-generate-a-random-uuid">generating a random UUID</dfn></li>
</ul>
</dd>
<dt>WebSockets</dt>
<dd>
<p>The following terms are defined in <cite>WebSockets</cite>: <ref>WEBSOCKETS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://websockets.spec.whatwg.org/#websocket"><code>WebSocket</code></dfn></li>
<li><dfn data-x-href="https://websockets.spec.whatwg.org/#make-disappear" for="WebSocket">make disappear</dfn></li>
</ul>
</dd>
<dt>WebTransport</dt>
<dd>
<p>The following terms are defined in <cite>WebTransport</cite>: <ref>WEBTRANSPORT</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webtransport/#webtransport"><code>WebTransport</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webtransport/#context-cleanup-steps"><code>context cleanup steps</code></dfn></li>
</ul>
</dd>
<dt>Web Authentication: An API for accessing Public Key Credentials</dt>
<dd>
<p>The following terms are defined in <cite>Web Authentication: An API for accessing Public Key
Credentials</cite>: <ref>WEBAUTHN</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webauthn/#public-key-credential">public key credential</dfn></li>
</ul>
</dd>
<dt>Credential Management</dt>
<dd>
<p>The following terms are defined in <cite>Credential Management</cite>: <ref>CREDMAN</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webappsec-credential-management/#dom-credentialmediationrequirement-conditional">conditional mediation</dfn></li>
<li><dfn data-x="credman-credential" data-x-href="https://w3c.github.io/webappsec-credential-management/#credential">credential</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webappsec-credential-management/#dom-credentialscontainer-get"><code>navigator.credentials.get()</code></dfn></li>
</ul>
</dd>
<dt>Console</dt>
<dd>
<p>The following terms are defined in <cite>Console</cite>: <ref>CONSOLE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://console.spec.whatwg.org/#report-a-warning-to-the-console">report a warning to the console</dfn></li>
</ul>
</dd>
<dt>Web Locks API</dt>
<dd>
<p>The following terms are defined in <cite>Web Locks API</cite>: <ref>WEBLOCKS</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/web-locks/#lock-concept">locks</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/web-locks/#lock-request">lock requests</dfn></li>
</ul>
</dd>
<dt>Trusted Types</dt>
<dd>
<p>This specification uses the following features defined in <cite>Trusted Types</cite>:
<ref>TRUSTED-TYPES</ref></p>
<ul class="brief">
<li><dfn data-x="tt-trustedhtml" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#trustedhtml"><code>TrustedHTML</code></dfn></li>
<li><dfn data-x="tt-trustedhtml-data" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#trustedhtml-data">data</dfn></li>
<li><dfn data-x="tt-trustedscript" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#trusted-script"><code>TrustedScript</code></dfn></li>
<li><dfn data-x="tt-trustedscript-data" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#trustedscript-data"><code>data</code></dfn></li>
<li><dfn data-x="tt-trustedscripturl" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#trustedscripturl"><code>TrustedScriptURL</code></dfn></li>
<li><dfn data-x="tt-getcompliantstring" data-x-href="https://w3c.github.io/trusted-types/dist/spec/#get-trusted-type-compliant-string-algorithm">Get Trusted Type compliant string</dfn></li>
</ul>
</dd>
<dt>WebRTC API</dt>
<dd>
<p>The following terms are defined in <cite>WebRTC API</cite>: <ref>WEBRTC</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/webrtc-pc/#dom-rtcdatachannel"><code>RTCDataChannel</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection"><code>RTCPeerConnection</code></dfn></li>
</ul>
</dd>
<dt>Picture-in-Picture API</dt>
<dd>
<p>The following terms are defined in <cite>Picture-in-Picture API</cite>: <ref>PICTUREINPICTURE</ref></p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/picture-in-picture/#pictureinpicturewindow"><code>PictureInPictureWindow</code></dfn></li>
</ul>
</dd>
<dt>Idle Detection API</dt>
<dd>
<p>The following terms are defined in <cite>Idle Detection API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/idle-detection/#idledetector"><code>IdleDetector</code></dfn></li>
</ul>
</dd>
<dt>Web Speech API</dt>
<dd>
<p>The following terms are defined in <cite>Web Speech API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/speech-api/#speechrecognition"><code>SpeechRecognition</code></dfn></li>
</ul>
</dd>
<dt>WebOTP API</dt>
<dd>
<p>The following terms are defined in <cite>WebOTP API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/web-otp/#otpcredential"><code>OTPCredential</code></dfn></li>
</ul>
</dd>
<dt>Web Share API</dt>
<dd>
<p>The following terms are defined in <cite>Web Share API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/web-share/#share-method" data-x="dom-Navigator-share">share()</dfn></li>
</ul>
</dd>
<dt>Web Smart Card API</dt>
<dd>
<p>The following terms are defined in <cite>Web Smart Card API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/web-smart-card/#dom-smartcardconnection"><code>SmartCardConnection</code></dfn></li>
</ul>
</dd>
<dt>Web Background Synchronization</dt>
<dd>
<p>The following terms are defined in <cite>Web Background Synchronization</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/background-sync/spec/#syncmanager"><code>SyncManager</code></dfn></li>
<li><dfn data-x-href="https://wicg.github.io/background-sync/spec/#dom-syncmanager-register" data-x="dom-SyncManager-register"><code>register()</code></dfn></li>
</ul>
</dd>
<dt>Web Periodic Background Synchronization</dt>
<dd>
<p>The following terms are defined in <cite>Web Periodic Background Synchronization</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/periodic-background-sync/#periodicsyncmanager"><code>PeriodicSyncManager</code></dfn></li>
<li><dfn data-x-href="https://wicg.github.io/periodic-background-sync/#dom-periodicsyncmanager-register" data-x="dom-PeriodicSyncManager-register"><code>register()</code></dfn></li>
</ul>
</dd>
<dt>Web Background Fetch</dt>
<dd>
<p>The following terms are defined in <cite>Background Fetch</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/background-fetch/#backgroundfetchmanager"><code>BackgroundFetchManager</code></dfn></li>
<li><dfn data-x-href="https://wicg.github.io/background-fetch/#dom-backgroundfetchmanager-fetch" data-x="dom-BackgroundFetchManager-fetch"><code>fetch()</code></dfn></li>
</ul>
</dd>
<dt>Keyboard Lock</dt>
<dd>
<p>The following terms are defined in <cite>Keyboard Lock</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://wicg.github.io/keyboard-lock/#keyboard"><code>Keyboard</code></dfn></li>
<li><dfn data-x-href="https://wicg.github.io/keyboard-lock/#dom-keyboard-lock" data-x="dom-Keyboard-lock"><code>lock()</code></dfn></li>
</ul>
</dd>
<dt>Web MIDI API</dt>
<dd>
<p>The following terms are defined in <cite>Web MIDI API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://webaudio.github.io/web-midi-api/#dom-navigator-requestmidiaccess" data-x="dom-Navigator-requestMIDIAccess"><code>requestMIDIAccess()</code></dfn></li>
</ul>
</dd>
<dt>Generic Sensor API</dt>
<dd>
<p>The following terms are defined in <cite>Generic Sensor API</cite>:</p>
<ul class="brief">
<li><dfn data-x="request-sensor-access" data-x-href="https://w3c.github.io/sensors/#request-sensor-access">request sensor access</dfn></li>
</ul>
</dd>
<dt>WebHID API</dt>
<dd>
<p>The following terms are defined in <cite>WebHID API</cite>:</p>
<ul class="brief">
<li><dfn data-x="request-device" data-x-href="https://wicg.github.io/webhid/#requestdevice-method"><code>requestDevice</code></dfn></li>
</ul>
</dd>
<dt>WebXR Device API</dt>
<dd>
<p>The following terms are defined in <cite>WebXR Device API</cite>:</p>
<ul class="brief">
<li><dfn data-x-href="https://immersive-web.github.io/webxr/#xrsystem"><code>XRSystem</code></dfn></li>
</ul>
</dd>
</dl>
<hr>
<p>This specification does not <em>require</em> support of any particular network protocol, style
sheet language, scripting language, or any of the DOM specifications beyond those required in the
list above. However, the language described by this specification is biased towards CSS as the
styling language, JavaScript as the scripting language, and HTTP as the network protocol, and
several features assume that those languages and protocols are in use.</p>
<p>A user agent that implements the HTTP protocol must implement <cite>HTTP State Management
Mechanism</cite> (Cookies) as well. <ref>HTTP</ref> <ref>COOKIES</ref></p>
<p class="note">This specification might have certain additional requirements on character
encodings, image formats, audio formats, and video formats in the respective sections.</p>
</div>
<h4>Extensibility</h4>
<p>Vendor-specific proprietary user agent extensions to this specification are strongly
discouraged. Documents must not use such extensions, as doing so reduces interoperability and
fragments the user base, allowing only users of specific user agents to access the content in
question.</p>
<div w-nodev>
<p>All extensions must be defined so that the use of extensions neither contradicts nor causes the
non-conformance of functionality defined in the specification.</p> <!-- thanks to QA Framework -->
<div class="example">
<p>For example, while strongly discouraged from doing so, an implementation could add a new IDL
attribute "<code data-x="">typeTime</code>" to a control that returned the time it took the user
to select the current value of a control (say). On the other hand, defining a new control that
appears in a form's <code data-x="dom-form-elements">elements</code> array would be in violation
of the above requirement, as it would violate the definition of <code
data-x="dom-form-elements">elements</code> given in this specification.</p>
</div>
</div>
<hr>
<p>When vendor-neutral extensions to this specification are needed, either this specification can
be updated accordingly, or an extension specification can be written that overrides the
requirements in this specification. When someone applying this specification to their activities
decides that they will recognize the requirements of such an extension specification, it becomes
an <dfn data-x="other applicable specifications">applicable specification</dfn> for the purposes
of conformance requirements in this specification.</p>
<p class="note">Someone could write a specification that defines any arbitrary byte stream as
conforming, and then claim that their random junk is conforming. However, that does not mean that
their random junk actually is conforming for everyone's purposes: if someone else decides that
that specification does not apply to their work, then they can quite legitimately say that the
aforementioned random junk is just that, junk, and not conforming at all. As far as conformance
goes, what matters in a particular community is what that community <em>agrees</em> is
applicable.</p>
<div w-nodev>
<hr>
<p>User agents must treat elements and attributes that they do not understand as semantically
neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS
processors), but not inferring any meaning from them.</p>
<p>When support for a feature is disabled (e.g. as an emergency measure to mitigate a security
problem, or to aid in development, or for performance reasons), user agents must act as if they
had no support for the feature whatsoever, and as if the feature was not mentioned in this
specification. For example, if a particular feature is accessed via an attribute in a Web IDL
interface, the attribute itself would be omitted from the objects that implement that interface
— leaving the attribute on the object but making it return null or throw an exception is
insufficient.</p>
</div>
<div w-nodev>
<h4>Interactions with XPath and XSLT</h4>
<p id="xpath-1.0-processors">Implementations of XPath 1.0 that operate on <span>HTML
documents</span> parsed or created in the manners described in this specification (e.g. as part of
the <code data-x="">document.evaluate()</code> API) must act as if the following edit was applied
to the XPath 1.0 specification.</p>
<p>First, remove this paragraph:</p>
<blockquote cite="https://www.w3.org/TR/1999/REC-xpath-19991116/#node-tests">
<p>A <a href="https://www.w3.org/TR/REC-xml-names/#NT-QName">QName</a> in the node test is expanded
into an <a href="https://www.w3.org/TR/1999/REC-xpath-19991116/#dt-expanded-name">expanded-name</a>
using the namespace declarations from the expression context. This is the same way expansion is
done for element type names in start and end-tags except that the default namespace declared with
<code data-x="">xmlns</code> is not used: if the <a
href="https://www.w3.org/TR/REC-xml-names/#NT-QName">QName</a> does not have a prefix, then the
namespace URI is null (this is the same way attribute names are expanded). It is an error if the
<a href="https://www.w3.org/TR/REC-xml-names/#NT-QName">QName</a> has a prefix for which there is
no namespace declaration in the expression context.</p>
</blockquote>
<p>Then, insert in its place the following:</p>
<blockquote cite="https://www.w3.org/Bugs/Public/show_bug.cgi?id=7059#c37">
<p>A QName in the node test is expanded into an expanded-name using the namespace declarations
from the expression context. If the QName has a prefix, then there must be a<!-- added 2009-10-27
- https://www.w3.org/Bugs/Public/show_bug.cgi?id=8062 --> namespace declaration for this prefix in
the expression context, and the corresponding<!-- typo fixed 2009-10-27 -
https://www.w3.org/Bugs/Public/show_bug.cgi?id=8063 --> namespace URI is the one that is
associated with this prefix. It is an error if the QName has a prefix for which there is no
namespace declaration in the expression context. </p>
<p>If the QName has no prefix and the principal node type of the axis is element, then the
default element namespace is used. Otherwise, if the QName has no prefix, the namespace URI is
null. The default element namespace is a member of the context for the XPath expression. The
value of the default element namespace when executing an XPath expression through the DOM3 XPath
API is determined in the following way:</p>
<ol>
<li>If the context node is from an HTML DOM, the default element namespace is
"http://www.w3.org/1999/xhtml".</li>
<li>Otherwise, the default element namespace URI is null.</li>
</ol>
<p class="note">This is equivalent to adding the default element namespace feature of XPath 2.0
to XPath 1.0, and using the HTML namespace as the default element namespace for HTML documents.
It is motivated by the desire to have implementations be compatible with legacy HTML content
while still supporting the changes that this specification introduces to HTML regarding the
namespace used for HTML elements, and by the desire to use XPath 1.0 rather than XPath 2.0.</p>
</blockquote>
<p class="note">This change is a <span>willful violation</span> of the XPath 1.0 specification,
motivated by desire to have implementations be compatible with legacy content while still
supporting the changes that this specification introduces to HTML regarding which namespace is
used for HTML elements. <ref>XPATH10</ref></p> <!-- note: version matters for
this ref -->
<hr>
<p id="dom-based-xslt-1.0-processors">XSLT 1.0 processors outputting to a DOM when the output
method is "html" (either explicitly or via the defaulting rule in XSLT 1.0) are affected as
follows:</p>
<p>If the transformation program outputs an element in no namespace, the processor must, prior to
constructing the corresponding DOM element node, change the namespace of the element to the
<span>HTML namespace</span>, <span data-x="converted to ASCII lowercase">ASCII-lowercase</span> the
element's local name, and <span data-x="converted to ASCII lowercase">ASCII-lowercase</span> the
names of any non-namespaced attributes on the element.</p>
<p class="note">This requirement is a <span>willful violation</span> of the XSLT 1.0
specification, required because this specification changes the namespaces and case-sensitivity
rules of HTML in a manner that would otherwise be incompatible with DOM-based XSLT
transformations. (Processors that serialize the output are unaffected.) <ref>XSLT10</ref></p> <!--
note: version matters for this ref -->
<hr>
<p>This specification does not specify precisely how XSLT processing interacts with the <span>HTML
parser</span> infrastructure (for example, whether an XSLT processor acts as if it puts any
elements into a <span>stack of open elements</span>). However, XSLT processors must <span>stop
parsing</span> if they successfully complete, and must <span>update the current document
readiness</span> first to "<code data-x="">interactive</code>" and then to "<code
data-x="">complete</code>" if they are aborted.</p>
<hr>
<p>This specification does not specify how XSLT interacts with the <span
data-x="navigate">navigation</span> algorithm, how it fits in with the <span>event loop</span>, nor
how error pages are to be handled (e.g. whether XSLT errors are to replace an incremental XSLT
output, or are rendered inline, etc.).</p>
<p class="note">There are also additional non-normative comments regarding the interaction of XSLT
and HTML <a href="#scriptTagXSLT">in the <code>script</code> element section</a>, and of
XSLT, XPath, and HTML <a href="#template-XSLT-XPath">in the <code>template</code> element
section</a>.</p>
</div>
<h3 id="policy-controlled-features">Policy-controlled features</h3>
<p>This document defines the following <span
data-x="concept-policy-controlled-feature">policy-controlled features</span>:</p>
<ul>
<li>"<dfn data-x="autoplay-feature"><code data-x="">autoplay</code></dfn>", which has a <span
data-x="concept-default-allowlist">default allowlist</span> of <code
data-x="">'self'</code>.</li>
<li>"<dfn data-x="cross-origin-isolated-feature"><code
data-x="">cross-origin-isolated</code></dfn>", which has a <span
data-x="concept-default-allowlist">default allowlist</span> of <code
data-x="">'self'</code>.</li>
<li>"<dfn data-x="focus-without-user-activation-feature"><code
data-x="">focus-without-user-activation</code></dfn>", which has a <span
data-x="concept-default-allowlist">default allowlist</span> of <code
data-x="">'self'</code>.</li>
</ul>
<h3 split-filename="common-microsyntaxes">Common microsyntaxes</h3>
<p>There are various places in HTML that accept particular data types, such as dates or numbers.
This section describes what the conformance criteria for content in those formats is, and how to
parse them.</p>
<div w-nodev>
<p class="note">Implementers are strongly urged to carefully examine any third-party libraries
they might consider using to implement the parsing of syntaxes described below. For example, date
libraries are likely to implement error handling behavior that differs from what is required in
this specification, since error-handling behavior is often not defined in specifications that
describe date syntaxes similar to those used in this specification, and thus implementations tend
to vary greatly in how they handle errors.</p>
</div>
<div w-nodev>
<h4>Common parser idioms</h4>
<p>Some of the micro-parsers described below follow the pattern of having an <var>input</var>
variable that holds the string being parsed, and having a <var>position</var> variable pointing at
the next character to parse in <var>input</var>.</p>
</div>
<h4>Boolean attributes</h4>
<p>A number of attributes are <dfn data-x="boolean attribute">boolean attributes</dfn>. The
presence of a boolean attribute on an element represents the true value, and the absence of the
attribute represents the false value.</p>
<p>If the attribute is present, its value must either be the empty string or a value that is an
<span>ASCII case-insensitive</span> match for the attribute's canonical name, with no leading or
trailing whitespace.</p>
<p class="note">The values "true" and "false" are not allowed on boolean attributes. To represent
a false value, the attribute has to be omitted altogether.</p>
<div class="example">
<p>Here is an example of a checkbox that is checked and disabled. The <code
data-x="attr-input-checked">checked</code> and <code data-x="attr-fe-disabled">disabled</code>
attributes are the boolean attributes.</p>
<pre><code class="html"><label><input type=checkbox checked name=cheese disabled> Cheese</label></code></pre>
<p>This could be equivalently written as this:
<pre><code class="html"><label><input type=checkbox checked=checked name=cheese disabled=disabled> Cheese</label></code></pre>
<p>You can also mix styles; the following is still equivalent:</p>
<pre><code class="html"><label><input type='checkbox' checked name=cheese disabled=""> Cheese</label></code></pre>
</div>
<h4>Keywords and enumerated attributes</h4>
<p>Some attributes, called <dfn data-x="enumerated attribute" data-lt="enumerated attribute"
export>enumerated attributes</dfn>, take on a finite set of states. The state for such an
attribute is derived by combining the attribute's value, a set of keyword/state mappings given in
the specification of each attribute, and two possible special states that can also be given in the
specification of the attribute. These special states are the <dfn><i>invalid value
default</i></dfn> and the <dfn><i>missing value default</i></dfn>.</p>
<p class="note">Multiple keywords can map to the same state.</p>
<p class="note">The empty string can be a valid keyword. Note that the <i data-x="missing value
default">missing value default</i> applies only when the attribute is <em>missing</em>, not when
it is present with an empty string value.</p>
<p>To determine the state of an attribute, use the following steps:</p>
<ol>
<li>
<p>If the attribute is not specified:</p>
<ol>
<li><p>If the attribute has a <i data-x="missing value default">missing value default</i>
state defined, then return that <i data-x="missing value default">missing value default</i>
state.</p></li>
<li><p>Otherwise, return no state.</p></li>
</ol>
</li>
<li><p>If the attribute's value is an <span>ASCII case-insensitive</span> match for one of the
keywords defined for the attribute, then return the state represented by that keyword.</p></li>
<li><p>If the attribute has an <i data-x="invalid value default">invalid value default</i> state
defined, then return that <i data-x="invalid value default">invalid value default</i>
state.</p></li>
<li><p>Return no state.</p></li>
</ol>
<p>For authoring conformance purposes, if an enumerated attribute is specified, the attribute's
value must be an <span>ASCII case-insensitive</span> match for one of the conforming keywords for
that attribute, with no leading or trailing whitespace.</p>
<p>For <span data-x="reflect">reflection</span> purposes, states which have any keywords mapping
to them are said to have a <dfn>canonical keyword</dfn>. This is determined as follows:</p>
<ul>
<li><p>If there is only one keyword mapping to the given state, then it is that keyword.</p></li>
<li><p>If there is only one <em>conforming</em> keyword mapping to the given state, then it is
that conforming keyword.</p></li>
<li><p>Otherwise, the canonical keyword for the state will be explicitly given in the
specification for the attribute.</p></li>
</ul>
<h4>Numbers</h4>
<h5>Signed integers</h5>
<p>A string is a <dfn>valid integer</dfn> if it consists of one or more <span>ASCII digits</span>,
optionally prefixed with a U+002D HYPHEN-MINUS character (-).</p>
<p>A <span>valid integer</span> without a U+002D HYPHEN-MINUS (-) prefix represents the number
that is represented in base ten by that string of digits. A <span>valid integer</span>
<em>with</em> a U+002D HYPHEN-MINUS (-) prefix represents the number represented in base ten by
the string of digits that follows the U+002D HYPHEN-MINUS, subtracted from zero.</p>
<div w-nodev>
<p>The <dfn>rules for parsing integers</dfn> are as given in the following algorithm. When
invoked, the steps must be followed in the order given, aborting at the first step that returns a
value. This algorithm will return either an integer or an error.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially pointing at the
start of the string.</p></li>
<li><p>Let <var>sign</var> have the value "positive".</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, return an error.</p></li>
<li>
<p>If the character indicated by <var>position</var> (the first character) is a U+002D
HYPHEN-MINUS character (-):</p>
<ol>
<li>Let <var>sign</var> be "negative".</li>
<li>Advance <var>position</var> to the next character.</li>
<li>If <var>position</var> is past the end of <var>input</var>, return an error.</li>
</ol>
<p>Otherwise, if the character indicated by <var>position</var> (the first character) is a
U+002B PLUS SIGN character (+):</p>
<ol>
<li>Advance <var>position</var> to the next character. (The "<code data-x="">+</code>" is
ignored, but it is not conforming.)</li>
<li>If <var>position</var> is past the end of <var>input</var>, return an error.</li>
</ol>
</li>
<li><p>If the character indicated by <var>position</var> is not an <span data-x="ASCII
digits">ASCII digit</span>, then return an error.</p></li>
<!-- Ok. At this point we know we have a number. It might have trailing garbage which we'll
ignore, but it's a number, and we won't return an error. -->
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and interpret the resulting sequence as a base-ten
integer. Let <var>value</var> be that integer.</p></li>
<li><p>If <var>sign</var> is "positive", return <var>value</var>, otherwise return the result of
subtracting <var>value</var> from zero.</p></li>
</ol>
</div>
<h5>Non-negative integers</h5>
<p>A string is a <dfn>valid non-negative integer</dfn> if it consists of one or more <span>ASCII
digits</span>.</p>
<p>A <span>valid non-negative integer</span> represents the number that is represented in base ten
by that string of digits.</p>
<div w-nodev>
<p>The <dfn>rules for parsing non-negative integers</dfn> are as given in the following algorithm.
When invoked, the steps must be followed in the order given, aborting at the first step that
returns a value. This algorithm will return either zero, a positive integer, or an error.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>value</var> be the result of parsing <var>input</var> using the
<span>rules for parsing integers</span>.</p></li>
<li><p>If <var>value</var> is an error, return an error.</p></li>
<li><p>If <var>value</var> is less than zero, return an error.</p></li>
<li><p>Return <var>value</var>.</p></li>
</ol>
<!-- Implications: A leading + is ignored. A leading - is ignored if the value is zero. -->
</div>
<h5>Floating-point numbers</h5>
<p>A string is a <dfn>valid floating-point number</dfn> if it consists of:</p>
<ol>
<li><p>Optionally, a U+002D HYPHEN-MINUS character (-).</p></li>
<li>
<p>One or both of the following, in the given order:</p>
<ol>
<li><p>A series of one or more <span>ASCII digits</span>.</p></li>
<li>
<p>Both of the following, in the given order:</p>
<ol>
<li><p>A single U+002E FULL STOP character (.).</p></li>
<li><p>A series of one or more <span>ASCII digits</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Optionally:</p>
<ol>
<li><p>Either a U+0065 LATIN SMALL LETTER E character (e) or a U+0045 LATIN CAPITAL LETTER E
character (E).</p></li>
<li><p>Optionally, a U+002D HYPHEN-MINUS character (-) or U+002B PLUS SIGN character
(+).</p></li>
<li><p>A series of one or more <span>ASCII digits</span>.</p></li>
</ol>
</li>
</ol>
<p>A <span>valid floating-point number</span> represents the number obtained by multiplying the
significand by ten raised to the power of the exponent, where the significand is the first number,
interpreted as base ten (including the decimal point and the number after the decimal point, if
any, and interpreting the significand as a negative number if the whole string starts with a
U+002D HYPHEN-MINUS character (-) and the number is not zero), and where the exponent is the
number after the E, if any (interpreted as a negative number if there is a U+002D HYPHEN-MINUS
character (-) between the E and the number and the number is not zero, or else ignoring a U+002B
PLUS SIGN character (+) between the E and the number if there is one). If there is no E, then the
exponent is treated as zero.</p>
<p class="note">The Infinity and Not-a-Number (NaN) values are not <span data-x="valid
floating-point number">valid floating-point numbers</span>.</p>
<div w-nodev>
<p class="note">The <span>valid floating-point number</span> concept is typically only used to
restrict what is allowed for authors, while the user agent requirements use the <span>rules for
parsing floating-point number values</span> below (e.g., the <code
data-x="attr-progress-max">max</code> attribute of the <code>progress</code> element). However, in
some cases the user agent requirements include checking if a string is a <span>valid
floating-point number</span> (e.g., the <span>value sanitization algorithm</span> for the <span
data-x="attr-input-type-number">Number</span> state of the <code>input</code> element, or the
<span>parse a srcset attribute</span> algorithm).</p>
<p>The <dfn data-x="best representation of the number as a floating-point number">best
representation of the number <var>n</var> as a floating-point number</dfn> is the string
obtained from running <span>ToString</span>(<var>n</var>). The abstract operation
<span>ToString</span> is not uniquely determined. When there are multiple possible strings that
could be obtained from <span>ToString</span> for a particular value, the user agent must always
return the same string for that value (though it may differ from the value used by other user
agents).</p>
<p>The <dfn export>rules for parsing floating-point number values</dfn> are as given in the
following algorithm. This algorithm must be aborted at the first step that returns something.
This algorithm will return either a number or an error.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially pointing at the
start of the string.</p></li>
<li><p>Let <var>value</var> have the value 1.</li>
<li><p>Let <var>divisor</var> have the value 1.</p></li>
<li><p>Let <var>exponent</var> have the value 1.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, return an error.</p></li>
<li>
<p>If the character indicated by <var>position</var> is a U+002D HYPHEN-MINUS character (-):</p>
<ol>
<li>Change <var>value</var> and <var>divisor</var> to −1.</li>
<li>Advance <var>position</var> to the next character.</li>
<li>If <var>position</var> is past the end of <var>input</var>, return an error.</li>
</ol>
<p>Otherwise, if the character indicated by <var>position</var> (the first character) is a
U+002B PLUS SIGN character (+):</p>
<ol>
<li>Advance <var>position</var> to the next character. (The "<code data-x="">+</code>"
is ignored, but it is not conforming.)</li>
<li>If <var>position</var> is past the end of <var>input</var>, return an error.</li>
</ol>
</li>
<li><p>If the character indicated by <var>position</var> is a U+002E FULL STOP (.), and that is
not the last character in <var>input</var>, and the character after the character indicated by
<var>position</var> is an <span data-x="ASCII digits">ASCII digit</span>, then set
<var>value</var> to zero and jump to the step labeled <i>fraction</i>.</p> <!-- we have to check
there's a number so that ".e1" fails to parse but ".0" does not -->
<li><p>If the character indicated by <var>position</var> is not an <span data-x="ASCII
digits">ASCII digit</span>, then return an error.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and interpret the resulting sequence as a base-ten
integer. Multiply <var>value</var> by that integer.</p></li>
<li>If <var>position</var> is past the end of <var>input</var>, jump to the step labeled
<i>conversion</i>.</li>
<li><p><i>Fraction</i>: If the character indicated by <var>position</var> is a U+002E
FULL STOP (.), run these substeps:</p>
<ol>
<li><p>Advance <var>position</var> to the next character.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, or if the character
indicated by <var>position</var> is not an <span data-x="ASCII digits">ASCII digit</span>,
U+0065 LATIN SMALL LETTER E (e), or U+0045 LATIN CAPITAL LETTER E (E), then jump to the step
labeled <i>conversion</i>.</li>
<li><p>If the character indicated by <var>position</var> is a U+0065 LATIN SMALL
LETTER E character (e) or a U+0045 LATIN CAPITAL LETTER E character (E), skip the remainder of
these substeps.</p>
<li><p><i>Fraction loop</i>: Multiply <var>divisor</var> by ten.</p></li>
<li>Add the value of the character indicated by <var>position</var>, interpreted as a
base-ten digit (0..9) and divided by <var>divisor</var>, to <var>value</var>.</li>
<li><p>Advance <var>position</var> to the next character.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then jump to the step
labeled <i>conversion</i>.</li>
<li><p>If the character indicated by <var>position</var> is an <span data-x="ASCII
digits">ASCII digit</span>, jump back to the step labeled <i>fraction loop</i> in these
substeps.</p></li>
</ol>
</li>
<li><p>If the character indicated by <var>position</var> is U+0065 (e) or a U+0045 (E), then:</p>
<ol>
<li><p>Advance <var>position</var> to the next character.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then jump to the step
labeled <i>conversion</i>.</li>
<li>
<p>If the character indicated by <var>position</var> is a U+002D HYPHEN-MINUS character
(-):</p>
<ol>
<li>Change <var>exponent</var> to −1.</li>
<li>Advance <var>position</var> to the next character.</li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then jump to the step
labeled <i>conversion</i>.</li>
</ol>
<p>Otherwise, if the character indicated by <var>position</var> is a U+002B PLUS SIGN
character (+):</p>
<ol>
<li>Advance <var>position</var> to the next character.</li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then jump to the step
labeled <i>conversion</i>.</li>
</ol>
</li>
<li><p>If the character indicated by <var>position</var> is not an <span data-x="ASCII
digits">ASCII digit</span>, then jump to the step labeled <i>conversion</i>.</li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and interpret the resulting sequence as a base-ten
integer. Multiply <var>exponent</var> by that integer.</p></li>
<li><p>Multiply <var>value</var> by ten raised to the <var>exponent</var>th power.</p></li>
</ol>
</li>
<li><p><i>Conversion</i>: Let <var>S</var> be the set of finite IEEE 754 double-precision
floating-point values except −0, but with two special values added: 2<sup>1024</sup> and −2<sup>1024</sup>.</p></li>
<li><p>Let <var>rounded-value</var> be the number in <var>S</var> that is closest to
<var>value</var>, selecting the number with an even significand if there are two equally close
values. (The two special values 2<sup>1024</sup> and −2<sup>1024</sup>
are considered to have even significands for this purpose.)</p></li>
<li><p>If <var>rounded-value</var> is 2<sup>1024</sup> or −2<sup>1024</sup>, return an error.</p></li>
<li><p>Return <var>rounded-value</var>.</p></li>
</ol>
</div>
<div w-nodev>
<h5 id="percentages-and-dimensions">Percentages and lengths</h5>
<p>The <dfn>rules for parsing dimension values</dfn> are as given in the following algorithm. When
invoked, the steps must be followed in the order given, aborting at the first step that returns a
value. This algorithm will return either a number greater than or equal to 0.0, or failure; if a
number is returned, then it is further categorized as either a percentage or a length.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a <span>position variable</span> for <var>input</var>,
initially pointing at the start of <var>input</var>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var> or the code point at
<var>position</var> within <var>input</var> is not an <span data-x="ASCII digits">ASCII
digit</span>, then return failure.</p></li>
<!-- Ok. At this point we know we have a number. It might have trailing garbage which we'll
ignore, but it's a number, and we won't return an error. -->
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and interpret the resulting sequence as a base-ten
integer. Let <var>value</var> be that number.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then return <var>value</var>
as a length.</p></li>
<li>
<p>If the code point at <var>position</var> within <var>input</var> is U+002E (.), then:</p>
<ol>
<li><p>Advance <var>position</var> by 1.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var> or the code point at
<var>position</var> within <var>input</var> is not an <span data-x="ASCII digits">ASCII
digit</span>, then return the <span>current dimension value</span> with <var>value</var>,
<var>input</var>, and <var>position</var>.</p></li>
<li><p>Let <var>divisor</var> have the value 1.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>Multiply <var>divisor</var> by ten.</p></li>
<li><p>Add the value of the code point at <var>position</var> within <var>input</var>,
interpreted as a base-ten digit (0..9) and divided by <var>divisor</var>, to
<var>value</var>.</p></li>
<li><p>Advance <var>position</var> by 1.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then return
<var>value</var> as a length.</p></li>
<li><p>If the code point at <var>position</var> within <var>input</var> is not an <span
data-x="ASCII digits">ASCII digit</span>, then <span>break</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return the <span>current dimension value</span> with <var>value</var>, <var>input</var>,
and <var>position</var>.</p></li>
</ol>
<p>The <dfn>current dimension value</dfn>, given <var>value</var>, <var>input</var>, and
<var>position</var>, is determined as follows:</p>
<ol>
<li><p>If <var>position</var> is past the end of <var>input</var>, then return <var>value</var>
as a length.</p></li>
<li><p>If the code point at <var>position</var> within <var>input</var> is U+0025 (%), then
return <var>value</var> as a percentage.</p></li>
<li><p>Return <var>value</var> as a length.</p></li>
</ol>
<h5 id="nonzero-percentages-and-lengths">Nonzero percentages and lengths</h5>
<p>The <dfn id="rules-for-parsing-non-zero-dimension-values">rules for parsing nonzero dimension
values</dfn> are as given in the following algorithm. When invoked, the steps must be followed in
the order given, aborting at the first step that returns a value. This algorithm will return
either a number greater than 0.0, or an error; if a number is returned, then it is further
categorized as either a percentage or a length.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>value</var> be the result of parsing <var>input</var> using the <span>rules for
parsing dimension values</span>.</p></li>
<li><p>If <var>value</var> is an error, return an error.</p></li>
<li><p>If <var>value</var> is zero, return an error.</p></li>
<li><p>If <var>value</var> is a percentage, return <var>value</var> as a percentage.</p></li>
<li><p>Return <var>value</var> as a length.</p></li>
</ol>
</div>
<h5>Lists of floating-point numbers</h5>
<p>A <dfn>valid list of floating-point numbers</dfn> is a number of <span data-x="valid
floating-point number">valid floating-point numbers</span> separated by U+002C COMMA characters,
with no other characters (e.g. no <span>ASCII whitespace</span>). In addition, there might be
restrictions on the number of floating-point numbers that can be given, or on the range of values
allowed.</p>
<div w-nodev>
<p>The <dfn>rules for parsing a list of floating-point numbers</dfn> are as follows:</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially pointing at the
start of the string.</p></li>
<li><p>Let <var>numbers</var> be an initially empty list of floating-point numbers. This list
will be the result of this algorithm.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII whitespace</span>,
U+002C COMMA, or U+003B SEMICOLON characters from <var>input</var> given <var>position</var>.
This skips past any leading delimiters.</p></li>
<li><p>While <var>position</var> is not past the end of <var>input</var>:</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are not <span>ASCII
whitespace</span>, U+002C COMMA, U+003B SEMICOLON, <span>ASCII digits</span>, U+002E FULL STOP,
or U+002D HYPHEN-MINUS characters from <var>input</var> given <var>position</var>. This skips
past leading garbage.</p></li>
<li><p><span>Collect a sequence of code points</span> that are not <span>ASCII
whitespace</span>, U+002C COMMA, or U+003B SEMICOLON characters from <var>input</var> given
<var>position</var>, and let <var>unparsed number</var> be the result.</p></li>
<li><p>Let <var>number</var> be the result of parsing <var>unparsed number</var> using the
<span>rules for parsing floating-point number values</span>.</p></li>
<li><p>If <var>number</var> is an error, set <var>number</var> to zero.</p></li>
<li><p>Append <var>number</var> to <var>numbers</var>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII whitespace</span>,
U+002C COMMA, or U+003B SEMICOLON characters from <var>input</var> given <var>position</var>.
This skips past the delimiter.</p></li>
</ol>
</li>
<li><p>Return <var>numbers</var>.</p></li>
</ol>
</div>
<div w-nodev>
<h5>Lists of dimensions</h5>
<!-- no definition of a type since no conforming feature uses this syntax (it's only used in
cols="" and rows="" on <frameset> elements -->
<p>The <dfn>rules for parsing a list of dimensions</dfn> are as follows. These rules return a list
of zero or more pairs consisting of a number and a unit, the unit being one of <i>percentage</i>,
<i>relative</i>, and <i>absolute</i>.</p>
<ol>
<li><p>Let <var>raw input</var> be the string being parsed.</p></li>
<li><p>If the last character in <var>raw input</var> is a U+002C COMMA character (,),
then remove that character from <var>raw input</var>.</p></li>
<li><p><span data-x="split a string on commas">Split the string <var>raw input</var> on
commas</span>. Let <var>raw tokens</var> be the resulting list of tokens.</p></li>
<li><p>Let <var>result</var> be an empty list of number/unit pairs.</p></li>
<li>
<p>For each token in <var>raw tokens</var>, run the following substeps:</p>
<ol>
<li><p>Let <var>input</var> be the token.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>,
initially pointing at the start of the string.</p></li>
<li><p>Let <var>value</var> be the number 0.</p></li>
<li><p>Let <var>unit</var> be <i>absolute</i>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, set <var>unit</var> to <i>relative</i> and jump to the last substep.</p></li>
<li><p>If the character at <var>position</var> is an <span data-x="ASCII
digits">ASCII digit</span>, <span>collect a sequence of code points</span> that are <span>ASCII
digits</span> from <var>input</var> given <var>position</var>, interpret the resulting sequence
as an integer in base ten, and increment <var>value</var> by that integer.</p></li>
<li>
<p>If the character at <var>position</var> is U+002E (.), then:</p>
<ol>
<li><p><span>Collect a sequence of code points</span> consisting of <span>ASCII
whitespace</span> and <span>ASCII digits</span> from <var>input</var> given
<var>position</var>. Let <var>s</var> be the resulting sequence.</p></li>
<li><p>Remove all <span>ASCII whitespace</span> in <var>s</var>.</p></li>
<li>
<p>If <var>s</var> is not the empty string, then:</p>
<ol>
<li><p>Let <var>length</var> be the number of characters in <var>s</var> (after the spaces were removed).</p></li>
<li><p>Let <var>fraction</var> be the result of interpreting <var>s</var> as a base-ten integer, and then dividing that number by <span
data-x="">10<sup><var>length</var></sup></span>.</li>
<li><p>Increment <var>value</var> by <var>fraction</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li>
<p>If the character at <var>position</var> is a U+0025 PERCENT SIGN character (%),
then set <var>unit</var> to <i>percentage</i>.</p>
<p>Otherwise, if the character at <var>position</var> is a U+002A ASTERISK character
(*), then set <var>unit</var> to <i>relative</i>.</p>
</li>
<!-- the remaining characters in /input/ are ignored -->
<li><p>Add an entry to <var>result</var> consisting of the number given by <var>value</var> and the unit given by <var>unit</var>.</p></li>
</ol>
</li>
<li><p>Return the list <var>result</var>.</p></li>
</ol>
</div>
<h4>Dates and times</h4>
<p>In the algorithms below, the <dfn>number of days in month <var>month</var> of year
<var>year</var></dfn> is: <em>31</em> if <var>month</var> is 1, 3, 5, 7, 8,
10, or 12; <em>30</em> if <var>month</var> is 4, 6, 9, or 11; <em>29</em> if <var>month</var> is 2
and <var>year</var> is a number divisible by 400, or if <var>year</var> is a number divisible by 4
but not by 100; and <em>28</em> otherwise. This takes into account leap years in the Gregorian
calendar. <ref>GREGORIAN</ref></p>
<p>When <span>ASCII digits</span> are used in the date and time syntaxes defined in this section,
they express numbers in base ten.</p>
<div w-nodev>
<p class="note">While the formats described here are intended to be subsets of the corresponding
ISO8601 formats, this specification defines parsing rules in much more detail than ISO8601.
Implementers are therefore encouraged to carefully examine any date parsing libraries before using
them to implement the parsing rules described below; ISO8601 libraries might not parse dates and
times in exactly the same manner. <ref>ISO8601</ref></p>
</div>
<p>Where this specification refers to the <dfn>proleptic Gregorian calendar</dfn>, it means the
modern Gregorian calendar, extrapolated backwards to year 1. A date in the <span>proleptic
Gregorian calendar</span>, sometimes explicitly referred to as a <dfn>proleptic-Gregorian
date</dfn>, is one that is described using that calendar even if that calendar was not in use at
the time (or place) in question. <ref>GREGORIAN</ref></p>
<p class="note">The use of the Gregorian calendar as the wire format in this specification is an
arbitrary choice resulting from the cultural biases of those involved in the decision. See also
the section discussing <a href="#input-author-notes">date, time, and number formats</a> in forms
<span w-nodev>(for authors), <a href="#input-impl-notes">implementation notes regarding
localization of form controls</a>,</span> and the <code>time</code> element.</p>
<h5>Months</h5>
<p>A <dfn data-x="concept-month">month</dfn> consists of a specific <span>proleptic-Gregorian
date</span> with no time-zone information and no date information beyond a year and a month.
<ref>GREGORIAN</ref></p>
<p>A string is a <dfn>valid month string</dfn> representing a year <var>year</var> and
month <var>month</var> if it consists of the following components in the given order:</p>
<ol>
<li>Four or more <span>ASCII digits</span>, representing <var>year</var>, where <var>year</var> > 0</li>
<li>A U+002D HYPHEN-MINUS character (-)</li>
<li>Two <span>ASCII digits</span>, representing the month <var>month</var>, in the range
1 ≤ <var>month</var> ≤ 12</li>
</ol>
<div w-nodev>
<p>The rules to <dfn>parse a month string</dfn> are as follows. This will return either a year and
month, or nothing. If at any point the algorithm says that it "fails", this means that it is
aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a month component</span> to obtain <var>year</var> and <var>month</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the
end of <var>input</var>, then fail.</p></li>
<li><p>Return <var>year</var> and <var>month</var>.</p></li>
</ol>
<p>The rules to <dfn>parse a month component</dfn>, given an <var>input</var> string and
a <var>position</var>, are as follows. This will return either a year and a month, or
nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
point and returns nothing.</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not at least four
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>year</var>.</p></li>
<li><p>If <var>year</var> is not a number greater than zero, then fail.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+002D HYPHEN-MINUS character, then fail.
Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>month</var>.</p></li>
<li><p>If <var>month</var> is not a number in the range 1 ≤ <var>month</var> ≤ 12, then fail.</p></li>
<li><p>Return <var>year</var> and <var>month</var>.</p></li>
</ol>
</div>
<h5>Dates</h5>
<p>A <dfn data-x="concept-date">date</dfn> consists of a specific <span>proleptic-Gregorian
date</span> with no time-zone information, consisting of a year, a month, and a day.
<ref>GREGORIAN</ref></p>
<p>A string is a <dfn>valid date string</dfn> representing a year <var>year</var>, month
<var>month</var>, and day <var>day</var> if it consists of the following
components in the given order:</p>
<ol>
<li>A <span>valid month string</span>, representing <var>year</var> and <var>month</var></li>
<li>A U+002D HYPHEN-MINUS character (-)</li>
<li>Two <span>ASCII digits</span>, representing <var>day</var>, in the range
1 ≤ <var>day</var> ≤ <var>maxday</var> where <var>maxday</var> is the <span data-x="number of days in month month of year year">number of
days in the month <var>month</var> and year <var>year</var></span></li>
</ol>
<div w-nodev>
<p>The rules to <dfn>parse a date string</dfn> are as follows. This will return either a date, or
nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a date component</span> to obtain <var>year</var>, <var>month</var>, and <var>day</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Let <var>date</var> be the date with year <var>year</var>, month <var>month</var>, and day <var>day</var>.</p></li>
<li><p>Return <var>date</var>.</p></li>
</ol>
<p>The rules to <dfn>parse a date component</dfn>, given an <var>input</var> string and a
<var>position</var>, are as follows. This will return either a year, a month, and a day,
or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at
that point and returns nothing.</p>
<ol>
<li><p><span>Parse a month component</span> to obtain <var>year</var> and <var>month</var>. If this returns nothing, then fail.</li>
<li><p>Let <var>maxday</var> be the <span>number of days in month <var>month</var> of year <var>year</var></span>.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+002D HYPHEN-MINUS character, then fail.
Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>day</var>.</p></li>
<li><p>If <var>day</var> is not a number in the range 1 ≤ <var>day</var> ≤ <var>maxday</var>, then fail.</li>
<li><p>Return <var>year</var>, <var>month</var>, and <var>day</var>.</p></li>
</ol>
</div>
<h5>Yearless dates</h5>
<p>A <dfn data-x="concept-yearless-date">yearless date</dfn> consists of a Gregorian month and a
day within that month, but with no associated year. <ref>GREGORIAN</ref></p>
<p>A string is a <dfn>valid yearless date string</dfn> representing a month <var>month</var> and a day <var>day</var> if it consists of the following components
in the given order:</p>
<ol>
<li>Optionally, two U+002D HYPHEN-MINUS characters (-)</li>
<li>Two <span>ASCII digits</span>, representing the month <var>month</var>, in the range
1 ≤ <var>month</var> ≤ 12</li>
<li>A U+002D HYPHEN-MINUS character (-)</li>
<li>Two <span>ASCII digits</span>, representing <var>day</var>, in the range
1 ≤ <var>day</var> ≤ <var>maxday</var> where <var>maxday</var> is the <span data-x="number of days in month month of year year">number of
days</span> in the month <var>month</var> and any arbitrary leap year (e.g. 4 or
2000)</li>
</ol>
<p class="note">In other words, if the <var>month</var> is "<code data-x="">02</code>",
meaning February, then the day can be 29, as if the year was a leap year.</p>
<div w-nodev>
<p>The rules to <dfn>parse a yearless date string</dfn> are as follows. This will return either a
month and a day, or nothing. If at any point the algorithm says that it "fails", this means that
it is aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a yearless date component</span> to obtain <var>month</var> and <var>day</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Return <var>month</var> and <var>day</var>.</p></li>
</ol>
<p>The rules to <dfn>parse a yearless date component</dfn>, given an <var>input</var>
string and a <var>position</var>, are as follows. This will return either a month and a
day, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted
at that point and returns nothing.</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are U+002D HYPHEN-MINUS characters (-)
from <var>input</var> given <var>position</var>. If the collected sequence is not exactly zero or
two characters long, then fail.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>month</var>.</p></li>
<li><p>If <var>month</var> is not a number in the range 1 ≤ <var>month</var> ≤ 12, then fail.</p></li>
<li><p>Let <var>maxday</var> be the <span data-x="number of days in month month of year
year">number of days</span> in month <var>month</var> of any arbitrary leap year (e.g. 4
or 2000).</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+002D HYPHEN-MINUS character, then fail.
Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>day</var>.</p></li>
<li><p>If <var>day</var> is not a number in the range 1 ≤ <var>day</var> ≤ <var>maxday</var>, then fail.</li>
<li><p>Return <var>month</var> and <var>day</var>.</p></li>
</ol>
</div>
<h5>Times</h5>
<p>A <dfn data-x="concept-time">time</dfn> consists of a specific time with no time-zone
information, consisting of an hour, a minute, a second, and a fraction of a second.</p>
<p>A string is a <dfn>valid time string</dfn> representing an hour <var>hour</var>, a
minute <var>minute</var>, and a second <var>second</var> if it consists of the
following components in the given order:</p>
<ol>
<li>Two <span>ASCII digits</span>, representing <var>hour</var>, in the range
0 ≤ <var>hour</var> ≤ 23</li>
<li>A U+003A COLON character (:)</li>
<li>Two <span>ASCII digits</span>, representing <var>minute</var>, in the range
0 ≤ <var>minute</var> ≤ 59</li>
<li>If <var>second</var> is nonzero, or optionally if <var>second</var> is
zero:
<ol>
<li>A U+003A COLON character (:)</li>
<li>Two <span>ASCII digits</span>, representing the integer part of <var>second</var>,
in the range 0 ≤ <var>s</var> ≤ 59</li>
<li>If <var>second</var> is not an integer, or optionally if <var>second</var> is an integer:
<ol>
<li>A U+002E FULL STOP character (.)</li>
<li>One, two, or three <span>ASCII digits</span>, representing the fractional part of <var>second</var></li>
</ol>
</li>
</ol>
</li>
</ol>
<p class="note">The <var>second</var> component cannot be 60 or 61; leap seconds cannot
be represented.</p>
<div w-nodev>
<p>The rules to <dfn>parse a time string</dfn> are as follows. This will return either a time, or
nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a time component</span> to obtain <var>hour</var>, <var>minute</var>, and <var>second</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Let <var>time</var> be the time with hour <var>hour</var>, minute <var>minute</var>, and second <var>second</var>.</p></li>
<li><p>Return <var>time</var>.</p></li>
</ol>
<p>The rules to <dfn>parse a time component</dfn>, given an <var>input</var> string and a
<var>position</var>, are as follows. This will return either an hour, a minute, and a
second, or nothing. If at any point the algorithm says that it "fails", this means that it is
aborted at that point and returns nothing.</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>hour</var>.</p></li>
<li>If <var>hour</var> is not a number in the range 0 ≤ <var>hour</var> ≤ 23, then fail.</li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+003A COLON character, then fail. Otherwise,
move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>minute</var>.</p></li>
<li>If <var>minute</var> is not a number in the range 0 ≤ <var>minute</var> ≤ 59, then fail.</li>
<li><p>Let <var>second</var> be 0.</p></li>
<li>
<p>If <var>position</var> is not beyond the end of <var>input</var> and the character at
<var>position</var> is U+003A (:), then:</p>
<ol>
<li><p>Advance <var>position</var> to the next character in <var>input</var>.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var>, or at
the last character in <var>input</var>, or if the next <em>two</em> characters in <var>input</var> starting at <var>position</var> are not both <span>ASCII
digits</span>, then fail.</p></li>
<li><p><span>Collect a sequence of code points</span> that are either <span>ASCII digits</span>
or U+002E FULL STOP characters from <var>input</var> given <var>position</var>. If the
collected sequence is three characters long, or if it is longer than three characters long and
the third character is not a U+002E FULL STOP character, or if it has more than one U+002E FULL
STOP character, then fail. Otherwise, interpret the resulting sequence as a base-ten number
(possibly with a fractional part). Set <var>second</var> to that number.</p></li>
<li><p>If <var>second</var> is not a number in the range
0 ≤ <var>second</var> < 60, then fail.</p></li>
</ol>
</li>
<li><p>Return <var>hour</var>, <var>minute</var>, and <var>second</var>.</p></li>
</ol>
</div>
<h5>Local dates and times</h5>
<p>A <dfn data-x="concept-datetime-local">local date and time</dfn> consists of a specific
<span>proleptic-Gregorian date</span>, consisting of a year, a month, and a day, and a time,
consisting of an hour, a minute, a second, and a fraction of a second, but expressed without a
time zone. <ref>GREGORIAN</ref></p>
<p>A string is a <dfn>valid local date and time string</dfn> representing a date and time if it
consists of the following components in the given order:</p>
<ol>
<li>A <span>valid date string</span> representing the date</li>
<li>A U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character</li>
<li>A <span>valid time string</span> representing the time</li>
</ol>
<p>A string is a <!--en-GB--><dfn id="valid-normalised-local-date-and-time-string">valid
normalized local date and time string</dfn> representing a date and time if it consists of the
following components in the given order:</p>
<ol>
<li>A <span>valid date string</span> representing the date</li>
<li>A U+0054 LATIN CAPITAL LETTER T character (T)</li>
<li>A <span>valid time string</span> representing the time, expressed as the shortest possible
string for the given time (e.g. omitting the seconds component entirely if the given time is zero
seconds past the minute)</li>
</ol>
<div w-nodev>
<p>The rules to <dfn>parse a local date and time string</dfn> are as follows. This will return
either a date and time, or nothing. If at any point the algorithm says that it "fails", this means
that it is aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a date component</span> to obtain <var>year</var>, <var>month</var>, and <var>day</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is neither a U+0054 LATIN CAPITAL LETTER T character
(T) nor a U+0020 SPACE character, then fail. Otherwise, move <var>position</var>
forwards one character.</p></li>
<li><p><span>Parse a time component</span> to obtain <var>hour</var>, <var>minute</var>, and <var>second</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Let <var>date</var> be the date with year <var>year</var>, month <var>month</var>, and day <var>day</var>.</p></li>
<li><p>Let <var>time</var> be the time with hour <var>hour</var>, minute <var>minute</var>, and second <var>second</var>.</p></li>
<li><p>Return <var>date</var> and <var>time</var>.</p></li>
</ol>
</div>
<h5>Time zones</h5>
<p>A <dfn data-x="concept-timezone">time-zone offset</dfn> consists of a signed number of hours and
minutes.</p>
<p>A string is a <dfn>valid time-zone offset string</dfn> representing a time-zone offset if it
consists of either:</p>
<ul>
<li><p>A U+005A LATIN CAPITAL LETTER Z character (Z), allowed only if the time zone is
UTC</p></li>
<li>
<p>Or, the following components, in the given order:</p>
<ol>
<li>Either a U+002B PLUS SIGN character (+) or, if the time-zone offset is not zero, a U+002D
HYPHEN-MINUS character (-), representing the sign of the time-zone offset</li>
<!-- the -00:00 offset is disallowed because RFC3339 gives it a special semantic -->
<li>Two <span>ASCII digits</span>, representing the hours component <var>hour</var> of
the time-zone offset, in the range 0 ≤ <var>hour</var> ≤ 23</li>
<li>Optionally, a U+003A COLON character (:)</li>
<li>Two <span>ASCII digits</span>, representing the minutes component <var>minute</var> of the time-zone offset, in the range 0 ≤ <var>minute</var> ≤ 59</li>
</ol>
</li>
</ul>
<p class="note">This format allows for time-zone offsets from -23:59 to +23:59. Right now, in
practice, the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component
of offsets of actual time zones is always either 00, 30, or 45. There is no guarantee that this
will remain so forever, however, since time zones are used as political footballs and are thus
subject to very whimsical policy decisions.</p>
<p class="note">See also the usage notes and examples in the <span data-x="concept-datetime">global
date and time</span> section below for details on using time-zone offsets with historical times
that predate the formation of formal time zones.</p>
<div w-nodev>
<p>The rules to <dfn>parse a time-zone offset string</dfn> are as follows. This will return either
a time-zone offset, or nothing. If at any point the algorithm says that it "fails", this means
that it is aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a time-zone offset component</span> to obtain <var>timezone<sub>hours</sub></var> and <var>timezone<sub>minutes</sub></var>. If this
returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Return the time-zone offset that is <var>timezone<sub>hours</sub></var>
hours and <var>timezone<sub>minutes</sub></var> minutes from UTC.</p></li>
</ol>
<p>The rules to <dfn>parse a time-zone offset component</dfn>, given an <var>input</var>
string and a <var>position</var>, are as follows. This will return either time-zone hours
and time-zone minutes, or nothing. If at any point the algorithm says that it "fails", this means
that it is aborted at that point and returns nothing.</p>
<ol>
<li>
<p>If the character at <var>position</var> is a U+005A LATIN CAPITAL LETTER Z character
(Z), then:</p>
<ol>
<li><p>Let <var>timezone<sub>hours</sub></var> be 0.</p></li>
<li><p>Let <var>timezone<sub>minutes</sub></var> be 0.</p></li>
<li><p>Advance <var>position</var> to the next character in <var>input</var>.</p></li>
</ol>
<p>Otherwise, if the character at <var>position</var> is either a U+002B PLUS SIGN (+)
or a U+002D HYPHEN-MINUS (-), then:</p>
<ol>
<li><p>If the character at <var>position</var> is a U+002B PLUS SIGN (+), let <var>sign</var> be "positive". Otherwise, it's a U+002D HYPHEN-MINUS (-); let <var>sign</var> be "negative".</p></li>
<li><p>Advance <var>position</var> to the next character in <var>input</var>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. Let <var>s</var> be the collected
sequence.</p></li>
<li>
<p>If <var>s</var> is exactly two characters long, then:</p>
<ol>
<li><p>Interpret <var>s</var> as a base-ten integer. Let that number be the <var>timezone<sub>hours</sub></var>.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if
the character at <var>position</var> is not a U+003A COLON character, then fail.
Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten
integer. Let that number be the <var>timezone<sub>minutes</sub></var>.</p></li>
</ol>
<p>If <var>s</var> is exactly four characters long, then:</p>
<ol>
<li><p>Interpret the first two characters of <var>s</var> as a base-ten integer. Let
that number be the <var>timezone<sub>hours</sub></var>.</p></li>
<li><p>Interpret the last two characters of <var>s</var> as a base-ten integer. Let
that number be the <var>timezone<sub>minutes</sub></var>.</p></li>
</ol>
<p>Otherwise, fail.</p>
</li>
<li>If <var>timezone<sub>hours</sub></var> is not a number in the range
0 ≤ <var>timezone<sub>hours</sub></var> ≤ 23, then
fail.</li>
<li>If <var>sign</var> is "negative", then negate <var>timezone<sub>hours</sub></var>.</li>
<li>If <var>timezone<sub>minutes</sub></var> is not a number in the range
0 ≤ <var>timezone<sub>minutes</sub></var> ≤ 59,
then fail.</li>
<li>If <var>sign</var> is "negative", then negate <var>timezone<sub>minutes</sub></var>.</li>
</ol>
<p>Otherwise, fail.</p>
</li>
<li><p>Return <var>timezone<sub>hours</sub></var> and <var>timezone<sub>minutes</sub></var>.</p></li>
</ol>
</div>
<h5>Global dates and times</h5>
<p>A <dfn data-x="concept-datetime">global date and time</dfn> consists of a specific
<span>proleptic-Gregorian date</span>, consisting of a year, a month, and a day, and a time,
consisting of an hour, a minute, a second, and a fraction of a second, expressed with a time-zone
offset, consisting of a signed number of hours and minutes. <ref>GREGORIAN</ref></p>
<p>A string is a <dfn>valid global date and time string</dfn> representing a date, time, and a
time-zone offset if it consists of the following components in the given order:</p>
<ol>
<li>A <span>valid date string</span> representing the date</li>
<li>A U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character</li>
<li>A <span>valid time string</span> representing the time</li>
<li>A <span>valid time-zone offset string</span> representing the time-zone offset</li>
</ol>
<p>Times in dates before the formation of UTC in the mid-twentieth century must be expressed and
interpreted in terms of UT1 (contemporary Earth solar time at the 0° longitude), not UTC (the
approximation of UT1 that ticks in SI seconds). Time before the formation of time zones must be
expressed and interpreted as UT1 times with explicit time zones that approximate the contemporary
difference between the appropriate local time and the time observed at the location of Greenwich,
London.</p>
<div class="example">
<p>The following are some examples of dates written as <span data-x="valid global date and time
string">valid global date and time strings</span>.</p>
<dl>
<dt>"<code data-x="">0037-12-13 00:00Z</code>"</dt>
<dd>Midnight in areas using London time on the birthday of Nero (the Roman Emperor). See below
for further discussion on which date this actually corresponds to.</dd>
<dt>"<code data-x="">1979-10-14T12:00:00.001-04:00</code>"</dt>
<dd>One millisecond after noon on October 14th 1979, in the time zone in use on the east coast
of the USA during daylight saving time.</dd>
<dt>"<code data-x="">8592-01-01T02:09+02:09</code>"</dt>
<dd>Midnight UTC on the 1st of January, 8592. The time zone associated with that time is two
hours and nine minutes ahead of UTC, which is not currently a real time zone, but is nonetheless
allowed.</dd>
</dl>
<p>Several things are notable about these dates:</p>
<ul>
<li>Years with fewer than four digits have to be zero-padded. The date "37-12-13" would not be a
valid date.</li>
<li>If the "<code data-x="">T</code>" is replaced by a space, it must be a single space
character. The string "<code data-x="">2001-12-21 12:00Z</code>" (with two spaces
between the components) would not be parsed successfully.</li>
<li>To unambiguously identify a moment in time prior to the introduction of the Gregorian
calendar (insofar as moments in time before the formation of UTC can be unambiguously
identified), the date has to be first converted to the Gregorian calendar from the calendar in
use at the time (e.g. from the Julian calendar). The date of Nero's birth is the 15th of
December 37, in the Julian Calendar, which is the 13th of December 37 in the <span>proleptic
Gregorian calendar</span>.</li> <!-- This might not be true. I can't find a reference that gives
his birthday with an explicit statement about the calendar being used. However, it seems
unlikely that it would be given in the Gregorian calendar, so I assume sites use the Julian one.
-->
<li>The time and time-zone offset components are not optional.</li>
<li>Dates before the year one can't be represented as a datetime in this version of HTML.</li>
<li>Times of specific events in ancient times are, at best, approximations, since time was not
well coordinated or measured until relatively recent decades.</li>
<li>Time-zone offsets differ based on daylight saving time.</li>
</ul>
</div>
<div w-nodev>
<p>The rules to <dfn>parse a global date and time string</dfn> are as follows. This will return
either a time in UTC, with associated time-zone offset information for round-tripping or display
purposes, or nothing. If at any point the algorithm says that it "fails", this means that it is
aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Parse a date component</span> to obtain <var>year</var>, <var>month</var>, and <var>day</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is neither a U+0054 LATIN CAPITAL LETTER T character
(T) nor a U+0020 SPACE character, then fail. Otherwise, move <var>position</var>
forwards one character.</p></li>
<li><p><span>Parse a time component</span> to obtain <var>hour</var>, <var>minute</var>, and <var>second</var>. If this returns nothing, then fail.</p>
<li><p>If <var>position</var> is beyond the end of <var>input</var>, then
fail.</p></li>
<li><p><span>Parse a time-zone offset component</span> to obtain <var>timezone<sub>hours</sub></var> and <var>timezone<sub>minutes</sub></var>. If this
returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Let <var>time</var> be the moment in time at year <var>year</var>, month
<var>month</var>, day <var>day</var>, hours <var>hour</var>, minute
<var>minute</var>, second <var>second</var>, subtracting <var>timezone<sub>hours</sub></var> hours and <var>timezone<sub>minutes</sub></var> minutes. That moment in time is a moment in the UTC time
zone.</p></li>
<li><p>Let <var>timezone</var> be <var>timezone<sub>hours</sub></var>
hours and <var>timezone<sub>minutes</sub></var> minutes from UTC.</p></li>
<li><p>Return <var>time</var> and <var>timezone</var>.</p></li>
</ol>
</div>
<h5>Weeks</h5>
<p>A <dfn data-x="concept-week">week</dfn> consists of a week-year number and a week number
representing a seven-day period starting on a Monday. Each week-year in this calendaring system
has either 52 or 53 such seven-day periods, as defined below. The seven-day period starting on the
Gregorian date Monday December 29th 1969 (1969-12-29) is defined as week number 1 in week-year
1970. Consecutive weeks are numbered sequentially. The week before the number 1 week in a
week-year is the last week in the previous week-year, and vice versa. <ref>GREGORIAN</ref></p>
<p>A week-year with a number <var>year</var> has 53 weeks if it corresponds to either a
year <var>year</var> in the <span>proleptic Gregorian calendar</span> that has a Thursday
as its first day (January 1st), or a year <var>year</var> in the <span>proleptic
Gregorian calendar</span> that has a Wednesday as its first day (January 1st) and where <var>year</var> is a number divisible by 400, or a number divisible by 4 but not by 100. All
other week-years have 52 weeks.</p>
<p>The <dfn>week number of the last day</dfn> of a week-year with 53 weeks is 53; the week number
of the last day of a week-year with 52 weeks is 52.</p>
<p class="note">The week-year number of a particular day can be different than the number of the
year that contains that day in the <span>proleptic Gregorian calendar</span>. The first week in a
week-year <var>y</var> is the week that contains the first Thursday of the Gregorian year
<var>y</var>.</p>
<p class="note">For modern purposes, a <span data-x="concept-week">week</span> as defined here is
equivalent to ISO weeks as defined in ISO 8601. <ref>ISO8601</ref></p>
<p>A string is a <dfn>valid week string</dfn> representing a week-year <var>year</var>
and week <var>week</var> if it consists of the following components in the given
order:</p>
<ol>
<li>Four or more <span>ASCII digits</span>, representing <var>year</var>, where <var>year</var> > 0</li>
<li>A U+002D HYPHEN-MINUS character (-)</li>
<li>A U+0057 LATIN CAPITAL LETTER W character (W)</li>
<li>Two <span>ASCII digits</span>, representing the week <var>week</var>, in the range
1 ≤ <var>week</var> ≤ <var>maxweek</var>, where <var>maxweek</var> is the <span>week number of the last day</span> of week-year <var>year</var></li>
</ol>
<div w-nodev>
<p>The rules to <dfn>parse a week string</dfn> are as follows. This will return either a week-year
number and week number, or nothing. If at any point the algorithm says that it "fails", this means
that it is aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not at least four
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>year</var>.</p></li>
<li><p>If <var>year</var> is not a number greater than zero, then fail.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+002D HYPHEN-MINUS character, then fail.
Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p>If <var>position</var> is beyond the end of <var>input</var> or if the
character at <var>position</var> is not a U+0057 LATIN CAPITAL LETTER W character (W),
then fail. Otherwise, move <var>position</var> forwards one character.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. If the collected sequence is not exactly two
characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the <var>week</var>.</p></li>
<li><p>Let <var>maxweek</var> be the <span>week number of the last day</span> of year
<var>year</var>.</p></li>
<li><p>If <var>week</var> is not a number in the range 1 ≤ <var>week</var> ≤ <var>maxweek</var>, then fail.</p></li>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li><p>Return the week-year number <var>year</var> and the week number <var>week</var>.</p></li>
</ol>
</div>
<h5>Durations</h5>
<!-- if you add support for year and month durations, then search for MONTHS throughout the spec
(not just this section) for things that have to change -->
<p>A <dfn data-x="concept-duration">duration</dfn> consists of <!--MONTHS: either a number of
months or--> a number of seconds.</p>
<p class="note">Since months and seconds are not comparable (a month is not a precise number of
seconds, but is instead a period whose exact length depends on the precise day from which it is
measured) a <span data-x="concept-duration">duration</span> as defined in this specification cannot
<!--MONTHS: consist of a mixture of both--> include months (or years, which are equivalent to
twelve months). Only durations that describe a specific number of seconds can be described.</p>
<p>A string is a <dfn>valid duration string</dfn> representing a <span
data-x="concept-duration">duration</span> <var>t</var> if it consists of either of the
following:</p>
<ul>
<li>
<!-- The ISO format -->
<!-- NOTE: ISO durations also have a number of formats we do not
consider conforming:
- a "week" format (e.g. P4W). This one is actually supported
by the parser.
- P<date>T<time>, with or without hyphens
- All these formats, with commas instead of periods for the
seconds decimal
-->
<p>A literal U+0050 LATIN CAPITAL LETTER P character followed by one or more of the following
subcomponents, in the order given, where <!--the number of years, if any, multiplied by twelve,
plus the number of months, if any, equals the number of months in <var>t</var>, if the
duration is in months; or, if it is in seconds, -->the number of days, hours, minutes, and
seconds corresponds to the same number of seconds as in <var>t</var>:</p>
<ol>
<!--MONTHS:
<li><p>One or more <span>ASCII digits</span> followed by a U+0059 LATIN CAPITAL LETTER Y
character, representing a number of years.</p></li>
<li><p>One or more <span>ASCII digits</span> followed by a U+004D LATIN CAPITAL LETTER M
character, representing a number of months.</p></li>
-->
<li><p>One or more <span>ASCII digits</span> followed by a U+0044 LATIN CAPITAL LETTER D
character, representing a number of days.</p></li>
<li>
<p>A U+0054 LATIN CAPITAL LETTER T character followed by one or more of the following
subcomponents, in the order given:</p>
<ol>
<li><p>One or more <span>ASCII digits</span> followed by a U+0048 LATIN CAPITAL LETTER H
character, representing a number of hours.</p></li>
<li><p>One or more <span>ASCII digits</span> followed by a U+004D LATIN CAPITAL LETTER M
character, representing a number of minutes.</p></li>
<li>
<p>The following components:</p>
<ol>
<li><p>One or more <span>ASCII digits</span>, representing a number of seconds.</p></li>
<li><p>Optionally, a U+002E FULL STOP character (.) followed by one, two, or three
<span>ASCII digits</span>, representing a fraction of a second.</p></li>
<li><p>A U+0053 LATIN CAPITAL LETTER S character.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p class="note">This, as with a number of other date- and time-related microsyntaxes defined in
this specification, is based on one of the formats defined in ISO 8601. <ref>ISO8601</ref></p>
</li>
<li>
<p>One or more <span data-x="duration time component">duration time components</span>, each with
a different <span>duration time component scale</span>, in any order; the sum of the represented
seconds being equal to the number of seconds in <var>t</var>.</p>
<p>A <dfn>duration time component</dfn> is a string consisting of the following components:</p>
<ol>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
<li><p>One or more <span>ASCII digits</span>, representing a number of time units, scaled by
the <span>duration time component scale</span> specified (see below) to represent a number of
seconds.</p></li>
<li><p>If the <span>duration time component scale</span> specified is 1 (i.e. the units are
seconds), then, optionally, a U+002E FULL STOP character (.) followed by one, two, or three
<span>ASCII digits</span>, representing a fraction of a second.</p></li>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
<li>
<p>One of the following characters, representing the <dfn>duration time component scale</dfn>
of the time unit used in the numeric part of the <span>duration time component</span>:</p>
<dl>
<dt>U+0057 LATIN CAPITAL LETTER W character</dt>
<dt>U+0077 LATIN SMALL LETTER W character</dt>
<dd>Weeks. The scale is 604800.</dd>
<dt>U+0044 LATIN CAPITAL LETTER D character</dt>
<dt>U+0064 LATIN SMALL LETTER D character</dt>
<dd>Days. The scale is 86400.</dd>
<dt>U+0048 LATIN CAPITAL LETTER H character</dt>
<dt>U+0068 LATIN SMALL LETTER H character</dt>
<dd>Hours. The scale is 3600.</dd>
<dt>U+004D LATIN CAPITAL LETTER M character</dt>
<dt>U+006D LATIN SMALL LETTER M character</dt>
<dd>Minutes. The scale is 60.</dd>
<dt>U+0053 LATIN CAPITAL LETTER S character</dt>
<dt>U+0073 LATIN SMALL LETTER S character</dt>
<dd>Seconds. The scale is 1.</dd>
</dl>
</li>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
</ol>
<p class="note">This is not based on any of the formats in ISO 8601. It is intended to be a more
human-readable alternative to the ISO 8601 duration format.</p>
</li>
</ul>
<div w-nodev>
<p>The rules to <dfn>parse a duration string</dfn> are as follows. This will return either a <span
data-x="concept-duration">duration</span> or nothing. If at any point the algorithm says that it
"fails", this means that it is aborted at that point and returns nothing.</p>
<ol>
<!--MONTHS: this algorithm actually already parses months adequately, though it would need
tweaking if we introduced a "mo" unit for the non-ISO variant. See other "MONTHS" annotations
below. -->
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p>Let <var>months</var>, <var>seconds</var>, and <var>component
count</var> all be zero.</p></li>
<li>
<p>Let <var>M-disambiguator</var> be <i>minutes</i>.</p>
<!--MONTHS: this note would change-->
<p class="note">This flag's other value is <i>months</i>. It is used to disambiguate the "M"
unit in ISO8601 durations, which use the same unit for months and minutes. Months are not
allowed, but are parsed for future compatibility and to avoid misinterpreting ISO8601 durations
that would be valid in other contexts.</p>
</li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then
fail.</p></li>
<li><p>If the character in <var>input</var> pointed to by <var>position</var> is a U+0050 LATIN
CAPITAL LETTER P character, then advance <var>position</var> to the next character, set
<var>M-disambiguator</var> to <i>months</i>, and <span>skip ASCII whitespace</span> within
<var>input</var> given <var>position</var>.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>Let <var>units</var> be undefined. It will be assigned one of the following
values: <i>years</i>, <i>months</i>, <i>weeks</i>, <i>days</i>, <i>hours</i>, <i>minutes</i>,
and <i>seconds</i>.</p></li>
<li><p>Let <var>next character</var> be undefined. It is used to process characters
from the <var>input</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then break.</p></li>
<li><p>If the character in <var>input</var> pointed to by <var>position</var> is a U+0054 LATIN
CAPITAL LETTER T character, then advance <var>position</var> to the next character, set
<var>M-disambiguator</var> to <i>minutes</i>, <span>skip ASCII whitespace</span> within
<var>input</var> given <var>position</var>, and <span>continue</span>.</p></li>
<li><p>Set <var>next character</var> to the character in <var>input</var>
pointed to by <var>position</var>.</p></li>
<li>
<p>If <var>next character</var> is a U+002E FULL STOP character (.), then let <var>N</var> equal zero. (Do not advance <var>position</var>. That is taken care
of below.)</p>
<p>Otherwise, if <var>next character</var> is an <span data-x="ASCII digits">ASCII
digit</span>, then <span>collect a sequence of code points</span> that are <span>ASCII
digits</span> from <var>input</var> given <var>position</var>, interpret the resulting
sequence as a base-ten integer, and let <var>N</var> be that number.</p>
<p>Otherwise, <var>next character</var> is not part of a number; fail.</p>
</li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then
fail.</p></li>
<li><p>Set <var>next character</var> to the character in <var>input</var>
pointed to by <var>position</var>, and this time advance <var>position</var>
to the next character. (If <var>next character</var> was a U+002E FULL STOP character
(.) before, it will still be that character this time.)</p></li>
<li>
<p>If <var>next character</var> is U+002E (.), then:</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>. Let <var>s</var> be the resulting
sequence.</p></li>
<li><p>If <var>s</var> is the empty string, then fail.</p></li>
<li><p>Let <var>length</var> be the number of characters in <var>s</var>.</p></li>
<li><p>Let <var>fraction</var> be the result of interpreting <var>s</var>
as a base-ten integer, and then dividing that number by <span data-x="">10<sup><var>length</var></sup></span>.</li>
<li><p>Increment <var>N</var> by <var>fraction</var>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, then
fail.</p></li>
<li><p>Set <var>next character</var> to the character in <var>input</var>
pointed to by <var>position</var>, and advance <var>position</var> to the
next character.</p></li>
<li><p>If <var>next character</var> is neither a U+0053 LATIN CAPITAL LETTER S
character nor a U+0073 LATIN SMALL LETTER S character, then fail.</p></li>
<li><p>Set <var>units</var> to <i>seconds</i>.</p></li>
</ol>
<p>Otherwise:</p>
<ol>
<li><p>If <var>next character</var> is <span>ASCII whitespace</span>, then <span>skip ASCII
whitespace</span> within <var>input</var> given <var>position</var>, set <var>next
character</var> to the character in <var>input</var> pointed to by <var>position</var>, and
advance <var>position</var> to the next character.</p></li>
<li>
<!--MONTHS: this would probably be where we would add more
logic to support a new unit like 'mo' -->
<p>If <var>next character</var> is a U+0059 LATIN CAPITAL LETTER Y character, or a
U+0079 LATIN SMALL LETTER Y character, set <var>units</var> to <i>years</i> and set
<var>M-disambiguator</var> to <i>months</i>.</p>
<p>If <var>next character</var> is a U+004D LATIN CAPITAL LETTER M character or a
U+006D LATIN SMALL LETTER M character, and <var>M-disambiguator</var> is
<i>months</i>, then set <var>units</var> to <i>months</i>.</p>
<p>If <var>next character</var> is a U+0057 LATIN CAPITAL LETTER W character or a
U+0077 LATIN SMALL LETTER W character, set <var>units</var> to <i>weeks</i> and set
<var>M-disambiguator</var> to <i>minutes</i>.</p>
<p>If <var>next character</var> is a U+0044 LATIN CAPITAL LETTER D character or a
U+0064 LATIN SMALL LETTER D character, set <var>units</var> to <i>days</i> and set
<var>M-disambiguator</var> to <i>minutes</i>.</p>
<p>If <var>next character</var> is a U+0048 LATIN CAPITAL LETTER H character or a
U+0068 LATIN SMALL LETTER H character, set <var>units</var> to <i>hours</i> and set
<var>M-disambiguator</var> to <i>minutes</i>.</p>
<p>If <var>next character</var> is a U+004D LATIN CAPITAL LETTER M character or a
U+006D LATIN SMALL LETTER M character, and <var>M-disambiguator</var> is
<i>minutes</i>, then set <var>units</var> to <i>minutes</i>.</p>
<p>If <var>next character</var> is a U+0053 LATIN CAPITAL LETTER S character or a
U+0073 LATIN SMALL LETTER S character, set <var>units</var> to <i>seconds</i> and
set <var>M-disambiguator</var> to <i>minutes</i>.</p>
<p>Otherwise, if <var>next character</var> is none of the above characters, then
fail.</p>
</li>
</ol>
</li>
<li><p>Increment <var>component count</var>.</p></li>
<li><p>Let <var>multiplier</var> be 1.</p></li>
<li><p>If <var>units</var> is <i>years</i>, multiply <var>multiplier</var> by
12 and set <var>units</var> to <i>months</i>.</p></li>
<li>
<p>If <var>units</var> is <i>months</i>, add the product of <var>N</var> and
<var>multiplier</var> to <var>months</var>.</p>
<p>Otherwise:</p>
<ol>
<li><p>If <var>units</var> is <i>weeks</i>, multiply <var>multiplier</var>
by 7 and set <var>units</var> to <i>days</i>.</p></li>
<li><p>If <var>units</var> is <i>days</i>, multiply <var>multiplier</var>
by 24 and set <var>units</var> to <i>hours</i>.</p></li>
<li><p>If <var>units</var> is <i>hours</i>, multiply <var>multiplier</var>
by 60 and set <var>units</var> to <i>minutes</i>.</p></li>
<li><p>If <var>units</var> is <i>minutes</i>, multiply <var>multiplier</var> by 60 and set <var>units</var> to <i>seconds</i>.</p></li>
<li><p>Forcibly, <var>units</var> is now <i>seconds</i>. Add the product of <var>N</var> and <var>multiplier</var> to <var>seconds</var>.</p></li>
</ol>
</li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
</ol>
</li>
<li><p>If <var>component count</var> is zero,
fail.</p></li>
<!--MONTHS: if we add month support this is where you'd return them-->
<li><p>If <var>months</var> is not zero, fail.</p></li>
<li><p>Return the <span data-x="concept-duration">duration</span> consisting of <var>seconds</var> seconds.</p></li>
</ol>
</div>
<h5>Vaguer moments in time</h5>
<p>A string is a <dfn>valid date string with optional time</dfn> if
it is also one of the following:</p>
<ul>
<li>A <span>valid date string</span></li>
<li>A <span>valid global date and time string</span></li>
</ul>
<div w-nodev>
<hr>
<p>The rules to <dfn>parse a date or time string</dfn> are as follows. The algorithm will return
either a <span data-x="concept-date">date</span>, a <span data-x="concept-time">time</span>, a <span
data-x="concept-datetime">global date and time</span>, or nothing. If at any point the algorithm
says that it "fails", this means that it is aborted at that point and returns nothing.</p>
<ol>
<li><p>Let <var>input</var> be the string being parsed.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
pointing at the start of the string.</p></li>
<li><p>Set <var>start position</var> to the same position as <var>position</var>.</p></li>
<li><p>Set the <var>date present</var> and <var>time present</var> flags to
true.</p></li>
<li><p><span>Parse a date component</span> to obtain <var>year</var>, <var>month</var>, and <var>day</var>. If this fails, then set the <var>date
present</var> flag to false.</p>
<li>
<p>If <var>date present</var> is true, and <var>position</var> is not beyond
the end of <var>input</var>, and the character at <var>position</var> is
either a U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character, then advance
<var>position</var> to the next character in <var>input</var>.</p>
<p>Otherwise, if <var>date present</var> is true, and either <var>position</var> is beyond the end of <var>input</var> or the character at <var>position</var> is neither a U+0054 LATIN CAPITAL LETTER T character (T) nor a U+0020
SPACE character, then set <var>time present</var> to false.</p>
<p>Otherwise, if <var>date present</var> is false, set <var>position</var>
back to the same position as <var>start position</var>.</p>
</li>
<li><p>If the <var>time present</var> flag is true, then <span>parse a time
component</span> to obtain <var>hour</var>, <var>minute</var>, and <var>second</var>. If this returns nothing, then fail.</p></li>
<li><p>If the <var>date present</var> and <var>time present</var> flags are
both true, but <var>position</var> is beyond the end of <var>input</var>, then
fail.</p></li>
<li><p>If the <var>date present</var> and <var>time present</var> flags are
both true, <span>parse a time-zone offset component</span> to obtain <var>timezone<sub>hours</sub></var> and <var>timezone<sub>minutes</sub></var>. If this
returns nothing, then fail.</p>
<li><p>If <var>position</var> is <em>not</em> beyond the end of <var>input</var>, then fail.</p></li>
<li>
<p>If the <var>date present</var> flag is true and the <var>time present</var>
flag is false, then let <var>date</var> be the date with year <var>year</var>,
month <var>month</var>, and day <var>day</var>, and return <var>date</var>.</p>
<p>Otherwise, if the <var>time present</var> flag is true and the <var>date
present</var> flag is false, then let <var>time</var> be the time with hour <var>hour</var>, minute <var>minute</var>, and second <var>second</var>,
and return <var>time</var>.</p>
<p>Otherwise, let <var>time</var> be the moment in time at year <var>year</var>, month <var>month</var>, day <var>day</var>, hours <var>hour</var>, minute <var>minute</var>, second <var>second</var>,
subtracting <var>timezone<sub>hours</sub></var> hours and <var>timezone<sub>minutes</sub></var> minutes, that moment in time being a moment
in the UTC time zone; let <var>timezone</var> be <var>timezone<sub>hours</sub></var> hours and <var>timezone<sub>minutes</sub></var>
minutes from UTC; and return <var>time</var> and <var>timezone</var>.</p>
</li>
</ol>
</div>
<div w-nodev>
<!--en-GB--><h4 id="colours">Legacy colors</h4>
<p>Some obsolete legacy attributes parse colors using the
<!--en-GB--><dfn id="rules-for-parsing-a-legacy-colour-value">rules for parsing a legacy color
value</dfn>, given a string <var>input</var>. They will return either a CSS color or failure.</p>
<ol>
<li><p>If <var>input</var> is the empty string, then return failure.</p></li>
<li><p><span>Strip leading and trailing ASCII whitespace</span> from <var>input</var>.</p></li>
<li><p>If <var>input</var> is an <span>ASCII case-insensitive</span> match for "<code
data-x="">transparent</code>", then return failure.</p></li>
<li>
<p>If <var>input</var> is an <span>ASCII case-insensitive</span> match for one of the <span
data-x="named color">named colors</span>, then return the CSS color corresponding to that
keyword. <ref>CSSCOLOR</ref></p>
<p class="note"><a
href="https://www.w3.org/TR/css3-color/#css2-system">CSS2 System
Colors</a> are not recognized.</p>
</li>
<li>
<p>If <var>input</var>'s <span>code point length</span> is four, and the first character in
<var>input</var> is U+0023 (#), and the last three characters of <var>input</var> are all
<span>ASCII hex digits</span>, then:</p>
<ol>
<li><p>Let <var>result</var> be a CSS color.</p>
<li><p>Interpret the second character of <var>input</var> as a hexadecimal digit; let
the red component of <var>result</var> be the resulting number multiplied by 17.</p>
<li><p>Interpret the third character of <var>input</var> as a hexadecimal digit; let
the green component of <var>result</var> be the resulting number multiplied by 17.</p>
<li><p>Interpret the fourth character of <var>input</var> as a hexadecimal digit; let
the blue component of <var>result</var> be the resulting number multiplied by 17.</p>
<li><p>Return <var>result</var>.</p>
</ol>
</li>
<li><p>Replace any <span data-x="code point">code points</span> greater than U+FFFF in
<var>input</var> (i.e., any characters that are not in the basic multilingual plane) with "<code
data-x="">00</code>".</p></li>
<li><p>If <var>input</var>'s <span>code point length</span> is greater than 128, truncate
<var>input</var>, leaving only the first 128 characters.</p></li>
<li><p>If the first character in <var>input</var> is U+0023 (#), then remove it.</p></li>
<li><p>Replace any character in <var>input</var> that is not an <span data-x="ASCII hex
digits">ASCII hex digit</span> with U+0030 (0).</p></li>
<li><p>While <var>input</var>'s <span>code point length</span> is zero or not a multiple of
three, append U+0030 (0) to <var>input</var>.</p></li>
<li><p>Split <var>input</var> into three strings of equal <span>code point length</span>, to
obtain three components. Let <var>length</var> be the <span>code point length</span> that all of
those components have (one third the <span>code point length</span> of <var>input</var>).</p></li>
<li><p>If <var>length</var> is greater than 8, then remove the leading <span
data-x=""><var>length</var>-8</span> characters in each component, and let <var>length</var> be 8.</p></li>
<li><p>While <var>length</var> is greater than two and the first character in each
component is U+0030 (0), remove that character and reduce <var>length</var> by one.</p></li>
<li><p>If <var>length</var> is <em>still</em> greater than two, truncate each component,
leaving only the first two characters in each.</p></li>
<li><p>Let <var>result</var> be a CSS color.</p>
<li><p>Interpret the first component as a hexadecimal number; let the red component of <var>result</var> be the resulting number.</p></li>
<li><p>Interpret the second component as a hexadecimal number; let the green component of <var>result</var> be the resulting number.</p></li>
<li><p>Interpret the third component as a hexadecimal number; let the blue component of <var>result</var> be the resulting number.</p></li>
<li><p>Return <var>result</var>.</p>
</ol>
</div>
<h4>Space-separated tokens</h4>
<p>A <dfn export>set of space-separated tokens</dfn> is a string containing zero or more words
(known as tokens) separated by one or more <span>ASCII whitespace</span>, where words consist of
any string of one or more characters, none of which are <span>ASCII whitespace</span>.</p>
<p>A string containing a <span>set of space-separated tokens</span> may have leading or trailing
<span>ASCII whitespace</span>.</p>
<p>An <dfn export>unordered set of unique space-separated tokens</dfn> is a <span>set of
space-separated tokens</span> where none of the tokens are duplicated.</p>
<p>An <dfn>ordered set of unique space-separated tokens</dfn> is a <span>set of space-separated
tokens</span> where none of the tokens are duplicated but where the order of the tokens is
meaningful.</p>
<p><span data-x="set of space-separated tokens">Sets of space-separated tokens</span> sometimes
have a defined set of allowed values. When a set of allowed values is defined, the tokens must all
be from that list of allowed values; other values are non-conforming. If no such set of allowed
values is provided, then all values are conforming.</p>
<p class="note">How tokens in a <span>set of space-separated tokens</span> are to be compared
(e.g. case-sensitively or not) is defined on a per-set basis.</p>
<h4>Comma-separated tokens</h4>
<p>A <dfn>set of comma-separated tokens</dfn> is a string containing zero or more tokens each
separated from the next by a single U+002C COMMA character (,), where tokens consist of any string
of zero or more characters, neither beginning nor ending with <span>ASCII whitespace</span>, nor
containing any U+002C COMMA characters (,), and optionally surrounded by <span>ASCII
whitespace</span>.</p>
<p class="example">For instance, the string "<code
data-x=""> a ,b,,d d </code>" consists of four tokens: "a", "b", the empty
string, and "d d". Leading and trailing whitespace around each token doesn't count as part of
the token, and the empty string can be a token.</p>
<p><span data-x="set of comma-separated tokens">Sets of comma-separated tokens</span> sometimes
have further restrictions on what consists a valid token. When such restrictions are defined, the
tokens must all fit within those restrictions; other values are non-conforming. If no such
restrictions are specified, then all values are conforming.</p>
<h4 id="syntax-references">References</h4>
<p>A <dfn>valid hash-name reference</dfn> to an element of type <var>type</var> is a
string consisting of a U+0023 NUMBER SIGN character (#) followed by a string which exactly matches
the value of the <code data-x="">name</code> attribute of an element with type <var>type</var> in
the same <span>tree</span>.</p>
<div w-nodev>
<p>The <dfn>rules for parsing a hash-name reference</dfn> to an element of type <var>type</var>,
given a context node <var>scope</var>, are as follows:</p>
<ol>
<li><p>If the string being parsed does not contain a U+0023 NUMBER SIGN character, or if the
first such character in the string is the last character in the string, then return null.</p></li>
<li><p>Let <var>s</var> be the string from the character immediately after the first
U+0023 NUMBER SIGN character in the string being parsed up to the end of that string.</p></li>
<li>
<p>Return the first element of type <var>type</var> in <var>scope</var>'s <span>tree</span>, in
<span>tree order</span>, that has an <code data-x="attr-id">id</code> or <code
data-x="">name</code> attribute whose value is <var>s</var>, or null if there is no such
element.</p>
<p class="note">Although <code data-x="attr-id">id</code> attributes are accounted for when
parsing, they are not used in determining whether a value is a <span><em>valid</em> hash-name
reference</span>. That is, a hash-name reference that refers to an element based on <code
data-x="attr-id">id</code> is a conformance error (unless that element also has a <code
data-x="">name</code> attribute with the same value).</p>
</li>
<!-- History behind case-sensitive matching above: https://github.com/whatwg/html/issues/1666 -->
</ol>
</div>
<h4 id="mq">Media queries</h4>
<p>A string is a <dfn>valid media query list</dfn> if it matches the <code
data-x=""><media-query-list></code> production of <cite>Media Queries</cite>.
<ref>MQ</ref></p>
<p>A string <dfn>matches the environment</dfn> of the user if it is the empty string, a string
consisting of only <span>ASCII whitespace</span>, or is a media query list that matches the user's
environment according to the definitions given in <cite>Media Queries</cite>. <ref>MQ</ref></p>
<h4 id="unique-values">Unique internal values</h4>
<p>A <dfn>unique internal value</dfn> is a value that is serializable, comparable by value, and
never exposed to script.</p>
<p>To create a <dfn>new unique internal value</dfn>, return a <span>unique internal value</span>
that has never previously been returned by this algorithm.</p>
<h3 split-filename="urls-and-fetching">URLs</h3>
<h4>Terminology</h4>
<p>A string is a <dfn>valid non-empty URL</dfn> if it is a <span>valid URL string</span> but it is
not the empty string.</p>
<p>A string is a <dfn>valid URL potentially surrounded by spaces</dfn> if, after <span
data-x="strip leading and trailing ASCII whitespace">stripping leading and trailing ASCII
whitespace</span> from it, it is a <span>valid URL string</span>.</p>
<p>A string is a <dfn>valid non-empty URL potentially surrounded by spaces</dfn> if, after <span
data-x="strip leading and trailing ASCII whitespace">stripping leading and trailing ASCII
whitespace</span> from it, it is a <span>valid non-empty URL</span>.</p>
<p>This specification defines the URL <dfn><code>about:legacy-compat</code></dfn> as a reserved,
though unresolvable, <code data-x="about protocol">about:</code> URL, for use in <span
data-x="syntax-doctype">DOCTYPE</span>s in <span>HTML documents</span> when needed for
compatibility with XML tools. <ref>ABOUT</ref></p>
<p>This specification defines the URL <dfn><code>about:html-kind</code></dfn> as a reserved,
though unresolvable, <code data-x="about protocol">about:</code> URL, that is used as an
identifier for kinds of media tracks. <ref>ABOUT</ref></p>
<p>This specification defines the URL <dfn><code>about:srcdoc</code></dfn> as a reserved, though
unresolvable, <code data-x="about protocol">about:</code> URL, that is used as the <span
data-x="concept-document-url">URL</span> of <span data-x="an iframe srcdoc
document"><code>iframe</code> <code data-x="attr-iframe-srcdoc">srcdoc</code> documents</span>.
<ref>ABOUT</ref></p>
<p>The <dfn>fallback base URL</dfn> of a <code>Document</code> object <var>document</var> is the
<span>URL record</span> obtained by running these steps:</p>
<ol>
<li>
<p>If <var>document</var> is <span data-x="an iframe srcdoc document">an <code>iframe</code>
<code data-x="attr-iframe-srcdoc">srcdoc</code> document</span>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span
data-x="concept-document-about-base-url">about base URL</span> is non-null.</p></li>
<li><p>Return <var>document</var>'s <span data-x="concept-document-about-base-url">about base
URL</span>.</p></li>
</ol>
</li>
<li><p>If <var>document</var>'s <span data-x="concept-document-url">URL</span> <span>matches
<code>about:blank</code></span> and <var>document</var>'s <span
data-x="concept-document-about-base-url">about base URL</span> is non-null, then return
<var>document</var>'s <span data-x="concept-document-about-base-url">about base URL</span>.</p></li>
<!-- https://www.hixie.ch/tests/adhoc/dom/level0/history/pushState/001/ -->
<li><p>Return <var>document</var>'s <span data-x="concept-document-url">URL</span>.</p></li>
</ol>
<p>The <dfn export>document base URL</dfn> of a <code>Document</code> object is the
<span>URL record</span> obtained by running these steps:</p>
<ol>
<li><p>If there is no <code>base</code> element that has an <code
data-x="attr-base-href">href</code> attribute in the <code>Document</code>, then return the
<code>Document</code>'s <span>fallback base URL</span>.</p></li>
<li><p>Otherwise, return the <span>frozen base URL</span> of the first <code>base</code> element
in the <code>Document</code> that has an <code data-x="attr-base-href">href</code> attribute, in
<span>tree order</span>.</p></li>
</ol>
<hr>
<p>A <span>URL</span> <dfn>matches <code>about:blank</code></dfn> if its <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">about</code>", its <span
data-x="concept-url-path">path</span> contains a single string "<code data-x="">blank</code>", its
<span data-x="concept-url-username">username</span> and <span
data-x="concept-url-password">password</span> are the empty string, and its <span
data-x="concept-url-host">host</span> is null.</p>
<p class="note">Such a URL's <span data-x="concept-url-query">query</span> and <span
data-x="concept-url-fragment">fragment</span> can be non-null. For example, the <span>URL
record</span> created by <span data-x="URL parser">parsing</span> "<code
data-x="">about:blank?foo#bar</code>" <span>matches <code>about:blank</code></span>.</p>
<p>A <span>URL</span> <dfn>matches <code>about:srcdoc</code></dfn> if its <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">about</code>", its <span
data-x="concept-url-path">path</span> contains a single string "<code data-x="">srcdoc</code>",
its <span data-x="concept-url-query">query</span> is null, its <span
data-x="concept-url-username">username</span> and <span
data-x="concept-url-password">password</span> are the empty string, and its <span
data-x="concept-url-host">host</span> is null.</p>
<p class="note">The reason that <span>matches <code>about:srcdoc</code></span> ensures that the
<span>URL</span>'s <span data-x="concept-url-query">query</span> is null is because it is not
possible to create <span data-x="an iframe srcdoc document">an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span> whose <span
data-x="concept-document-url">URL</span> has a non-null <span
data-x="concept-url-query">query</span>, unlike <code>Document</code>s whose <span
data-x="concept-document-url">URL</span> <span>matches <code>about:blank</code></span>. In other
words, the set of all <span>URL</span>s that <span data-x="matches about:srcdoc">match
<code>about:srcdoc</code></span> only vary in their <span
data-x="concept-url-fragment">fragment</span>.</p>
<div w-nodev>
<h4 id="resolving-urls">Parsing URLs</h4>
<p>Parsing a URL is the process of taking a string and obtaining the <span>URL record</span> that
it represents. While this process is defined in <cite>URL</cite>, the HTML standard defines
several wrappers to abstract base URLs and encodings. <ref>URL</ref></p>
<p class="note">Most new APIs are to use <span>parse a URL</span>. Older APIs and HTML elements
might have reason to use <span data-x="encoding-parsing a URL">encoding-parse a URL</span>. When a
custom base URL is needed or no base URL is desired, the <span>URL parser</span> can of course be
used directly as well.</p>
<p>To <dfn export>parse a URL</dfn>, given a string <var>url</var>, relative to a
<code>Document</code> object or <span>environment settings object</span> <var>environment</var>,
run these steps. They return failure or a <span>URL</span>.</p>
<ol>
<li><p>Let <var>baseURL</var> be <var>environment</var>'s <span data-x="document base URL">base
URL</span>, if <var>environment</var> is a <code>Document</code> object; otherwise
<var>environment</var>'s <span>API base URL</span>.</p></li>
<li><p>Return the result of applying the <span>URL parser</span> to <var>url</var>, with
<var>baseURL</var>.</p></li>
</ol>
<p id="resolve-a-url">To <dfn export data-x="encoding-parsing a URL">encoding-parse a URL</dfn>,
given a string <var>url</var>, relative to a <code>Document</code> object or <span>environment
settings object</span> <var>environment</var>, run these steps. They return failure or a
<span>URL</span>.</p>
<ol>
<li><p>Let <var>encoding</var> be <span>UTF-8</span>.</p></li>
<li><p>If <var>environment</var> is a <code>Document</code> object, then set <var>encoding</var>
to <var>environment</var>'s <span data-x="document's character encoding">character
encoding</span>.</p></li>
<li><p>Otherwise, if <var>environment</var>'s <span>relevant global object</span> is a
<code>Window</code> object, set <var>encoding</var> to <var>environment</var>'s <span>relevant
global object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="document's character encoding">character
encoding</span>.</p></li>
<li><p>Let <var>baseURL</var> be <var>environment</var>'s <span data-x="document base URL">base
URL</span>, if <var>environment</var> is a <code>Document</code> object; otherwise
<var>environment</var>'s <span>API base URL</span>.</p></li>
<li><p>Return the result of applying the <span>URL parser</span> to <var>url</var>, with
<var>baseURL</var> and <var>encoding</var>.</p></li>
</ol>
<p>To <dfn data-x="encoding-parsing-and-serializing a URL">encoding-parse-and-serialize a
URL</dfn>, given a string <var>url</var>, relative to a <code>Document</code> object or
<span>environment settings object</span> <var>environment</var>, run these steps. They return
failure or a string.</p>
<ol>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to <var>environment</var>.</p></li>
<li><p>If <var>url</var> is failure, then return failure.</p></li>
<li><p>Return the result of applying the <span data-x="concept-url-serializer">URL
serializer</span> to <var>url</var>.</p></li>
</ol>
</div>
<div w-nodev>
<h4>Dynamic changes to base URLs</h4>
<p>When a document's <span>document base URL</span> changes, all elements in that document are
<span>affected by a base URL change</span>.</p>
<p>The following are <span>base URL change steps</span>, which run when an element is
<span>affected by a base URL change</span> (as defined by <cite>DOM</cite>):</p>
<dl class="switch">
<dt>If the element creates a <span>hyperlink</span></dt>
<dd>
<p>If the <span>URL</span> identified by the hyperlink is being shown to the user, or if any
data derived from that <span>URL</span> is affecting the display, then the <code
data-x="attr-hyperlink-href">href</code> attribute's value should be <span
data-x="encoding-parsing a URL">reparsed</span>, relative to the element's <span>node
document</span> and the UI updated appropriately.</p>
<p class="example">For example, the CSS <code data-x="selector-link">:link</code>/<code
data-x="selector-visited">:visited</code> <span data-x="pseudo-class">pseudo-classes</span>
might have been affected.</p>
<p>If the hyperlink has a <code data-x="attr-hyperlink-ping">ping</code> attribute and its
<span data-x="URL">URL(s)</span> are being shown to the user, then the <code
data-x="attr-hyperlink-ping">ping</code> attribute's tokens should be <span
data-x="encoding-parsing a URL">reparsed</span>, relative to the element's <span>node
document</span> and the UI updated appropriately.</p>
</dd>
<dt>If the element is a <code>q</code>, <code>blockquote</code>, <code>ins</code>, or
<code>del</code> element with a <code data-x="">cite</code> attribute</dt>
<dd>
<p>If the <span>URL</span> identified by the <code data-x="">cite</code> attribute is being
shown to the user, or if any data derived from that <span>URL</span> is affecting the display,
then the <code data-x="">cite</code> attribute's value should be <span data-x="encoding-parsing
a URL">reparsed</span>, relative to the element's <span>node document</span> and the UI updated
appropriately.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>The element is not directly affected.</p>
<p class="example">For instance, changing the base URL doesn't affect the image displayed by
<code>img</code> elements, although subsequent accesses of the <code
data-x="dom-img-src">src</code> IDL attribute from script will return a new <span>absolute
URL</span> that might no longer correspond to the image being shown.</p>
</dd>
</dl>
</div>
<div w-nodev>
<h3>Fetching resources</h3>
<h4>Terminology</h4>
<p>A <span data-x="concept-response">response</span> whose <span
data-x="concept-response-type">type</span> is "<code data-x="">basic</code>", "<code
data-x="">cors</code>", or "<code data-x="">default</code>" is <dfn export>CORS-same-origin</dfn>.
<ref>FETCH</ref></p>
<p>A <span data-x="concept-response">response</span> whose <span
data-x="concept-response-type">type</span> is "<code data-x="">opaque</code>" or "<code
data-x="">opaqueredirect</code>" is <dfn>CORS-cross-origin</dfn>.</p>
<p>A <span data-x="concept-response">response</span>'s <dfn export>unsafe response</dfn> is its
<span data-x="concept-internal-response">internal response</span> if it has one, and the <span
data-x="concept-response">response</span> itself otherwise.</p>
<p>To <dfn>create a potential-CORS request</dfn>, given a <var>url</var>, <var>destination</var>,
<var>corsAttributeState</var>, and an optional <i>same-origin fallback flag</i>, run these
steps:</p>
<ol>
<li><p>Let <var>mode</var> be "<code data-x="">no-cors</code>" if <var>corsAttributeState</var>
is <span data-x="attr-crossorigin-none">No CORS</span>, and "<code data-x="">cors</code>"
otherwise.</p></li>
<li><p>If <i>same-origin fallback flag</i> is set and <var>mode</var> is "<code
data-x="">no-cors</code>", set <var>mode</var> to "<code data-x="">same-origin</code>".</p></li>
<li><p>Let <var>credentialsMode</var> be "<code data-x="">include</code>".</p></li>
<li><p>If <var>corsAttributeState</var> is <span
data-x="attr-crossorigin-anonymous">Anonymous</span>, set <var>credentialsMode</var> to "<code
data-x="">same-origin</code>".</p></li>
<li><p>Return a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-destination">destination</span> is <var>destination</var>,
<span data-x="concept-request-mode">mode</span> is <var>mode</var>, <span
data-x="concept-request-credentials-mode">credentials mode</span> is
<var>credentialsMode</var>, and whose <span>use-URL-credentials flag</span> is set.</p></li>
</ol>
<h4 id="content-type-sniffing">Determining the type of a resource</h4>
<p>The <dfn data-x="Content-Type">Content-Type metadata</dfn> of a resource must be obtained and
interpreted in a manner consistent with the requirements of <cite>MIME Sniffing</cite>.
<ref>MIMESNIFF</ref></p>
<p>The <dfn data-x="Content-Type sniffing"
data-x-href="https://mimesniff.spec.whatwg.org/#computed-mime-type">computed MIME type</dfn> of a
resource must be found in a manner consistent with the requirements given in <cite>MIME
Sniffing</cite>. <ref>MIMESNIFF</ref></p>
<p>The <dfn data-x="Content-Type sniffing: image"
data-x-href="https://mimesniff.spec.whatwg.org/#rules-for-sniffing-images-specifically">rules for
sniffing images specifically</dfn>, the <dfn data-x="Content-Type sniffing: text or binary"
data-x-href="https://mimesniff.spec.whatwg.org/#rules-for-text-or-binary">rules for distinguishing
if a resource is text or binary</dfn>, and the <dfn data-x="Content-Type sniffing: video"
data-x-href="https://mimesniff.spec.whatwg.org/#rules-for-sniffing-audio-and-video-specifically">rules
for sniffing audio and video specifically</dfn> are also defined in <cite>MIME Sniffing</cite>.
These rules return a <span>MIME type</span> as their result. <ref>MIMESNIFF</ref></p>
<p class="warning">It is imperative that the rules in <cite>MIME Sniffing</cite> be
followed exactly. When a user agent uses different heuristics for content type detection than the
server expects, security problems can occur. For more details, see <cite>MIME Sniffing</cite>.
<ref>MIMESNIFF</ref></p>
<h4>Extracting character encodings from <code>meta</code> elements</h4>
<p>The <dfn>algorithm for extracting a character encoding from a <code>meta</code> element</dfn>,
given a string <var>s</var>, is as follows. It returns either a character encoding or
nothing.</p>
<ol> <!-- https://www.hixie.ch/tests/adhoc/html/parsing/encoding/all.html -->
<li><p>Let <var>position</var> be a pointer into <var>s</var>, initially
pointing at the start of the string.</p></li>
<li><p><i>Loop</i>: Find the first seven characters in <var>s</var> after <var>position</var> that are an <span>ASCII case-insensitive</span> match for the word "<code
data-x="">charset</code>". If no such match is found, return nothing.</p></li>
<li><p>Skip any <span>ASCII whitespace</span> that immediately follow the word "<code
data-x="">charset</code>" (there might not be any).</p></li>
<li><p>If the next character is not a U+003D EQUALS SIGN (=), then move <var>position</var> to point just before that next character, and jump back to the step
labeled <i>loop</i>.</p></li>
<li><p>Skip any <span>ASCII whitespace</span> that immediately follow the equals sign (there
might not be any).</p></li>
<li>
<p>Process the next character as follows:</p>
<dl class="switch">
<dt>If it is a U+0022 QUOTATION MARK character (") and there is a later U+0022 QUOTATION MARK character (") in <var>s</var></dt>
<dt>If it is a U+0027 APOSTROPHE character (') and there is a later U+0027 APOSTROPHE character (') in <var>s</var></dt>
<dd>Return the result of <span>getting an encoding</span> from the substring that is between
this character and the next earliest occurrence of this character.</dd>
<dt>If it is an unmatched U+0022 QUOTATION MARK character (")</dt>
<dt>If it is an unmatched U+0027 APOSTROPHE character (')</dt>
<dt>If there is no next character</dt>
<dd>Return nothing.</dd>
<dt>Otherwise</dt>
<dd>Return the result of <span>getting an encoding</span> from the substring that consists of
this character up to but not including the first <span>ASCII whitespace</span> or U+003B
SEMICOLON character (;), or the end of <var>s</var>, whichever comes first.</dd>
</dl>
</li>
</ol>
<p class="note">This algorithm is distinct from those in the HTTP specifications (for example,
HTTP doesn't allow the use of single quotes and requires supporting a backslash-escape mechanism
that is not supported by this algorithm<!-- not to mention not having any rules for
error-handling, which is of course why we're having to define it ourselves -->). While the
algorithm is used in contexts that, historically, were related to HTTP, the syntax as supported by
implementations diverged some time ago. <ref>HTTP</ref></p>
</div>
<h4>CORS settings attributes</h4>
<p>A <dfn>CORS settings attribute</dfn> is an <span>enumerated attribute</span> with the following
keywords and states:</p>
<table>
<thead>
<tr>
<th> Keyword
<th> State
<th> Brief description
<tbody>
<tr>
<td><dfn attr-value for="audio/crossorigin,video/crossorigin,img/crossorigin,link/crossorigin,script/crossorigin"><code data-x="attr-crossorigin-anonymous-keyword">anonymous</code></dfn>
<td rowspan=2><dfn data-x="attr-crossorigin-anonymous">Anonymous</dfn>
<td rowspan=2><span data-x="concept-request">Requests</span> for the element will have their
<span data-x="concept-request-mode">mode</span> set to "<code data-x="">cors</code>" and their
<span data-x="concept-request-credentials-mode">credentials mode</span> set to "<code
data-x="">same-origin</code>".
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="audio/crossorigin,video/crossorigin,img/crossorigin,link/crossorigin,script/crossorigin"><code data-x="attr-crossorigin-use-credentials-keyword">use-credentials</code></dfn>
<td><dfn data-x="attr-crossorigin-use-credentials">Use Credentials</dfn>
<td><span data-x="concept-request">Requests</span> for the element will have their <span
data-x="concept-request-mode">mode</span> set to "<code data-x="">cors</code>" and their <span
data-x="concept-request-credentials-mode">credentials mode</span> set to "<code
data-x="">include</code>".
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <dfn
data-x="attr-crossorigin-none">No CORS</dfn> state, and its <i data-x="invalid value
default">invalid value default</i> is the <span
data-x="attr-crossorigin-anonymous">Anonymous</span> state. For the purposes of <span
data-x="reflect">reflection</span>, the <span>canonical keyword</span> for the <span
data-x="attr-crossorigin-anonymous">Anonymous</span> state is the <code
data-x="attr-crossorigin-anonymous-keyword">anonymous</code> keyword.</p>
<p>The majority of fetches governed by <span data-x="CORS settings attribute">CORS settings
attributes</span> will be done via the <span>create a potential-CORS request</span> algorithm.</p>
<p id="module-script-credentials-mode">For more modern features, where the request's <span
data-x="concept-request-mode">mode</span> is always "<code data-x="">cors</code>", certain <span
data-x="CORS settings attribute">CORS settings attributes</span> have been repurposed to have a
slightly different meaning, wherein they only impact the <span
data-x="concept-request">request</span>'s <span
data-x="concept-request-credentials-mode">credentials mode</span>. To perform this translation, we
define the <dfn export>CORS settings attribute credentials mode</dfn> for a given <span>CORS
settings attribute</span> to be determined by switching on the attribute's state:</p>
<dl class="switch">
<dt><span data-x="attr-crossorigin-none">No CORS</span></dt>
<dt><span data-x="attr-crossorigin-anonymous">Anonymous</span></dt>
<dd>"<code data-x="">same-origin</code>"</dd>
<dt><span data-x="attr-crossorigin-none">Use Credentials</span></dt>
<dd>"<code data-x="">include</code>"</dd>
</dl>
<h4>Referrer policy attributes</h4>
<p>A <dfn export>referrer policy attribute</dfn> is an <span>enumerated attribute</span>. Each
<span>referrer policy</span>, including the empty string, is a keyword for this attribute, mapping
to a state of the same name.</p>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the empty string state.</p>
<p>The impact of these states on the processing model of various <span
data-x="concept-fetch">fetches</span> is defined in more detail throughout this specification, in
<cite>Fetch</cite>, and in <cite>Referrer Policy</cite>. <ref>FETCH</ref>
<ref>REFERRERPOLICY</ref></p>
<div class="note">
<p>Several signals can contribute to which processing model is used for a given <span
data-x="concept-fetch">fetch</span>; a <span>referrer policy attribute</span> is only one of
them. In general, the order in which these signals are processed are:</p>
<ol>
<li><p>First, the presence of a <code data-x="rel-noreferrer">noreferrer</code> link
type;</p></li>
<li><p>Then, the value of a <span>referrer policy attribute</span>;</p></li>
<li><p>Then, the presence of any <code>meta</code> element with <code
data-x="attr-meta-name">name</code> attribute set to <code
data-x="meta-referrer">referrer</code>.</p></li>
<li><p>Finally, the `<code data-x="http-referrer-policy">Referrer-Policy</code>` HTTP
header.</p></li>
</ol>
</div>
<h4>Nonce attributes</h4>
<p>A <dfn element-attr for="htmlsvg-global" data-x="attr-nonce"><code>nonce</code></dfn> content
attribute represents a cryptographic nonce ("number used once") which can be used by <cite>Content
Security Policy</cite> to determine whether or not a given fetch will be allowed to proceed. The
value is text. <ref>CSP</ref></p>
<p>Elements that have a <code data-x="attr-nonce">nonce</code> content attribute ensure that the
cryptographic nonce is only exposed to script (and not to side-channels like CSS attribute
selectors) by taking the value from the content attribute, moving it into an internal slot
named <dfn for="HTMLOrSVGElement" attribute>[[CryptographicNonce]]</dfn>, exposing it to script
via the <code>HTMLOrSVGElement</code> interface mixin, and setting the content attribute to the
empty string. Unless otherwise specified, the slot's value is the empty string.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-HTMLOrSVGElement-nonce">nonce</span></code></dt>
<dd><p>Returns the value set for <var>element</var>'s cryptographic nonce. If the setter was not
used, this will be the value originally found in the <code data-x="attr-nonce">nonce</code>
content attribute.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-HTMLOrSVGElement-nonce">nonce</span> = <var>value</var></code></dt>
<dd><p>Updates <var>element</var>'s cryptographic nonce value.</p></dd>
</dl>
<p>The <dfn id="dom-noncedelement-nonce" attribute for="HTMLOrSVGElement"><code
data-x="dom-HTMLOrSVGElement-nonce">nonce</code></dfn> IDL attribute must, on getting, return the
value of this element's <span>[[CryptographicNonce]]</span>; and on setting, set this element's
<span>[[CryptographicNonce]]</span> to the given value.</p>
<p class="note" id="nonce-does-not-update-dom">Note how the setter for the <code
data-x="dom-HTMLOrSVGElement-nonce">nonce</code> IDL attribute does not update the corresponding
content attribute. This, as well as the below setting of the <code
data-x="attr-nonce">nonce</code> content attribute to the empty string when an element
<span>becomes browsing-context connected</span>, is meant to prevent exfiltration of the nonce
value through mechanisms that can easily read content attributes, such as selectors. Learn more in
<a href="https://github.com/whatwg/html/issues/2369">issue #2369</a>, where this behavior was
introduced.</p>
<p>The following <span data-x="concept-element-attributes-change-ext">attribute change
steps</span> are used for the <code data-x="attr-nonce">nonce</code> content attribute:
<ol>
<li><p>If <var>element</var> does not <span>include</span> <code>HTMLOrSVGElement</code>, then
return.</p></li>
<li><p>If <var>localName</var> is not <code data-x="attr-nonce">nonce</code> or
<var>namespace</var> is not null, then return.</p></li>
<li><p>If <var>value</var> is null, then set <var>element</var>'s
<span>[[CryptographicNonce]]</span> to the empty string.</p></li>
<li><p>Otherwise, set <var>element</var>'s <span>[[CryptographicNonce]]</span> to
<var>value</var>.</p></li>
</ol>
<p>Whenever an element <span data-x="include">including</span> <code>HTMLOrSVGElement</code>
<span>becomes browsing-context connected</span>, the user agent must execute the following steps
on the <var>element</var>:</p>
<ol>
<li><p>Let <var>CSP list</var> be <var>element</var>'s <span data-x="shadow-including
root">shadow-including root</span>'s <span data-x="concept-document-policy-container">policy
container</span>'s <span data-x="policy-container-csp-list">CSP list</span>.</p></li>
<li>
<p>If <var>CSP list</var> <span>contains a header-delivered Content Security Policy</span>, and
<var>element</var> has a <code data-x="attr-nonce">nonce</code> content attribute
whose value is not the empty string, then:</p>
<ol>
<li><p>Let <var>nonce</var> be <var>element</var>'s
<span>[[CryptographicNonce]]</span>.</p></li>
<li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span> for
<var>element</var> using "<code data-x="attr-nonce">nonce</code>" and the empty
string.</p></li>
<li><p>Set <var>element</var>'s <span>[[CryptographicNonce]]</span> to
<var>nonce</var>.</p></li>
</ol>
<p class="note">If <var>element</var>'s <span>[[CryptographicNonce]]</span> were not restored it
would be the empty string at this point.</p>
</li>
</ol>
<p>The <span data-x="concept-node-clone-ext">cloning steps</span> for elements that
<span>include</span> <code>HTMLOrSVGElement</code> given <var>node</var>, <var>copy</var>, and
<var>subtree</var> are to set <var>copy</var>'s <span>[[CryptographicNonce]]</span> to
<var>node</var>'s <span>[[CryptographicNonce]]</span>.</p>
<h4>Lazy loading attributes</h4>
<p>A <dfn>lazy loading attribute</dfn> is an <span>enumerated attribute</span> with the following
keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="img/loading,iframe/loading"><code data-x="attr-loading-lazy">lazy</code></dfn>
<td><dfn data-x="attr-loading-lazy-state">Lazy</dfn>
<td>Used to defer fetching a resource until some conditions are met.
<tr>
<td><dfn attr-value for="img/loading,iframe/loading"><code data-x="attr-loading-eager">eager</code></dfn>
<td><dfn data-x="attr-loading-eager-state">Eager</dfn>
<td>Used to fetch a resource immediately; the default state.
</table>
<p>The attribute directs the user agent to fetch a resource immediately or to defer fetching until
some conditions associated with the element are met, according to the attribute's current
state.</p>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-loading-eager-state">Eager</span> state.</p>
<hr>
<p>The <dfn>will lazy load element steps</dfn>, given an element <var>element</var>,
are as follows:</p>
<ol>
<li>
<p>If <span data-x="concept-n-noscript">scripting is disabled</span> for <var>element</var>,
then return false.</p>
<p class="note">This is an anti-tracking measure, because if a user agent supported lazy loading
when scripting is disabled, it would still be possible for a site to track a user's approximate
scroll position throughout a session, by strategically placing images in a page's markup such
that a server can track how many images are requested and when.</p>
</li>
<li><p>If <var>element</var>'s <span>lazy loading attribute</span> is in the <span
data-x="attr-loading-lazy-state">Lazy</span> state, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>Each <code>img</code> and <code>iframe</code> element has associated <dfn>lazy load resumption
steps</dfn>, initially null.</p>
<p class="note">For <code>img</code> and <code>iframe</code> elements that <span data-x="will lazy
load element steps">will lazy load</span>, these steps are run from the <span>lazy load
intersection observer</span>'s callback or when their <span>lazy loading attribute</span> is set
to the <span data-x="attr-loading-eager-state">Eager</span> state. This causes the element to
continue loading.</p>
<p>Each <code>Document</code> has a <dfn>lazy load intersection observer</dfn>, initially set to
null but can be set to an <code>IntersectionObserver</code> instance.</p>
<p>To <dfn>start intersection-observing a lazy loading element</dfn> <var>element</var>, run these
steps:</p>
<ol>
<li><p>Let <var>doc</var> be <var>element</var>'s <span>node document</span>.</p></li>
<li>
<p>If <var>doc</var>'s <span>lazy load intersection observer</span> is null, set it to a new
<code>IntersectionObserver</code> instance, initialized as follows:</p>
<p class="XXX">The intention is to use the original value of the
<code>IntersectionObserver</code> constructor. However, we're forced to use the
JavaScript-exposed constructor in this specification, until <cite>Intersection Observer</cite>
exposes low-level hooks for use in specifications. See bug <a
href="https://github.com/w3c/IntersectionObserver/issues/464">w3c/IntersectionObserver#464</a>
which tracks this. <ref>INTERSECTIONOBSERVER</ref></p>
<ul>
<li>
<p>The <var>callback</var> is these steps, with arguments <var>entries</var> and
<var>observer</var>:</p>
<ol>
<li>
<p>For each <var>entry</var> in <var>entries</var> <span class="XXX">using a method of
iteration which does not trigger developer-modifiable array accessors or
iteration hooks</span>:</p>
<ol>
<li><p>Let <var>resumptionSteps</var> be null.</p></li>
<li><p>If <var>entry</var>.<code
data-x="dom-IntersectionObserverEntry-isIntersecting">isIntersecting</code> is true, then
set <var>resumptionSteps</var> to <var>entry</var>.<code
data-x="dom-IntersectionObserverEntry-target">target</code>'s
<span>lazy load resumption steps</span>.</p></li>
<li><p>If <var>resumptionSteps</var> is null, then return.</p></li>
<li><p><span>Stop intersection-observing a lazy loading element</span> for
<var>entry</var>.<code data-x="dom-IntersectionObserverEntry-target">target</code>.</p></li>
<li><p>Set <var>entry</var>.<code
data-x="dom-IntersectionObserverEntry-target">target</code>'s <span>lazy load resumption
steps</span> to null.</p></li>
<li><p>Invoke <var>resumptionSteps</var>.</p></li>
</ol>
<p class="XXX">The intention is to use the original value of the
<code data-x="dom-IntersectionObserverEntry-isIntersecting">isIntersecting</code> and
<code data-x="dom-IntersectionObserverEntry-target">target</code> getters. See <a
href="https://github.com/w3c/IntersectionObserver/issues/464">w3c/IntersectionObserver#464</a>.
<ref>INTERSECTIONOBSERVER</ref></p>
</li>
</ol>
</li>
<li>
<p>The <var>options</var> is an <code>IntersectionObserverInit</code> dictionary with the
following dictionary members: «[ "<code data-x="">scrollMargin</code>" → <span>lazy load scroll
margin</span> ]»</p>
<p class="note">This allows for fetching the image during scrolling, when it does not yet —
but is about to — intersect the viewport.</p>
<p class="XXX">The <span>lazy load scroll margin</span> suggestions imply dynamic changes to the
value, but the <code>IntersectionObserver</code> API does not support changing the scroll
margin. See issue <a
href="https://github.com/w3c/IntersectionObserver/issues/428">w3c/IntersectionObserver#428</a>.</p>
</li>
</ul>
</li>
<li>
<p>Call <var>doc</var>'s <span>lazy load intersection observer</span>'s <code
data-x="dom-IntersectionObserver-observe">observe</code> method with <var>element</var> as the
argument.</p>
<p class="XXX">The intention is to use the original value of the <code
data-x="dom-IntersectionObserver-observe">observe</code> method. See <a
href="https://github.com/w3c/IntersectionObserver/issues/464">w3c/IntersectionObserver#464</a>.
<ref>INTERSECTIONOBSERVER</ref></p>
</li>
</ol>
<p>To <dfn>stop intersection-observing a lazy loading element</dfn> <var>element</var>, run these
steps:</p>
<ol>
<li><p>Let <var>doc</var> be <var>element</var>'s <span>node document</span>.</p></li>
<li><p><span>Assert</span>: <var>doc</var>'s <span>lazy load intersection observer</span> is not
null.</p></li>
<li>
<p>Call <var>doc</var>'s <span>lazy load intersection observer</span>'s <code
data-x="dom-IntersectionObserver-unobserve">unobserve</code> method with <var>element</var> as
the argument.</p>
<p class="XXX">The intention is to use the original value of the <code
data-x="dom-IntersectionObserver-unobserve">unobserve</code> method. See <a
href="https://github.com/w3c/IntersectionObserver/issues/464">w3c/IntersectionObserver#464</a>.
<ref>INTERSECTIONOBSERVER</ref></p>
</li>
</ol>
<p>
<!--INSERT TRACKING-->
The <dfn id="lazy-load-root-margin">lazy load scroll margin</dfn> is an
<span>implementation-defined</span> value, but with the following suggestions to consider:</p>
<ul>
<li><p>Set a minimum value that most often results in the resources being loaded before they
intersect the viewport under normal usage patterns for the given device.</p></li>
<li><p>The typical scrolling speed: increase the value for devices with faster typical scrolling
speeds.</p></li>
<li><p>The current scrolling speed or momentum: the UA can attempt to predict where the scrolling
will likely stop, and adjust the value accordingly.</p></li>
<li><p>The network quality: increase the value for slow or high-latency connections.</p></li>
<li><p>User preferences can influence the value.</p></li>
</ul>
<p class="note">It is important <span data-x="tracking vector">for privacy</span> that the
<span>lazy load scroll margin</span> not leak additional information. For example, the typical
scrolling speed on the current device could be imprecise so as to not introduce a new
fingerprinting vector.</p>
<h4>Blocking attributes</h4>
<p>A <dfn>blocking attribute</dfn> explicitly indicates that certain operations should be blocked
on the fetching of an external resource. The operations that can be blocked are represented by
<dfn data-x="possible blocking token">possible blocking tokens</dfn>, which are strings listed by
the following table:</p>
<table>
<thead>
<tr>
<th>Possible blocking token
<th>Description
<tbody>
<tr>
<td>"<dfn><code data-x="blocking-token-render">render</code></dfn>"
<td>The element is <span>potentially render-blocking</span>.
</table>
<p class="note" id="future-blocking-tokens">In the future, there might be more <span
data-x="possible blocking token">possible blocking tokens</span>.</p>
<p>A <span>blocking attribute</span> must have a value that is an <span>unordered set of unique
space-separated tokens</span>, each of which are <span data-x="possible blocking token">possible
blocking tokens</span>. The <span data-x="concept-supported-tokens">supported tokens</span> of a
<span>blocking attribute</span> are the <span data-x="possible blocking token">possible blocking
tokens</span>. Any element can have at most one <span>blocking attribute</span>.</p>
<p>The <dfn>blocking tokens set</dfn> for an element <var>el</var> are the result of the
following steps:</p>
<ol>
<li><p>Let <var>value</var> be the value of <var>el</var>'s <span>blocking attribute</span>, or
the empty string if no such attribute exists.</p>
<li><p>Set <var>value</var> to <var>value</var>, <span>converted to ASCII lowercase</span>.</p>
<li><p>Let <var>rawTokens</var> be the result of <span data-x="split a string on ASCII
whitespace">splitting <var>value</var> on ASCII whitespace</span>.</p>
<li><p>Return a set containing the elements of <var>rawTokens</var> that are <span
data-x="possible blocking token">possible blocking tokens</span>.</p>
</ol>
<p>An element is <dfn>potentially render-blocking</dfn> if its <span>blocking tokens set</span>
contains "<code data-x="blocking-token-render">render</code>", or if it is
<dfn>implicitly potentially render-blocking</dfn>, which will be defined at the individual
elements. By default, an element is not <span>implicitly potentially render-blocking</span>.</p>
<h4>Fetch priority attributes</h4>
<p>A <dfn>fetch priority attribute</dfn> is an <span>enumerated attribute</span> with the
following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value
for="img/fetchpriority,script/fetchpriority,link/fetchpriority"
data-x="attr-fetchpriority-high"><code>high</code></dfn>
<td><dfn data-x="attr-fetchpriority-high-state">high</dfn>
<td>Signals a high-priority <span data-x="concept-fetch">fetch</span> relative to other
resources with the same <span data-x="concept-request-destination">destination</span>.
<tr>
<td><dfn attr-value
for="img/fetchpriority,script/fetchpriority,link/fetchpriority"
data-x="attr-fetchpriority-low"><code>low</code></dfn>
<td><dfn data-x="attr-fetchpriority-low-state">low</dfn>
<td>Signals a low-priority <span data-x="concept-fetch">fetch</span> relative to other
resources with the same <span data-x="concept-request-destination">destination</span>.
<tr>
<td><dfn attr-value
for="img/fetchpriority,script/fetchpriority,link/fetchpriority"
data-x="attr-fetchpriority-auto"><code>auto</code></dfn>
<td><dfn data-x="attr-fetchpriority-auto-state">auto</dfn>
<td>Signals automatic determination of <span data-x="concept-fetch">fetch</span> priority
relative to other resources with the same <span
data-x="concept-request-destination">destination</span>.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and
<i data-x="invalid value default">invalid value default</i> are both the
<span data-x="attr-fetchpriority-auto-state">auto</span> state.</p>
<h3 split-filename="common-dom-interfaces">Common DOM interfaces</h3>
<h4>Reflecting content attributes in IDL attributes</h4>
<p>The building blocks for reflecting are as follows:</p>
<ul>
<li><p>A <dfn>reflected target</dfn> is an element or <code>ElementInternals</code>
object. It is typically clear from context and typically identical to the interface of the
<span>reflected IDL attribute</span>. It is always identical to that interface when it is an
<code>ElementInternals</code> object.</p></li>
<li><p>A <dfn>reflected IDL attribute</dfn> is an attribute interface member.</p></li>
<li><p>A <dfn>reflected content attribute name</dfn> is a string. When the <span>reflected
target</span> is an element, it represents the local name of a content attribute whose namespace
is null. When the <span>reflected target</span> is an <code>ElementInternals</code> object, it
represents a key of the <span>reflected target</span>'s <span data-x="internals-target">target
element</span>'s <span>internal content attribute map</span>.</p></li>
</ul>
<p>A <span>reflected IDL attribute</span> can be defined to <dfn export>reflect</dfn> a
<span>reflected content attribute name</span> of a <span>reflected target</span>. In general this
means that the IDL attribute getter returns the current value of the content attribute, and the
setter changes the value of the content attribute to the given value.</p>
<p>If the <span>reflected target</span> is an element, then the <span>reflected IDL
attribute</span> can additionally declare to <dfn>support <code>ElementInternals</code></dfn>.
This means that the <code>ElementInternals</code> interface also has a <span>reflected IDL
attribute</span>, with the same identifier, and that <span>reflected IDL attribute</span> <span
data-x="reflect">reflects</span> the same <span>reflected content attribute name</span>.</p>
<p class="example" id="example-reflect-incantation">The <code data-x=""><var>fooBar</var></code>
IDL attribute <!--non-normative-->must <span>reflect</span> the <code
data-x=""><var>foobar</var></code> content attribute and <span>support
<code>ElementInternals</code></span>.</p>
<div w-nodev>
<p><span data-x="reflected target">Reflected targets</span> have these associated algorithms:
<ul class="brief">
<li><dfn>get the element</dfn>: takes no arguments; returns an element.</li>
<li><dfn>get the content attribute</dfn>: takes no arguments; returns null or a string.</li>
<li><dfn>set the content attribute</dfn>: takes a string <var>value</var>; returns nothing.</li>
<li><dfn>delete the content attribute</dfn>: takes no arguments; returns nothing.</li>
</ul>
<p>For a <span>reflected target</span> that is an element <var>element</var>, these are defined as
follows:</p>
<dl>
<dt><span>get the element</span></dt>
<dd><ol><li><p>Return <var>element</var>.</p></li></ol></dd>
<dt><span>get the content attribute</span></dt>
<dd>
<ol>
<li><p>Let <var>attribute</var> be the result of running <span
data-x="concept-element-attributes-get-by-namespace">get an attribute by namespace and local
name</span> given null, the <span>reflected content attribute name</span>, and
<var>element</var>.</p></li>
<li><p>If <var>attribute</var> is null, then return null.</p></li>
<li><p>Return <var>attribute</var>'s <span
data-x="concept-attribute-value">value</span>.</p></li>
</ol>
</dd>
<dt><span>set the content attribute</span> with a string <var>value</var></dt>
<dd><ol><li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span>
given <var>element</var>, the <span>reflected content attribute name</span>, and
<var>value</var>.</p></li></ol></dd>
<dt><span>delete the content attribute</span></dt>
<dd><ol><li><p><span data-x="concept-element-attributes-remove-by-namespace">Remove an attribute
by namespace and local name</span> given null, the <span>reflected content attribute name</span>,
and <var>element</var>.</p></li></ol></dd>
</dl>
<p>For a <span>reflected target</span> that is an <code>ElementInternals</code> object
<var>elementInternals</var>, they are defined as follows:</p>
<dl>
<dt><span>get the element</span></dt>
<dd><ol><li><p>Return <var>elementInternals</var>'s <span data-x="internals-target">target
element</span>.</p></li></ol></dd>
<dt><span>get the content attribute</span></dt>
<dd>
<ol>
<li><p>If <var>elementInternals</var>'s <span data-x="internals-target">target element</span>'s
<span>internal content attribute map</span>[the <span>reflected content attribute name</span>]
<span data-x="map exists">does not exist</span>, then return null.
<li><p>Return <var>elementInternals</var>'s <span data-x="internals-target">target
element</span>'s <span>internal content attribute map</span>[the <span>reflected content
attribute name</span>].</p></li>
</ol>
</dd>
<dt><span>set the content attribute</span> with a string <var>value</var></dt>
<dd><ol><li><p><span data-x="map set">Set</span> <var>elementInternals</var>'s <span
data-x="internals-target">target element</span>'s <span>internal content attribute map</span>[the
<span>reflected content attribute name</span>] to <var>value</var>.</p></li></ol></dd>
<dt><span>delete the content attribute</span></dt>
<dd><ol><li><p><span data-x="map remove">Remove</span> <var>elementInternals</var>'s <span
data-x="internals-target">target element</span>'s <span>internal content attribute map</span>[the
<span>reflected content attribute name</span>].</p></li></ol></dd>
</dl>
<p class="note">This results in somewhat redundant data structures for
<code>ElementInternals</code> objects as their <span data-x="internals-target">target
element</span>'s <span>internal content attribute map</span> cannot be directly manipulated and as
such reflection is only happening in a single direction. This approach was nevertheless chosen to
make it less error-prone to define IDL attributes that are shared between <span data-x="reflected
target">reflected targets</span> and benefit from common API semantics.</p>
<hr>
<p>IDL attributes of type <code data-x="idl-DOMString">DOMString</code> or <code data-x=""><span
data-x="idl-DOMString">DOMString</span>?</code> that <span>reflect</span> <span data-x="enumerated
attribute">enumerated</span> content attributes can be <dfn>limited to only known values</dfn>.
Per the processing models below, those will cause the getters for such IDL attributes to only
return keywords for those enumerated attributes, or the empty string or null.</p>
<p>If a <span>reflected IDL attribute</span> has the type <code
data-x="idl-DOMString">DOMString</code>:</p>
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>element</var> be the result of running <span>this</span>'s <span>get the
element</span>.</p></li>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li><p>Let <var>attributeDefinition</var> be the attribute definition of <var>element</var>'s
content attribute whose namespace is null and local name is the <span>reflected content
attribute name</span>.
<li>
<p>If <var>attributeDefinition</var> indicates it is an <span>enumerated attribute</span> and
the <span>reflected IDL attribute</span> is defined to be <span>limited to only known
values</span>:</p>
<ol>
<li><p>If <var>contentAttributeValue</var> does not correspond to any state of
<var>attributeDefinition</var> (e.g., it is null and there is no <i data-x="missing value
default">missing value default</i>), or if it is in a state of
<var>attributeDefinition</var> with no associated keyword value, then return the empty
string.</p></li>
<li><p>Return the <span>canonical keyword</span> for the state of
<var>attributeDefinition</var> that <var>contentAttributeValue</var> corresponds to.</p></li>
</ol>
</li>
<li><p>If <var>contentAttributeValue</var> is null, then return the empty string.</p></li>
<li><p>Return <var>contentAttributeValue</var>.</p></li>
</ol>
</li>
<li><p>The setter steps are to run <span>this</span>'s <span>set the content attribute</span>
with the given value.</p></li>
</ul>
<p>If a <span>reflected IDL attribute</span> has the type <code data-x=""><span
data-x="idl-DOMString">DOMString</span>?</code>:</p>
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>element</var> be the result of running <span>this</span>'s <span>get the
element</span>.</p></li>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li><p>Let <var>attributeDefinition</var> be the attribute definition of <var>element</var>'s
content attribute whose namespace is null and local name is the <span>reflected content
attribute name</span>.
<li>
<p>If <var>attributeDefinition</var> indicates it is an <span>enumerated attribute</span>:</p>
<ol>
<li><p><span>Assert</span>: the <span>reflected IDL attribute</span> is <span>limited to only
known values</span>.</p></li>
<li><p><span>Assert</span>: <var>contentAttributeValue</var> corresponds to a state of
<var>attributeDefinition</var>.</p></li>
<li><p>If <var>contentAttributeValue</var> corresponds to a state of
<var>attributeDefinition</var> with no associated keyword value, then return null.</p></li>
<li><p>Return the <span>canonical keyword</span> for the state of
<var>attributeDefinition</var> that <var>contentAttributeValue</var> corresponds to.</p></li>
</ol>
</li>
<li><p>Return <var>contentAttributeValue</var>.</p></li>
</ol>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li><p>If the given value is null, then run <span>this</span>'s <span>delete the content
attribute</span>.</p></li>
<li><p>Otherwise, run <span>this</span>'s <span>set the content attribute</span> with the given
value.</p></li>
</ol>
</li>
</ul>
<p>If a <span>reflected IDL attribute</span> has the type <code
data-x="idl-USVString">USVString</code>:</p>
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>element</var> be the result of running <span>this</span>'s <span>get the
element</span>.</p></li>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li><p>Let <var>attributeDefinition</var> be the attribute definition of <var>element</var>'s
content attribute whose namespace is null and local name is the <span>reflected content
attribute name</span>.
<li>
<p>If <var>attributeDefinition</var> indicates it contains a <span>URL</span>:</p>
<ol>
<li><p>If <var>contentAttributeValue</var> is null, then return the empty string.</p></li>
<li><p>Let <var>urlString</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given <var>contentAttributeValue</var>, relative to <var>element</var>'s
<span>node document</span>.</p></li>
<li><p>If <var>urlString</var> is not failure, then return <var>urlString</var>.</p></li>
</ol>
</li>
<li><p>Return <var>contentAttributeValue</var>, <span
data-x="convert">converted to a scalar value string</span>.</p></li>
</ol>
</li>
<li><p>The setter steps are to run <span>this</span>'s <span>set the content attribute</span>
with the given value.</p></li>
</ul>
<p>If a <span>reflected IDL attribute</span> has the type <code
data-x="idl-boolean">boolean</code>:</p>
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li><p>If <var>contentAttributeValue</var> is null, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li><p>If the given value is false, then run <span>this</span>'s <span>delete the content
attribute</span>.</p></li>
<li><p>If the given value is true, then run <span>this</span>'s <span>set the content
attribute</span> with the empty string.
</ol>
</li>
</ul>
<p class="note">This corresponds to the rules for <span data-x="boolean attribute">boolean content
attributes</span>.
<p>If a <span>reflected IDL attribute</span> has the type <code data-x="idl-long">long</code>,
optionally <dfn>limited to only non-negative numbers</dfn> and optionally with a <dfn>default
value</dfn> <var>defaultValue</var>:
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li>
<p>If <var>contentAttributeValue</var> is not null:
<ol>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="rules for parsing
integers">integer parsing</span> <var>contentAttributeValue</var> if the <span>reflected IDL
attribute</span> is not <span>limited to only non-negative numbers</span>; otherwise the
result of <span data-x="rules for parsing non-negative integers">non-negative integer
parsing</span> <var>contentAttributeValue</var>.</p></li>
<li><p>If <var>parsedValue</var> is not an error and is within the <code
data-x="idl-long">long</code> range, then return <var>parsedValue</var>.</p></li>
</ol>
</li>
<li><p>If the <span>reflected IDL attribute</span> has a <span>default value</span>, then
return <var>defaultValue</var>.</p></li>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only non-negative
numbers</span>, then return −1.</p></li>
<li><p>Return 0.</p></li>
</ol>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only non-negative
numbers</span> and the given value is negative, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Run <span>this</span>'s <span>set the content attribute</span> with the given value
converted to the shortest possible string representing the number as a <span>valid
integer</span>.</p></li>
</ol>
</li>
</ul>
<p>If a <span>reflected IDL attribute</span> has the type <code
data-x="idl-unsigned-long">unsigned long</code>, optionally <dfn
id="limited-to-only-non-negative-numbers-greater-than-zero">limited to only positive
numbers</dfn>, <dfn
id="limited-to-only-non-negative-numbers-greater-than-zero-with-fallback">limited to only positive
numbers with fallback</dfn>, or <dfn>clamped to the range</dfn> [<var>clampedMin</var>,
<var>clampedMax</var>], and optionally with a <span>default value</span> <var>defaultValue</var>:
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li><p>Let <var>minimum</var> be 0.</p></li>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only positive
numbers</span> or <span>limited to only positive numbers with fallback</span>, then set
<var>minimum</var> to 1.</p></li>
<li><p>If the <span>reflected IDL attribute</span> is <span>clamped to the range</span>, then
set <var>minimum</var> to <var>clampedMin</var>.</p></li>
<li><p>Let <var>maximum</var> be 2147483647 if the <span>reflected IDL attribute</span> is not
<span>clamped to the range</span>; otherwise <var>clampedMax</var>.</p></li>
<li>
<p>If <var>contentAttributeValue</var> is not null:
<ol>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="rules for parsing
non-negative integers">non-negative integer parsing</span>
<var>contentAttributeValue</var>.</p></li>
<li><p>If <var>parsedValue</var> is not an error and is in the range <var>minimum</var> to
<var>maximum</var>, inclusive, then return <var>parsedValue</var>.</p></li>
<li>
<p>If <var>parsedValue</var> is not an error and the <span>reflected IDL attribute</span> is
<span>clamped to the range</span>:
<ol>
<li><p>If <var>parsedValue</var> is less than <var>minimum</var>, then return
<var>minimum</var>.</p></li>
<li><p>Return <var>maximum</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If the <span>reflected IDL attribute</span> has a <span>default value</span>, then
return <var>defaultValue</var>.</p></li>
<li><p>Return <var>minimum</var>.</p></li>
</ol>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only positive
numbers</span> and the given value is 0, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>minimum</var> be 0.</p></li>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only positive
numbers</span> or <span>limited to only positive numbers with fallback</span>, then set
<var>minimum</var> to 1.</p></li>
<li><p>Let <var>newValue</var> be <var>minimum</var>.</p></li>
<li><p>If the <span>reflected IDL attribute</span> has a <span>default value</span>, then set
<var>newValue</var> to <var>defaultValue</var>.</p></li>
<li><p>If the given value is in the range <var>minimum</var> to 2147483647, inclusive,
then set <var>newValue</var> to it.</p></li>
<li><p>Run <span>this</span>'s <span>set the content attribute</span> with <var>newValue</var>
converted to the shortest possible string representing the number as a <span>valid non-negative
integer</span>.</p></li>
</ol>
<p class="note"><span>Clamped to the range</span> has no effect on the setter steps.</p>
</li>
</ul>
<!-- see https://www.w3.org/Bugs/Public/show_bug.cgi?id=10352
https://bugzilla.mozilla.org/show_bug.cgi?id=586118
https://www.w3.org/Bugs/Public/show_bug.cgi?id=17705
...for why the range is clamped to 2147483647 rather the normal unsigned long maximum value
of 4294967295 -->
<p>If a <span>reflected IDL attribute</span> has the type <code data-x="idl-double">double</code>,
optionally <span id="limited-to-numbers-greater-than-zero">limited to only positive numbers</span>
and optionally with a <span>default value</span> <var>defaultValue</var>:
<ul>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>contentAttributeValue</var> be the result of running <span>this</span>'s
<span>get the content attribute</span>.</p></li>
<li>
<p>If <var>contentAttributeValue</var> is not null:
<ol>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="rules for parsing
floating-point number values">floating-point number parsing</span>
<var>contentAttributeValue</var>.</p></li>
<li><p>If <var>parsedValue</var> is not an error and is greater than 0, then return
<var>parsedValue</var>.</p></li>
<li><p>If <var>parsedValue</var> is not an error and the <span>reflected IDL attribute</span>
is not <span>limited to only positive numbers</span>, then return
<var>parsedValue</var>.</p></li>
</ol>
</li>
<li><p>If the <span>reflected IDL attribute</span> has a <span>default value</span>, then
return <var>defaultValue</var>.</p></li>
<li><p>Return 0.</p></li>
</ol>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li><p>If the <span>reflected IDL attribute</span> is <span>limited to only positive
numbers</span> and the given value is not greater than 0, then return.</p></li>
<li><p>Run <span>this</span>'s <span>set the content attribute</span> with the given value,
converted to the <span>best representation of the number as a floating-point
number</span>.</p></li>
</ol>
</li>
</ul>
<p class="note">The values Infinity and Not-a-Number (NaN) values throw an exception on setting,
as defined in <cite>Web IDL</cite>. <ref>WEBIDL</ref></p>
<p>If a <span>reflected IDL attribute</span> has the type <code>DOMTokenList</code>, then its
getter steps are to return a <code>DOMTokenList</code> object whose associated element is
<span>this</span> and associated attribute's local name is the <span>reflected content
attribute name</span>. Specification authors cannot use <span>support
<code>ElementInternals</code></span> for IDL attributes of this type.</p>
<!-- Supporting ElementInternals is doable in theory, but would require corresponding changes to
DOMTokenList. -->
<p>If a <span>reflected IDL attribute</span> has the type <code data-x=""><var>T</var>?</code>,
where <var>T</var> is either <code>Element</code> or an interface that inherits from
<code>Element</code>, then with <var>attr</var> being the <span>reflected content attribute
name</span>:</p>
<ul>
<li><p>Its <span>reflected target</span> has an <dfn>explicitly set
<var>attr</var>-element</dfn>, which is a weak reference to an element or null. It is initially
null.</p></li>
<li>
<p>Its <span>reflected target</span> <var>reflectedTarget</var> has a <dfn
for="Element,ElementInternals" export id="attr-associated-element">get the
<var>attr</var>-associated element</dfn> algorithm, that runs these steps:</p>
<ol>
<li><p>Let <var>element</var> be the result of running <var>reflectedTarget</var>'s <span>get
the element</span>.</p></li>
<li><p>Let <var>contentAttributeValue</var> be the result of running
<var>reflectedTarget</var>'s <span>get the content attribute</span>.</p></li>
<li>
<p>If <var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-element</span> is not
null:</p>
<ol>
<li><p>If <var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-element</span> is
a <span>descendant</span> of any of <var>element</var>'s <span
data-x="concept-shadow-including-ancestor">shadow-including ancestors</span>, then return
<var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-element</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>contentAttributeValue</var> is not null, return the first element
<var>candidate</var>, in <span>tree order</span>, that meets the following criteria:</p>
<ul>
<li><p><var>candidate</var>'s <span>root</span> is the same as <var>element</var>'s
<span>root</span>;</p></li>
<li><p><var>candidate</var>'s <span data-x="concept-ID">ID</span> is
<var>contentAttributeValue</var>; and</p></li>
<li><p><var>candidate</var> <span>implements</span> <var>T</var>.</p></li>
</ul>
<p>If no such element exists, then return null.</p>
</li>
<li><p>Return null.</p></li>
</ol>
</li>
<li><p>The getter steps are to return the result of running <span>this</span>'s <span>get the
<var>attr</var>-associated element</span>.</p></li>
<li>
<p>The setter steps are:</p>
<ol>
<li>
<p>If the given value is null, then:</p>
<ol>
<li><p>Set <span>this</span>'s <span>explicitly set <var>attr</var>-element</span> to
null.</p></li>
<li><p>Run <span>this</span>'s <span>delete the content attribute</span>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Run <span>this</span>'s <span>set the content attribute</span> with the empty
string.</p></li>
<li><p>Set <span>this</span>'s <span>explicitly set <var>attr</var>-element</span> to a weak
reference to the given value.</p></li>
</ol>
</li>
<li>
<p>For element <span data-x="reflected target">reflected targets</span> only: the following
<span data-x="concept-element-attributes-change-ext">attribute change steps</span>, given
<var>element</var>, <var>localName</var>, <var>oldValue</var>, <var>value</var>, and
<var>namespace</var>, are used to synchronize between the content attribute and the IDL
attribute:</p>
<ol>
<li><p>If <var>localName</var> is not <var>attr</var> or <var>namespace</var> is not null, then
return.</p></li>
<li><p>Set <var>element</var>'s <span>explicitly set <var>attr</var>-element</span> to
null.</p></li>
</ol>
</li>
</ul>
<p class="note"><span data-x="reflected IDL attribute">Reflected IDL attributes</span> of this
type are strongly encouraged to have their identifier end in "<code data-x="">Element</code>" for
consistency.</p>
<p>If a <span>reflected IDL attribute</span> has the type <code
data-x="">FrozenArray<<var>T</var>>?</code>, where <var>T</var> is either
<code>Element</code> or an interface that inherits from <code>Element</code>, then with
<var>attr</var> being the <span>reflected content attribute name</span>:</p>
<ul>
<li><p>Its <span>reflected target</span> has an <dfn>explicitly set
<var>attr</var>-elements</dfn>, which is either a <span>list</span> of weak references to
elements or null. It is initially null.</p></li>
<li><p>Its <span>reflected target</span> has a <dfn>cached <var>attr</var>-associated
elements</dfn>, which is a <span>list</span> of elements. It is initially « ».</p></li>
<li><p>Its <span>reflected target</span> has a <dfn>cached <var>attr</var>-associated
elements object</dfn>, which is a <code data-x="">FrozenArray<<var>T</var>>?</code>. It is
initially null.</p></li>
<li>
<p>Its <span>reflected target</span> <var>reflectedTarget</var> has a <dfn
for="Element,ElementInternals" export id="attr-associated-elements">get the
<var>attr</var>-associated elements</dfn> algorithm, which runs these steps:</p>
<ol>
<li><p>Let <var>elements</var> be an empty <span>list</span>.</p></li>
<li><p>Let <var>element</var> be the result of running <var>reflectedTarget</var>'s <span>get
the element</span>.</p></li>
<li>
<p>If <var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-elements</span> is not
null:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>attrElement</var> in
<var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-elements</span>:</p>
<ol>
<li><p>If <var>attrElement</var> is not a <span>descendant</span> of any of
<var>element</var>'s <span data-x="concept-shadow-including-ancestor">shadow-including
ancestors</span>, then <span>continue</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>attrElement</var> to
<var>elements</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>contentAttributeValue</var> be the result of running
<var>reflectedTarget</var>'s <span>get the content attribute</span>.
<li><p>If <var>contentAttributeValue</var> is null, then return null.</p></li>
<li><p>Let <var>tokens</var> be <var>contentAttributeValue</var>, <span data-x="split a
string on ASCII whitespace">split on ASCII whitespace</span>.
<li>
<p><span data-x="list iterate">For each</span> <var>id</var> of <var>tokens</var>:</p>
<ol>
<li>
<p>Let <var>candidate</var> be the first element, in <span>tree order</span>, that meets
the following criteria:</p>
<ul>
<li><p><var>candidate</var>'s <span>root</span> is the same as <var>element</var>'s
<span>root</span>;</p></li>
<li><p><var>candidate</var>'s <span data-x="concept-ID">ID</span> is <var>id</var>;
and</p></li>
<li><p><var>candidate</var> <span>implements</span> <var>T</var>.</p></li>
</ul>
<p>If no such element exists, then <span>continue</span>.</p>
</li>
<li><p><span data-x="list append">Append</span> <var>candidate</var> to
<var>elements</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>elements</var>.</p></li>
</ol>
</li>
<li>
<p>The getter steps are:</p>
<ol>
<li><p>Let <var>elements</var> be the result of running <span>this</span>'s <span>get the
<var>attr</var>-associated elements</span>.</p></li>
<li><p>If the contents of <var>elements</var> is equal to the contents of <span>this</span>'s
<span>cached <var>attr</var>-associated elements</span>, then return <span>this</span>'s
<span>cached <var>attr</var>-associated elements object</span>.</p></li>
<li><p>Let <var>elementsAsFrozenArray</var> be <var>elements</var>, <span
data-x="concept-idl-convert">converted</span> to a <code
data-x="">FrozenArray<<var>T</var>>?</code>.</p></li>
<li><p>Set <span>this</span>'s <span>cached <var>attr</var>-associated elements</span> to
<var>elements</var>.</p></li>
<li><p>Set <span>this</span>'s <span>cached <var>attr</var>-associated elements object</span>
to <var>elementsAsFrozenArray</var>.</p></li>
<li><p>Return <var>elementsAsFrozenArray</var>.</p></li>
</ol>
<p class="note">This extra caching layer is necessary to preserve the invariant that <code
data-x="">element.reflectedElements === element.reflectedElements</code>.</p>
</li>
<li>
<p>The setter steps are:</p>
<ol>
<li>
<p>If the given value is null:</p>
<ol>
<li><p>Set <span>this</span>'s <span>explicitly set <var>attr</var>-elements</span> to
null.</p></li>
<li><p>Run <span>this</span>'s <span>delete the content attribute</span>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Run <span>this</span>'s <span>set the content attribute</span> with the empty
string.</p></li>
<li><p>Let <var>elements</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>element</var> in the given value:</p>
<ol>
<li><p><span data-x="list append">Append</span> a weak reference to <var>element</var> to
<var>elements</var>.</p></li>
</ol>
</li>
<li><p>Set <span>this</span>'s <span>explicitly set <var>attr</var>-elements</span> to
<var>elements</var>.</p></li>
</ol>
</li>
<li>
<p>For element <span data-x="reflected target">reflected targets</span> only: the following
<span data-x="concept-element-attributes-change-ext">attribute change steps</span>, given
<var>element</var>, <var>localName</var>, <var>oldValue</var>, <var>value</var>, and
<var>namespace</var>, are used to synchronize between the content attribute and the IDL
attribute:</p>
<ol>
<li><p>If <var>localName</var> is not <var>attr</var> or <var>namespace</var> is not null, then
return.</p></li>
<li><p>Set <var>element</var>'s <span>explicitly set <var>attr</var>-elements</span> to
null.</p></li>
</ol>
</li>
</ul>
<p class="note"><span data-x="reflected IDL attribute">Reflected IDL attributes</span> of this
type are strongly encouraged to have their identifier end in "<code data-x="">Elements</code>" for
consistency.</p>
<h4>Using reflect in specifications</h4>
<p><span data-x="reflect">Reflection</span> is primarily about improving web developer ergonomics
by giving them typed access to content attributes through <span data-x="reflected IDL
attribute">reflected IDL attributes</span>. The ultimate source of truth, which the web platform
builds upon, is the content attributes themselves. That is, specification authors must not use the
<span>reflected IDL attribute</span> getter or setter steps, but instead must use the content
attribute presence and value. (Or an abstraction on top, such as the state of an <span>enumerated
attribute</span>.)</p>
<p>Two important exceptions to this are <span data-x="reflected IDL attribute">reflected IDL
attributes</span> whose type is one of the following:</p>
<ul>
<li><p><code data-x=""><var>T</var>?</code>, where <var>T</var> is either <code>Element</code> or
an interface that inherits from <code>Element</code></p></li>
<li><p><code data-x="">FrozenArray<<var>T</var>>?</code>, where <var>T</var> is either
<code>Element</code> or an interface that inherits from <code>Element</code></p></li>
</ul>
<p>For those, specification authors must use the <span>reflected target</span>'s
<span>get the <var>attr</var>-associated element</span> and <span>get the
<var>attr</var>-associated elements</span>, respectively. The content attribute presence and value
must not be used as they cannot be fully synchronized with the <span>reflected IDL
attribute</span>.</p>
<p>A <span>reflected target</span>'s <span>explicitly set <var>attr</var>-element</span>,
<span>explicitly set <var>attr</var>-elements</span>, <span>cached <var>attr</var>-associated
elements</span>, and <span>cached <var>attr</var>-associated elements object</span> are to be
treated as internal implementation details and not to be built upon.</p>
</div>
<h4>Collections</h4>
<p>The <code>HTMLFormControlsCollection</code> and <code>HTMLOptionsCollection</code> interfaces
are <span data-x="concept-collection">collections</span> derived from the
<code>HTMLCollection</code> interface. The <code>HTMLAllCollection</code> interface is a <span
data-x="concept-collection">collection</span>, but is not so derived.</p>
<h5>The <code>HTMLAllCollection</code> interface</h5>
<p>The <code>HTMLAllCollection</code> interface is used for the legacy <code
data-x="dom-document-all">document.all</code> attribute. It operates similarly to
<code>HTMLCollection</code>; the main differences are that it allows a staggering variety of
different (ab)uses of its methods to all end up returning something, and that it can be called as
a function as an alternative to property access.</p>
<p class="note">All <code>HTMLAllCollection</code> objects are rooted at a <code>Document</code>
and have a filter that matches all elements, so the elements <span>represented by the
collection</span> of an <code>HTMLAllCollection</code> object consist of all the descendant
elements of the root <code>Document</code>.</p>
<p w-nodev>Objects that implement the <code>HTMLAllCollection</code> interface are <span
data-x="legacy platform object">legacy platform objects</span> with an additional [[Call]] internal
method described in the <a href="#HTMLAllCollection-call">section below</a>. They also have an
<span>[[IsHTMLDDA]]</span> internal slot.</p>
<div class="note">
<p>Objects that implement the <code>HTMLAllCollection</code> interface have several unusual
behaviors, due of the fact that they have an <span>[[IsHTMLDDA]]</span> internal slot:</p>
<ul>
<li><p>The <span data-x="js-ToBoolean">ToBoolean</span> abstract operation in JavaScript returns
false when given objects implementing the <code>HTMLAllCollection</code> interface.</p></li>
<li><p>The <span data-x="js-abstract-equality">IsLooselyEqual</span> abstract operation,
when given objects implementing the <code>HTMLAllCollection</code> interface, returns true when
compared to the <code data-x="">undefined</code> and <code data-x="">null</code> values.
(Comparisons using the <span data-x="js-strict-equality">IsStrictlyEqual</span> abstract
operation, and IsLooselyEqual comparisons to other values such as strings or objects, are
unaffected.)</p></li>
<li><p>The <code data-x="js-typeof">typeof</code> operator in JavaScript returns the string
<code data-x="">"undefined"</code> when applied to objects implementing the
<code>HTMLAllCollection</code> interface.</p></li>
</ul>
<p>These special behaviors are motivated by a desire for compatibility with two classes of legacy
content: one that uses the presence of <code data-x="dom-document-all">document.all</code> as a
way to detect legacy user agents, and one that only supports those legacy user agents and uses
the <code data-x="dom-document-all">document.all</code> object without testing for its presence
first. <ref>JAVASCRIPT</ref></p>
</div>
<pre><code class="idl">[Exposed=Window,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface>HTMLAllCollection</dfn> {
readonly attribute unsigned long <span data-x="dom-HTMLAllCollection-length">length</span>;
getter <span>Element</span> (unsigned long index);
getter (<span>HTMLCollection</span> or <span>Element</span>)? <span data-x="dom-HTMLAllCollection-namedItem">namedItem</span>(DOMString name);
(<span>HTMLCollection</span> or <span>Element</span>)? <span data-x="dom-HTMLAllCollection-item">item</span>(optional DOMString nameOrIndex);
// Note: HTMLAllCollection objects have a <a href="#HTMLAllCollection-call">custom [[Call]] internal method</a> and an <span>[[IsHTMLDDA]]</span> internal slot.
};</code></pre>
<div w-nodev>
<p>The object's <span>supported property indices</span> are as defined for
<code>HTMLCollection</code> objects.</p>
<p>The <span>supported property names</span> consist of the non-empty values of all the <code
data-x="attr-id">id</code> attributes of all the elements <span>represented by the
collection</span>, and the non-empty values of all the <code data-x="">name</code> attributes of
all the <span>"all"-named elements</span> <span>represented by the collection</span>, in
<span>tree order</span>, ignoring later duplicates, with the <code data-x="attr-id">id</code> of
an element preceding its <code data-x="">name</code> if it contributes both, they differ from
each other, and neither is the duplicate of an earlier entry.</p>
<p>The <dfn attribute for="HTMLAllCollection"><code
data-x="dom-HTMLAllCollection-length">length</code></dfn> getter steps are to return the number
of nodes <span>represented by the collection</span>.</p>
<p>The indexed property getter must return the result of <span
data-x="concept-get-all-indexed">getting the "all"-indexed element</span> from <span>this</span>
given the passed index.</p>
<p>The <dfn method for="HTMLAllCollection"><code
data-x="dom-HTMLAllCollection-namedItem">namedItem(<var>name</var>)</code></dfn> method steps are
to return the result of <span data-x="concept-get-all-named">getting the "all"-named
element(s)</span> from <span>this</span> given <var>name</var>.</p>
<p>The <dfn method for="HTMLAllCollection"><code
data-x="dom-HTMLAllCollection-item">item(<var>nameOrIndex</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>If <var>nameOrIndex</var> was not provided, return null.</p></li>
<li><p>Return the result of <span data-x="concept-get-all-indexed-or-named">getting the
"all"-indexed or named element(s)</span> from <span>this</span>, given
<var>nameOrIndex</var>.</p></li>
</ol>
<hr>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2837 -->
<p>The following elements are <dfn>"all"-named elements</dfn>:
<code>a</code>,
<code>button</code>,
<code>embed</code>,
<code>form</code>,
<code>frame</code>,
<code>frameset</code>,
<code>iframe</code>,
<code>img</code>,
<code>input</code>,
<code>map</code>,
<code>meta</code>,
<code>object</code>,
<code>select</code>, and
<code>textarea</code>
</p>
<p>To <dfn data-x="concept-get-all-indexed">get the "all"-indexed element</dfn> from an
<code>HTMLAllCollection</code> <var>collection</var> given an index <var>index</var>, return the
<var>index</var><sup>th</sup> element in <var>collection</var>, or null if there is no such
<var>index</var><sup>th</sup> element.</p>
<p>To <dfn data-x="concept-get-all-named">get the "all"-named element(s)</dfn> from an
<code>HTMLAllCollection</code> <var>collection</var> given a name <var>name</var>, perform the
following steps:</p>
<ol>
<li><p>If <var>name</var> is the empty string, return null.</p></li>
<li>
<p>Let <var>subCollection</var> be an <code>HTMLCollection</code> object rooted at the same
<code>Document</code> as <var>collection</var>, whose filter matches only elements that are
either:</p>
<ul>
<li><p><span>"all"-named elements</span> with a <code data-x="">name</code> attribute equal to
<var>name</var>, or,</p></li>
<li><p>elements with an <span data-x="concept-id">ID</span> equal to <var>name</var>.</p></li>
</ul>
</li>
<li><p>If there is exactly one element in <var>subCollection</var>, then return that
element.</p></li>
<li><p>Otherwise, if <var>subCollection</var> is empty, return null.</p></li>
<li><p>Otherwise, return <var>subCollection</var>.</p></li>
</ol>
<p>To <dfn data-x="concept-get-all-indexed-or-named">get the "all"-indexed or named
element(s)</dfn> from an <code>HTMLAllCollection</code> <var>collection</var> given
<var>nameOrIndex</var>:
<ol>
<li><p>If <var>nameOrIndex</var>, <span data-x="concept-idl-convert">converted</span> to a
JavaScript String value, is an <span>array index property name</span>, return the result of <span
data-x="concept-get-all-indexed">getting the "all"-indexed element</span> from
<var>collection</var> given the number represented by <var>nameOrIndex</var>.</p></li>
<li><p>Return the result of <span data-x="concept-get-all-named">getting the "all"-named
element(s)</span> from <var>collection</var> given <var>nameOrIndex</var>.</p></li>
</ol>
<h6 id="HTMLAllCollection-call">[[Call]] ( <var>thisArgument</var>, <var>argumentsList</var> )</h6>
<ol>
<li><p>If <var>argumentsList</var>'s <span data-x="list size">size</span> is zero, or if
<var>argumentsList</var>[0] is undefined, return null.</p></li>
<li><p>Let <var>nameOrIndex</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>argumentsList</var>[0] to a <code
data-x="idl-DOMString">DOMString</code>.</p></li>
<li><p>Let <var>result</var> be the result of <span
data-x="concept-get-all-indexed-or-named">getting the "all"-indexed or named element(s)</span>
from this <code>HTMLAllCollection</code> given <var>nameOrIndex</var>.</p></li>
<li><p>Return the result of <span data-x="concept-idl-convert">converting</span>
<var>result</var> to an ECMAScript value.</p></li>
</ol>
<p class="note">The <var>thisArgument</var> is ignored, and thus code such as <code
data-x="">Function.prototype.call.call(document.all, null, "x")</code> will still search for
elements. (<code data-x="">document.all.call</code> does not exist, since <code
data-x="">document.all</code> does not inherit from <code
data-x="">Function.prototype</code>.)</p>
</div>
<h5>The <code>HTMLFormControlsCollection</code> interface</h5>
<p>The <code>HTMLFormControlsCollection</code> interface is used for
<span data-x="concept-collection">collections</span> of <span data-x="category-listed">listed
elements</span> in <code>form</code> elements.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLFormControlsCollection</dfn> : <span>HTMLCollection</span> {
// inherits <span data-x="dom-HTMLCollection-length">length</span> and <span data-x="dom-HTMLCollection-item">item</span>()
getter (<span>RadioNodeList</span> or <span>Element</span>)? <span data-x="dom-HTMLFormControlsCollection-namedItem">namedItem</span>(DOMString name); // shadows inherited <span data-x="dom-HTMLCollection-namedItem">namedItem()</span>
};
[Exposed=Window]
interface <dfn interface>RadioNodeList</dfn> : <span>NodeList</span> {
attribute DOMString <span data-x="dom-RadioNodeList-value">value</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>collection</var>.<span subdfn data-x="dom-HTMLCollection-length">length</span></code></dt>
<dd><p>Returns the number of elements in <var>collection</var>.</p></dd>
<dt><code data-x=""><var>element</var> = <var>collection</var>.<span subdfn data-x="dom-HTMLCollection-item">item</span>(<var>index</var>)</code></dt>
<dt><code data-x=""><var>element</var> = <var>collection</var>[<var>index</var>]</code></dt>
<dd><p>Returns the item at index <var>index</var> in <var>collection</var>. The items are sorted
in <span>tree order</span>.</p></dd>
<dt><code data-x=""><var>element</var> = <var>collection</var>.<span subdfn data-x="dom-HTMLFormControlsCollection-namedItem">namedItem</span>(<var>name</var>)</code></dt>
<dt><code data-x=""><var>radioNodeList</var> = <var>collection</var>.<span data-x="dom-HTMLFormControlsCollection-namedItem">namedItem</span>(<var>name</var>)</code></dt>
<dt><code data-x=""><var>element</var> = <var>collection</var>[<var>name</var>]</code></dt>
<dt><code data-x=""><var>radioNodeList</var> = <var>collection</var>[<var>name</var>]</code></dt>
<dd>
<p>Returns the item with <span data-x="concept-id">ID</span> or <code
data-x="attr-fe-name">name</code> <var>name</var> from <var>collection</var>.</p>
<p>If there are multiple matching items, then a <code>RadioNodeList</code> object containing all
those elements is returned.</p>
</dd>
<dt><code data-x=""><var>radioNodeList</var>.<span subdfn data-x="dom-radionodelist-value">value</span></code></dt>
<dd><p>Returns the value of the first checked radio button represented by
<var>radioNodeList</var>.</p></dd>
<dt><code data-x=""><var>radioNodeList</var>.<span data-x="dom-radionodelist-value">value</span> = <var>value</var></code></dt>
<dd><p>Checks the first radio button represented by <var>radioNodeList</var> that has value
<var>value</var>.</p></dd>
</dl>
<div w-nodev>
<p>The object's <span>supported property indices</span> are as defined for
<code>HTMLCollection</code> objects.</p>
<p>The <span>supported property names</span> consist of the non-empty values of all the <code
data-x="attr-id">id</code> and <code data-x="attr-fe-name">name</code> attributes of all the
elements <span>represented by the collection</span>, in <span>tree order</span>, ignoring later
duplicates, with the <code data-x="attr-id">id</code> of an element preceding its <code
data-x="attr-fe-name">name</code> if it contributes both, they differ from each other, and neither is the
duplicate of an earlier entry.</p>
<p>The <dfn method for="HTMLFormControlsCollection"><code
data-x="dom-HTMLFormControlsCollection-namedItem">namedItem(<var>name</var>)</code></dfn> method
must act according to the following algorithm:</p>
<ol>
<li>If <var>name</var> is the empty string, return null and stop the algorithm.</li>
<li>If, at the time the method is called, there is exactly one node in the collection that has
either an <code data-x="attr-id">id</code> attribute or a <code data-x="attr-fe-name">name</code>
attribute equal to <var>name</var>, then return that node and stop the algorithm.</li>
<li>Otherwise, if there are no nodes in the collection that have either an <code
data-x="attr-id">id</code> attribute or a <code data-x="attr-fe-name">name</code> attribute equal
to <var>name</var>, then return null and stop the algorithm.</li>
<li>Otherwise, create a new <code>RadioNodeList</code> object representing a <span>live</span>
view of the <code>HTMLFormControlsCollection</code> object, further filtered so that the only
nodes in the <code>RadioNodeList</code> object are those that have either an <code
data-x="attr-id">id</code> attribute or a <code data-x="attr-fe-name">name</code> attribute equal
to <var>name</var>. The nodes in the <code>RadioNodeList</code> object must be sorted in
<span>tree order</span>.</li>
<li>Return that <code>RadioNodeList</code> object.</li>
</ol>
<hr>
<p>Members of the <code>RadioNodeList</code> interface inherited from the <code>NodeList</code>
interface must behave as they would on a <code>NodeList</code> object.</p>
<p>The <dfn attribute for="RadioNodeList"><code
data-x="dom-RadioNodeList-value">value</code></dfn> IDL attribute on the
<code>RadioNodeList</code> object, on getting, must return the value returned by running the
following steps:</p>
<ol>
<li><p>Let <var>element</var> be the first element in <span>tree order</span>
represented by the <code>RadioNodeList</code> object that is an <code>input</code> element whose
<code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> is true. Otherwise, let it be null.</p></li>
<li><p>If <var>element</var> is null, return the empty string.</p></li>
<li><p>If <var>element</var> is an element with no <code
data-x="attr-input-value">value</code> attribute, return the string "<code data-x="">on</code>".</p></li>
<li><p>Otherwise, return the value of <var>element</var>'s <code
data-x="attr-input-value">value</code> attribute.</p></li>
</ol>
<p>On setting, the <code data-x="dom-RadioNodeList-value">value</code> IDL attribute must run the
following steps:</p>
<ol>
<li><p>If the new value is the string "<code data-x="">on</code>": let <var>element</var> be the first element in <span>tree order</span>
represented by the <code>RadioNodeList</code> object that is an <code>input</code> element whose
<code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button</span> state and whose <code
data-x="attr-input-value">value</code> content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let <var>element</var> be null.</p>
<p>Otherwise: let <var>element</var> be the first element in <span>tree order</span>
represented by the <code>RadioNodeList</code> object that is an <code>input</code> element whose
<code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button</span> state and whose <code
data-x="attr-input-value">value</code> content attribute is present and equal to the new value, if
any. If no such element exists, then instead let <var>element</var> be null.</p></li>
<li><p>If <var>element</var> is not null, then set its <span
data-x="concept-fe-checked">checkedness</span> to true.</p>
</ol>
<!--
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E...%0A%3Cform%20name%3D%22a%22%3E%3Cinput%20id%3D%22x%22%20name%3D%22y%22%3E%3Cinput%20name%3D%22x%22%20id%3D%22y%22%3E%3C/form%3E%0A%3Cscript%3E%0A%20%20var%20x%3B%0A%20%20w%28x%20%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20x%5B0%5D.parentNode.removeChild%28x%5B0%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20w%28x%20%3D%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%3C/script%3E%0A
-->
</div>
<h5>The <code>HTMLOptionsCollection</code> interface</h5>
<p>The <code>HTMLOptionsCollection</code> interface is used for <span
data-x="concept-collection">collections</span> of <code>option</code> elements. It is always
rooted on a <code>select</code> element and has attributes and methods that manipulate that
element's descendants.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLOptionsCollection</dfn> : <span>HTMLCollection</span> {
// inherits <span data-x="dom-HTMLCollection-item">item</span>(), <span data-x="dom-HTMLCollection-namedItem">namedItem</span>()
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-HTMLOptionsCollection-length">length</span>; // shadows inherited <span data-x="dom-HTMLCollection-length">length</span>
[<span>CEReactions</span>] <a href="#dom-htmloptionscollection-setter">setter</a> undefined (unsigned long index, <span>HTMLOptionElement</span>? option);
[<span>CEReactions</span>] undefined <span data-x="dom-HTMLOptionsCollection-add">add</span>((<span>HTMLOptionElement</span> or <span>HTMLOptGroupElement</span>) element, optional (<span>HTMLElement</span> or long)? before = null);
[<span>CEReactions</span>] undefined <span data-x="dom-HTMLOptionsCollection-remove">remove</span>(long index);
attribute long <span data-x="dom-HTMLOptionsCollection-selectedIndex">selectedIndex</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>collection</var>.<span subdfn data-x="dom-HTMLOptionsCollection-length">length</span></code></dt>
<dd><p>Returns the number of elements in <var>collection</var>.</p></dd>
<dt><code data-x=""><var>collection</var>.<span data-x="dom-HTMLOptionsCollection-length">length</span> = <var>value</var></code></dt>
<dd>
<p>When set to a smaller number than the existing length, truncates the number of
<code>option</code> elements in the container corresponding to <var>collection</var>.</p>
<p>When set to a greater number than the existing length, if that number is less than or equal
to 100000, adds new blank <code>option</code> elements to the container corresponding to
<var>collection</var>.</p>
</dd>
<dt><code data-x=""><var>element</var> = <var>collection</var>.<span data-x="dom-HTMLCollection-item">item</span>(<var>index</var>)</code></dt>
<dt><code data-x=""><var>element</var> = <var>collection</var>[<var>index</var>]</code></dt>
<dd><p>Returns the item at index <var>index</var> in <var>collection</var>. The items are sorted
in <span>tree order</span>.</p></dd>
<dt><code data-x=""><var>collection</var>[<var>index</var>] = <var>element</var></code></dt>
<dd>
<p>When <var>index</var> is a greater number than the number of items in <var>collection</var>,
adds new blank <code>option</code> elements in the corresponding container.</p>
<p>When set to null, removes the item at index <var>index</var> from <var>collection</var>.</p>
<p>When set to an <code>option</code> element, adds or replaces it at index <var>index</var> in
<var>collection</var>.</p>
</dd>
<dt><code data-x=""><var>element</var> = <var>collection</var>.<span subdfn data-x="dom-HTMLCollection-namedItem">namedItem</span>(<var>name</var>)</code></dt>
<dt><code data-x=""><var>element</var> = <var>collection</var>[<var>name</var>]</code></dt>
<dd>
<p>Returns the item with <span data-x="concept-id">ID</span> or <code
data-x="attr-option-name">name</code> <var>name</var> from <var>collection</var>.</p>
<p>If there are multiple matching items, then the first is returned.</p>
</dd>
<dt><code data-x=""><var>collection</var>.<span subdfn data-x="dom-HTMLOptionsCollection-add">add</span>(<var>element</var>[, <var>before</var>])</code></dt>
<dd>
<p>Inserts <var>element</var> before the node given by <var>before</var>.</p>
<p>The <var>before</var> argument can be a number, in which case <var>element</var> is inserted
before the item with that number, or an element from <var>collection</var>, in which case
<var>element</var> is inserted before that element.</p>
<p>If <var>before</var> is omitted, null, or a number out of range, then <var>element</var> will
be added at the end of the list.</p>
<p>Throws a <span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code> if
<var>element</var> is an ancestor of the element into which it is to be inserted.</p>
</dd>
<dt><code data-x=""><var>collection</var>.<span subdfn data-x="dom-HTMLOptionsCollection-remove">remove</span>(<var>index</var>)</code></dt>
<dd><p>Removes the item with index <var>index</var> from <var>collection</var>.</p></dd>
<dt><code data-x=""><var>collection</var>.<span data-x="dom-HTMLOptionsCollection-selectedIndex">selectedIndex</span></code></dt>
<dd><p>Returns the index of the first selected item, if any, or −1 if there is no selected
item.</p></dd>
<dt><code data-x=""><var>collection</var>.<span subdfn data-x="dom-HTMLOptionsCollection-selectedIndex">selectedIndex</span> = <var>index</var></code></dt>
<dd><p>Changes the selection to the <code>option</code> element at index <var>index</var> in
<var>collection</var>.</p></dd>
</dl>
<div w-nodev>
<p>The object's <span>supported property indices</span> are as defined for
<code>HTMLCollection</code> objects.</p>
<p>The <dfn attribute for="HTMLOptionsCollection"><code
data-x="dom-HTMLOptionsCollection-length">length</code></dfn> getter steps are to return the
number of nodes <span>represented by the collection</span>.</p>
<p>The <code data-x="dom-HTMLOptionsCollection-length">length</code> setter steps are:</p>
<ol>
<li><p>Let <var>current</var> be the number of nodes <span>represented by the
collection</span>.</p></li>
<li>
<p>If the given value is greater than <var>current</var>, then:</p>
<ol>
<li><p>If the given value is greater than 100,000, then return.</p></li>
<li><p>Let <var>n</var> be <var>value</var> − <var>current</var>.</p></li>
<li><p>Append <var>n</var> new <code>option</code> elements with no attributes and no child
nodes to the <code>select</code> element on which <span>this</span> is rooted.</p></li>
</ol>
</li>
<li>
<p>If the given value is less than <var>current</var>, then:</p>
<ol>
<li><p>Let <var>n</var> be <var>current</var> − <var>value</var>.</p></li>
<li><p>Remove the last <var>n</var> nodes in the collection from their parent nodes.</p></li>
</ol>
</li>
</ol>
<p class="note">Setting <code data-x="dom-HTMLOptionsCollection-length">length</code> never removes
or adds any <code>optgroup</code> elements, and never adds new children to existing
<code>optgroup</code> elements (though it can remove children from them).</p>
<p>The <span>supported property names</span> consist of the non-empty values of all the <code
data-x="attr-id">id</code> and <code data-x="attr-option-name">name</code> attributes of all the
elements <span>represented by the collection</span>, in <span>tree order</span>, ignoring later
duplicates, with the <code data-x="attr-id">id</code> of an element preceding its <code
data-x="attr-option-name">name</code> if it contributes both, they differ from each other, and neither is
the duplicate of an earlier entry.</p>
<p id="dom-htmloptionscollection-setter">When the user agent is to <span>set the value of a new
indexed property</span> or <span>set the value of an existing indexed property</span> for a given
property index <var>index</var> to a new value <var>value</var>, it must run the following
algorithm:</p>
<ol>
<li><p>If <var>value</var> is null, invoke the steps for the <code
data-x="dom-HTMLOptionsCollection-remove">remove</code> method with <var>index</var> as
the argument, and return.</p></li>
<li><p>Let <var>length</var> be the number of nodes <span>represented by the
collection</span>.</p></li>
<li><p>Let <var>n</var> be <var>index</var> minus <var>length</var>.</p></li>
<li><p>If <var>n</var> is greater than zero, then <span
data-x="concept-node-append">append</span> a <code>DocumentFragment</code> consisting of <span
data-x=""><var>n</var>-1</span> new <code>option</code> elements with no attributes and
no child nodes to the <code>select</code> element on which the <code>HTMLOptionsCollection</code>
is rooted.</p></li>
<li><p>If <var>n</var> is greater than or equal to zero, <span
data-x="concept-node-append">append</span> <var>value</var> to the <code>select</code>
element. Otherwise, <span data-x="concept-node-replace">replace</span> the <var>index</var>th element in the collection by <var>value</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLOptionsCollection"><code
data-x="dom-HTMLOptionsCollection-add">add(<var>element</var>, <var>before</var>)</code></dfn>
method must act according to the following algorithm:</p>
<ol>
<li><p>If <var>element</var> is an ancestor of the <code>select</code> element on which
the <code>HTMLOptionsCollection</code> is rooted, then throw a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</li>
<li><p>If <var>before</var> is an element, but that element isn't a descendant of the
<code>select</code> element on which the <code>HTMLOptionsCollection</code> is rooted, then throw
a <span>"<code>NotFoundError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>element</var> and <var>before</var> are the same element, then
return.</li>
<li><p>If <var>before</var> is a node, then let <var>reference</var> be that
node. Otherwise, if <var>before</var> is an integer, and there is a <var>before</var>th node in the collection, let <var>reference</var> be that node.
Otherwise, let <var>reference</var> be null.</p></li>
<li><p>If <var>reference</var> is not null, let <var>parent</var> be the parent
node of <var>reference</var>. Otherwise, let <var>parent</var> be the
<code>select</code> element on which the <code>HTMLOptionsCollection</code> is rooted.</p></li>
<li><p><span>Pre-insert</span> <var>element</var> into <var>parent</var> node before
<var>reference</var>.</p>
</ol>
<p>The <dfn method for="HTMLOptionsCollection"><code
data-x="dom-HTMLOptionsCollection-remove">remove(<var>index</var>)</code></dfn> method must act
according to the following algorithm:</p>
<ol>
<li><p>If the number of nodes <span>represented by the collection</span> is zero, return.</li>
<li><p>If <var>index</var> is not a number greater than or equal to 0 and less than the
number of nodes <span>represented by the collection</span>, return.</p></li>
<!-- note that Web IDL converts 'a', NaN, -0.5, 0.5, most objects, and null to 0, and numbers in
general truncate. so what we're checking against here in a way has very little to do with what's
going on in the JS -->
<!-- objects get converted by calling ToNumber which calls ToPrimitive which eventually calls valueOf:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2828
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2833
-->
<!-- same for select.remove(), which calls this algorithm also:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2826
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2825
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2827
-->
<li><p>Let <var>element</var> be the <var>index</var>th element in the
collection.</p></li>
<li><p>Remove <var>element</var> from its parent node.</p></li>
</ol>
<p>The <dfn attribute for="HTMLOptionsCollection"><code
data-x="dom-HTMLOptionsCollection-selectedIndex">selectedIndex</code></dfn> IDL attribute must act
like the identically named attribute on the <code>select</code> element on which the
<code>HTMLOptionsCollection</code> is rooted</p>
<!-- see also https://ln.hixie.ch/?start=1161042744&count=1 -->
</div>
<h4>The <code>DOMStringList</code> interface</h4>
<p>The <code>DOMStringList</code> interface is a non-fashionable retro way of representing a list
of strings.</p>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>DOMStringList</dfn> {
readonly attribute unsigned long <span data-x="dom-DOMStringList-length">length</span>;
getter DOMString? <span data-x="dom-DOMStringList-item">item</span>(unsigned long index);
boolean <span data-x="dom-DOMStringList-contains">contains</span>(DOMString string);
};</code></pre>
<p w-nodev class="warning">New APIs must use <code data-x="">sequence<DOMString></code> or
equivalent rather than <code>DOMStringList</code>.</p>
<dl class="domintro">
<dt><code data-x=""><var>strings</var>.<span subdfn data-x="dom-DOMStringList-length">length</span></code></dt>
<dd><p>Returns the number of strings in <var>strings</var>.</p></dd>
<dt><code data-x=""><var>strings</var>[<var>index</var>]</code></dt>
<dt><code data-x=""><var>strings</var>.<span subdfn data-x="dom-DOMStringList-item">item</span>(<var>index</var>)</code></dt>
<dd><p>Returns the string with index <var>index</var> from <var>strings</var>.</p></dd>
<dt><code data-x=""><var>strings</var>.<span subdfn data-x="dom-DOMStringList-contains">contains</span>(<var>string</var>)</code></dt>
<dd><p>Returns true if <var>strings</var> contains <var>string</var>, and false
otherwise.</p></dd>
</dl>
<div w-nodev>
<p>Each <code>DOMStringList</code> object has an associated <span>list</span>.</p>
<p>The <code>DOMStringList</code> interface <span>supports indexed properties</span>. The
<span>supported property indices</span> are the <span>indices</span> of <span>this</span>'s
associated list.</p>
<p>The <dfn attribute for="DOMStringList"
data-x="dom-DOMStringList-length"><code>length</code></dfn> getter steps are to return
<span>this</span>'s associated list's <span data-x="list size">size</span>.</p>
<p>The <dfn method for="DOMStringList"
data-x="dom-DOMStringList-item"><code>item(<var>index</var>)</code></dfn> method steps are to
return the <var>index</var>th item in <span>this</span>'s associated list, or null if
<var>index</var> plus one is greater than <span>this</span>'s associated list's <span data-x="list
size">size</span>.</p>
<p>The <dfn method for="DOMStringList"
data-x="dom-DOMStringList-contains"><code>contains(<var>string</var>)</code></dfn> method steps
are to return true if <span>this</span>'s associated list <span data-x="list
contains">contains</span> <var>string</var>, and false otherwise.</p>
</div>
<h3 split-filename="structured-data">Safe passing of structured data</h3>
<p id="structuredclone"><span id="structured-clone"></span>To support passing JavaScript objects,
including <span data-x="platform object">platform objects</span>, across <span>realm</span>
boundaries, this specification defines <span w-nodev>the following </span>infrastructure for
serializing and deserializing objects, including in some cases transferring the underlying data
instead of copying it. Collectively this serialization/deserialization process is known as
"structured cloning", although most APIs perform separate serialization and deserialization steps.
(With the notable exception being the <code data-x="dom-structuredClone">structuredClone()</code>
method.)</p>
<div w-nodev>
<p>This section uses the terminology and typographic conventions from the JavaScript
specification. <ref>JAVASCRIPT</ref></p>
</div>
<h4 export data-lt="serializable object"><dfn>Serializable objects</dfn></h4>
<p><span>Serializable objects</span> support being serialized, and later deserialized, in a way
that is independent of any given <span>realm</span>. This allows them to be stored on disk and
later restored, or cloned across <span>agent</span> and even <span>agent cluster</span>
boundaries.</p>
<p>Not all objects are <span>serializable objects</span>, and not all aspects of objects that are
<span>serializable objects</span> are necessarily preserved when they are serialized.</p>
<div w-nodev>
<p><span data-x="platform object">Platform objects</span> can be <span>serializable objects</span>
if their <span>primary interface</span> is decorated with the <dfn extended-attribute
data-lt="Serializable" data-x="Serializable"><code>[Serializable]</code></dfn> IDL <span>extended
attribute</span>. Such interfaces must also define the following algorithms:</p>
<dl>
<dt><dfn export>serialization steps</dfn>, taking a <span>platform object</span>
<var>value</var>, a <span>Record</span> <var>serialized</var>, and a boolean
<var>forStorage</var></dt>
<dd>
<p>A set of steps that serializes the data in <var>value</var> into fields of
<var>serialized</var>. The resulting data serialized into <var>serialized</var> must be
independent of any <span>realm</span>.</p>
<p>These steps may throw an exception if serialization is not possible.</p>
<p>These steps may perform a <span>sub-serialization</span> to serialize nested data
structures. They should not call <span>StructuredSerialize</span> directly, as doing so will
omit the important <var>memory</var> argument.</p>
<p>The introduction of these steps should omit mention of the <var>forStorage</var> argument if
it is not relevant to the algorithm.</p>
</dd>
<dt><dfn export>deserialization steps</dfn>, taking a <span>Record</span> <var>serialized</var>,
a <span>platform object</span> <var>value</var>, and a <span>realm</span>
<var>targetRealm</var></dt>
<dd>
<p>A set of steps that deserializes the data in <var>serialized</var>, using it to set up
<var>value</var> as appropriate. <var>value</var> will be a newly-created instance of the
<span>platform object</span> type in question, with none of its internal data set up; setting
that up is the job of these steps.</p>
<p>These steps may throw an exception if deserialization is not possible.</p>
<p>These steps may perform a <span>sub-deserialization</span> to deserialize nested data
structures. They should not call <span>StructuredDeserialize</span> directly, as doing so will
omit the important <var>targetRealm</var> and <var>memory</var> arguments.</p>
</dd>
</dl>
<p>It is up to the definition of individual platform objects to determine what data is serialized
and deserialized by these steps. Typically the steps are very symmetric.</p>
<p>The <code data-x="Serializable">[Serializable]</code> extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.</p>
<p>For a given <span>platform object</span>, only the object's <span>primary interface</span> is
considered during the (de)serialization process. Thus, if inheritance is involved in defining the
interface, each <code data-x="Serializable">[Serializable]</code>-annotated interface in the
inheritance chain needs to define standalone <span>serialization steps</span> and
<span>deserialization steps</span>, including taking into account any important data that might
come from inherited interfaces.</p>
<div class="example">
<p>Let's say we were defining a platform object <code data-x="">Person</code>, which had
associated with it two pieces of associated data:</p>
<ul>
<li><p>a name value, which is a string; and</p></li>
<li><p>a best friend value, which is either another <code data-x="">Person</code> instance
or null.</p></li>
</ul>
<p>We could then define <code data-x="">Person</code> instances to be <span>serializable
objects</span> by annotating the <code data-x="">Person</code> interface with the <code
data-x="Serializable">[Serializable]</code> <span>extended attribute</span>, and defining the
following accompanying algorithms:</p>
<dl>
<dt><span>serialization steps</span></dt>
<dd>
<ol>
<li><p>Set <var>serialized</var>.[[Name]] to <var>value</var>'s associated name
value.</p></li>
<li><p>Let <var>serializedBestFriend</var> be the <span>sub-serialization</span> of
<var>value</var>'s associated best friend value.</p></li>
<li><p>Set <var>serialized</var>.[[BestFriend]] to <var>serializedBestFriend</var>.</p></li>
</ol>
</dd>
<dt><span>deserialization steps</span></dt>
<dd>
<ol>
<li><p>Set <var>value</var>'s associated name value to
<var>serialized</var>.[[Name]].</p></li>
<li><p>Let <var>deserializedBestFriend</var> be the <span>sub-deserialization</span> of
<var>serialized</var>.[[BestFriend]].</p></li>
<li><p>Set <var>value</var>'s associated best friend value to
<var>deserializedBestFriend</var>.</p></li>
</ol>
</dd>
</dl>
</div>
<p>Objects defined in the JavaScript specification are handled by the
<span>StructuredSerialize</span> abstract operation directly.</p>
<p class="note" id="cloneable-objects">Originally, this specification defined the concept of
"cloneable objects", which could be cloned from one <span>realm</span> to another. However, to
better specify the behavior of certain more complex situations, the model was updated to make the
serialization and deserialization explicit.</p>
</div>
<h4 export data-lt="transferable object"><dfn>Transferable objects</dfn></h4>
<p><span>Transferable objects</span> support being transferred across <span
data-x="agent">agents</span>. Transferring is effectively recreating the object while sharing a
reference to the underlying data and then detaching the object being transferred. This is useful
to transfer ownership of expensive resources. Not all objects are <span>transferable
objects</span> and not all aspects of objects that are <span>transferable objects</span> are
necessarily preserved when transferred.</p>
<p class="note">Transferring is an irreversible and non-idempotent operation. Once an object has
been transferred, it cannot be transferred, or indeed used, again.</p>
<div w-nodev>
<p><span data-x="platform object">Platform objects</span> can be <span>transferable objects</span>
if their <span>primary interface</span> is decorated with the <dfn extended-attribute
data-lt="Transferable" data-x="Transferable"><code>[Transferable]</code></dfn> IDL <span>extended
attribute</span>. Such interfaces must also define the following algorithms:</p>
<dl>
<dt><dfn export>transfer steps</dfn>, taking a <span>platform object</span>
<var>value</var> and a <span>Record</span> <var>dataHolder</var></dt>
<dd>
<p>A set of steps that transfers the data in <var>value</var> into fields of
<var>dataHolder</var>. The resulting data held in <var>dataHolder</var> must be
independent of any <span>realm</span>.</p>
<p>These steps may throw an exception if transferral is not possible.</p>
</dd>
<dt><dfn export>transfer-receiving steps</dfn>, taking a <span>Record</span>
<var>dataHolder</var> and a <span>platform object</span> <var>value</var></dt>
<dd>
<p>A set of steps that receives the data in <var>dataHolder</var>, using it to set up
<var>value</var> as appropriate. <var>value</var> will be a newly-created instance of the
<span>platform object</span> type in question, with none of its internal data set up; setting
that up is the job of these steps.</p>
<p>These steps may throw an exception if it is not possible to receive the transfer.</p>
</dd>
</dl>
<p>It is up to the definition of individual platform objects to determine what data is transferred
by these steps. Typically the steps are very symmetric.</p>
<p>The <code data-x="Transferable">[Transferable]</code> extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.</p>
<p>For a given <span>platform object</span>, only the object's <span>primary interface</span> is
considered during the transferring process. Thus, if inheritance is involved in defining the
interface, each <code data-x="Transferable">[Transferable]</code>-annotated interface in the
inheritance chain needs to define standalone <span>transfer steps</span> and
<span>transfer-receiving steps</span>, including taking into account any important data that might
come from inherited interfaces.</p>
<p><span data-x="platform object">Platform objects</span> that are <span>transferable
objects</span> have a <dfn for="platform object" attribute>[[Detached]]</dfn> internal slot. This
is used to ensure that once a platform object has been transferred, it cannot be transferred
again.</p>
<p>Objects defined in the JavaScript specification are handled by the
<span>StructuredSerializeWithTransfer</span> abstract operation directly.</p>
<h4 id="structuredserializeinternal" noexport data-lt="StructuredSerializeInternal"
abstract-op><dfn>StructuredSerializeInternal</dfn> ( <var>value</var>, <var>forStorage</var> [ ,
<var>memory</var> ] )</h4>
<p>The <span>StructuredSerializeInternal</span> abstract operation takes as input a JavaScript
value <var>value</var> and serializes it to a <span>realm</span>-independent form, represented
here as a <span>Record</span>. This serialized form has all the information necessary to later
deserialize into a new JavaScript value in a different realm.</p>
<p>This process can throw an exception, for example when trying to serialize un-serializable
objects.</p>
<ol>
<li>
<p>If <var>memory</var> was not supplied, let <var>memory</var> be an empty <span
data-x="ordered map">map</span>.</p>
<p class="note">The purpose of the <var>memory</var> map is to avoid serializing objects twice.
This ends up preserving cycles and the identity of duplicate objects in graphs.</p>
</li>
<li><p>If <var>memory</var>[<var>value</var>] <span data-x="map exists">exists</span>, then
return <var>memory</var>[<var>value</var>].</p></li>
<li><p>Let <var>deep</var> be false.</p></li>
<li><p>If <var>value</var> is undefined, null, <span data-x="js-Boolean">a Boolean</span>, <span
data-x="js-Number">a Number</span>, <span data-x="js-BigInt">a BigInt</span>, or <span
data-x="js-String">a String</span>, then return { [[Type]]: "primitive", [[Value]]:
<var>value</var> }.</p></li>
<li><p>If <var>value</var> <span data-x="js-Symbol">is a Symbol</span>, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>serialized</var> be an uninitialized value.</p></li>
<li><p>If <var>value</var> has a [[BooleanData]] internal slot, then set <var>serialized</var> to
{ [[Type]]: "Boolean", [[BooleanData]]: <var>value</var>.[[BooleanData]] }.</p></li>
<li><p>Otherwise, if <var>value</var> has a [[NumberData]] internal slot, then set
<var>serialized</var> to { [[Type]]: "Number", [[NumberData]]: <var>value</var>.[[NumberData]]
}.</p></li>
<li><p>Otherwise, if <var>value</var> has a [[BigIntData]]
internal slot, then set <var>serialized</var> to { [[Type]]: "BigInt", [[BigIntData]]:
<var>value</var>.[[BigIntData]] }.</p></li>
<li><p>Otherwise, if <var>value</var> has a [[StringData]] internal slot, then set
<var>serialized</var> to { [[Type]]: "String", [[StringData]]: <var>value</var>.[[StringData]]
}.</p></li>
<li><p>Otherwise, if <var>value</var> has a [[DateValue]] internal slot, then set
<var>serialized</var> to { [[Type]]: "Date", [[DateValue]]: <var>value</var>.[[DateValue]]
}.</p></li>
<li><p>Otherwise, if <var>value</var> has a [[RegExpMatcher]] internal slot, then set
<var>serialized</var> to { [[Type]]: "RegExp", [[RegExpMatcher]]:
<var>value</var>.[[RegExpMatcher]], [[OriginalSource]]: <var>value</var>.[[OriginalSource]],
[[OriginalFlags]]: <var>value</var>.[[OriginalFlags]] }.</p></li>
<li>
<p>Otherwise, if <var>value</var> has an [[ArrayBufferData]] internal slot, then:</p>
<ol>
<li>
<p>If <span>IsSharedArrayBuffer</span>(<var>value</var>) is true, then:
<ol>
<li>
<p>If the <span>current settings object</span>'s <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span> is false, then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.</p>
<p class="note">This check is only needed when serializing (and not when deserializing) as
the <span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin
isolated capability</span> cannot change over time and a <code>SharedArrayBuffer</code>
cannot leave an <span>agent cluster</span>.</p>
</li>
<li><p>If <var>forStorage</var> is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>value</var> has an [[ArrayBufferMaxByteLength]] internal slot, then set
<var>serialized</var> to { [[Type]]: "GrowableSharedArrayBuffer", [[ArrayBufferData]]:
<var>value</var>.[[ArrayBufferData]], [[ArrayBufferByteLengthData]]:
<var>value</var>.[[ArrayBufferByteLengthData]], [[ArrayBufferMaxByteLength]]:
<var>value</var>.[[ArrayBufferMaxByteLength]], [[AgentCluster]]: the <span>surrounding
agent</span>'s <span>agent cluster</span> }.</p></li>
<li><p>Otherwise, set <var>serialized</var> to { [[Type]]: "SharedArrayBuffer",
[[ArrayBufferData]]: <var>value</var>.[[ArrayBufferData]], [[ArrayBufferByteLength]]:
<var>value</var>.[[ArrayBufferByteLength]], [[AgentCluster]]: the <span>surrounding
agent</span>'s <span>agent cluster</span> }.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>If <span>IsDetachedBuffer</span>(<var>value</var>) is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>size</var> be <var>value</var>.[[ArrayBufferByteLength]].</li>
<li>
<p>Let <var>dataCopy</var> be ? <span>CreateByteDataBlock</span>(<var>size</var>).</p>
<p class="note">This can throw a <code data-x="js-RangeError">RangeError</code> exception
upon allocation failure.</p>
</li>
<li><p>Perform <span>CopyDataBlockBytes</span>(<var>dataCopy</var>, 0,
<var>value</var>.[[ArrayBufferData]], 0, <var>size</var>).</p></li>
<li><p>If <var>value</var> has an [[ArrayBufferMaxByteLength]] internal slot, then set
<var>serialized</var> to { [[Type]]: "ResizableArrayBuffer", [[ArrayBufferData]]:
<var>dataCopy</var>, [[ArrayBufferByteLength]]: <var>size</var>,
[[ArrayBufferMaxByteLength]]: <var>value</var>.[[ArrayBufferMaxByteLength]] }.</p></li>
<li><p>Otherwise, set <var>serialized</var> to { [[Type]]: "ArrayBuffer",
[[ArrayBufferData]]: <var>dataCopy</var>, [[ArrayBufferByteLength]]: <var>size</var>
}.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> has a [[ViewedArrayBuffer]] internal slot, then:</p>
<ol>
<li><p>If <span>IsArrayBufferViewOutOfBounds</span>(<var>value</var>) is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>buffer</var> be the value of <var>value</var>'s [[ViewedArrayBuffer]] internal
slot.</p></li>
<li><p>Let <var>bufferSerialized</var> be ?
<span>StructuredSerializeInternal</span>(<var>buffer</var>, <var>forStorage</var>,
<var>memory</var>).</p></li>
<li><p><span>Assert</span>: <var>bufferSerialized</var>.[[Type]] is "ArrayBuffer",
"ResizableArrayBuffer", "SharedArrayBuffer", or "GrowableSharedArrayBuffer".</p></li>
<li><p>If <var>value</var> has a [[DataView]] internal slot, then set <var>serialized</var> to
{ [[Type]]: "ArrayBufferView", [[Constructor]]: "DataView", [[ArrayBufferSerialized]]:
<var>bufferSerialized</var>, [[ByteLength]]: <var>value</var>.[[ByteLength]], [[ByteOffset]]:
<var>value</var>.[[ByteOffset]] }.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>value</var> has a [[TypedArrayName]] internal slot.</p></li>
<li><p>Set <var>serialized</var> to { [[Type]]: "ArrayBufferView", [[Constructor]]:
<var>value</var>.[[TypedArrayName]], [[ArrayBufferSerialized]]: <var>bufferSerialized</var>,
[[ByteLength]]: <var>value</var>.[[ByteLength]], [[ByteOffset]]:
<var>value</var>.[[ByteOffset]], [[ArrayLength]]: <var>value</var>.[[ArrayLength]] }.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> has [[MapData]] internal slot, then:</p>
<ol>
<li><p>Set <var>serialized</var> to { [[Type]]: "Map", [[MapData]]: a new empty <span
data-x="js-List">List</span> }.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> has [[SetData]] internal slot, then:</p>
<ol>
<li><p>Set <var>serialized</var> to { [[Type]]: "Set", [[SetData]]: a new empty <span
data-x="js-List">List</span> }.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> has an [[ErrorData]] internal slot and <var>value</var> is not
a <span>platform object</span>, then:</p>
<!-- "is not a platform object" check is needed because DOMExceptions can have [[ErrorData]]
too -->
<ol>
<li><p>Let <var>name</var> be ? <span data-x="js-Get">Get</span>(<var>value</var>,
"name").</p></li>
<li><p>If <var>name</var> is not one of "Error", "EvalError", "RangeError", "ReferenceError",
"SyntaxError", "TypeError", or "URIError", then set <var>name</var> to "Error".</p></li>
<li><p>Let <var>valueMessageDesc</var> be ? <var>value</var>.[[GetOwnProperty]]("<code
data-x="">message</code>").</p></li>
<li><p>Let <var>message</var> be undefined if
<span>IsDataDescriptor</span>(<var>valueMessageDesc</var>) is false, and
? <span>ToString</span>(<var>valueMessageDesc</var>.[[Value]]) otherwise.</p></li>
<li><p>Set <var>serialized</var> to { [[Type]]: "Error", [[Name]]: <var>name</var>,
[[Message]]: <var>message</var> }.</p></li>
<li>
<p>User agents should attach a serialized representation of any interesting accompanying
data which are not yet specified, notably the <code data-x="">stack</code> property, to
<var>serialized</var>.</p>
<p class="note">See the <cite>Error Stacks</cite> proposal for in-progress work on specifying
this data. <ref>JSERRORSTACKS</ref></p>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> is an Array exotic object, then:</p>
<!-- IsArray supports proxies too, which we cannot -->
<ol>
<li><p>Let <var>valueLenDescriptor</var> be ?
<span>OrdinaryGetOwnProperty</span>(<var>value</var>, "<code data-x="">length</code>").</p></li>
<li><p>Let <var>valueLen</var> be <var>valueLenDescriptor</var>.[[Value]].</p></li>
<li><p>Set <var>serialized</var> to { [[Type]]: "Array", [[Length]]: <var>valueLen</var>,
[[Properties]]: a new empty <span data-x="js-List">List</span> }.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> is a <span>platform object</span> that is a <span
data-x="serializable objects">serializable object</span>:</p>
<ol>
<li><p>If <var>value</var> has a <span>[[Detached]]</span> internal slot whose value is true,
then throw a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>typeString</var> be the identifier of the <span>primary interface</span> of
<var>value</var>.</p></li>
<li><p>Set <var>serialized</var> to { [[Type]]: <var>typeString</var> }.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>value</var> is a <span>platform object</span>, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Otherwise, if <span>IsCallable</span>(<var>value</var>) is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>Otherwise, if <var>value</var> has any internal slot other than [[Prototype]],
[[Extensible]], or [[PrivateElements]], then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.</p>
<p class="example">For instance, a [[PromiseState]] or [[WeakMapData]] internal slot.</p>
</li>
<li>
<p>Otherwise, if <var>value</var> is an exotic object and <var>value</var> is not the
<span>%Object.prototype%</span> intrinsic object associated with any <span>realm</span>, then
throw a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p>
<p class="example">For instance, a proxy object.</p>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Set <var>serialized</var> to { [[Type]]: "Object", [[Properties]]: a new empty <span
data-x="js-List">List</span> }.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
<p class="note"><span>%Object.prototype%</span> will end up being handled via this step and
subsequent steps. The end result is that its exoticness is ignored, and after deserialization
the result will be an empty object (not an <span>immutable prototype exotic object</span>).
</li>
<li><p><span data-x="map set">Set</span> <var>memory</var>[<var>value</var>] to
<var>serialized</var>.</p></li>
<li>
<p>If <var>deep</var> is true, then:</p>
<ol>
<li>
<p>If <var>value</var> has a [[MapData]] internal slot, then:
<ol>
<li><p>Let <var>copiedList</var> be a new empty <span data-x="js-List">List</span>.
<li>
<p><span data-x="list iterate">For each</span> <span>Record</span> { [[Key]], [[Value]] }
<var>entry</var> of <var>value</var>.[[MapData]]:</p>
<ol>
<li><p>Let <var>copiedEntry</var> be a new <span>Record</span> { [[Key]]:
<var>entry</var>.[[Key]], [[Value]]: <var>entry</var>.[[Value]] }.</p></li>
<li><p>If <var>copiedEntry</var>.[[Key]] is not the special value <i>empty</i>, <span
data-x="list append">append</span> <var>copiedEntry</var> to <var>copiedList</var>.</p></li>
</ol>
</li>
<li>
<p><span data-x="list iterate">For each</span> <span>Record</span> { [[Key]], [[Value]] }
<var>entry</var> of <var>copiedList</var>:</p>
<ol>
<li><p>Let <var>serializedKey</var> be ?
<span>StructuredSerializeInternal</span>(<var>entry</var>.[[Key]], <var>forStorage</var>,
<var>memory</var>).</p></li>
<li><p>Let <var>serializedValue</var> be ?
<span>StructuredSerializeInternal</span>(<var>entry</var>.[[Value]], <var>forStorage</var>,
<var>memory</var>).</p></li>
<li><p><span data-x="list append">Append</span> { [[Key]]: <var>serializedKey</var>,
[[Value]]: <var>serializedValue</var> } to <var>serialized</var>.[[MapData]].</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> has a [[SetData]] internal slot, then:</p>
<ol>
<li><p>Let <var>copiedList</var> be a new empty <span data-x="js-List">List</span>.
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>value</var>.[[SetData]]:</p>
<ol>
<li><p>If <var>entry</var> is not the special value <i>empty</i>, <span data-x="list
append">append</span> <var>entry</var> to <var>copiedList</var>.</p></li>
</ol>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>copiedList</var>:</p>
<ol>
<li><p>Let <var>serializedEntry</var> be ?
<span>StructuredSerializeInternal</span>(<var>entry</var>, <var>forStorage</var>,
<var>memory</var>).</p></li>
<li><p><span data-x="list append">Append</span> <var>serializedEntry</var> to
<var>serialized</var>.[[SetData]].</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>value</var> is a <span>platform object</span> that is a <span
data-x="serializable objects">serializable object</span>, then perform the <span>serialization
steps</span> for <var>value</var>'s <span>primary interface</span>, given <var>value</var>,
<var>serialized</var>, and <var>forStorage</var>.</p>
<p>The <span>serialization steps</span> may need to perform a <dfn
export>sub-serialization</dfn>. This is an operation which takes as input a value
<var>subValue</var>, and returns <span>StructuredSerializeInternal</span>(<var>subValue</var>,
<var>forStorage</var>, <var>memory</var>). (In other words, a <span>sub-serialization</span>
is a specialization of <span>StructuredSerializeInternal</span> to be consistent within this
invocation.)</p>
</li>
<li>
<p>Otherwise, for each <var>key</var> in !
<span>EnumerableOwnProperties</span>(<var>value</var>, key):</p>
<ol>
<li>
<p>If ! <span>HasOwnProperty</span>(<var>value</var>, <var>key</var>) is true, then:</p>
<ol>
<li><p>Let <var>inputValue</var> be ? <var>value</var>.[[Get]](<var>key</var>,
<var>value</var>).</p></li>
<li><p>Let <var>outputValue</var> be ?
<span>StructuredSerializeInternal</span>(<var>inputValue</var>, <var>forStorage</var>,
<var>memory</var>).</p></li>
<li><p><span data-x="list append">Append</span> { [[Key]]: <var>key</var>, [[Value]]:
<var>outputValue</var> } to <var>serialized</var>.[[Properties]].</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>serialized</var>.</p></li>
</ol>
<div class="example">
<p>It's important to realize that the <span data-x="Record">Records</span>
produced by <span>StructuredSerializeInternal</span> might contain "pointers" to other records
that create circular references. For example, when we pass the following JavaScript object into
<span>StructuredSerializeInternal</span>:</p>
<pre><code class="js">const o = {};
o.myself = o;</code></pre>
<p>it produces the following result:</p>
<pre><samp>{
[[Type]]: "Object",
[[Properties]]: «
{
[[Key]]: "myself",
[[Value]]: <i><a pointer to this whole structure></i>
}
»
}</samp></pre>
</div>
<h4 id="structuredserialize" data-lt="StructuredSerialize"
abstract-op><dfn>StructuredSerialize</dfn> ( <var>value</var> )</h4>
<ol>
<li><p>Return ? <span>StructuredSerializeInternal</span>(<var>value</var>, false).</p></li>
</ol>
<h4 id="structuredserializeforstorage" data-lt="StructuredSerializeForStorage"
abstract-op><dfn>StructuredSerializeForStorage</dfn> ( <var>value</var> )</h4>
<ol>
<li><p>Return ? <span>StructuredSerializeInternal</span>(<var>value</var>, true).</p></li>
</ol>
<h4 id="structureddeserialize" data-lt="StructuredDeserialize"
abstract-op><dfn>StructuredDeserialize</dfn> ( <var>serialized</var>, <var>targetRealm</var> [ ,
<var>memory</var> ] )</h4>
<p>The <span>StructuredDeserialize</span> abstract operation takes as input a <span>Record</span>
<var>serialized</var>, which was previously produced by <span>StructuredSerialize</span> or
<span>StructuredSerializeForStorage</span>, and deserializes it into a new JavaScript value,
created in <var>targetRealm</var>.</p>
<p>This process can throw an exception, for example when trying to allocate memory for the new
objects (especially <code data-x="">ArrayBuffer</code> objects).</p>
<ol>
<li>
<p>If <var>memory</var> was not supplied, let <var>memory</var> be an empty <span
data-x="ordered map">map</span>.</p>
<p class="note">The purpose of the <var>memory</var> map is to avoid deserializing objects
twice. This ends up preserving cycles and the identity of duplicate objects in graphs.</p>
</li>
<li><p>If <var>memory</var>[<var>serialized</var>] <span data-x="map exists">exists</span>, then
return <var>memory</var>[<var>serialized</var>].</p></li>
<li><p>Let <var>deep</var> be false.</p></li>
<li><p>Let <var>value</var> be an uninitialized value.</p></li>
<li><p>If <var>serialized</var>.[[Type]] is "primitive", then set <var>value</var> to
<var>serialized</var>.[[Value]].</p>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "Boolean", then set <var>value</var> to a
new Boolean object in <var>targetRealm</var> whose [[BooleanData]] internal slot value is
<var>serialized</var>.[[BooleanData]].</p></li>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "Number", then set <var>value</var> to a
new Number object in <var>targetRealm</var> whose [[NumberData]] internal slot value is
<var>serialized</var>.[[NumberData]].</p></li>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "BigInt", then set <var>value</var> to a
new BigInt object in <var>targetRealm</var> whose [[BigIntData]] internal slot value is
<var>serialized</var>.[[BigIntData]].</p></li>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "String", then set <var>value</var> to a
new String object in <var>targetRealm</var> whose [[StringData]] internal slot value is
<var>serialized</var>.[[StringData]].</p></li>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "Date", then set <var>value</var> to a new
Date object in <var>targetRealm</var> whose [[DateValue]] internal slot value is
<var>serialized</var>.[[DateValue]].</p></li>
<li><p>Otherwise, if <var>serialized</var>.[[Type]] is "RegExp", then set <var>value</var> to a
new RegExp object in <var>targetRealm</var> whose [[RegExpMatcher]] internal slot value is
<var>serialized</var>.[[RegExpMatcher]], whose [[OriginalSource]] internal slot value is
<var>serialized</var>.[[OriginalSource]], and whose [[OriginalFlags]] internal slot value is
<var>serialized</var>.[[OriginalFlags]].</p></li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "SharedArrayBuffer", then:</p>
<ol>
<li><p>If <var>targetRealm</var>'s corresponding <span>agent cluster</span> is not
<var>serialized</var>.[[AgentCluster]], then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Otherwise, set <var>value</var> to a new SharedArrayBuffer object in
<var>targetRealm</var> whose [[ArrayBufferData]] internal slot value is
<var>serialized</var>.[[ArrayBufferData]] and whose [[ArrayBufferByteLength]] internal slot
value is <var>serialized</var>.[[ArrayBufferByteLength]].</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "GrowableSharedArrayBuffer", then:</p>
<ol>
<li><p>If <var>targetRealm</var>'s corresponding <span>agent cluster</span> is not
<var>serialized</var>.[[AgentCluster]], then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Otherwise, set <var>value</var> to a new SharedArrayBuffer object in
<var>targetRealm</var> whose [[ArrayBufferData]] internal slot value is
<var>serialized</var>.[[ArrayBufferData]], whose [[ArrayBufferByteLengthData]] internal slot
value is <var>serialized</var>.[[ArrayBufferByteLengthData]], and whose
[[ArrayBufferMaxByteLength]] internal slot value is
<var>serialized</var>.[[ArrayBufferMaxByteLength]].</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "ArrayBuffer", then set <var>value</var> to a
new ArrayBuffer object in <var>targetRealm</var> whose [[ArrayBufferData]] internal slot value
is <var>serialized</var>.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot
value is <var>serialized</var>.[[ArrayBufferByteLength]].</p>
<p>If this throws an exception, catch it, and then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p>
<p class="note">This step might throw an exception if there is not enough memory available to
create such an ArrayBuffer object.</p>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "ResizableArrayBuffer", then set
<var>value</var> to a new ArrayBuffer object in <var>targetRealm</var> whose [[ArrayBufferData]]
internal slot value is <var>serialized</var>.[[ArrayBufferData]], whose
[[ArrayBufferByteLength]] internal slot value is
<var>serialized</var>.[[ArrayBufferByteLength]], and whose [[ArrayBufferMaxByteLength]] internal
slot value is <var>serialized</var>.[[ArrayBufferMaxByteLength]].</p>
<p>If this throws an exception, catch it, and then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p>
<p class="note">This step might throw an exception if there is not enough memory available to
create such an ArrayBuffer object.</p>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "ArrayBufferView", then:</p>
<ol>
<li><p>Let <var>deserializedArrayBuffer</var> be ?
<span>StructuredDeserialize</span>(<var>serialized</var>.[[ArrayBufferSerialized]],
<var>targetRealm</var>, <var>memory</var>).</p></li>
<li><p>If <var>serialized</var>.[[Constructor]] is "DataView", then set <var>value</var> to a
new DataView object in <var>targetRealm</var> whose [[ViewedArrayBuffer]] internal slot value
is <var>deserializedArrayBuffer</var>, whose [[ByteLength]] internal slot value is
<var>serialized</var>.[[ByteLength]], and whose [[ByteOffset]] internal slot value is
<var>serialized</var>.[[ByteOffset]].</p></li>
<li><p>Otherwise, set <var>value</var> to a new typed array object in <var>targetRealm</var>,
using the constructor given by <var>serialized</var>.[[Constructor]], whose
[[ViewedArrayBuffer]] internal slot value is <var>deserializedArrayBuffer</var>, whose
[[TypedArrayName]] internal slot value is <var>serialized</var>.[[Constructor]], whose
[[ByteLength]] internal slot value is <var>serialized</var>.[[ByteLength]], whose
[[ByteOffset]] internal slot value is <var>serialized</var>.[[ByteOffset]], and whose
[[ArrayLength]] internal slot value is <var>serialized</var>.[[ArrayLength]].</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Map", then:</p>
<ol>
<li><p>Set <var>value</var> to a new Map object in <var>targetRealm</var> whose [[MapData]]
internal slot value is a new empty <span data-x="js-List">List</span>.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Set", then:</p>
<ol>
<li><p>Set <var>value</var> to a new Set object in <var>targetRealm</var> whose [[SetData]]
internal slot value is a new empty <span data-x="js-List">List</span>.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Array", then:</p>
<ol>
<li><p>Let <var>outputProto</var> be
<var>targetRealm</var>.[[Intrinsics]].[[<span>%Array.prototype%</span>]].</p></li>
<li><p>Set <var>value</var> to ! <span>ArrayCreate</span>(<var>serialized</var>.[[Length]],
<var>outputProto</var>).</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Object", then:</p>
<ol>
<li><p>Set <var>value</var> to a new Object in <var>targetRealm</var>.</p></li>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Error", then:</p>
<ol>
<li><p>Let <var>prototype</var> be <span>%Error.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "EvalError", then set <var>prototype</var> to
<span>%EvalError.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "RangeError", then set <var>prototype</var>
to <span>%RangeError.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "ReferenceError", then set
<var>prototype</var> to <span>%ReferenceError.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "SyntaxError", then set <var>prototype</var>
to <span>%SyntaxError.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "TypeError", then set <var>prototype</var> to
<span>%TypeError.prototype%</span>.</p></li>
<li><p>If <var>serialized</var>.[[Name]] is "URIError", then set <var>prototype</var> to
<span>%URIError.prototype%</span>.</p></li>
<li><p>Let <var>message</var> be <var>serialized</var>.[[Message]].</p></li>
<li><p>Set <var>value</var> to <span>OrdinaryObjectCreate</span>(<var>prototype</var>, «
[[ErrorData]] »).</p></li>
<li><p>Let <var>messageDesc</var> be <span>PropertyDescriptor</span>{ [[Value]]:
<var>message</var>, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true
}.</p></li>
<li><p>If <var>message</var> is not undefined, then perform !
<span>OrdinaryDefineOwnProperty</span>(<var>value</var>, "<code data-x="">message</code>",
<var>messageDesc</var>).</p></li>
<li><p>Any interesting accompanying data attached to <var>serialized</var> should be
deserialized and attached to <var>value</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>interfaceName</var> be <var>serialized</var>.[[Type]].</p></li>
<li><p>If the interface identified by <var>interfaceName</var> is not
<span data-x="idl-exposed">exposed</span> in <var>targetRealm</var>, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <var>value</var> to a new instance of the interface identified by
<var>interfaceName</var>, created in <var>targetRealm</var>.</p>
<li><p>Set <var>deep</var> to true.</p></li>
</ol>
</li>
<li><p><span data-x="map set">Set</span> <var>memory</var>[<var>serialized</var>] to
<var>value</var>.</p></li>
<li>
<p>If <var>deep</var> is true, then:</p>
<ol>
<li>
<p>If <var>serialized</var>.[[Type]] is "Map", then:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <span>Record</span> { [[Key]], [[Value]] }
<var>entry</var> of <var>serialized</var>.[[MapData]]:</p>
<ol>
<li><p>Let <var>deserializedKey</var> be ?
<span>StructuredDeserialize</span>(<var>entry</var>.[[Key]], <var>targetRealm</var>,
<var>memory</var>).</p></li>
<li><p>Let <var>deserializedValue</var> be ?
<span>StructuredDeserialize</span>(<var>entry</var>.[[Value]], <var>targetRealm</var>,
<var>memory</var>).</p></li>
<li><p><span data-x="list append">Append</span> { [[Key]]: <var>deserializedKey</var>,
[[Value]]: <var>deserializedValue</var> } to <var>value</var>.[[MapData]].</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Set", then:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of
<var>serialized</var>.[[SetData]]:</p>
<ol>
<li><p>Let <var>deserializedEntry</var> be ?
<span>StructuredDeserialize</span>(<var>entry</var>, <var>targetRealm</var>,
<var>memory</var>).</p></li>
<li><p><span data-x="list append">Append</span> <var>deserializedEntry</var> to
<var>value</var>.[[SetData]].</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise, if <var>serialized</var>.[[Type]] is "Array" or "Object", then:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <span>Record</span> { [[Key]], [[Value]] }
<var>entry</var> of <var>serialized</var>.[[Properties]]:</p>
<ol>
<li><p>Let <var>deserializedValue</var> be ?
<span>StructuredDeserialize</span>(<var>entry</var>.[[Value]], <var>targetRealm</var>,
<var>memory</var>).</p></li>
<li><p>Let <var>result</var> be ! <span>CreateDataProperty</span>(<var>value</var>,
<var>entry</var>.[[Key]], <var>deserializedValue</var>).</p></li>
<li><p><span>Assert</span>: <var>result</var> is true.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li>
<p>Perform the appropriate <span>deserialization steps</span> for the interface identified
by <var>serialized</var>.[[Type]], given <var>serialized</var>, <var>value</var>, and
<var>targetRealm</var>.</p>
<p>The <span>deserialization steps</span> may need to perform a <dfn
export>sub-deserialization</dfn>. This is an operation which takes as input a
previously-serialized <span>Record</span> <var>subSerialized</var>, and returns
<span>StructuredDeserialize</span>(<var>subSerialized</var>, <var>targetRealm</var>,
<var>memory</var>). (In other words, a <span>sub-deserialization</span> is a specialization
of <span>StructuredDeserialize</span> to be consistent within this invocation.)</p>
</li>
</ol>
</ol>
</li>
<li><p>Return <var>value</var>.</p></li>
</ol>
<h4 id="structuredserializewithtransfer" data-lt="StructuredSerializeWithTransfer"
abstract-op><dfn>StructuredSerializeWithTransfer</dfn> ( <var>value</var>, <var>transferList</var>
)</h4>
<ol>
<li>
<p>Let <var>memory</var> be an empty <span data-x="ordered map">map</span>.</p>
<p class="note">In addition to how it is used normally by
<span>StructuredSerializeInternal</span>, in this algorithm <var>memory</var> is also used to
ensure that <span>StructuredSerializeInternal</span> ignores items in <var>transferList</var>,
and let us do our own handling instead.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>transferable</var> of
<var>transferList</var>:</p>
<ol>
<li><p>If <var>transferable</var> has neither an [[ArrayBufferData]] internal slot nor a
<span>[[Detached]]</span> internal slot, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>transferable</var> has an [[ArrayBufferData]] internal slot and
<span>IsSharedArrayBuffer</span>(<var>transferable</var>) is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>memory</var>[<var>transferable</var>] <span data-x="map exists">exists</span>,
then throw a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p><span data-x="map set">Set</span> <var>memory</var>[<var>transferable</var>] to {
[[Type]]: an uninitialized value }.</p>
<p class="note"><var>transferable</var> is not transferred yet as transferring has side
effects and <span>StructuredSerializeInternal</span> needs to be able to throw first.</p>
</li>
</ol>
</li>
<li><p>Let <var>serialized</var> be ? <span>StructuredSerializeInternal</span>(<var>value</var>,
false, <var>memory</var>).</p></li>
<li><p>Let <var>transferDataHolders</var> be a new empty <span
data-x="js-List">List</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>transferable</var> of
<var>transferList</var>:</p>
<ol>
<li><p>If <var>transferable</var> has an [[ArrayBufferData]] internal slot and
<span>IsDetachedBuffer</span>(<var>transferable</var>) is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>transferable</var> has a <span>[[Detached]]</span> internal slot and
<var>transferable</var>.<span>[[Detached]]</span> is true, then throw a
<span>"<code>DataCloneError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>dataHolder</var> be <var>memory</var>[<var>transferable</var>].</p></li>
<li>
<p>If <var>transferable</var> has an [[ArrayBufferData]] internal slot, then:</p>
<ol>
<li>
<p>If <var>transferable</var> has an [[ArrayBufferMaxByteLength]] internal slot, then:</p>
<ol>
<li><p>Set <var>dataHolder</var>.[[Type]] to "ResizableArrayBuffer".</p></li>
<li><p>Set <var>dataHolder</var>.[[ArrayBufferData]] to
<var>transferable</var>.[[ArrayBufferData]].</p></li>
<li><p>Set <var>dataHolder</var>.[[ArrayBufferByteLength]] to
<var>transferable</var>.[[ArrayBufferByteLength]].</p></li>
<li><p>Set <var>dataHolder</var>.[[ArrayBufferMaxByteLength]] to
<var>transferable</var>.[[ArrayBufferMaxByteLength]].</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Set <var>dataHolder</var>.[[Type]] to "ArrayBuffer".</p></li>
<li><p>Set <var>dataHolder</var>.[[ArrayBufferData]] to
<var>transferable</var>.[[ArrayBufferData]].</p></li>
<li><p>Set <var>dataHolder</var>.[[ArrayBufferByteLength]] to
<var>transferable</var>.[[ArrayBufferByteLength]].</p></li>
</ol>
</li>
<li>
<p>Perform ? <span>DetachArrayBuffer</span>(<var>transferable</var>).</p>
<p class="note">Specifications can use the [[ArrayBufferDetachKey]] internal slot to prevent
<code data-x="idl-ArrayBuffer">ArrayBuffer</code>s from being detached. This is used in
<cite>WebAssembly JavaScript Interface</cite>, for example. <ref>WASMJS</ref></p>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>transferable</var> is a <span>platform object</span> that is
a <span data-x="transferable objects">transferable object</span>.</p></li>
<li><p>Let <var>interfaceName</var> be the identifier of the <span>primary interface</span>
of <var>transferable</var>.</p></li>
<li><p>Set <var>dataHolder</var>.[[Type]] to <var>interfaceName</var>.</p></li>
<li><p>Perform the appropriate <span>transfer steps</span> for the interface identified by
<var>interfaceName</var>, given <var>transferable</var> and <var>dataHolder</var>.</p></li>
<li><p>Set <var>transferable</var>.<span>[[Detached]]</span> to true.</p></li>
</ol>
</li>
<li><p><span data-x="list append">Append</span> <var>dataHolder</var> to
<var>transferDataHolders</var>.</p></li>
</ol>
</li>
<li><p>Return { [[Serialized]]: <var>serialized</var>, [[TransferDataHolders]]:
<var>transferDataHolders</var> }.</p></li>
</ol>
<h4 id="structureddeserializewithtransfer" data-lt="StructuredDeserializeWithTransfer"
abstract-op><dfn>StructuredDeserializeWithTransfer</dfn> ( <var>serializeWithTransferResult</var>,
<var>targetRealm</var> )</h4>
<ol>
<li>
<p>Let <var>memory</var> be an empty <span data-x="ordered map">map</span>.</p>
<p class="note">Analogous to <span>StructuredSerializeWithTransfer</span>, in addition to how it
is used normally by <span>StructuredDeserialize</span>, in this algorithm <var>memory</var> is
also used to ensure that <span>StructuredDeserialize</span> ignores items in
<var>serializeWithTransferResult</var>.[[TransferDataHolders]], and let us do our own handling
instead.</p>
</li>
<li><p>Let <var>transferredValues</var> be a new empty <span
data-x="js-List">List</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>transferDataHolder</var> of
<var>serializeWithTransferResult</var>.[[TransferDataHolders]]:</p>
<ol>
<li><p>Let <var>value</var> be an uninitialized value.</p></li>
<li>
<p>If <var>transferDataHolder</var>.[[Type]] is "ArrayBuffer", then set <var>value</var> to a
new ArrayBuffer object in <var>targetRealm</var> whose [[ArrayBufferData]] internal slot value
is <var>transferDataHolder</var>.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]]
internal slot value is <var>transferDataHolder</var>.[[ArrayBufferByteLength]].</p>
<p class="note">In cases where the original memory occupied by [[ArrayBufferData]] is
accessible during the deserialization, this step is unlikely to throw an exception, as no new
memory needs to be allocated: the memory occupied by [[ArrayBufferData]] is instead just
getting transferred into the new ArrayBuffer. This could be true, for example, when both the
source and target realms are in the same process.</p>
</li>
<li>
<p>Otherwise, if <var>transferDataHolder</var>.[[Type]] is "ResizableArrayBuffer", then set
<var>value</var> to a new ArrayBuffer object in <var>targetRealm</var> whose
[[ArrayBufferData]] internal slot value is <var>transferDataHolder</var>.[[ArrayBufferData]],
whose [[ArrayBufferByteLength]] internal slot value is
<var>transferDataHolder</var>.[[ArrayBufferByteLength]], and whose
[[ArrayBufferMaxByteLength]] internal slot value is
<var>transferDataHolder</var>.[[ArrayBufferMaxByteLength]].</p>
<p class="note">For the same reason as the previous step, this step is also unlikely to throw
an exception.</p>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>interfaceName</var> be <var>transferDataHolder</var>.[[Type]].</p></li>
<li><p>If the interface identified by <var>interfaceName</var> is not exposed in
<var>targetRealm</var>, then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>value</var> to a new instance of the interface identified by
<var>interfaceName</var>, created in <var>targetRealm</var>.</p></li>
<li><p>Perform the appropriate <span>transfer-receiving steps</span> for the interface
identified by <var>interfaceName</var> given <var>transferDataHolder</var> and
<var>value</var>.</p></li>
</ol>
</li>
<li><p><span data-x="map set">Set</span> <var>memory</var>[<var>transferDataHolder</var>] to
<var>value</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>value</var> to
<var>transferredValues</var>.</p></li>
</ol>
</li>
<li><p>Let <var>deserialized</var> be ?
<span>StructuredDeserialize</span>(<var>serializeWithTransferResult</var>.[[Serialized]],
<var>targetRealm</var>, <var>memory</var>).</p></li>
<li><p>Return { [[Deserialized]]: <var>deserialized</var>, [[TransferredValues]]:
<var>transferredValues</var> }.</p></li>
</ol>
<h4 id="performing-structured-clones-from-other-specifications">Performing serialization and
transferring from other specifications</h4>
<p>Other specifications may use the abstract operations defined here. The following provides
some guidance on when each abstract operation is typically useful, with examples.</p>
<dl>
<dt><span>StructuredSerializeWithTransfer</span></dt>
<dt><span>StructuredDeserializeWithTransfer</span></dt>
<dd>
<p>Cloning a value to another <span>realm</span>, with a transfer list, but where the target
realm is not known ahead of time. In this case the serialization step can be performed
immediately, with the deserialization step delayed until the target realm becomes known.</p>
<p class="example"><code data-x="dom-MessagePort-postMessage">messagePort.postMessage()</code>
uses this pair of abstract operations, as the destination realm is not known until the
<code>MessagePort</code> <span>has been shipped</span>.</p>
</dd>
<dt><span>StructuredSerialize</span></dt>
<dt><span>StructuredSerializeForStorage</span></dt>
<dt><span>StructuredDeserialize</span></dt>
<dd>
<p>Creating a <span>realm</span>-independent snapshot of a given value which can be saved for an
indefinite amount of time, and then reified back into a JavaScript value later, possibly
multiple times.</p>
<p><span>StructuredSerializeForStorage</span> can be used for situations where the serialization
is anticipated to be stored in a persistent manner, instead of passed between realms. It throws
when attempting to serialize <code>SharedArrayBuffer</code> objects, since storing shared memory
does not make sense. Similarly, it can throw or possibly have different behavior when given a
<span>platform object</span> with custom <span>serialization steps</span> when the
<var>forStorage</var> argument is true.</p>
<p class="example"><code data-x="dom-history-pushState">history.pushState()</code> and <code
data-x="dom-history-replaceState">history.replaceState()</code> use
<span>StructuredSerializeForStorage</span> on author-supplied state objects, storing them as
<span>serialized state</span> in the appropriate <span>session history entry</span>. Then,
<span>StructuredDeserialize</span> is used so that the <code
data-x="dom-history-state">history.state</code> property can return a clone of the
originally-supplied state object.</p>
<p class="example"><code
data-x="dom-BroadcastChannel-postMessage">broadcastChannel.postMessage()</code> uses
<span>StructuredSerialize</span> on its input, then uses <span>StructuredDeserialize</span>
multiple times on the result to produce a fresh clone for each destination being broadcast
to. Note that transferring does not make sense in multi-destination situations.</p>
<p class="example">Any API for persisting JavaScript values to the filesystem would also use
<span>StructuredSerializeForStorage</span> on its input and <span>StructuredDeserialize</span>
on its output.</p>
</dd>
</dl>
<p>In general, call sites may pass in Web IDL values instead of JavaScript values; this is to be
understood to perform an implicit <span data-x="concept-idl-convert">conversion</span> to the
JavaScript value before invoking these algorithms.</p>
<hr>
<p>Call sites that are not invoked as a result of author code synchronously calling into a user
agent method must take care to properly <span>prepare to run script</span> and <span>prepare to
run a callback</span> before invoking <span>StructuredSerialize</span>,
<span>StructuredSerializeForStorage</span>, or <span>StructuredSerializeWithTransfer</span>
abstract operations, if they are being performed on arbitrary objects. This is necessary because
the serialization process can invoke author-defined accessors as part of its final
deep-serialization steps, and these accessors could call into operations that rely on the <span
data-x="concept-entry-everything">entry</span> and <span
data-x="concept-incumbent-everything">incumbent</span> concepts being properly set up.</p>
<p class="example"><code data-x="dom-window-postMessage">window.postMessage()</code> performs
<span>StructuredSerializeWithTransfer</span> on its arguments, but is careful to do so
immediately, inside the synchronous portion of its algorithm. Thus it is able to use the
algorithms without needing to <span>prepare to run script</span> and <span>prepare to run a
callback</span>.</p>
<p class="example">In contrast, a hypothetical API that used <span>StructuredSerialize</span> to
serialize some author-supplied object periodically, directly from a <span
data-x="concept-task">task</span> on the <span>event loop</span>, would need to ensure it performs
the appropriate preparations beforehand. As of this time, we know of no such APIs on the platform;
usually it is simpler to perform the serialization ahead of time, as a synchronous consequence of
author code.</p>
</div>
<h4 id="structured-cloning">Structured cloning API</h4>
<dl class="domintro">
<dt><code data-x=""><var>result</var> = self.<span subdfn data-x="dom-structuredClone">structuredClone</span>(<var>value</var>[, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> }])</code></dt>
<dd>
<p>Takes the input value and returns a deep copy by performing the structured clone algorithm.
<span>Transferable objects</span> listed in the <code
data-x="dom-StructuredSerializeOptions-transfer">transfer</code> array are transferred, not
just cloned, meaning that they are no longer usable in the input value.</p>
<p>Throws a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code> if any part of
the input value is not <span data-x="serializable objects">serializable</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="WindowOrWorkerGlobalScope"
data-x="dom-structuredClone"><code>structuredClone(<var>value</var>,
<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>serialized</var> be ?
<span>StructuredSerializeWithTransfer</span>(<var>value</var>, <var>options</var>["<code
data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"]).</p></li>
<li><p>Let <var>deserializeRecord</var> be ?
<span>StructuredDeserializeWithTransfer</span>(<var>serialized</var>, <span>this</span>'s
<span data-x="concept-relevant-realm">relevant realm</span>).</p></li>
<li><p>Return <var>deserializeRecord</var>.[[Deserialized]].</p></li>
</ol>
</div>
<h2 split-filename="dom" id="dom">Semantics, structure, and APIs of HTML documents</h2>
<h3>Documents</h3>
<p>Every XML and HTML document in an HTML UA is represented by a <code>Document</code> object.
<ref>DOM</ref></p>
<p>The <code>Document</code> object's <dfn id="the-document's-address"
data-x="concept-document-url"
data-x-href="https://dom.spec.whatwg.org/#concept-document-url">URL</dfn> is defined in
<cite>DOM</cite>. It is initially set when the <code>Document</code> object is created, but can
change during the lifetime of the <code>Document</code> object; for example, it changes when the
user <span data-x="navigate">navigates</span> to a <span data-x="navigate-fragid">fragment</span>
on the page and when the <code data-x="dom-history-pushState">pushState()</code> method is called
with a new <span>URL</span>. <ref>DOM</ref></p>
<!--
https://www.hixie.ch/tests/adhoc/dom/level0/history/pushState/002/
https://www.hixie.ch/tests/adhoc/html/navigation/fragids/016.html
-->
<p class="warning">Interactive user agents typically expose the <code>Document</code> object's
<span data-x="concept-document-url">URL</span> in their user interface. This is the primary
mechanism by which a user can tell if a site is attempting to impersonate another.</p>
<p>The <code>Document</code> object's <dfn data-x="concept-document-origin"
data-x-href="https://dom.spec.whatwg.org/#concept-document-origin">origin</dfn> is defined in
<cite>DOM</cite>. It is initially set when the <code>Document</code> object is created, and can
change during the lifetime of the <code>Document</code> only upon setting <code
data-x="dom-document-domain">document.domain</code>. A <code>Document</code>'s <span
data-x="concept-document-origin">origin</span> can differ from the <span
data-x="concept-url-origin">origin</span> of its <span data-x="concept-document-url">URL</span>;
for example when a <span>child navigable</span> is <span data-x="create a new child
navigable">created</span>, its <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is inherited from its <span
data-x="nav-parent">parent</span>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span>, even though its <span
data-x="nav-document">active document</span>'s <span data-x="concept-document-url">URL</span> is
<code>about:blank</code>. <ref>DOM</ref></p>
<p>When a <code>Document</code> is created by a <span data-x="concept-script">script</span> using
the <code data-x="dom-DOMImplementation-createDocument">createDocument()</code> or <code
data-x="dom-DOMImplementation-createHTMLDocument">createHTMLDocument()</code> methods, the
<code>Document</code> is <span>ready for post-load tasks</span> immediately.</p>
<p><dfn export>The document's referrer</dfn> is a string (representing a <span>URL</span>) that
can be set when the <code>Document</code> is created. If it is not explicitly set, then its value
is the empty string.</p>
<h4>The <code>Document</code> object</h4>
<p><cite>DOM</cite> defines a <code data-x="DOM Document">Document</code> interface, which
this specification extends significantly.</p>
<pre><code class="idl">enum <dfn enum>DocumentReadyState</dfn> { "loading", "interactive", "complete" };
enum <dfn enum>DocumentVisibilityState</dfn> { "visible", "hidden" };
typedef (<span>HTMLScriptElement</span> or <span>SVGScriptElement</span>) <dfn typedef>HTMLOrSVGScriptElement</dfn>;
[<span>LegacyOverrideBuiltIns</span>]
partial interface <dfn id="document" data-lt="">Document</dfn> {
static <code>Document</code> <span data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
// <span>resource metadata management</span>
[PutForwards=<span data-x="dom-location-href">href</span>, <span>LegacyUnforgeable</span>] readonly attribute <span>Location</span>? <span data-x="dom-document-location">location</span>;
attribute USVString <span data-x="dom-document-domain">domain</span>;
readonly attribute USVString <span data-x="dom-document-referrer">referrer</span>;
attribute USVString <span data-x="dom-document-cookie">cookie</span>;
readonly attribute DOMString <span data-x="dom-document-lastModified">lastModified</span>;
readonly attribute <span>DocumentReadyState</span> <span data-x="dom-document-readyState">readyState</span>;
// <span>DOM tree accessors</span>
<a href="#dom-document-nameditem">getter</a> object (DOMString name);
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-document-title">title</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-document-dir">dir</span>;
[<span>CEReactions</span>] attribute <span>HTMLElement</span>? <span data-x="dom-document-body">body</span>;
readonly attribute <span>HTMLHeadElement</span>? <span data-x="dom-document-head">head</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-images">images</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-embeds">embeds</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-plugins">plugins</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-links">links</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-forms">forms</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-scripts">scripts</span>;
NodeList <span data-x="dom-document-getElementsByName">getElementsByName</span>(DOMString elementName);
readonly attribute <span>HTMLOrSVGScriptElement</span>? <span data-x="dom-document-currentScript">currentScript</span>; // classic scripts in a document tree only
// <span>dynamic markup insertion</span>
[<span>CEReactions</span>] <span>Document</span> <span data-x="dom-document-open">open</span>(optional DOMString unused1, optional DOMString unused2); // both arguments are <a href="#dom-document-open-unused-arguments">ignored</a>
<span>WindowProxy</span>? <span data-x="dom-document-open-window">open</span>(USVString url, DOMString name, DOMString features);
[<span>CEReactions</span>] undefined <span data-x="dom-document-close">close</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-document-write">write</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString)... text);
[<span>CEReactions</span>] undefined <span data-x="dom-document-writeln">writeln</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString)... text);
// <span>user interaction</span>
readonly attribute <span>WindowProxy</span>? <span data-x="dom-document-defaultView">defaultView</span>;
boolean <span data-x="dom-document-hasFocus">hasFocus</span>();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-document-designMode">designMode</span>;
[<span>CEReactions</span>] boolean <span data-x="dom-document-execCommand">execCommand</span>(DOMString commandId, optional boolean showUI = false, optional DOMString value = "");
boolean <span data-x="dom-document-queryCommandEnabled">queryCommandEnabled</span>(DOMString commandId);
boolean <span data-x="dom-document-queryCommandIndeterm">queryCommandIndeterm</span>(DOMString commandId);
boolean <span data-x="dom-document-queryCommandState">queryCommandState</span>(DOMString commandId);
boolean <span data-x="dom-document-queryCommandSupported">queryCommandSupported</span>(DOMString commandId);
DOMString <span data-x="dom-document-queryCommandValue">queryCommandValue</span>(DOMString commandId);
readonly attribute boolean <span data-x="dom-document-hidden">hidden</span>;
readonly attribute <span>DocumentVisibilityState</span> <span data-x="dom-document-visibilityState">visibilityState</span>;
// special <span>event handler IDL attributes</span> that only apply to Document objects
[<span>LegacyLenientThis</span>] attribute <span>EventHandler</span> <span data-x="handler-onreadystatechange">onreadystatechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onvisibilitychange">onvisibilitychange</span>;
// <a href="#Document-partial">also has obsolete members</a>
};
<span>Document</span> includes <span>GlobalEventHandlers</span>;</code></pre>
<p>Each <code>Document</code> has a <dfn data-x="concept-document-policy-container" export
for="Document">policy container</dfn> (a <span>policy container</span>), initially a new policy
container, which contains policies which apply to the <code>Document</code>.</p>
<p id="concept-document-feature-policy">Each <code>Document</code> has a <dfn
data-x="concept-document-permissions-policy" export for="Document">permissions policy</dfn>, which
is a <span data-x="concept-permissions-policy">permissions policy</span>, which is initially
empty.</p>
<p>Each <code>Document</code> has a <dfn data-x="concept-document-module-map">module map</dfn>,
which is a <span>module map</span>, initially empty.</p>
<p>Each <code>Document</code> has an <dfn data-x="concept-document-coop">opener policy</dfn>,
which is an <span>opener policy</span>, initially a new opener policy.</p>
<p>Each <code>Document</code> has an <dfn>is initial <code>about:blank</code></dfn>, which is a
boolean, initially false.</p>
<p>Each <code>Document</code> has a <dfn data-x="concept-document-navigation-id">during-loading
navigation ID for WebDriver BiDi</dfn>, which is a <span>navigation ID</span> or null, initially
null.</p>
<p class="note">As the name indicates, this is used for interfacing with the <cite>WebDriver
BiDi</cite> specification, which needs to be informed about certain occurrences during the early
parts of the <code>Document</code>'s lifecycle, in a way that ties them to the original
<span>navigation ID</span> used when the navigation that created this <code>Document</code> was
the <span>ongoing navigation</span>. This eventually gets set back to null, after <cite>WebDriver
BiDi</cite> considers the loading process to be finished. <ref>BIDI</ref></p>
<p>Each <code>Document</code> has an <dfn data-x="concept-document-about-base-url">about base
URL</dfn>, which is a <span>URL</span> or null, initially null.</p>
<p class="note">This is only populated for "<code data-x="">about:</code>"-schemed
<code>Document</code>s.</p>
<p>Each <code>Document</code> has a <dfn
data-x="concept-document-bfcache-blocking-details">bfcache blocking details</dfn>, which is a
<span>set</span> of <span data-x="nrr-details-struct">not restored reason details</span>,
initially empty.</p>
<p>Each <code>Document</code> has an <dfn>open dialogs list</dfn>, which is a <span>list</span> of
<code>dialog</code> elements, initially empty.</p>
<h4>The <code>DocumentOrShadowRoot</code> interface</h4>
<p><cite>DOM</cite> defines the <code data-x="DOM
DocumentOrShadowRoot">DocumentOrShadowRoot</code> mixin, which this specification
extends.</p>
<pre><code class="idl">partial interface mixin <dfn data-lt="">DocumentOrShadowRoot</dfn> {
readonly attribute <span>Element</span>? <span data-x="dom-documentorshadowroot-activeElement">activeElement</span>;
};</code></pre>
<h4><dfn>Resource metadata management</dfn></h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-referrer">referrer</span></code></dt>
<dd>
<p>Returns the <span data-x="concept-document-url">URL</span> of the <code>Document</code> from
which the user navigated to this one, unless it was blocked or there was no such document, in
which case it returns the empty string.</p>
<p>The <code data-x="rel-noreferrer">noreferrer</code> link type can be used to block the
referrer.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Document"><code data-x="dom-document-referrer">referrer</code></dfn>
attribute must return <span>the document's referrer</span>.</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-cookie">cookie</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the HTTP cookies that apply to the <code>Document</code>. If there are no cookies or
cookies can't be applied to this resource, the empty string will be returned.</p>
<p>Can be set, to add a new cookie to the element's set of HTTP cookies.</p>
<p>If the contents are <span data-x="sandboxed origin browsing context flag">sandboxed into an
opaque origin</span> (e.g., in an <code>iframe</code> with the <code
data-x="attr-iframe-sandbox">sandbox</code> attribute), a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> will be thrown on getting
and setting.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Document"><code data-x="dom-document-cookie">cookie</code></dfn>
attribute represents the cookies of the resource identified by the document's <span
data-x="concept-document-url">URL</span>.</p>
<p>A <code>Document</code> object that falls into one of the following conditions is a
<dfn>cookie-averse <code>Document</code> object</dfn>:</p>
<ul>
<li>A <code>Document</code> object whose <span data-x="concept-document-bc">browsing
context</span> is null.</li>
<li>A <code>Document</code> whose <span data-x="concept-document-url">URL</span>'s <span
data-x="concept-url-scheme">scheme</span> is not an <span>HTTP(S) scheme</span>.</li>
</ul>
<!--Other specifications can also define <code>Document</code> objects as being <span
data-x="cookie-averse Document object">cookie-averse <code>Document</code> objects</span>.-->
<p id="sandboxCookies">
<!--INSERT TRACKING-->
On getting, if the document is a <span>cookie-averse <code>Document</code> object</span>, then the
user agent must return the empty string. Otherwise, if the <code>Document</code>'s <span
data-x="concept-document-origin">origin</span> is an <span data-x="concept-origin-opaque">opaque
origin</span>, the user agent must throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>. Otherwise, the user agent must return the <span>cookie-string</span>
for the document's <span data-x="concept-document-url">URL</span> for a "non-HTTP" API, decoded
using <span>UTF-8 decode without BOM</span>. <ref>COOKIES</ref></p>
<p>On setting, if the document is a <span>cookie-averse <code>Document</code> object</span>, then
the user agent must do nothing. Otherwise, if the <code>Document</code>'s <span
data-x="concept-document-origin">origin</span> is an <span data-x="concept-origin-opaque">opaque
origin</span>, the user agent must throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>. Otherwise, the user agent must act as it would when <span
data-x="receives a set-cookie-string">receiving a set-cookie-string</span> for the document's
<span data-x="concept-document-url">URL</span> via a "non-HTTP" API, consisting of the new value
<span data-x="utf-8 encode">encoded as UTF-8</span>. <ref>COOKIES</ref> <ref>ENCODING</ref></p>
<p class="note">Since the <code data-x="dom-document-cookie">cookie</code> attribute is accessible
across frames, the path restrictions on cookies are only a tool to help manage which cookies are
sent to which parts of the site, and are not in any way a security feature.</p>
<p class="warning">The <code data-x="dom-document-cookie">cookie</code> attribute's getter and
setter synchronously access shared state. Since there is no locking mechanism, other browsing
contexts in a multiprocess user agent can modify cookies while scripts are running. A site could,
for instance, try to read a cookie, increment its value, then write it back out, using the new
value of the cookie as a unique identifier for the session; if the site does this twice in two
different browser windows at the same time, it might end up using the same "unique" identifier for
both sessions, with potentially disastrous effects.</p>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-lastmodified">lastModified</span></code></dt>
<dd>
<p>Returns the date of the last modification to the document, as reported by the server, in the
form "<code data-x="">MM/DD/YYYY hh:mm:ss</code>", in the user's local time zone.</p>
<p>If the last modification date is not known, the current time is returned instead.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Document"><code
data-x="dom-document-lastModified">lastModified</code></dfn> attribute, on getting, must return
the date and time of the <code>Document</code>'s source file's last modification, in the user's
local time zone, in the following format:</p>
<ol>
<li><p>The month component of the date.</p></li>
<li><p>A U+002F SOLIDUS character (/).</p></li>
<li><p>The day component of the date.</p></li>
<li><p>A U+002F SOLIDUS character (/).</p></li>
<li><p>The year component of the date.</p></li>
<li><p>A U+0020 SPACE character.</p></li>
<li><p>The hours component of the time.</p></li>
<li><p>A U+003A COLON character (:).</p></li>
<li><p>The minutes component of the time.</p></li>
<li><p>A U+003A COLON character (:).</p></li>
<li><p>The seconds component of the time.</p></li>
</ol>
<p>All the numeric components above, other than the year, must be given as two <span>ASCII
digits</span> representing the number in base ten, zero-padded if necessary. The year must be
given as the shortest possible string of four or more <span>ASCII digits</span> representing the
number in base ten, zero-padded if necessary.</p>
<p>The <code>Document</code>'s source file's last modification date and time must be derived from
relevant features of the networking protocols used, e.g. from the value of the HTTP `<code
data-x="http-last-modified">Last-Modified</code>` header of the document, or from metadata in the
file system for local files. If the last modification date and time are not known, the attribute
must return the current date and time in the above format.</p>
</div>
<h4>Reporting document loading status</h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-readyState">readyState</span></code></dt>
<dd>
<p>Returns "<code data-x="">loading</code>" while the <code>Document</code> is loading, "<code
data-x="">interactive</code>" once it is finished parsing but still loading subresources, and
"<code data-x="">complete</code>" once it has loaded.</p>
<p>The <code data-x="event-readystatechange">readystatechange</code> event fires on the
<code>Document</code> object when this value changes.</p>
<p><span w-dev subdfn data-x="stop parsing"></span>The <code
data-x="event-DOMContentLoaded">DOMContentLoaded</code> event fires after the transition to
"<code data-x="">interactive</code>" but before the transition to "<code
data-x="">complete</code>", at the point where all subresources apart from <code
data-x="attr-script-async">async</code> <code>script</code> elements have loaded.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <code>Document</code> has a <dfn>current document readiness</dfn>, a string, initially
"<code data-x="">complete</code>".</p>
<p class="note">For <code>Document</code> objects created via the <span
data-x="create-the-document-object">create and initialize a <code>Document</code> object</span>
algorithm, this will be immediately reset to "<code data-x="">loading</code>" before any script
can observe the value of <code data-x="dom-document-readyState">document.readyState</code>. This
default applies to other cases such as <span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code>s or <code>Document</code>s without a
<span data-x="concept-document-bc">browsing context</span>.</p>
<p>The <dfn attribute for="Document"><code
data-x="dom-document-readyState">readyState</code></dfn> getter steps are to return
<span>this</span>'s <span>current document readiness</span>.</p>
<p>To <dfn>update the current document readiness</dfn> for <code>Document</code>
<var>document</var> to <var>readinessValue</var>:</p>
<ol>
<li><p>If <var>document</var>'s <span>current document readiness</span> equals
<var>readinessValue</var>, then return.</p></li>
<li><p>Set <var>document</var>'s <span>current document readiness</span> to
<var>readinessValue</var>.</p></li>
<li>
<p>If <var>document</var> is associated with an <span>HTML parser</span>, then:</p>
<ol>
<li><p>Let <var>now</var> be the <span>current high resolution time</span> given
<var>document</var>'s <span>relevant global object</span>.</p></li>
<li><p>If <var>readinessValue</var> is "<code data-x="">complete</code>", and
<var>document</var>'s <span>load timing info</span>'s <span>DOM complete time</span> is 0, then
set <var>document</var>'s <span>load timing info</span>'s <span>DOM complete time</span> to
<var>now</var>.</p></li>
<li><p>Otherwise, if <var>readinessValue</var> is "<code data-x="">interactive</code>", and
<var>document</var>'s <span>load timing info</span>'s <span>DOM interactive time</span> is 0,
then set <var>document</var>'s <span>load timing info</span>'s <span>DOM interactive
time</span> to <var>now</var>.</p></li>
</ol>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-readystatechange">readystatechange</code> at <var>document</var>.</p></li>
</ol>
<hr>
<p>A <code>Document</code> is said to have an <dfn>active parser</dfn> if it is associated with an
<span>HTML parser</span> or an <span>XML parser</span> that has not yet been <span data-x="stop
parsing">stopped</span> or <span data-x="abort a parser">aborted</span>.</p>
<hr>
<p>A <code>Document</code> has a <span>document load timing info</span> <dfn export
for="Document">load timing info</dfn>.</p>
<p>A <code>Document</code> has a <span>document unload timing info</span> <dfn export
for="Document">previous document unload timing</dfn>.</p>
<p>A <code>Document</code> has a boolean <dfn export>was created via cross-origin redirects</dfn>,
initially false.</p>
<p>The <dfn export>document load timing info</dfn> <span>struct</span> has the following <span
data-x="struct item">items</span>:</p>
<dl>
<dt><dfn export for="document load timing info">navigation start time</dfn> (default 0)</dt>
<dd>A number</dd>
<dt><dfn export for="document load timing info">DOM interactive time</dfn> (default 0)</dt>
<dt><dfn export for="document load timing info">DOM content loaded event start time</dfn>
(default 0)</dt>
<dt><dfn export for="document load timing info">DOM content loaded event end time</dfn> (default
0)</dt>
<dt><dfn export for="document load timing info">DOM complete time</dfn> (default 0)</dt>
<dt><dfn export for="document load timing info">load event start time</dfn> (default 0)</dt>
<dt><dfn export for="document load timing info">load event end time</dfn> (default 0)</dt>
<dd><code>DOMHighResTimeStamp</code> values</dd>
</dl>
<p>The <dfn export>document unload timing info</dfn> <span>struct</span> has the following <span
data-x="struct item">items</span>:</p>
<dl>
<dt><dfn export for="document unload timing info">unload event start time</dfn> (default 0)</dt>
<dt><dfn export for="document unload timing info">unload event end time</dfn> (default 0)</dt>
<dd><code>DOMHighResTimeStamp</code> values</dd>
</dl>
</div>
<h4><dfn>Render-blocking mechanism</dfn></h4>
<p>Each <code>Document</code> has a <dfn>render-blocking element set</dfn>, a <span>set</span> of
elements, initially the empty set.</p>
<p>A <code>Document</code> <var>document</var> <dfn>allows adding render-blocking elements</dfn>
if <var>document</var>'s <span data-x="concept-document-content-type">content type</span> is
"<code>text/html</code>" and <span>the body element</span> of <var>document</var> is null.</p>
<p>A <code>Document</code> <var>document</var> is <dfn>render-blocked</dfn> if both of the
following are true:</p>
<ul>
<li><p><var>document</var>'s <span>render-blocking element set</span> is non-empty, or
<var>document</var> <span>allows adding render-blocking elements</span>.</p>
<li><p>The <span>current high resolution time</span> given <var>document</var>'s <span>relevant
global object</span> has not exceeded an <span>implementation-defined</span> timeout value.</p>
</ul>
<p>An element <var>el</var> is <dfn>render-blocking</dfn> if <var>el</var>'s
<span>node document</span> <var>document</var> is <span>render-blocked</span>, and <var>el</var>
is in <var>document</var>'s <span>render-blocking element set</span>.</p>
<p>To <dfn>block rendering</dfn> on an element <var>el</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>el</var>'s <span>node document</span>.</p>
<li><p>If <var>document</var> <span>allows adding render-blocking elements</span>, then
<span data-x="set append">append</span> <var>el</var> to <var>document</var>'s
<span>render-blocking element set</span>.</p>
</ol>
<p>To <dfn>unblock rendering</dfn> on an element <var>el</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>el</var>'s <span>node document</span>.</p>
<li><p><span data-x="list remove">Remove</span> <var>el</var> from <var>document</var>'s
<span>render-blocking element set</span>.</p>
</ol>
<p>Whenever a <span>render-blocking</span> element <var>el</var>
<span>becomes browsing-context disconnected</span>, or <var>el</var>'s
<span>blocking attribute</span>'s value is changed so that <var>el</var> is no longer
<span>potentially render-blocking</span>, then <span>unblock rendering</span> on
<var>el</var>.</p>
<h4><dfn>DOM tree accessors</dfn></h4>
<p><dfn>The <code>html</code> element</dfn> of a document is its <span>document element</span>,
if it's an <code>html</code> element, and null otherwise.</p>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-head">head</span></code></dt>
<dd><p>Returns <span>the <code>head</code> element</span>.</p></dd>
</dl>
<p><dfn>The <code>head</code> element</dfn> of a document is the first <code>head</code> element
that is a child of <span>the <code>html</code> element</span>, if there is one, or null
otherwise.</p>
<div w-nodev>
<p>The <dfn attribute for="Document"><code data-x="dom-document-head">head</code></dfn> attribute,
on getting, must return <span>the <code>head</code> element</span> of the document (a
<code>head</code> element or null).</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-title">title</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the document's title, as given by <span>the <code>title</code> element</span> for
HTML and as given by the <span>SVG <code>title</code></span> element for SVG.</p>
<p>Can be set, to update the document's title. If there is no appropriate element to update, the
new value is ignored.</p>
</dd>
</dl>
<p><dfn>The <code>title</code> element</dfn> of a document is the first <code>title</code> element
in the document (in <span>tree order</span>), if there is one, or null otherwise.</p>
<div w-nodev>
<p>The <dfn attribute for="Document" id="document.title"
data-x="dom-document-title"><code>title</code></dfn> attribute must, on getting, run the following
algorithm:</p>
<ol>
<li><p>If the <span>document element</span> is an <span>SVG <code>svg</code></span> element, then
let <var>value</var> be the <span>child text content</span> of the first <span>SVG
<code>title</code></span> element that is a child of the <span>document element</span>.</p></li>
<li><p>Otherwise, let <var>value</var> be the <span>child text content</span> of <span>the
<code>title</code> element</span>, or the empty string if <span>the <code>title</code>
element</span> is null.</p></li>
<li><p><span>Strip and collapse ASCII whitespace</span> in <var>value</var>.</p></li>
<li><p>Return <var>value</var>.</p></li>
</ol>
<p>On setting, the steps corresponding to the first matching condition in the following list must
be run:</p>
<dl class="switch">
<dt>If the <span>document element</span> is an <span>SVG <code>svg</code></span> element</dt>
<dd>
<ol>
<li><p>If there is an <span>SVG <code>title</code></span> element that is a child of the
<span>document element</span>, let <var>element</var> be the first such element.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>element</var> be the result of <span data-x="create an element">creating an
element</span> given the <span>document element</span>'s <span>node document</span>, "<code
data-x="">title</code>", and the <span>SVG namespace</span>.</p>
<li><p>Insert <var>element</var> as the <span>first child</span> of the <span>document
element</span>.</p></li>
</ol>
</li>
<li><p><span>String replace all</span> with the given value within <var>element</var>.</p></li>
</ol>
</dd>
<dt>If the <span>document element</span> is in the <span>HTML namespace</span></dt>
<dd>
<ol>
<li><p>If <span>the <code>title</code> element</span> is null and <span>the <code>head</code>
element</span> is null, then return.</p></li>
<li><p>If <span>the <code>title</code> element</span> is non-null, let <var>element</var> be
<span>the <code>title</code> element</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>element</var> be the result of <span data-x="create an element">creating an
element</span> given the <span>document element</span>'s <span>node document</span>, "<code
data-x="">title</code>", and the <span>HTML namespace</span>.</p>
<li><p><span data-x="concept-node-append">Append</span> <var>element</var> to <span>the
<code>head</code> element</span>.</p></li>
</ol>
</li>
<li><p><span>String replace all</span> with the given value within <var>element</var>.</p></li>
</ol>
</dd>
<dt>Otherwise</dt>
<dd>
<p>Do nothing.</p>
</dd>
</dl>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-body">body</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns <span>the body element</span>.</p>
<p>Can be set, to replace <span>the body element</span>.</p>
<p>If the new value is not a <code>body</code> or <code>frameset</code> element, this will throw
a <span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</p>
</dd>
</dl>
<p><dfn export>The body element</dfn> of a document is the first of <span>the <code>html</code>
element</span>'s children that is either a <code>body</code> element or a <code>frameset</code>
element, or null if there is no such element.</p>
<div w-nodev>
<p>The <dfn attribute for="Document"><code data-x="dom-document-body">body</code></dfn> attribute,
on getting, must return <span>the body element</span> of the document (either a <code>body</code>
element, a <code>frameset</code> element, or null). On setting, the following algorithm must be
run:</p>
<ol>
<!-- if changes are requested:
http://searchfox.org/mozilla-central/source/dom/html/nsHTMLDocument.cpp
search for ::GetBody ::SetBody
https://trac.webkit.org/browser/trunk/Source/WebCore/html/HTMLDocument.cpp
search for ::setBody
https://trac.webkit.org/browser/trunk/Source/WebCore/dom/Document.cpp
search for ::body
-->
<li>If the new value is not a <code>body</code> or <code>frameset</code> element, then throw a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</li>
<li>Otherwise, if the new value is the same as <span>the body element</span>, return.</li>
<li>Otherwise, if <span>the body element</span> is not null, then <span
data-x="concept-node-replace">replace</span> <span>the body element</span> with the new value
within <span>the body element</span>'s parent and return.</li>
<li>Otherwise, if there is no <span>document element</span>, throw a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</li>
<li>Otherwise, <span>the body element</span> is null, but there's a
<span>document element</span>. <span data-x="concept-node-append">Append</span> the new value to
the <span>document element</span>.</li>
</ol>
<p class="note">The value returned by the <code data-x="dom-document-body">body</code> getter is
not always the one passed to the setter.</p>
<div class="example">
<p>In this example, the setter successfully inserts a <code>body</code> element (though this is
non-conforming since SVG does not allow a <code>body</code> as child of <span>SVG
<code>svg</code></span>). However the getter will return null because the document element is not
<code>html</code>.</p>
<pre><code class="html"><svg xmlns="http://www.w3.org/2000/svg">
<script>
document.body = document.createElementNS("http://www.w3.org/1999/xhtml", "body");
console.assert(document.body === null);
</script>
</svg></code></pre>
</div>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-images">images</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>img</code> elements in the
<code>Document</code>.</p>
</dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-embeds">embeds</span></code></dt>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-plugins">plugins</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>embed</code> elements in the
<code>Document</code>.</p>
</dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-links">links</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>a</code> and <code>area</code> elements
in the <code>Document</code> that have <code data-x="attr-hyperlink-href">href</code>
attributes.</p>
</dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-forms">forms</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>form</code> elements in the
<code>Document</code>.</p>
</dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-scripts">scripts</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>script</code> elements in the
<code>Document</code>.</p>
</dd>
</dl>
<div w-nodev>
<!-- these all return the same object each time because of a rule in the collection section -->
<p>The <dfn attribute for="Document"><code data-x="dom-document-images">images</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>img</code> elements.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-embeds">embeds</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>embed</code> elements.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-plugins">plugins</code></dfn>
attribute must return the same object as that returned by the <code
data-x="dom-document-embeds">embeds</code> attribute.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-links">links</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>a</code> elements with <code
data-x="attr-hyperlink-href">href</code> attributes and <code>area</code> elements with <code
data-x="attr-hyperlink-href">href</code> attributes.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-forms">forms</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>form</code> elements.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-scripts">scripts</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>script</code> elements.</p>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>collection</var> = <var>document</var>.<span subdfn data-x="dom-document-getElementsByName">getElementsByName</span>(<var>name</var>)</code></dt>
<dd><p>Returns a <code>NodeList</code> of elements in the <code>Document</code> that have a <code
data-x="">name</code> attribute with the value <var>name</var>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="Document"><code
data-x="dom-document-getElementsByName">getElementsByName(<var>elementName</var>)</code></dfn> method
steps are to return a <span>live</span> <code>NodeList</code> containing all the <span>HTML
elements</span> in that document that have a <code data-x="">name</code> attribute whose value is
<span>identical to</span> the <var>elementName</var> argument, in <span>tree order</span>. When the
method is invoked on a <code>Document</code> object again with the same argument, the user agent
may return the same as the object returned by the earlier call. In other cases, a new
<code>NodeList</code> object must be returned.</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-currentScript">currentScript</span></code></dt>
<dd>
<p>Returns the <code>script</code> element, or the <span>SVG <code>script</code></span> element,
that is currently executing, as long as the element represents a <span>classic script</span>. In
the case of reentrant script execution, returns the one that most recently started executing
amongst those that have not yet finished executing.</p>
<p>Returns null if the <code>Document</code> is not currently executing a <code>script</code> or
<span>SVG <code>script</code></span> element (e.g., because the running script is an event
handler, or a timeout), or if the currently executing <code>script</code> or <span>SVG
<code>script</code></span> element represents a <span>module script</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Document"><code
data-x="dom-document-currentScript">currentScript</code></dfn> attribute, on getting, must return
the value to which it was most recently set. When the <code>Document</code> is created, the <code
data-x="dom-document-currentScript">currentScript</code> must be initialized to null.</p>
</div>
<p class="note">This API has fallen out of favor in the implementer and standards community, as
it globally exposes <code>script</code> or <span>SVG <code>script</code></span> elements. As such,
it is not available in newer contexts, such as when running <span data-x="module script">module
scripts</span> or when running scripts in a <span>shadow tree</span>. We are looking into creating
a new solution for identifying the running script in such contexts, which does not make it
globally available: see <a href="https://github.com/whatwg/html/issues/1013">issue #1013</a>.</p>
<div w-nodev>
<hr>
<p id="dom-document-namedItem-which">The <code>Document</code> interface <span data-x="support
named properties">supports named properties</span>. The <span>supported property names</span> of a
<code>Document</code> object <var>document</var> at any moment consist of the following, in
<span>tree order</span> according to the element that contributed them, ignoring later duplicates,
and with values from <code data-x="attr-id">id</code> attributes coming before values from <code
data-x="">name</code> attributes when the same element contributes both:</p>
<!-- KEEP THIS LIST IN SYNC WITH "NAMED ELEMENTS" DEFINITION BELOW -->
<ul>
<li><p>the value of the <code data-x="">name</code> content attribute for all
<span>exposed</span> <code>embed</code>, <code>form</code>, <code>iframe</code>,
<code>img</code>, and <span>exposed</span> <code>object</code> elements that have a non-empty
<code data-x="">name</code> content attribute and are <span>in a document tree</span> with
<var>document</var> as their <span>root</span>;</p></li>
<li><p>the value of the <code data-x="attr-id">id</code> content attribute for all
<span>exposed</span> <code>object</code> elements that have a non-empty
<code data-x="attr-id">id</code> content attribute and are <span>in a document tree</span> with
<var>document</var> as their <span>root</span>; and</p></li>
<li><p>the value of the <code data-x="attr-id">id</code> content attribute for all
<code>img</code> elements that have both a non-empty <code data-x="attr-id">id</code> content
attribute and a non-empty <code data-x="">name</code> content attribute, and are <span>in a
document tree</span> with <var>document</var> as their <span>root</span>.</p></li>
</ul>
<p id="dom-document-nameditem">To <span>determine the value of a named property</span>
<var>name</var> for a <code>Document</code>, the user agent must return the value obtained using
the following steps:</p>
<ol>
<li>
<p>Let <var>elements</var> be the list of <span data-x="dom-document-namedItem-filter">named
elements</span> with the name <var>name</var> that are <span>in a document tree</span> with the
<code>Document</code> as their <span>root</span>.</p>
<p class="note">There will be at least one such element, since the algorithm would otherwise not
have been <span data-x="LegacyPlatformObjectGetOwnProperty">invoked by Web IDL</span>.</p>
</li>
<li><p>If <var>elements</var> has only one element, and that element is an <code>iframe</code>
element, and that <code>iframe</code> element's <span>content navigable</span> is not null, then
return the <span data-x="nav-wp">active <code>WindowProxy</code></span> of the element's
<span>content navigable</span>.</p></li>
<li>
<p>Otherwise, if <var>elements</var> has only one element, return that element.</p>
</li>
<li>
<p>Otherwise, return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <span data-x="dom-document-namedItem-filter">named elements</span> with
the name <var>name</var>.</p> <!-- the same one each time is returned, because of the
rule under collections -->
</li>
<!--
Note that this named getter overrides built-in properties, as in:
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E%0D%0A...%3Ciframe%20name%3Dbody%3E%3C%2Fiframe%3E%3Cscript%3Ew(document.body)%3C%2Fscript%3E
This is what the "LegacyOverrideBuiltIns" bit means in the IDL.
-->
</ol>
<p><dfn data-x="dom-document-nameditem-filter">Named elements</dfn> with the name <var>name</var>, for the purposes of the above algorithm, are those that are either:</p>
<!-- KEEP THIS LIST IN SYNC WITH SUPPORTED PROPERTY VALUES ABOVE -->
<ul>
<li><span>Exposed</span> <code>embed</code>, <code>form</code>, <code>iframe</code>,
<code>img</code>, or <span>exposed</span> <code>object</code> elements that have a <code
data-x="">name</code> content attribute whose value is <var>name</var>, or</li>
<li><span>Exposed</span> <code>object</code> elements that have an <code
data-x="attr-id">id</code> content attribute whose value is <var>name</var>, or</li>
<li><code>img</code> elements that have an <code data-x="attr-id">id</code> content attribute
whose value is <var>name</var>, and that have a non-empty <code data-x="">name</code>
content attribute present also.</li>
</ul>
<p>An <code>embed</code> or <code>object</code> element is said to be <dfn>exposed</dfn> if it has
no <span>exposed</span> <code>object</code> ancestor, and, for <code>object</code> elements, is
additionally either not showing its <span>fallback content</span> or has no <code>object</code> or
<code>embed</code> descendants.</p>
</div>
<hr>
<p class="note">The <code data-x="dom-document-dir">dir</code> attribute on the
<code>Document</code> interface is defined along with the <code data-x="attr-dir">dir</code>
content attribute.</p>
<h3>Elements</h3>
<h4>Semantics</h4>
<p>Elements, attributes, and attribute values in HTML are defined (by this specification) to have
certain meanings (semantics). For example, the <code>ol</code> element represents an ordered list,
and the <code data-x="attr-lang">lang</code> attribute represents the language of the content.</p>
<p>These definitions allow HTML processors, such as web browsers or search engines, to present and
use documents and applications in a wide variety of contexts that the author might not have
considered.</p>
<div class="example">
<p>As a simple example, consider a web page written by an author who only considered desktop
computer web browsers:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<h1>Welcome to my page</h1>
<p>I like cars and lorries and have a big Jeep!</p>
<h2>Where I live</h2>
<p>I live in a small hut on a mountain!</p>
</body>
</html></code></pre>
<p>Because HTML conveys <em>meaning</em>, rather than presentation, the same
page can also be used by a small browser on a mobile phone, without any change to the page.
Instead of headings being in large letters as on the desktop, for example, the browser on the
mobile phone might use the same size text for the whole page, but with the headings in bold.</p>
<p>But it goes further than just differences in screen size: the same page could equally be used
by a blind user using a browser based around speech synthesis, which instead of displaying the
page on a screen, reads the page to the user, e.g. using headphones. Instead of large text for
the headings, the speech browser might use a different volume or a slower voice.</p>
<p>That's not all, either. Since the browsers know which parts of the page are the headings, they
can create a document outline that the user can use to quickly navigate around the document,
using keys for "jump to next heading" or "jump to previous heading". Such features are especially
common with speech browsers, where users would otherwise find quickly navigating a page quite
difficult.</p>
<p>Even beyond browsers, software can make use of this information. Search engines can use the
headings to more effectively index a page, or to provide quick links to subsections of the page
from their results. Tools can use the headings to create a table of contents (that is in fact how
this very specification's table of contents is generated).</p>
<p>This example has focused on headings, but the same principle applies to all of the semantics
in HTML.</p>
</div>
<p>Authors must not use elements, attributes, or attribute values for purposes other than their
appropriate intended semantic purpose, as doing so prevents software from correctly processing the
page.</p>
<div class="example">
<p>For example, the following snippet, intended to represent the heading of a
corporate site, is non-conforming because the second line is not intended to
be a heading of a subsection, but merely a subheading or subtitle (a
subordinate heading for the same section).</p>
<pre class="bad"><code class="html"><body>
<h1>ACME Corporation</h1>
<h2>The leaders in arbitrary fast delivery since 1920</h2>
...</code></pre>
<p>The <code>hgroup</code> element can be used for these kinds of situations:</p>
<pre><code class="html"><body>
<hgroup>
<h1>ACME Corporation</h1>
<p>The leaders in arbitrary fast delivery since 1920</p>
</hgroup>
...</code></pre>
</div>
<div class="example">
<p>The document in this next example is similarly non-conforming, despite
being syntactically correct, because the data placed in the cells is clearly
not tabular data, and the <code>cite</code> element mis-used:</p>
<pre class="bad" lang="en-GB"><code class="html"><!DOCTYPE HTML>
<html lang="en-GB">
<head> <title> Demonstration </title> </head>
<body>
<table>
<tr> <td> <!--en-GB-->My favourite animal is the cat. </td> </tr>
<tr>
<td>
—<a href="https://example.org/~ernest/"><cite>Ernest</cite></a>,
in an essay from 1992
</td>
</tr>
</table>
</body>
</html></code></pre>
<p>This would make software that relies on these semantics fail: for example,
a speech browser that allowed a blind user to navigate tables in the document
would report the quote above as a table, confusing the user; similarly, a
tool that extracted titles of works from pages would extract "Ernest" as the
title of a work, even though it's actually a person's name, not a title.</p>
<p>A corrected version of this document might be:</p>
<pre lang="en-GB"><code class="html"><!DOCTYPE HTML>
<html lang="en-GB">
<head> <title> Demonstration </title> </head>
<body>
<blockquote>
<p> <!--en-GB-->My favourite animal is the cat. </p>
</blockquote>
<p>
—<a href="https://example.org/~ernest/">Ernest</a>,
in an essay from 1992
</p>
</body>
</html></code></pre>
</div>
<p>Authors must not use elements, attributes, or attribute values that are not permitted by this
specification or <span>other applicable specifications</span>, as doing so makes it significantly
harder for the language to be extended in the future.</p>
<div class="example">
<p>In the next example, there is a non-conforming attribute value ("carpet") and a non-conforming
attribute ("texture"), which is not permitted by this specification:</p>
<pre class="bad"><code class="html"><label>Carpet: <input type="carpet" name="c" texture="deep pile"></label></code></pre>
<p>Here would be an alternative and correct way to mark this up:</p>
<pre><code class="html"><label>Carpet: <input type="text" class="carpet" name="c" data-texture="deep pile"></label></code></pre>
</div>
<p id="no-browsing-context">DOM nodes whose <span>node document</span>'s <span
data-x="concept-document-bc">browsing context</span> is null are exempt from all document
conformance requirements other than the <a href="#writing">HTML syntax</a> requirements and <a
href="#writing-xhtml-documents">XML syntax</a> requirements.</p>
<div class="example">
<p>In particular, the <code>template</code> element's <span>template contents</span>'s <span>node
document</span>'s <span data-x="concept-document-bc">browsing context</span> is null. For
example, the <span data-x="concept-element-content-model">content model</span> requirements and
attribute value microsyntax requirements do not apply to a <code>template</code> element's
<span>template contents</span>. In this example an <code>img</code> element has attribute values
that are placeholders that would be invalid outside a <code>template</code> element.</p>
<pre><code class="html"><template>
<article>
<img <mark>src="{{src}}" alt="{{alt}}"</mark>>
<h1></h1>
</article>
</template></code></pre>
<p>However, if the above markup were to omit the <code data-x=""></h1></code> end tag, that
would be a violation of the <a href="#writing">HTML syntax</a>, and would thus be flagged as an
error by conformance checkers.</p>
</div>
<p>Through scripting and using other mechanisms, the values of attributes, text, and indeed the
entire structure of the document may change dynamically while a user agent is processing it. The
semantics of a document at an instant in time are those represented by the state of the document
at that instant in time, and the semantics of a document can therefore change over time. User
agents <span w-nodev>must</span> update their presentation of the document as this
occurs.</p>
<p class="example">HTML has a <code>progress</code> element that describes a progress bar. If its
"value" attribute is dynamically updated by a script, the UA would update the rendering to show
the progress changing.</p>
<h4>Elements in the DOM</h4>
<p>The nodes representing <span>HTML elements</span> in the DOM <span w-nodev>must</span>
implement, and expose to scripts, the interfaces listed for them in the relevant sections of this
specification. This includes <span>HTML elements</span> in <span>XML documents</span>, even when
those documents are in another context (e.g. inside an XSLT transform).</p>
<p>Elements in the DOM <dfn data-x="represents">represent</dfn> things; that is, they have
intrinsic <em>meaning</em>, also known as semantics.</p>
<p class="example">For example, an <code>ol</code> element represents an ordered list.</p>
<p>Elements can be <dfn data-x="referenced">referenced</dfn> (referred to) in some way, either
explicitly or implicitly. One way that an element in the DOM can be explicitly referenced is by
giving an <code data-x="attr-id">id</code> attribute to the element, and then creating a
<span>hyperlink</span> with that <code data-x="attr-id">id</code> attribute's value as the <span
data-x="navigate-fragid">fragment</span> for the <span>hyperlink</span>'s <code
data-x="attr-hyperlink-href">href</code> attribute value. Hyperlinks are not necessary for a
reference, however; any manner of referring to the element in question will suffice.</p>
<div class="example">
<p>Consider the following <code>figure</code> element, which is given an <code
data-x="attr-id">id</code> attribute:</p>
<pre><code class="html"><figure id="module-script-graph">
<img src="module-script-graph.svg"
alt="Module A depends on module B, which depends
on modules C and D.">
<figcaption>Figure 27: a simple module graph</figcaption>
</figure></code></pre>
<p>A <span>hyperlink</span>-based <span data-x="referenced">reference</span> could be created
using the <code>a</code> element, like so:</p>
<pre><code class="html">As we can see in <a href="#module-script-graph">figure 27</a>, ...</code></pre>
<p>However, there are many other ways of <span data-x="referenced">referencing</span> the
<code>figure</code> element, such as:</p>
<ul>
<li><p>"As depicted in the figure of modules A, B, C, and D..."</p></li>
<li><p>"In Figure 27..." (without a hyperlink)</p></li>
<li><p>"From the contents of the 'simple module graph' figure..."</p></li>
<li><p>"In the figure below..." (but <a href="#figure-note-about-references">this is
discouraged</a>)</p></li>
</ul>
</div>
<p>The basic interface, from which all the <span>HTML elements</span>' interfaces inherit, <span
w-nodev>and which must be used by elements that have no additional requirements,</span> is
the <code>HTMLElement</code> interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLElement</dfn> : <span>Element</span> {
[<span>HTMLConstructor</span>] constructor();
// metadata attributes
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-title">title</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-lang">lang</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-translate">translate</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dir">dir</span>;
// <span>user interaction</span>
[<span>CEReactions</span>] attribute (boolean or unrestricted double or DOMString)? <span data-x="dom-hidden">hidden</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-inert">inert</span>;
undefined <span data-x="dom-click">click</span>();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-accessKey">accessKey</span>;
readonly attribute DOMString <span data-x="dom-accessKeyLabel">accessKeyLabel</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-draggable">draggable</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-spellcheck">spellcheck</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-writingSuggestions">writingSuggestions</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-autocapitalize">autocapitalize</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-autocorrect">autocorrect</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-innerText">innerText</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-outerText">outerText</span>;
<span>ElementInternals</span> <span data-x="dom-attachInternals">attachInternals</span>();
// The popover API
undefined <span data-x="dom-showPopover">showPopover</span>(optional <span>ShowPopoverOptions</span> options = {});
undefined <span data-x="dom-hidePopover">hidePopover</span>();
boolean <span data-x="dom-togglePopover">togglePopover</span>(optional (<span>TogglePopoverOptions</span> or boolean) options = {});
[<span>CEReactions</span>] attribute DOMString? <span data-x="dom-popover">popover</span>;
};
dictionary <dfn dictionary>ShowPopoverOptions</dfn> {
<span>HTMLElement</span> <dfn dict-member for="ShowPopoverOptions" data-x="dom-ShowPopoverOptions-source">source</dfn>;
};
dictionary <dfn dictionary>TogglePopoverOptions</dfn> : <span>ShowPopoverOptions</span> {
boolean <dfn dict-member for="TogglePopoverOptions" data-x="dom-TogglePopoverOptions-force">force</dfn>;
};
<span>HTMLElement</span> includes <span>GlobalEventHandlers</span>;
<span>HTMLElement</span> includes <span>ElementContentEditable</span>;
<span>HTMLElement</span> includes <span>HTMLOrSVGElement</span>;
[Exposed=Window]
interface <dfn interface>HTMLUnknownElement</dfn> : <span>HTMLElement</span> {
// Note: <a href="#customized-built-in-element-restrictions">intentionally</a> no [<span>HTMLConstructor</span>]
};</code></pre>
<p>The <code>HTMLElement</code> interface holds methods and attributes related to a number of
disparate features, and the members of this interface are therefore described in various different
sections of this specification.</p>
<div w-nodev>
<hr>
<p>The <span>element interface</span> for an element with name <var>name</var> in the
<span>HTML namespace</span> is determined as follows:</p>
<ol>
<li><p>If <var>name</var> is <code>applet</code>, <code>bgsound</code>, <code>blink</code>,
<code>isindex</code>, <code>keygen</code>, <code>multicol</code>, <code>nextid</code>, or
<code>spacer</code>, then return <code>HTMLUnknownElement</code>.</p></li>
<li><p>If <var>name</var> is <code>acronym</code>, <code>basefont</code>, <code>big</code>,
<code>center</code>, <code>nobr</code>, <code>noembed</code>, <code>noframes</code>,
<code>plaintext</code>, <code>rb</code>, <code>rtc</code>, <code>strike</code>, or
<code>tt</code>, then return <code>HTMLElement</code>.</p></li>
<li><p>If <var>name</var> is <code>listing</code> or <code>xmp</code>, then return
<code>HTMLPreElement</code>.</p></li>
<li><p>Otherwise, if this specification defines an interface appropriate for the <span>element
type</span> corresponding to the local name <var>name</var>, then return that interface.</p></li>
<li><p>If <span>other applicable specifications</span> define an appropriate interface for
<var>name</var>, then return the interface they define.</p></li>
<li><p>If <var>name</var> is a <span>valid custom element name</span>, then return
<code>HTMLElement</code>.</p>
<li><p>Return <code>HTMLUnknownElement</code>.</p></li>
</ol>
<p class="note">The use of <code>HTMLElement</code> instead of <code>HTMLUnknownElement</code> in
the case of <span data-x="valid custom element name">valid custom element names</span> is done to
ensure that any potential future <span data-x="custom-element-upgrades">upgrades</span> only cause
a linear transition of the element's prototype chain, from <code>HTMLElement</code> to a subclass,
instead of a lateral one, from <code>HTMLUnknownElement</code> to an unrelated subclass.</p>
<p>Features shared between HTML and SVG elements use the <code>HTMLOrSVGElement</code> interface
mixin: <ref>SVG</ref></p>
<pre><code class="idl">interface mixin <dfn interface>HTMLOrSVGElement</dfn> {
[SameObject] readonly attribute <span>DOMStringMap</span> <span data-x="dom-dataset">dataset</span>;
attribute DOMString <span data-x="dom-HTMLOrSVGElement-nonce">nonce</span>; // <a href="#nonce-does-not-update-dom">intentionally no [CEReactions]</a>
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fe-autofocus">autofocus</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-tabindex">tabIndex</span>;
undefined <span data-x="dom-focus">focus</span>(optional <span>FocusOptions</span> options = {});
undefined <span data-x="dom-blur">blur</span>();
};</code></pre>
</div>
<div class="example">
<p>An example of an element that is neither an HTML nor SVG element is one created as
follows:</p>
<pre><code class="html">const el = document.createElementNS("some namespace", "example");
console.assert(el.constructor === Element);</code></pre>
</div>
<div w-nodev>
<h4 id="html-element-constructors">HTML element constructors</h4>
<p>To support the <a href="#custom-elements">custom elements</a> feature, all HTML elements have
special constructor behavior. This is indicated via the <dfn extended-attribute
data-lt="HTMLConstructor" data-x="HTMLConstructor"><code>[HTMLConstructor]</code></dfn> IDL
<span>extended attribute</span>. It indicates that the interface object for the given interface
will have a specific behavior when called, as defined in detail below.</p>
<p>The <code data-x="HTMLConstructor">[HTMLConstructor]</code> extended attribute must take no
arguments, and must only appear on <span data-x="constructor operation">constructor
operations</span>. It must appear only once on a constructor operation, and the interface must
contain only the single, annotated constructor operation, and no others. The annotated
constructor operation must be declared to take no arguments.</p>
<p>Interfaces declared with constructor operations that are annotated with the <code
data-x="HTMLConstructor">[HTMLConstructor]</code> extended attribute have the following
<span>overridden constructor steps</span>:</p>
<ol>
<li><p>Let <var>registry</var> be <span>current global object</span>'s <span
data-x="global-custom-element-registry">custom element registry</span>.</p></li>
<li>
<p>If <span>NewTarget</span> is equal to the <span>active function
object</span>, then throw a <code>TypeError</code>.</p>
<div class="example">
<p>This can occur when a custom element is defined using an <span>element interface</span> as
its constructor:</p>
<pre><code class="js">customElements.define("bad-1", HTMLButtonElement);
new HTMLButtonElement(); // (1)
document.createElement("bad-1"); // (2)</code></pre>
<p>In this case, during the execution of <code>HTMLButtonElement</code> (either explicitly, as
in (1), or implicitly, as in (2)), both the <span>active function object</span> and
<span>NewTarget</span> are <code>HTMLButtonElement</code>. If this check was not present, it
would be possible to create an instance of <code>HTMLButtonElement</code> whose local name was
<code data-x="">bad-1</code>.</p>
</div>
</li>
<li>
<p>Let <var>definition</var> be the item in <var>registry</var>'s <span>custom element
definition set</span> with <span
data-x="concept-custom-element-definition-constructor">constructor</span> equal to
<span>NewTarget</span>. If there is no such item, then throw a <code>TypeError</code>.</p>
<p class="note">Since there can be no item in <var>registry</var>'s <span>custom element
definition set</span> with a <span
data-x="concept-custom-element-definition-constructor">constructor</span> of undefined, this
step also prevents HTML element constructors from being called as functions (since in that case
<span>NewTarget</span> will be undefined).</p>
</li>
<li><p>Let <var>isValue</var> be null.</p></li>
<li>
<p>If <var>definition</var>'s <span data-x="concept-custom-element-definition-local-name">local
name</span> is equal to <var>definition</var>'s <span
data-x="concept-custom-element-definition-name">name</span> (i.e., <var>definition</var> is for
an <span>autonomous custom element</span>):</p>
<ol>
<li>
<p>If the <span>active function object</span> is not <code>HTMLElement</code>, then throw a
<code>TypeError</code>.</p>
<div class="example">
<p>This can occur when a custom element is defined to not extend any local names, but
inherits from a non-<code>HTMLElement</code> class:</p>
<pre><code class="js">customElements.define("bad-2", class Bad2 extends HTMLParagraphElement {});</code></pre>
<p>In this case, during the (implicit) <code data-x="">super()</code> call that occurs when
constructing an instance of <code data-x="">Bad2</code>, the <span>active function
object</span> is <code>HTMLParagraphElement</code>, not <code>HTMLElement</code>.</p>
</div>
</li>
</ol>
</li>
<li>
<p>Otherwise (i.e., if <var>definition</var> is for a <span>customized built-in
element</span>):</p>
<ol>
<li><p>Let <var>valid local names</var> be the list of local names for elements defined in this
specification or in <span>other applicable specifications</span> that use the <span>active
function object</span> as their <span>element interface</span>.</p></li>
<li>
<p>If <var>valid local names</var> does not contain <var>definition</var>'s <span
data-x="concept-custom-element-definition-local-name">local name</span>, then throw a
<code>TypeError</code>.</p>
<div class="example">
<p>This can occur when a custom element is defined to extend a given local name but inherits
from the wrong class:</p>
<pre><code class="js">customElements.define("bad-3", class Bad3 extends HTMLQuoteElement {}, { extends: "p" });</code></pre>
<p>In this case, during the (implicit) <code data-x="">super()</code> call that occurs when
constructing an instance of <code data-x="">Bad3</code>, <var>valid local names</var> is the
list containing <code>q</code> and <code>blockquote</code>, but <var>definition</var>'s <span
data-x="concept-custom-element-definition-local-name">local name</span> is <code>p</code>,
which is not in that list.</p>
</div>
</li>
<li><p>Set <var>isValue</var> to <var>definition</var>'s <span
data-x="concept-custom-element-definition-name">name</span>.</p></li>
</ol>
</li>
<li>
<p>If <var>definition</var>'s <span
data-x="concept-custom-element-definition-construction-stack">construction stack</span> is
empty:</p>
<ol>
<li><p>Let <var>element</var> be the result of <span data-x="internally create a new object
implementing the interface">internally creating a new object implementing the interface</span>
to which the <span>active function object</span> corresponds, given the <span>current
realm</span> and <span>NewTarget</span>.</p></li>
<li><p>Set <var>element</var>'s <span>node document</span> to the <span>current global
object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-namespace">namespace</span> to
the <span>HTML namespace</span>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-namespace-prefix">namespace
prefix</span> to null.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-local-name">local name</span> to
<var>definition</var>'s <span data-x="concept-custom-element-definition-local-name">local
name</span>.</p></li>
<li><p>Set <var>element</var>'s <span>custom element state</span> to "<code
data-x="">custom</code>".</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-custom-element-definition">custom
element definition</span> to <var>definition</var>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-is-value"><code
data-x="">is</code> value</span> to <var>isValue</var>.</p></li>
<li><p>Return <var>element</var>.</p></li>
</ol>
<p class="note">This occurs when author script constructs a new custom element directly, e.g.
via <code data-x="">new MyCustomElement()</code>.</p>
</li>
<li><p>Let <var>prototype</var> be ? <span data-x="js-Get">Get</span>(<span>NewTarget</span>,
"prototype").</p></li>
<li>
<p>If <var>prototype</var> <span data-x="js-Object">is not an Object</span>, then:</p>
<ol>
<li><p>Let <var>realm</var> be ? <span>GetFunctionRealm</span>(<span>NewTarget</span>).</p></li>
<li><p>Set <var>prototype</var> to the <span>interface prototype object</span> of
<var>realm</var> whose interface is the same as the interface of the <span>active function
object</span>.</p></li>
</ol>
<p class="note">The realm of the <span>active function object</span> might not be
<var>realm</var>, so we are using the more general concept of "the same interface" across
realms; we are not looking for equality of <span data-x="interface object">interface
objects</span>. This fallback behavior, including using the realm of <span>NewTarget</span> and
looking up the appropriate prototype there, is designed to match analogous behavior for the
JavaScript built-ins and Web IDL's <span>internally create a new object implementing the
interface</span> algorithm.</p>
</li>
<li><p>Let <var>element</var> be the last entry in <var>definition</var>'s <span
data-x="concept-custom-element-definition-construction-stack">construction stack</span>.</li>
<li>
<p>If <var>element</var> is an <span data-x="concept-already-constructed-marker"><i>already
constructed</i> marker</span>, then throw a <code>TypeError</code>.</p>
<div class="example">
<p>This can occur when the author code inside the <span>custom element
constructor</span> <a href="#custom-element-conformance">non-conformantly</a> creates another
instance of the class being constructed, before calling <code
data-x="">super()</code>:</p>
<pre><code class="js">let doSillyThing = true;
class DontDoThis extends HTMLElement {
constructor() {
if (doSillyThing) {
doSillyThing = false;
new DontDoThis();
// Now the construction stack will contain an <i>already constructed</i> marker.
}
// This will then fail with a TypeError:
super();
}
}</code></pre>
</div>
<div class="example">
<p>This can also occur when author code inside the <span>custom element constructor</span> <a
href="#custom-element-conformance">non-conformantly</a> calls <code data-x="">super()</code>
twice, since per the JavaScript specification, this actually executes the superclass
constructor (i.e. this algorithm) twice, before throwing an error:
<pre><code class="js">class DontDoThisEither extends HTMLElement {
constructor() {
super();
// This will throw, but not until it has already called into the HTMLElement constructor
super();
}
}</code></pre>
</div>
</li>
<li><p>Perform ? <var>element</var>.[[SetPrototypeOf]](<var>prototype</var>).</p></li>
<li><p>Replace the last entry in <var>definition</var>'s <span
data-x="concept-custom-element-definition-construction-stack">construction stack</span> with an
<span data-x="concept-already-constructed-marker"><i>already constructed</i>
marker</span>.</p></li>
<li>
<p>Return <var>element</var>.</p>
<p class="note">This step is normally reached when <span
data-x="custom-element-upgrades">upgrading</span> a custom element; the existing element is
returned, so that the <code data-x="">super()</code> call inside the <span>custom element
constructor</span> assigns that existing element to <b>this</b>.</p>
</li>
</ol>
<hr>
<p>In addition to the constructor behavior implied by <code
data-x="HTMLConstructor">[HTMLConstructor]</code>, some elements also have <span data-x="named
constructor">named constructors</span> (which are really factory functions with a modified <code
data-x="">prototype</code> property).
<div class="example">
<p>Named constructors for HTML elements can also be used in an <code
data-x="dom-ElementDefinitionOptions-extends">extends</code> clause when defining a <span>custom
element constructor</span>:</p>
<pre><code class="js">class AutoEmbiggenedImage extends Image {
constructor(width, height) {
super(width * 10, height * 10);
}
}
customElements.define("auto-embiggened", AutoEmbiggenedImage, { extends: "img" });
const image = new AutoEmbiggenedImage(15, 20);
console.assert(image.width === 150);
console.assert(image.height === 200);</code></pre>
</div>
</div>
<h4>Element definitions</h4>
<p>Each element in this specification has a definition that includes the following
information:</p>
<dl>
<dt><dfn data-x="concept-element-categories">Categories</dfn></dt>
<dd><p>A list of <span data-x="content categories">categories</span> to which the element belongs.
These are used when defining the <span>content models</span> for each element.</p></dd>
<dt><dfn data-x="concept-element-contexts">Contexts in which this element can be used</dfn></dt>
<dd>
<p>A <em>non-normative</em> description of where the element can be used. This information is
redundant with the content models of elements that allow this one as a child, and is provided
only as a convenience.</p>
<div class="note">
<p>For simplicity, only the most specific expectations are listed.</p>
<p>For example, all <span>phrasing content</span> is <span>flow content</span>. Thus, elements
that are <span>phrasing content</span> will only be listed as "where <span>phrasing
content</span> is expected", since this is the more-specific expectation. Anywhere that expects
<span>flow content</span> also expects <span>phrasing content</span>, and thus also meets this
expectation.</p>
</div>
</dd>
<dt><dfn data-x="concept-element-content-model">Content model</dfn></dt>
<dd><p>A normative description of what content must be included as children and descendants of
the element.</p></dd>
<dt><dfn data-x="concept-element-tag-omission">Tag omission in text/html</dfn></dt>
<dd><p>A <em>non-normative</em> description of whether, in the <code>text/html</code> syntax, the
<span data-x="syntax-start-tag">start</span> and <span data-x="syntax-end-tag">end</span> tags can
be omitted. This information is redundant with the normative requirements given in the <span
data-x="syntax-tag-omission">optional tags</span> section, and is provided in the element
definitions only as a convenience.</p></dd>
<dt><dfn data-x="concept-element-attributes">Content attributes</dfn></dt>
<dd><p>A normative list of attributes that may be specified on the element (except where
otherwise disallowed), along with non-normative descriptions of those attributes. (The content to
the left of the dash is normative, the content to the right of the dash is not.)</p></dd>
<dt><dfn
data-x="concept-element-accessibility-considerations">Accessibility considerations</dfn></dt>
<dd>
<p>For authors: Conformance requirements for use of <cite>ARIA</cite> <code
data-x="attr-aria-role">role</code> and <code data-x="attr-aria-*">aria-*</code> attributes are
defined in <cite>ARIA in HTML</cite>. <ref>ARIA</ref> <ref>ARIAHTML</ref></p>
<p>For implementers: User agent requirements for implementing accessibility API semantics are
defined in <cite>HTML Accessibility API Mappings</cite>. <ref>HTMLAAM</ref></p>
</dd>
<dt><dfn data-x="concept-element-dom">DOM interface</dfn></dt>
<dd><p>A normative definition of a DOM interface that such elements must implement.</p></dd>
</dl>
<p>This is then followed by a description of what the element <span>represents</span>, along with
any additional normative conformance criteria that may apply to authors<span data-x=""
w-nodev> and implementations</span>. Examples are sometimes also included.</p>
<h5>Attributes</h5>
<p id="attribute-text">An attribute value is a string. Except where otherwise specified,
attribute values on <span>HTML elements</span> may be any string value, including the empty
string, and there is no restriction on what text can be specified in such attribute values.</p>
<h4><dfn>Content models</dfn></h4>
<p>Each element defined in this specification has a content model: a description of the element's
expected <span data-x="concept-html-contents">contents</span>. An <span data-x="HTML elements">HTML
element</span> must have contents that match the requirements described in the element's content
model. The <dfn data-x="concept-html-contents">contents</dfn> of an element are its children in the
DOM.</p>
<p><span>ASCII whitespace</span> is always allowed between elements. User agents represent these
characters between elements in the source markup as <code>Text</code> nodes in the DOM.<!-- not a
conf criteria since the parser now requires this --> Empty <code>Text</code> nodes and
<code>Text</code> nodes consisting of just sequences of those characters are considered
<dfn>inter-element whitespace</dfn>.</p>
<p><span>Inter-element whitespace</span>, comment nodes, and processing instruction nodes must be
ignored when establishing whether an element's contents match the element's content model or not,
and must be ignored when following algorithms that define document and element semantics.</p>
<p class="note">Thus, an element <var>A</var> is said to be <i>preceded or followed</i>
by a second element <var>B</var> if <var>A</var> and <var>B</var> have
the same parent node and there are no other element nodes or <code>Text</code> nodes (other than
<span>inter-element whitespace</span>) between them. Similarly, a node is the <i>only child</i> of
an element if that element contains no other nodes other than <span>inter-element
whitespace</span>, comment nodes, and processing instruction nodes.</p>
<p>Authors must not use <span>HTML elements</span> anywhere except where they are explicitly
allowed, as defined for each element, or as explicitly required by other specifications. For XML
compound documents, these contexts could be inside elements from other namespaces, if those
elements are defined as providing the relevant contexts.</p>
<p class="example"><cite>The Atom Syndication Format</cite> defines a <code
data-x="">content</code> element. When its <code data-x="">type</code> attribute has the value
<code data-x="">xhtml</code>, <cite>The Atom Syndication Format</cite> requires that it contain a
single HTML <code>div</code> element. Thus, a <code>div</code> element is allowed in that context,
even though this is not explicitly normatively stated by this specification. <ref>ATOM</ref></p>
<p>In addition, <span>HTML elements</span> may be orphan nodes (i.e. without a parent node).</p>
<div class="example">
<p>For example, creating a <code>td</code> element and storing it in a global variable in a
script is conforming, even though <code>td</code> elements are otherwise only supposed to be used
inside <code>tr</code> elements.</p>
<pre><code class="js">var data = {
name: "Banana",
cell: document.createElement('td'),
};</code></pre>
</div>
<h5>The "nothing" content model</h5>
<p>When an element's content model is <dfn data-x="concept-content-nothing">nothing</dfn>, the
element must contain no <code>Text</code> nodes (other than <span>inter-element whitespace</span>)
and no element nodes.</p>
<p class="note">Most HTML elements whose content model is "nothing" are also, for convenience,
<span>void elements</span> (elements that have no <span data-x="syntax-end-tag">end tag</span> in
the <a href="#syntax">HTML syntax</a>). However, these are entirely separate concepts.</p>
<h5>Kinds of content</h5>
<p>Each element in HTML falls into zero or more <dfn data-x="content categories">categories</dfn>
that group elements with similar characteristics together. The following broad categories are used
in this specification:</p>
<ul class="brief">
<li><span>Metadata content</span></li>
<li><span>Flow content</span></li>
<li><span>Sectioning content</span></li>
<li><span>Heading content</span></li>
<li><span>Phrasing content</span></li>
<li><span>Embedded content</span></li>
<li><span>Interactive content</span></li>
</ul>
<p class="note">Some elements also fall into other categories, which are defined in other parts of
this specification.</p>
<p>These categories are related as follows:</p>
<p><iframe width="1000" height="288" src="/images/content-venn.svg"></iframe></p>
<p>Sectioning content, heading content, phrasing content, embedded content, and interactive
content are all types of flow content. Metadata is sometimes flow content. Metadata and
interactive content are sometimes phrasing content. Embedded content is also a type of phrasing
content, and sometimes is interactive content.</p>
<p>Other categories are also used for specific purposes, e.g. form controls are specified using a
number of categories to define common requirements. Some elements have unique requirements and do
not fit into any particular category.</p>
<h6>Metadata content</h6>
<p><dfn export>Metadata content</dfn> is content that sets up the presentation or behavior of the
rest of the content, or that sets up the relationship of the document with other documents, or
that conveys other "out of band" information.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>base</code></li>
<li><code>link</code></li>
<li><code>meta</code></li>
<li><code>noscript</code></li>
<li><code>script</code></li>
<li><code>style</code></li>
<li><code>template</code></li>
<li><code>title</code></li>
</ul>
<p>Elements from other namespaces whose semantics are primarily metadata-related (e.g. RDF) are
also <span>metadata content</span>.</p>
<div class="example">
<p>Thus, in the XML serialization, one can use RDF, like this:</p>
<pre><code class="html"><html xmlns="http://www.w3.org/1999/xhtml"
xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xml:lang="en">
<head>
<title>Hedral's Home Page</title>
<r:RDF>
<Person xmlns="http://www.w3.org/2000/10/swap/pim/contact#"
r:about="https://hedral.example.com/#">
<fullName>Cat Hedral</fullName>
<mailbox r:resource="mailto:hedral@damowmow.com"/>
<personalTitle>Sir</personalTitle>
</Person>
</r:RDF>
</head>
<body>
<h1>My home page</h1>
<p>I like playing with string, I guess. Sister says squirrels are fun
too so sometimes I follow her to play with them.</p>
</body>
</html></code></pre>
<p>This isn't possible in the HTML serialization, however.</p>
</div>
<h6>Flow content</h6>
<p>Most elements that are used in the body of documents and applications are categorized as
<dfn export>flow content</dfn>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>a</code></li>
<li><code>abbr</code></li>
<li><code>address</code></li>
<li><code>area</code> (if it is a descendant of a <code>map</code> element)</li>
<li><code>article</code></li>
<li><code>aside</code></li>
<li><code>audio</code></li>
<li><code>b</code></li>
<li><code>bdi</code></li>
<li><code>bdo</code></li>
<li><code>blockquote</code></li>
<li><code>br</code></li>
<li><code>button</code></li>
<li><code>canvas</code></li>
<li><code>cite</code></li>
<li><code>code</code></li>
<li><code>data</code></li>
<li><code>datalist</code></li>
<li><code>del</code></li>
<li><code>details</code></li>
<li><code>dfn</code></li>
<li><code>dialog</code></li>
<li><code>div</code></li>
<li><code>dl</code></li>
<li><code>em</code></li>
<li><code>embed</code></li>
<li><code>fieldset</code></li>
<li><code>figure</code></li>
<li><code>footer</code></li>
<li><code>form</code></li>
<li><code>h1</code></li>
<li><code>h2</code></li>
<li><code>h3</code></li>
<li><code>h4</code></li>
<li><code>h5</code></li>
<li><code>h6</code></li>
<li><code>header</code></li>
<li><code>hgroup</code></li>
<li><code>hr</code></li>
<li><code>i</code></li>
<li><code>iframe</code></li>
<li><code>img</code></li>
<li><code>input</code></li>
<li><code>ins</code></li>
<li><code>kbd</code></li>
<li><code>label</code></li>
<li><code>link</code> (if it is <span>allowed in the body</span>)</li>
<li><code>main</code> (if it is a <span>hierarchically correct <code>main</code> element</span>)</li>
<li><code>map</code></li>
<li><code>mark</code></li>
<li><span>MathML <code>math</code></span></li>
<li><code>menu</code></li>
<li><code>meta</code> (if the <code data-x="attr-itemprop">itemprop</code> attribute is present)</li>
<li><code>meter</code></li>
<li><code>nav</code></li>
<li><code>noscript</code></li>
<li><code>object</code></li>
<li><code>ol</code></li>
<li><code>output</code></li>
<li><code>p</code></li>
<li><code>picture</code></li>
<li><code>pre</code></li>
<li><code>progress</code></li>
<li><code>q</code></li>
<li><code>ruby</code></li>
<li><code>s</code></li>
<li><code>samp</code></li>
<li><code>script</code></li>
<li><code>search</code></li>
<li><code>section</code></li>
<li><code>select</code></li>
<li><code>slot</code></li>
<li><code>small</code></li>
<li><code>span</code></li>
<li><code>strong</code></li>
<li><code>sub</code></li>
<li><code>sup</code></li>
<li><span>SVG <code>svg</code></span></li>
<li><code>table</code></li>
<li><code>template</code></li>
<li><code>textarea</code></li>
<li><code>time</code></li>
<li><code>u</code></li>
<li><code>ul</code></li>
<li><code>var</code></li>
<li><code>video</code></li>
<li><code>wbr</code></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">text</span></li>
</ul>
<h6>Sectioning content</h6>
<p><dfn export>Sectioning content</dfn> is content that defines the scope of <code>header</code>
and <code>footer</code> elements.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>article</code></li>
<li><code>aside</code></li>
<li><code>nav</code></li>
<li><code>section</code></li>
</ul>
<h6>Heading content</h6>
<p><dfn export>Heading content</dfn> defines the heading of a section (whether explicitly marked
up using <span>sectioning content</span> elements, or implied by the heading content itself).</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>h1</code></li>
<li><code>h2</code></li>
<li><code>h3</code></li>
<li><code>h4</code></li>
<li><code>h5</code></li>
<li><code>h6</code></li>
<li><code>hgroup</code> (if it has a descendant <code>h1</code> to <code>h6</code> element)</li>
</ul>
<h6>Phrasing content</h6>
<p><dfn export>Phrasing content</dfn> is the text of the document, as well as elements that mark
up that text at the intra-paragraph level. Runs of <span>phrasing content</span> form <span
data-x="paragraph">paragraphs</span>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>a</code></li>
<li><code>abbr</code></li>
<li><code>area</code> (if it is a descendant of a <code>map</code> element)</li>
<li><code>audio</code></li>
<li><code>b</code></li>
<li><code>bdi</code></li>
<li><code>bdo</code></li>
<li><code>br</code></li>
<li><code>button</code></li>
<li><code>canvas</code></li>
<li><code>cite</code></li>
<li><code>code</code></li>
<li><code>data</code></li>
<li><code>datalist</code></li>
<li><code>del</code></li>
<li><code>dfn</code></li>
<li><code>em</code></li>
<li><code>embed</code></li>
<li><code>i</code></li>
<li><code>iframe</code></li>
<li><code>img</code></li>
<li><code>input</code></li>
<li><code>ins</code></li>
<li><code>kbd</code></li>
<li><code>label</code></li>
<li><code>link</code> (if it is <span>allowed in the body</span>)</li>
<li><code>map</code></li>
<li><code>mark</code></li>
<li><span>MathML <code>math</code></span></li>
<li><code>meta</code> (if the <code data-x="attr-itemprop">itemprop</code> attribute is present)</li>
<li><code>meter</code></li>
<li><code>noscript</code></li>
<li><code>object</code></li>
<li><code>output</code></li>
<li><code>picture</code></li>
<li><code>progress</code></li>
<li><code>q</code></li>
<li><code>ruby</code></li>
<li><code>s</code></li>
<li><code>samp</code></li>
<li><code>script</code></li>
<li><code>select</code></li>
<li><code>slot</code></li>
<li><code>small</code></li>
<li><code>span</code></li>
<li><code>strong</code></li>
<li><code>sub</code></li>
<li><code>sup</code></li>
<li><span>SVG <code>svg</code></span></li>
<li><code>template</code></li>
<li><code>textarea</code></li>
<li><code>time</code></li>
<li><code>u</code></li>
<li><code>var</code></li>
<li><code>video</code></li>
<li><code>wbr</code></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">text</span></li>
</ul>
<p class="note">Most elements that are categorized as phrasing content can only contain elements
that are themselves categorized as phrasing content, not any flow content.</p>
<p><dfn data-x="text content">Text</dfn>, in the context of content models, means either nothing,
or <code>Text</code> nodes. <span data-x="text content">Text</span> is sometimes used as a content
model on its own, but is also <span>phrasing content</span>, and can be <span>inter-element
whitespace</span> (if the <code>Text</code> nodes are empty or contain just <span>ASCII
whitespace</span>).</p>
<p><code>Text</code> nodes and attribute values must consist of <span data-x="scalar value">scalar
values</span>, excluding <span data-x="noncharacter">noncharacters</span>, and <span
data-x="control">controls</span> other than <span>ASCII whitespace</span>.
<!--<code>Text</code> nodes and attribute values may begin with an <i>isolated combining
character</i>.--> <!-- commented out since nothing disallows it currently, so it's implicit;
however, if we ever make charmod a normative reference, this will be needed to override it -->
<!-- see also https://www.w3.org/Bugs/Public/show_bug.cgi?id=13502#c22 -->
This specification includes extra constraints on the exact value of <code>Text</code> nodes and
attribute values depending on their precise context.
<!-- <ref>UNICODE</ref>-->
</p>
<h6>Embedded content</h6>
<p><dfn id="embedded-content-category" export>Embedded content</dfn> is content that imports
another resource into the document, or content from another vocabulary that
is inserted into the document.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>audio</code></li>
<li><code>canvas</code></li>
<li><code>embed</code></li>
<li><code>iframe</code></li>
<li><code>img</code></li>
<li><span>MathML <code>math</code></span></li>
<li><code>object</code></li>
<li><code>picture</code></li>
<li><span>SVG <code>svg</code></span></li>
<li><code>video</code></li>
</ul>
<p>Elements that are from namespaces other than the <span>HTML namespace</span> and that convey
content but not metadata, are <span>embedded content</span> for the purposes of the content models
defined in this specification. (For example, MathML or SVG.)</p>
<p>Some embedded content elements can have <dfn>fallback content</dfn>: content that is to be used
when the external resource cannot be used (e.g. because it is of an unsupported format). The
element definitions state what the fallback is, if any.</p>
<!-- we might not need to define fallback content at all. consider removing it if we don't end up
using it anywhere (e.g. Selection) -->
<h6>Interactive content</h6>
<!--
TESTS:
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cp%20tabindex%3D1%3Etest%20%3Ca%20href%3D%22%22%3E%20%3Cem%3Etest%3C/em%3E%20%3C/a%3E%0A%3Cscript%3E%0A%20function%20test%20%28e%29%20%7B%20w%28e.type%20+%20%27%20on%20%27%20+%20e.target.tagName%20+%20%27%20through%20%27%20+%20e.currentTarget.tagName%29%3B%20%7D%0A%20document.getElementsByTagName%28%27a%27%29%5B0%5D.addEventListener%28%27click%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27a%27%29%5B0%5D.addEventListener%28%27DOMActivate%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27p%27%29%5B0%5D.addEventListener%28%27click%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27p%27%29%5B0%5D.addEventListener%28%27DOMActivate%27%2C%20test%2C%20false%29%3B%0A%3C/script%3E%0A
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Ca%20href%3Dhttp%3A//google.com/%20target%3Da%3EA%3C/a%3E%3Ca%20href%3Dhttp%3A//yahoo.com/%20target%3Db%3EB%3C/a%3E%3Cbr%3E%0A%3Ciframe%20name%3Da%3E%3C/iframe%3E%3Ciframe%20name%3Db%3E%3C/iframe%3E%0A%3Cscript%3E%0A%20var%20a%20%3D%20document.getElementsByTagName%28%27a%27%29%5B0%5D%3B%0A%20var%20b%20%3D%20document.getElementsByTagName%28%27a%27%29%5B1%5D%3B%0A%20a.appendChild%28b%29%3B%0A%3C/script%3E
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Cform%20action%3D%22http%3A//google.com/%22%20onsubmit%3D%22w%28%27onsubmit%27%29%22%3E%3Cem%3EA%3C/em%3E%3C/form%3E%0A%3Cscript%3E%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.attachEvent%28%27onsubmit%27%2C%20function%20%28%29%20%7B%20w%28%27submit%20fired%27%29%20%7D%29%3B%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.fireEvent%28%27onsubmit%27%29%3B%0A%3C/script%3E
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Cform%20action%3D%22http%3A//google.com/%22%3EX%3C/form%3E%0A%3Cscript%3E%0Avar%20evt%20%3D%20document.createEvent%28%22Events%22%29%3B%0Aevt.initEvent%28%22submit%22%2C%20true%2C%20true%29%3B%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.dispatchEvent%28evt%29%3B%0A%3C/script%3E
-->
<p><dfn export>Interactive content</dfn> is content that is specifically intended for user
interaction.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>a</code> (if the <code data-x="attr-hyperlink-href">href</code> attribute is present)</li>
<li><code>audio</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present)</li>
<li><code>button</code></li>
<li><code>details</code></li>
<li><code>embed</code></li>
<li><code>iframe</code></li>
<li><code>img</code> (if the <code data-x="attr-hyperlink-usemap">usemap</code> attribute is present)</li>
<li><code>input</code> (if the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state)</li>
<li><code>label</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><code>video</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present)</li>
</ul>
<h6 id="palpable-content">Palpable content</h6>
<p>As a general rule, elements whose content model allows any <span>flow content</span> or
<span>phrasing content</span> should have at least one node in its <span
data-x="concept-html-contents">contents</span> that is <dfn export>palpable content</dfn> and
that does not have the <code data-x="attr-hidden">hidden</code> attribute specified.</p>
<p class="note"><span>Palpable content</span> makes an element non-empty by providing either
some descendant non-empty <span data-x="text content">text</span>, or else something users can
hear (<code>audio</code> elements) or view (<code>video</code>, <code>img</code>, or
<code>canvas</code> elements) or otherwise interact with (for example, interactive form
controls).</p>
<p>This requirement is not a hard requirement, however, as there are many cases where an element
can be empty legitimately, for example when it is used as a placeholder which will later be filled
in by a script, or when the element is part of a template and would on most pages be filled in but
on some pages is not relevant.</p>
<p>Conformance checkers are encouraged to provide a mechanism for authors to find elements that
fail to fulfill this requirement, as an authoring aid.</p>
<p>The following elements are palpable content:</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>a</code></li>
<li><code>abbr</code></li>
<li><code>address</code></li>
<li><code>article</code></li>
<li><code>aside</code></li>
<li><code>audio</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present)</li>
<li><code>b</code></li>
<li><code>bdi</code></li>
<li><code>bdo</code></li>
<li><code>blockquote</code></li>
<li><code>button</code></li>
<li><code>canvas</code></li>
<li><code>cite</code></li>
<li><code>code</code></li>
<li><code>data</code></li>
<li><code>del</code></li>
<li><code>details</code></li>
<li><code>dfn</code></li>
<li><code>div</code></li>
<li><code>dl</code> (if the element's children include at least one name-value group)</li>
<li><code>em</code></li>
<li><code>embed</code></li>
<li><code>fieldset</code></li>
<li><code>figure</code></li>
<li><code>footer</code></li>
<li><code>form</code></li>
<li><code>h1</code></li>
<li><code>h2</code></li>
<li><code>h3</code></li>
<li><code>h4</code></li>
<li><code>h5</code></li>
<li><code>h6</code></li>
<li><code>header</code></li>
<li><code>hgroup</code></li>
<li><code>i</code></li>
<li><code>iframe</code></li>
<li><code>img</code></li>
<li><code>input</code> (if the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state)</li>
<li><code>ins</code></li>
<li><code>kbd</code></li>
<li><code>label</code></li>
<li><code>main</code></li>
<li><code>map</code></li>
<li><code>mark</code></li>
<li><span>MathML <code>math</code></span></li>
<li><code>menu</code> (if the element's children include at least one <code>li</code> element)</li>
<li><code>meter</code></li>
<li><code>nav</code></li>
<li><code>object</code></li>
<li><code>ol</code> (if the element's children include at least one <code>li</code> element)</li>
<li><code>output</code></li>
<li><code>p</code></li>
<li><code>picture</code></li>
<li><code>pre</code></li>
<li><code>progress</code></li>
<li><code>q</code></li>
<li><code>ruby</code></li>
<li><code>s</code></li>
<li><code>samp</code></li>
<li><code>search</code></li>
<li><code>section</code></li>
<li><code>select</code></li>
<li><code>small</code></li>
<li><code>span</code></li>
<li><code>strong</code></li>
<li><code>sub</code></li>
<li><code>sup</code></li>
<li><span>SVG <code>svg</code></span></li>
<li><code>table</code></li>
<li><code>textarea</code></li>
<li><code>time</code></li>
<li><code>u</code></li>
<li><code>ul</code> (if the element's children include at least one <code>li</code> element)</li>
<li><code>var</code></li>
<li><code>video</code></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">text</span> that is not <span>inter-element whitespace</span></li>
</ul>
<h6>Script-supporting elements</h6>
<p><dfn>Script-supporting elements</dfn> are those that do not <span
data-x="represents">represent</span> anything themselves (i.e. they are not rendered), but are
used to support scripts, e.g. to provide functionality for the user.</p>
<p>The following elements are script-supporting elements:</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>script</code></li>
<li><code>template</code></li>
</ul>
<h5>Transparent content models</h5>
<p>Some elements are described as <dfn>transparent</dfn>; they have "transparent" in the
description of their content model. The content model of a <span>transparent</span> element is
derived from the content model of its parent element: the elements required in the part of the
content model that is "transparent" are the same elements as required in the part of the content
model of the parent of the transparent element in which the transparent element finds itself.</p>
<div class="example">
<p>For instance, an <code>ins</code> element inside a <code>ruby</code> element cannot contain an
<code>rt</code> element, because the part of the <code>ruby</code> element's content model that
allows <code>ins</code> elements is the part that allows <span>phrasing content</span>, and the
<code>rt</code> element is not <span>phrasing content</span>.</p>
</div>
<!--(as far as I can tell, there's no way to violate this requirement
without first violating the earlier requirement)
<p>Furthermore, when a content model includes a part that is "transparent", those parts must not
contain content that would not be conformant if all transparent elements in the tree were
replaced, in their parent element, by the <span data-x="concept-html-contents">contents</span> in
the "transparent" part of their content model, retaining order.</p>
<div class="example">
<p>Consider the following markup fragment:</p>
<pre><code class="html"><p>Hello <a href="world.html"><em>wonderful</em> world</a>!</p></code></pre>
<p>Its DOM looks like the following:</p>
<ul class="domTree"><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">Hello </span></li><li class="t1"><code>a</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-hyperlink-href">href</code>="<code class="attribute value" data-x="">world.html</code>"</span><ul><li class="t1"><code>em</code><ul><li class="t3"><code>#text</code>: <span data-x="">wonderful</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x=""> world</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">!</span></li></ul></li></ul>
<p>The content model of the <code>a</code> element is <span>transparent</span>. To see if its
contents are conforming, therefore, the element is replaced by its contents:</p>
<ul class="domTree"><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">Hello </span></li><li class="t1"><code>em</code><ul><li class="t3"><code>#text</code>: <span data-x="">wonderful</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x=""> world</span></li><li class="t3"><code>#text</code>: <span data-x="">!</span></li></ul></li></ul>
<p>Since that is conforming, the contents of the <code>a</code> are conforming in the original
fragment (there is no complication regarding the various parts of the <code>p</code> element's
content model, since that element's content model has only one part).</p>
</div>
-->
<p class="note">In some cases, where transparent elements are nested in each other, the process
has to be applied iteratively.</p>
<div class="example">
<p>Consider the following markup fragment:</p>
<pre><code class="html"><p><object><ins><map><a href="/">Apples</a></map></ins></object></p></code></pre>
<p>To check whether "Apples" is allowed inside the <code>a</code> element, the content models are
examined. The <code>a</code> element's content model is transparent, as is the <code>map</code>
element's, as is the <code>ins</code> element's, as is the <code>object</code> element's. The
<code>object</code> element is found in the <code>p</code> element, whose content model is
<span>phrasing content</span>. Thus, "Apples" is allowed, as text is phrasing content.</p>
</div>
<p>When a transparent element has no parent, then the part of its content model that is
"transparent" must instead be treated as accepting any <span>flow content</span>.</p>
<h5>Paragraphs</h5>
<p class="note">The term <span>paragraph</span> as defined in this section is used for more than
just the definition of the <code>p</code> element. The <span>paragraph</span> concept defined here
is used to describe how to interpret documents. The <code>p</code> element is merely one of
several ways of marking up a <span>paragraph</span>.</p>
<!-- note: the actual definition is below -->
<p>A <dfn>paragraph</dfn> is typically a run of <span>phrasing content</span> that forms a block
of text with one or more sentences that discuss a particular topic, as in typography, but can also
be used for more general thematic grouping. For instance, an address is also a paragraph, as is a
part of a form, a byline, or a stanza in a poem.</p>
<div class="example">
<p>In the following example, there are two paragraphs in a section. There is also a heading,
which contains phrasing content that is not a paragraph. Note how the comments and
<span>inter-element whitespace</span> do not form paragraphs.</p>
<pre><code class="html"><section>
<h2>Example of paragraphs</h2>
This is the <em>first</em> paragraph in this example.
<p>This is the second.</p>
<!-- This is not a paragraph. -->
</section></code></pre>
</div>
<p>Paragraphs in <span>flow content</span> are defined relative to what the document looks like
without the <code>a</code>, <code>ins</code>, <code>del</code>, and <code>map</code> elements
complicating matters, since those elements, with their hybrid content models, can straddle
paragraph boundaries, as shown in the first two examples below.</p>
<p class="note">Generally, having elements straddle paragraph boundaries is best avoided.
Maintaining such markup can be difficult.</p>
<div class="example">
<p>The following example takes the markup from the earlier example and puts <code>ins</code> and
<code>del</code> elements around some of the markup to show that the text was changed (though in
this case, the changes admittedly don't make much sense). Notice how this example has exactly the
same paragraphs as the previous one, despite the <code>ins</code> and <code>del</code> elements
— the <code>ins</code> element straddles the heading and the first paragraph, and the
<code>del</code> element straddles the boundary between the two paragraphs.</p>
<pre><code class="html"><section>
<ins><h2>Example of paragraphs</h2>
This is the <em>first</em> paragraph in</ins> this example<del>.
<p>This is the second.</p></del>
<!-- This is not a paragraph. -->
</section></code></pre>
</div>
<div w-nodev>
<p>Let <var>view</var> be a view of the DOM that replaces all <code>a</code>,
<code>ins</code>, <code>del</code>, and <code>map</code> elements in the document with their <span
data-x="concept-html-contents">contents</span>. Then, in <var>view</var>, for each run
of sibling <span>phrasing content</span> nodes uninterrupted by other types of content, in an
element that accepts content other than <span>phrasing content</span> as well as <span>phrasing
content</span>, let <var>first</var> be the first node of the run, and let <var>last</var> be the last node of the run. For each such run that consists of at least one
node that is neither <span>embedded content</span> nor <span>inter-element whitespace</span>, a
paragraph exists in the original DOM from immediately before <var>first</var> to
immediately after <var>last</var>. (Paragraphs can thus span across <code>a</code>,
<code>ins</code>, <code>del</code>, and <code>map</code> elements.)</p>
<p>Conformance checkers may warn authors of cases where they have paragraphs that overlap each
other (this can happen with <code>object</code>, <code>video</code>, <code>audio</code>, and
<code>canvas</code> elements, and indirectly through elements in other namespaces that allow HTML
to be further embedded therein, like <span>SVG <code>svg</code></span> or <span>MathML
<code>math</code></span>).</p>
<!-- example below -->
</div>
<p>A <span>paragraph</span> is also formed explicitly by <code>p</code> elements.</p>
<p class="note">The <code>p</code> element can be used to wrap individual paragraphs when there
would otherwise not be any content other than phrasing content to separate the paragraphs from
each other.</p>
<div class="example">
<p>In the following example, the link spans half of the first paragraph, all of the heading
separating the two paragraphs, and half of the second paragraph. It straddles the paragraphs and
the heading.</p>
<pre><code class="html"><header>
Welcome!
<a href="about.html">
This is home of...
<h1>The Falcons!</h1>
The Lockheed Martin multirole jet fighter aircraft!
</a>
This page discusses the F-16 Fighting Falcon's innermost secrets.
</header></code></pre>
<p>Here is another way of marking this up, this time showing the paragraphs explicitly, and
splitting the one link element into three:</p>
<pre><code class="html"><header>
<p>Welcome! <a href="about.html">This is home of...</a></p>
<h1><a href="about.html">The Falcons!</a></h1>
<p><a href="about.html">The Lockheed Martin multirole jet
fighter aircraft!</a> This page discusses the F-16 Fighting
Falcon's innermost secrets.</p>
</header></code></pre>
</div>
<div class="example">
<!-- I don't know if there's a better way to deal with this, but if there is, let me know... -->
<p>It is possible for paragraphs to overlap when using certain elements that define fallback
content. For example, in the following section:</p>
<pre><code class="html"><section>
<h2>My Cats</h2>
You can play with my cat simulator.
<object data="cats.sim">
To see the cat simulator, use one of the following links:
<ul>
<li><a href="cats.sim">Download simulator file</a>
<li><a href="https://sims.example.com/watch?v=LYds5xY4INU">Use online simulator</a>
</ul>
Alternatively, upgrade to the Mellblom Browser.
</object>
I'm quite proud of it.
</section></code></pre>
<p>There are five paragraphs:</p>
<ol class="brief">
<li>The paragraph that says "You can play with my cat simulator. <i>object</i> I'm
quite proud of it.", where <i>object</i> is the <code>object</code> element.</li>
<li>The paragraph that says "To see the cat simulator, use one of the following links:".</li>
<li>The paragraph that says "Download simulator file".</li>
<li>The paragraph that says "Use online simulator".</li>
<li>The paragraph that says "Alternatively, upgrade to the Mellblom Browser.".</li>
</ol>
<p>The first paragraph is overlapped by the other four. A user agent that supports the "cats.sim"
resource will only show the first one, but a user agent that shows the fallback will confusingly
show the first sentence of the first paragraph as if it was in the same paragraph as the second
one, and will show the last paragraph as if it was at the start of the second sentence of the
first paragraph.</p>
<p>To avoid this confusion, explicit <code>p</code> elements can be used. For example:</p>
<!-- My Fish -->
<pre><code class="html"><section>
<h2>My Cats</h2>
<p>You can play with my cat simulator.</p>
<object data="cats.sim">
<p>To see the cat simulator, use one of the following links:</p>
<ul>
<li><a href="cats.sim">Download simulator file</a>
<li><a href="https://sims.example.com/watch?v=LYds5xY4INU">Use online simulator</a>
</ul>
<p>Alternatively, upgrade to the Mellblom Browser.</p>
</object>
<p>I'm quite proud of it.</p>
</section></code></pre>
</div>
<h4><dfn>Global attributes</dfn></h4>
<p>The following attributes are common to and may be specified on all <span>HTML
elements</span><span w-nodev> (even those not defined in this specification)</span>:</p>
<ul class="brief">
<li><code data-x="attr-accesskey">accesskey</code></li>
<li><code data-x="attr-autocapitalize">autocapitalize</code></li>
<li><code data-x="attr-autocorrect">autocorrect</code></li>
<li><code data-x="attr-fe-autofocus">autofocus</code></li>
<li><code data-x="attr-contenteditable">contenteditable</code></li>
<li><code data-x="attr-dir">dir</code></li>
<li><code data-x="attr-draggable">draggable</code></li>
<li><code data-x="attr-enterkeyhint">enterkeyhint</code></li>
<li><code data-x="attr-hidden">hidden</code></li>
<li><code data-x="attr-inert">inert</code></li>
<li><code data-x="attr-inputmode">inputmode</code></li>
<li><code data-x="attr-is">is</code></li>
<li><code data-x="attr-itemid">itemid</code></li>
<li><code data-x="attr-itemprop">itemprop</code></li>
<li><code data-x="attr-itemref">itemref</code></li>
<li><code data-x="attr-itemscope">itemscope</code></li>
<li><code data-x="attr-itemtype">itemtype</code></li>
<li><code data-x="attr-lang">lang</code></li>
<li><code data-x="attr-nonce">nonce</code></li>
<li><code data-x="attr-popover">popover</code></li>
<li><code data-x="attr-spellcheck">spellcheck</code></li>
<li><code data-x="attr-style">style</code></li>
<li><code data-x="attr-tabindex">tabindex</code></li>
<li><code data-x="attr-title">title</code></li>
<li><code data-x="attr-translate">translate</code></li>
<li><code data-x="attr-writingsuggestions">writingsuggestions</code></li>
</ul>
<div w-nodev>
<p>These attributes are only defined by this specification as attributes for <span>HTML
elements</span>. When this specification refers to elements having these attributes, elements from
namespaces that are not defined as having these attributes must not be considered as being
elements with these attributes.</p>
<div class="example">
<p>For example, in the following XML fragment, the "<code data-x="">bogus</code>" element does not
have a <code data-x="attr-dir">dir</code> attribute as defined in this specification, despite
having an attribute with the literal name "<code data-x="">dir</code>". Thus, <span>the
directionality</span> of the inner-most <code>span</code> element is '<span
data-x="concept-rtl">rtl</span>', inherited from the <code>div</code> element indirectly through
the "<code data-x="">bogus</code>" element.</p>
<pre class="bad"><code class="html"><div xmlns="http://www.w3.org/1999/xhtml" dir="rtl">
<bogus xmlns="https://example.net/ns" dir="ltr">
<span xmlns="http://www.w3.org/1999/xhtml">
</span>
</bogus>
</div></code></pre>
</div>
</div>
<hr>
<p><cite>DOM</cite> defines the user agent requirements for the <dfn element-attr for="global"
data-x="attr-class" id="classes"><code>class</code></dfn>, <dfn element-attr for="global"
data-x="attr-id" id="the-id-attribute"><code>id</code></dfn>, and <dfn element-attr for="global"
data-x="attr-slot"><code>slot</code></dfn> attributes for any element in any namespace.
<ref>DOM</ref></p>
<p>The <code data-x="attr-class">class</code>, <code data-x="attr-id">id</code>, and <code
data-x="attr-slot">slot</code> attributes may be specified on all <span>HTML elements</span>.</p>
<p>When specified on <span>HTML elements</span>, the <code data-x="attr-class">class</code>
attribute must have a value that is a <span>set of space-separated tokens</span> representing the
various classes that the element belongs to.</p>
<div class="note">
<p>Assigning classes to an element affects class matching in selectors in CSS, the <code
data-x="dom-document-getElementsByClassName">getElementsByClassName()</code> method in the DOM,
and other such features.</p>
<p>There are no additional restrictions on the tokens authors can use in the <code
data-x="attr-class">class</code> attribute, but authors are encouraged to use values that describe
the nature of the content, rather than values that describe the desired presentation of the
content.</p>
</div>
<p>When specified on <span>HTML elements</span>, the <code data-x="attr-id">id</code> attribute
value must be unique amongst all the <span data-x="concept-id">IDs</span> in the element's
<span>tree</span> and must contain at least one character. The value must not contain any
<span>ASCII whitespace</span>.</p>
<!-- ASCII whitespace is disallowed because space-separated lists of IDs otherwise would not be
able to reach all valid IDs -->
<div class="note">
<p>The <code data-x="attr-id">id</code> attribute specifies its element's <span
data-x="concept-id">unique identifier (ID)</span>.</p>
<p>There are no other restrictions on what form an ID can take; in particular, IDs can consist of
just digits, start with a digit, start with an underscore, consist of just punctuation, etc.</p>
<p>An element's <span data-x="concept-id">unique identifier</span> can be used for a variety of
purposes, most notably as a way to link to specific parts of a document using <span
data-x="concept-url-fragment">fragments</span>, as a way to target an element when scripting, and
as a way to style a specific element from CSS.</p>
</div>
<div w-nodev>
<p>Identifiers are opaque strings. Particular meanings should not be derived from the value of the
<code data-x="attr-id">id</code> attribute.</p>
</div>
<p>There are no conformance requirements for the <code data-x="attr-slot">slot</code> attribute
specific to <span>HTML elements</span>.</p>
<p class="note">The <code data-x="attr-slot">slot</code> attribute is used to <span>assign a
slot</span> to an element: an element with a <code data-x="attr-slot">slot</code> attribute is
<span data-x="assign a slot">assigned</span> to the <span data-x="concept-slot">slot</span>
created by the <code>slot</code> element whose <span data-x="attr-slot-name">name</span>
attribute's value matches that <code data-x="attr-slot">slot</code> attribute's value — but only
if that <code>slot</code> element finds itself in the <span>shadow tree</span> whose
<span>root</span>'s <span data-x="concept-DocumentFragment-host">host</span> has the corresponding
<code data-x="attr-slot">slot</code> attribute value.</p>
<hr>
<p>To enable assistive technology products to expose a more fine-grained interface than is
otherwise possible with HTML elements and attributes, a set of <a href="#wai-aria">annotations
for assistive technology products</a> can be specified (the ARIA <code
data-x="attr-aria-role">role</code> and <code data-x="attr-aria-*">aria-*</code> attributes).
<ref>ARIA</ref></p>
<hr>
<p>The following <span>event handler content attributes</span> may be specified on any <span
data-x="HTML elements">HTML element</span>:</p>
<ul class="brief">
<li><code data-x="handler-onauxclick">onauxclick</code></li>
<li><code data-x="handler-onbeforeinput">onbeforeinput</code></li>
<li><code data-x="handler-onbeforematch">onbeforematch</code></li>
<li><code data-x="handler-onbeforetoggle">onbeforetoggle</code></li>
<li><code data-x="handler-onblur">onblur</code>*</li>
<li><code data-x="handler-oncancel">oncancel</code></li>
<li><code data-x="handler-oncanplay">oncanplay</code></li>
<li><code data-x="handler-oncanplaythrough">oncanplaythrough</code></li>
<li><code data-x="handler-onchange">onchange</code></li>
<li><code data-x="handler-onclick">onclick</code></li>
<li><code data-x="handler-onclose">onclose</code></li>
<li><code data-x="handler-oncommand">oncommand</code></li>
<li><code data-x="handler-oncontextlost">oncontextlost</code></li>
<li><code data-x="handler-oncontextmenu">oncontextmenu</code></li>
<li><code data-x="handler-oncontextrestored">oncontextrestored</code></li>
<li><code data-x="handler-oncopy">oncopy</code></li>
<li><code data-x="handler-oncuechange">oncuechange</code></li>
<li><code data-x="handler-oncut">oncut</code></li>
<li><code data-x="handler-ondblclick">ondblclick</code></li>
<li><code data-x="handler-ondrag">ondrag</code></li>
<li><code data-x="handler-ondragend">ondragend</code></li>
<li><code data-x="handler-ondragenter">ondragenter</code></li>
<li><code data-x="handler-ondragleave">ondragleave</code></li>
<li><code data-x="handler-ondragover">ondragover</code></li>
<li><code data-x="handler-ondragstart">ondragstart</code></li>
<li><code data-x="handler-ondrop">ondrop</code></li>
<li><code data-x="handler-ondurationchange">ondurationchange</code></li>
<li><code data-x="handler-onemptied">onemptied</code></li>
<li><code data-x="handler-onended">onended</code></li>
<li><code data-x="handler-onerror">onerror</code>*</li>
<li><code data-x="handler-onfocus">onfocus</code>*</li>
<li><code data-x="handler-onformdata">onformdata</code></li>
<li><code data-x="handler-oninput">oninput</code></li>
<li><code data-x="handler-oninvalid">oninvalid</code></li>
<li><code data-x="handler-onkeydown">onkeydown</code></li>
<li><code data-x="handler-onkeypress">onkeypress</code></li>
<li><code data-x="handler-onkeyup">onkeyup</code></li>
<li><code data-x="handler-onload">onload</code>*</li>
<li><code data-x="handler-onloadeddata">onloadeddata</code></li>
<li><code data-x="handler-onloadedmetadata">onloadedmetadata</code></li>
<li><code data-x="handler-onloadstart">onloadstart</code></li>
<li><code data-x="handler-onmousedown">onmousedown</code></li>
<li><code data-x="handler-onmouseenter">onmouseenter</code></li>
<li><code data-x="handler-onmouseleave">onmouseleave</code></li>
<li><code data-x="handler-onmousemove">onmousemove</code></li>
<li><code data-x="handler-onmouseout">onmouseout</code></li>
<li><code data-x="handler-onmouseover">onmouseover</code></li>
<li><code data-x="handler-onmouseup">onmouseup</code></li>
<li><code data-x="handler-onpaste">onpaste</code></li>
<li><code data-x="handler-onpause">onpause</code></li>
<li><code data-x="handler-onplay">onplay</code></li>
<li><code data-x="handler-onplaying">onplaying</code></li>
<li><code data-x="handler-onprogress">onprogress</code></li>
<li><code data-x="handler-onratechange">onratechange</code></li>
<li><code data-x="handler-onreset">onreset</code></li>
<li><code data-x="handler-onresize">onresize</code>*</li>
<li><code data-x="handler-onscroll">onscroll</code>*</li>
<li><code data-x="handler-onscrollend">onscrollend</code>*</li>
<li><code data-x="handler-onsecuritypolicyviolation">onsecuritypolicyviolation</code></li>
<li><code data-x="handler-onseeked">onseeked</code></li>
<li><code data-x="handler-onseeking">onseeking</code></li>
<li><code data-x="handler-onselect">onselect</code></li>
<li><code data-x="handler-onslotchange">onslotchange</code></li>
<li><code data-x="handler-onstalled">onstalled</code></li>
<li><code data-x="handler-onsubmit">onsubmit</code></li>
<li><code data-x="handler-onsuspend">onsuspend</code></li>
<li><code data-x="handler-ontimeupdate">ontimeupdate</code></li>
<li><code data-x="handler-ontoggle">ontoggle</code></li>
<li><code data-x="handler-onvolumechange">onvolumechange</code></li>
<li><code data-x="handler-onwaiting">onwaiting</code></li>
<li><code data-x="handler-onwheel">onwheel</code></li>
</ul>
<p class="note">The attributes marked with an asterisk have a different meaning when specified on
<code>body</code> elements as those elements expose <span>event handlers</span> of the
<code>Window</code> object with the same names.</p>
<p class="note">While these attributes apply to all elements, they are not useful on all elements.
For example, only <span data-x="media element">media elements</span> will ever receive a <code
data-x="event-media-volumechange">volumechange</code> event fired by the user agent.</p>
<hr>
<p><span data-x="custom data attribute">Custom data attributes</span> (e.g. <code
data-x="">data-foldername</code> or <code data-x="">data-msgid</code>) can be specified on any
<span data-x="HTML elements">HTML element</span>, to store custom data, state, annotations, and
similar, specific to the page.</p>
<hr>
<p>In <span>HTML documents</span>, elements in the <span>HTML namespace</span> may have an <code
data-x="">xmlns</code> attribute specified, if, and only if, it has the exact value "<code
data-x="">http://www.w3.org/1999/xhtml</code>". This does not apply to <span>XML
documents</span>.</p>
<p class="note">In HTML, the <code data-x="">xmlns</code> attribute has absolutely no effect. It
is basically a talisman. It is allowed merely to make migration to and from XML mildly easier.
When parsed by an <span>HTML parser</span>, the attribute ends up in no namespace, not the "<code
data-x="">http://www.w3.org/2000/xmlns/</code>" namespace like namespace declaration attributes in
XML do.</p>
<p class="note">In XML, an <code data-x="">xmlns</code> attribute is part of the namespace
declaration mechanism, and an element cannot actually have an <code data-x="">xmlns</code>
attribute in no namespace specified.</p>
<hr>
<p><cite>XML</cite> also allows the use of the <code data-x="attr-xml-space">xml:space</code>
attribute in the <span>XML namespace</span> on any element in an <span data-x="XML documents">XML
document</span>. This attribute has no effect on <span>HTML elements</span>, as the default
behavior in HTML is to preserve whitespace. <ref>XML</ref></p>
<p class="note">There is no way to serialize the <code data-x="attr-xml-space">xml:space</code>
attribute on <span>HTML elements</span> in the <code>text/html</code> syntax.</p>
<h5>The <code data-x="attr-title">title</code> attribute</h5>
<p>The <dfn element-attr for="html-global"><code data-x="attr-title">title</code></dfn> attribute
<span>represents</span> advisory information for the element, such as would be appropriate for a
tooltip. On a link, this could be the title or a description of the target resource; on an image,
it could be the image credit or a description of the image; on a paragraph, it could be a footnote
or commentary on the text; on a citation, it could be further information about the source; on
<span>interactive content</span>, it could be a label for, or instructions for, use of the
element; and so forth. The value is text.</p>
<!-- search for title-warning if modifying this paragraph -->
<p class="note">Relying on the <code data-x="attr-title">title</code> attribute is currently
discouraged as many user agents do not expose the attribute in an accessible manner as required by
this specification (e.g., requiring a pointing device such as a mouse to cause a tooltip to
appear, which excludes keyboard-only users and touch-only users, such as anyone with a modern
phone or tablet).</p>
<p>If this attribute is omitted from an element, then it implies that the <code
data-x="attr-title">title</code> attribute of the nearest ancestor <span data-x="HTML
elements">HTML element</span> with a <code data-x="attr-title">title</code> attribute set is also
relevant to this element. Setting the attribute overrides this, explicitly stating that the
advisory information of any ancestors is not relevant to this element. Setting the attribute to
the empty string indicates that the element has no advisory information.</p>
<p>If the <code data-x="attr-title">title</code> attribute's value contains U+000A LINE FEED (LF)
characters, the content is split into multiple lines. Each U+000A LINE FEED (LF) character
represents a line break.</p>
<div class="example">
<p>Caution is advised with respect to the use of newlines in <code
data-x="attr-title">title</code> attributes.</p>
<p>For instance, the following snippet actually defines an abbreviation's expansion <em>with a
line break in it</em>:</p>
<pre class="bad"><code class="html"><p>My logs show that there was some interest in <abbr title="Hypertext
Transport Protocol">HTTP</abbr> today.</p></code></pre> <!-- DO NOT REWRAP THIS LINE -->
</div>
<p>Some elements, such as <code>link</code>, <code>abbr</code>, and <code>input</code>, define
additional semantics for the <code data-x="attr-title">title</code> attribute beyond the semantics
described above.</p> <!-- the other two are <code>style</code> and <code>dfn</code> -->
<div w-nodev>
<p>The <dfn>advisory information</dfn> of an element is the value that the following algorithm
returns, with the algorithm being aborted once a value is returned. When the algorithm returns the
empty string, then there is no advisory information.</p>
<ol>
<li><p>If the element has a <code data-x="attr-title">title</code> attribute, then return the
result of running <span>normalize newlines</span> on its value.</p></li>
<li><p>If the element has a parent element, then return the parent element's <span>advisory
information</span>.</p></li>
<li><p>Return the empty string.</p></li>
</ol>
<p>User agents should inform the user when elements have <span>advisory information</span>,
otherwise the information would not be discoverable.</p>
<hr>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-title">title</code></dfn> IDL attribute
must <span>reflect</span> the <code data-x="attr-title">title</code> content attribute.</p>
</div>
<h5>The <code data-x="attr-lang">lang</code> and <code data-x="attr-xml-lang">xml:lang</code>
attributes</h5>
<p>The <dfn element-attr for="html-global"><code data-x="attr-lang">lang</code></dfn> attribute
(in no namespace) specifies the primary language for the element's contents and for any of the
element's attributes that contain text. Its value must be a valid BCP 47 language tag, or the
empty string. Setting the attribute to the empty string indicates that the primary language is
unknown<!-- UA conformance requirements for this are below -->. <ref>BCP47</ref></p>
<p>The <dfn data-x="attr-xml-lang" data-x-href="https://www.w3.org/TR/xml/#sec-lang-tag"><code
data-x="">lang</code></dfn> attribute in the <span>XML namespace</span> is defined in XML.
<ref>XML</ref></p>
<p>If these attributes are omitted from an element, then the language of this element is the same
as the language of its parent element, if any (except for <code>slot</code> elements in a
<span>shadow tree</span>).</p>
<p>The <code data-x="attr-lang">lang</code> attribute in no namespace may be used on any <span
data-x="HTML elements">HTML element</span>.</p>
<p>The <span data-x="attr-xml-lang"><code data-x="">lang</code> attribute in the <span>XML
namespace</span></span> may be used on <span>HTML elements</span> in <span>XML documents</span>,
as well as elements in other namespaces if the relevant specifications allow it (in particular,
MathML and SVG allow <span data-x="attr-xml-lang"><code data-x="">lang</code> attributes in the
<span>XML namespace</span></span> to be specified on their elements). If both the <code
data-x="attr-lang">lang</code> attribute in no namespace and the <span data-x="attr-xml-lang"><code
data-x="">lang</code> attribute in the <span>XML namespace</span></span> are specified on the same
element, they must have exactly the same value when compared in an <span>ASCII
case-insensitive</span> manner.</p>
<p>Authors must not use the <span data-x="attr-xml-lang"><code data-x="">lang</code> attribute in
the <span>XML namespace</span></span> on <span>HTML elements</span> in <span>HTML
documents</span>. To ease migration to and from XML, authors may specify an attribute in no
namespace with no prefix and with the literal localname "<code data-x="">xml:lang</code>" on
<span>HTML elements</span> in <span>HTML documents</span>, but such attributes must only be
specified if a <code data-x="attr-lang">lang</code> attribute in no namespace is also specified,
and both attributes must have the same value when compared in an <span>ASCII
case-insensitive</span> manner.</p>
<p class="note">The attribute in no namespace with no prefix and with the literal localname "<code
data-x="">xml:lang</code>" has no effect on language processing.</p>
<div w-nodev>
<hr>
<p>To determine the <dfn export for="Node">language</dfn> of a node, user agents must use the
first appropriate step in the following list:</p>
<dl class="switch">
<dt>If the node is an element that has a <span data-x="attr-xml-lang"><code data-x="">lang</code>
attribute in the <span>XML namespace</span></span> set</dt>
<dd><p>Use the value of that attribute.</p></dd>
<dt>If the node is an <span data-x="HTML elements">HTML element</span> or an element in the
<span>SVG namespace</span>, and it has a <code data-x="attr-lang">lang</code> in no namespace
attribute set</dt>
<dd><p>Use the value of that attribute.</p></dd>
<dt>If the node's parent is a <span>shadow root</span></dt>
<dd><p>Use the <span>language</span> of that <span>shadow root</span>'s <span
data-x="concept-DocumentFragment-host">host</span>.</p></dd>
<!-- this assumes that if there's an ancestor element, the parent must be an element -->
<dt>If the node's <span>parent element</span> is not null</dt>
<dd><p>Use the <span>language</span> of that <span>parent element</span>.</p></dd>
<dt>Otherwise</dt>
<dd><p>If there is a <span>pragma-set default language</span> set, then that is the language of
the node. If there is no <span>pragma-set default language</span> set, then language information
from a higher-level protocol (such as HTTP), if any, must be used as the final fallback language
instead. In the absence of any such language information, and in cases where the higher-level
protocol reports multiple languages, the language of the node is unknown, and the corresponding
language tag is the empty string.</p></dd>
</dl>
<p>If the resulting value is not a recognized language tag, then it must be treated as an unknown
language having the given language tag, distinct from all other languages. For the purposes of
round-tripping or communicating with other services that expect language tags, user agents should
pass unknown language tags through unmodified, and tagged as being BCP 47 language tags, so that
subsequent services do not interpret the data as another type of language description.
<ref>BCP47</ref></p>
<p class="example">Thus, for instance, an element with <code data-x="">lang="xyzzy"</code> would be
matched by the selector <code data-x="">:lang(xyzzy)</code> (e.g. in CSS), but it would not be
matched by <code data-x="">:lang(abcde)</code>, even though both are equally invalid. Similarly, if
a web browser and screen reader working in unison communicated about the language of the element,
the browser would tell the screen reader that the language was "xyzzy", even if it knew it was
invalid, just in case the screen reader actually supported a language with that tag after all.
Even if the screen reader supported both BCP 47 and another syntax for encoding language names,
and in that other syntax the string "xyzzy" was a way to denote the Belarusian language, it would
be <em>incorrect</em> for the screen reader to then start treating text as Belarusian, because
"xyzzy" is not how Belarusian is described in BCP 47 codes (BCP 47 uses the code "be" for
Belarusian).</p>
<p>If the resulting value is the empty string, then it must be interpreted as meaning that the
language of the node is <dfn data-x="concept-explicitly-unknown">explicitly unknown</dfn>.</p>
<hr>
<p>User agents may use the element's language to determine proper processing or rendering (e.g. in
the selection of appropriate fonts or pronunciations, for dictionary selection, or for the user
interfaces of form controls such as date pickers). <!--User agents must not use the element's
language to determine text directionality. (commented out because text directionality is a
rendering-level concern.)--></p>
<!-- Date pickers would use the language information for determining the language of months, for
example. They should use the page's _locale_ to figure out the format itself, not the language.
There's currently no way to determine the page's locale except by guessing from the charset and
language... -->
<hr>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-lang">lang</code></dfn> IDL attribute
must <span>reflect</span> the <code data-x="attr-lang">lang</code> content attribute in no
namespace.</p>
</div>
<h5>The <code data-x="attr-translate">translate</code> attribute</h5>
<!-- v2: a way to translate the declensions of the word(s), but keep the actual roots the same
for examples, see https://www.w3.org/Bugs/Public/show_bug.cgi?id=17954 -->
<p>The <dfn element-attr for="html-global"><code data-x="attr-translate">translate</code></dfn>
attribute is used to specify whether an element's attribute values and the values of its
<code>Text</code> node children are to be translated when the page is localized, or whether to
leave them unchanged. It is an attribute is an <span>enumerated attribute</span> with the
following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/translate"><code
data-x="attr-translate-yes-keyword">yes</code></dfn>
<td rowspan=2><dfn data-x="attr-translate-yes-state">yes</dfn>
<td rowspan=2>Sets <span>translation mode</span> to <span>translate-enabled</span>.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/translate"><code
data-x="attr-translate-no-keyword">no</code></dfn>
<td><dfn data-x="attr-translate-no-state">no</dfn>
<td>Sets <span>translation mode</span> to <span>no-translate</span>.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-translate-inherit-state">inherit</dfn> state.</p>
<p>Each element (even non-HTML elements) has a <dfn>translation mode</dfn>, which is in either the
<span>translate-enabled</span> state or the <span>no-translate</span> state. If an <span
data-x="HTML elements">HTML element</span>'s <code data-x="attr-translate">translate</code>
attribute is in the <span data-x="attr-translate-yes-state">yes</span> state, then the element's
<span>translation mode</span> is in the <span>translate-enabled</span> state; otherwise, if the
element's <code data-x="attr-translate">translate</code> attribute is in the <span
data-x="attr-translate-no-state">no</span> state, then the element's <span>translation mode</span>
is in the <span>no-translate</span> state. Otherwise, either the element's <code
data-x="attr-translate">translate</code> attribute is in the <span
data-x="attr-translate-inherit-state">inherit</span> state, or the element is not an <span
data-x="HTML elements">HTML element</span> and thus does not have a <code
data-x="attr-translate">translate</code> attribute; in either case, the element's
<span>translation mode</span> is in the same state as its <span>parent element</span>'s, if any,
or in the <span>translate-enabled</span> state, if the element's <span>parent element</span> is
null.</p>
<p>When an element is in the <dfn>translate-enabled</dfn> state, the element's <span>translatable
attributes</span> and the values of its <code>Text</code> node children are to be translated when
the page is localized.</p>
<p>When an element is in the <dfn>no-translate</dfn> state, the element's attribute values and the
values of its <code>Text</code> node children are to be left as-is when the page is localized,
e.g. because the element contains a person's name or a name of a computer program.</p>
<p>The following attributes are <dfn>translatable attributes</dfn>:</p>
<ul class="brief">
<li><code data-x="attr-th-abbr">abbr</code> on <code>th</code> elements</li>
<li><code data-x="">alt</code> on <code data-x="attr-area-alt">area</code>,
<code data-x="attr-img-alt">img</code>, and
<code data-x="attr-input-alt">input</code> elements</li>
<li><code data-x="attr-meta-content">content</code> on <code>meta</code> elements, if the <code data-x="attr-meta-name">name</code> attribute specifies a metadata name whose value is known to be translatable</li>
<li><code data-x="attr-hyperlink-download">download</code> on <code>a</code> and
<code>area</code> elements</li>
<li><code data-x="">label</code> on <code data-x="attr-optgroup-label">optgroup</code>,
<code data-x="attr-option-label">option</code>, and
<code data-x="attr-track-label">track</code> elements</li>
<li><code data-x="attr-lang">lang</code> on <span>HTML elements</span>; must be "translated" to match the language used in the translation</li>
<li><code data-x="">placeholder</code> on <code data-x="attr-input-placeholder">input</code> and
<code data-x="attr-textarea-placeholder">textarea</code> elements</li>
<li><code data-x="attr-iframe-srcdoc">srcdoc</code> on <code>iframe</code> elements; must be parsed and recursively processed</li>
<li><code data-x="attr-style">style</code> on <span>HTML elements</span>; must be parsed and
recursively processed (e.g. for the values of <span>'content'</span> properties)</li>
<li><code data-x="attr-title">title</code> on all <span>HTML elements</span></li>
<li><code data-x="attr-input-value">value</code> on <code>input</code> elements with a
<code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-button">Button</span> state
or the <span data-x="attr-input-type-reset">Reset Button</span> state</li>
<!-- <input value> on other types is excluded since we can't predict if it interferes with server-side processing -->
</ul>
<p>Other specifications may define other attributes that are also <span>translatable
attributes</span>. For example, <cite>ARIA</cite> would define the <code
data-x="attr-aria-label">aria-label</code> attribute as translatable.</p>
<div w-nodev>
<hr>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-translate">translate</code></dfn> IDL
attribute must, on getting, return true if the element's <span>translation mode</span> is
<span>translate-enabled</span>, and false otherwise. On setting, it must set the content
attribute's value to "<code data-x="">yes</code>" if the new value is true, and set the content
attribute's value to "<code data-x="">no</code>" otherwise.</p>
</div>
<div class="example">
<p>In this example, everything in the document is to be translated when the page is localized,
except the sample keyboard input and sample program output:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en> <!-- default on the document element is translate=yes -->
<head>
<title>The Bee Game</title> <!-- implied translate=yes inherited from ancestors -->
</head>
<body>
<p>The Bee Game is a text adventure game in English.</p>
<p>When the game launches, the first thing you should do is type
<kbd <strong>translate=no</strong>>eat honey</kbd>. The game will respond with:</p>
<pre><samp <strong>translate=no</strong>>Yum yum! That was some good honey!</samp></pre>
</body>
</html></code></pre>
</div>
<h5>The <code data-x="attr-dir">dir</code> attribute</h5>
<p>The <dfn element-attr for="html-global"><code data-x="attr-dir">dir</code></dfn> attribute
is an <span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/dir"><code data-x="attr-dir-ltr">ltr</code></dfn>
<td><dfn data-x="attr-dir-ltr-state">ltr</dfn>
<td>The contents of the element are explicitly directionally isolated left-to-right text.
<tr>
<td><dfn attr-value for="html-global/dir"><code data-x="attr-dir-rtl">rtl</code></dfn>
<td><dfn data-x="attr-dir-rtl-state">rtl</dfn>
<td>The contents of the element are explicitly directionally isolated right-to-left text.
<tr>
<td><dfn attr-value for="html-global/dir"><code data-x="attr-dir-auto">auto</code></dfn>
<td><dfn data-x="attr-dir-auto-state">auto</dfn>
<td>The contents of the element are explicitly directionally isolated text, but the direction
is to be determined programmatically using the contents of the element (as described
below).
</table>
<div class="note">
<p>The heuristic used by the <span data-x="attr-dir-auto-state">auto</span> state is very crude
(it just looks at the first character with a strong directionality, in a manner analogous to the
Paragraph Level determination in the bidirectional algorithm). Authors are urged to only use this
value as a last resort when the direction of the text is truly unknown and no better server-side
heuristic can be applied. <ref>BIDI</ref></p>
<p>For <code>textarea</code> and <code>pre</code> elements, the heuristic is applied on a
per-paragraph level.</p>
</div>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-dir-undefined-state">undefined</dfn> state.</p>
<hr>
<p>The <dfn data-x="the directionality">directionality</dfn> of an element (any element, not just
an <span data-x="HTML elements">HTML element</span>) is either '<dfn
data-x="concept-ltr">ltr</dfn>' or '<dfn data-x="concept-rtl">rtl</dfn>'. To compute the <span
data-x="the directionality">directionality</span> given an element <var>element</var>, switch on
<var>element</var>'s <code data-x="attr-dir">dir</code> attribute state:</p>
<dl class="switch">
<dt><span data-x="attr-dir-ltr-state">ltr</span></dt>
<dd><p>Return '<span data-x="concept-ltr">ltr</span>'.</p></dd>
<dt><span data-x="attr-dir-rtl-state">rtl</span></dt>
<dd><p>Return '<span data-x="concept-rtl">rtl</span>'.</p></dd>
<dt><span data-x="attr-dir-auto-state">auto</span></dt>
<dd>
<ol>
<li><p>Let <var>result</var> be the <span>auto directionality</span> of
<var>element</var>.</p></li>
<li><p>If <var>result</var> is null, then return '<span
data-x="concept-ltr">ltr</span>'.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
</dd>
<dt><span data-x="attr-dir-undefined-state">undefined</span></dt>
<dd>
<dl class="switch">
<dt>If <var>element</var> is a <code>bdi</code> element</dt>
<dd>
<ol>
<li><p>Let <var>result</var> be the <span>auto directionality</span> of
<var>element</var>.</p></li>
<li><p>If <var>result</var> is null, then return '<span
data-x="concept-ltr">ltr</span>'.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
</dd>
<dt>If <var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-tel">Telephone</span> state</dt>
<dd><p>Return '<span data-x="concept-ltr">ltr</span>'.</p></dd>
<!-- This looks odd, but is very much deliberate:
https://www.w3.org/Bugs/Public/show_bug.cgi?id=17835 -->
<dt>Otherwise</dt>
<dd><p>Return the <span>parent directionality</span> of <var>element</var>.</p></dd>
</dl>
</dd>
</dl>
<p class="note">Since the <code data-x="attr-dir">dir</code> attribute is only defined for
<span>HTML elements</span>, it cannot be present on elements from other namespaces. Thus, elements
from other namespaces always end up using the <span>parent directionality</span>.</p>
<p>The <dfn>auto-directionality form-associated elements</dfn> are:
<ul>
<li><p><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is
in the <span data-x="attr-input-type-hidden">Hidden</span>, <span
data-x="attr-input-type-text">Text</span>, <span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-tel">Telephone</span>, <span
data-x="attr-input-type-url">URL</span>, <span data-x="attr-input-type-email">Email</span>, <span
data-x="attr-input-type-password">Password</span>, <span data-x="attr-input-type-submit">Submit
Button</span>, <span data-x="attr-input-type-reset">Reset Button</span>, or <span
data-x="attr-input-type-button">Button</span> state, and</p></li>
<li><p><code>textarea</code> elements.</p></li>
</ul>
<p>To compute the <dfn>auto directionality</dfn> given an element <var>element</var>:</p>
<ol>
<li>
<p>If <var>element</var> is an <span data-x="auto-directionality form-associated
elements">auto-directionality form-associated element</span>:
<ol>
<li><p>If <var>element</var>'s <span data-x="concept-fe-value">value</span> contains a
character of bidirectional character type AL or R, and there is no character of bidirectional
character type L anywhere before it in the element's <span
data-x="concept-fe-value">value</span>, then return '<span data-x="concept-rtl">rtl</span>'.
<ref>BIDI</ref></p></li>
<li><p>If <var>element</var>'s <span data-x="concept-fe-value">value</span> is not the empty
string, then return '<span data-x="concept-ltr">ltr</span>'.</p></li>
<li><p>Return null.</p></li>
</ol>
</li>
<li>
<p>If <var>element</var> is a <code>slot</code> element whose <span>root</span> is a
<span>shadow root</span> and <var>element</var>'s <span>assigned nodes</span> are not empty:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> node <var>child</var> of <var>element</var>'s
<span>assigned nodes</span>:</p>
<ol>
<li><p>Let <var>childDirection</var> be null.</p></li>
<li><p>If <var>child</var> is a <code>Text</code> node, then set <var>childDirection</var> to
the <span>text node directionality</span> of <var>child</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>child</var> is an <code>Element</code> node.</p></li>
<li><p>Set <var>childDirection</var> to the <span>contained text auto directionality</span>
of <var>child</var> with <i><span
data-x="auto-directionality-can-exclude-root">canExcludeRoot</span></i> set to
true.</p></li>
</ol>
</li>
<li><p>If <var>childDirection</var> is not null, then return
<var>childDirection</var>.</p></li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
</li>
<li><p>Return the <span>contained text auto directionality</span> of <var>element</var> with
<i><span data-x="auto-directionality-can-exclude-root">canExcludeRoot</span></i> set to
false.</p></li>
</ol>
<p>To compute the <dfn>contained text auto directionality</dfn> of an element
<var>element</var> with a boolean <dfn
data-x="auto-directionality-can-exclude-root"><var>canExcludeRoot</var></dfn>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> node <var>descendant</var> of
<var>element</var>'s <span data-x="descendant">descendants</span>, in <span>tree
order</span>:</p>
<ol>
<li>
<p>If any of</p>
<ul class="brief">
<li><var>descendant</var></li>
<li>any ancestor element of <var>descendant</var> that is a descendant of <var>element</var></li>
<li>if <var>canExcludeRoot</var> is true, <var>element</var></li>
</ul>
<p>is one of</p>
<ul class="brief">
<li>a <code>bdi</code> element</li>
<li>a <code>script</code> element</li>
<li>a <code>style</code> element</li>
<li>a <code>textarea</code> element</li>
<li>an element whose <code data-x="attr-dir">dir</code> attribute is not in the <span
data-x="attr-dir-undefined-state">undefined</span> state</li>
</ul>
<p>then <span>continue</span>.</p>
</li>
<li><p>If <var>descendant</var> is a <code>slot</code> element whose <span>root</span> is a
<span>shadow root</span>, then return the <span data-x="the
directionality">directionality</span> of that <span>shadow root</span>'s <span
data-x="concept-DocumentFragment-host">host</span>.</p></li>
<li><p>If <var>descendant</var> is not a <code>Text</code> node, then
<span>continue</span>.</p></li>
<li><p>Let <var>result</var> be the <span>text node directionality</span> of
<var>descendant</var>.</li>
<li><p>If <var>result</var> is not null, then return <var>result</var>.</p></li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<p>To compute the <dfn>text node directionality</dfn> given a <code>Text</code> node
<var>text</var>:</p>
<ol>
<li><p>If <var>text</var>'s <span data-x="concept-cd-data">data</span> does not contain a code
point whose bidirectional character type is L, AL, or R, then return null.
<ref>BIDI</ref></p></li>
<li><p>Let <var>codePoint</var> be the first code point in <var>text</var>'s <span
data-x="concept-cd-data">data</span> whose bidirectional character type is L, AL, or R.</p></li>
<li><p>If <var>codePoint</var> is of bidirectional character type AL or R, then return '<span
data-x="concept-rtl">rtl</span>'.</p></li>
<li><p>If <var>codePoint</var> is of bidirectional character type L, then return '<span
data-x="concept-ltr">ltr</span>'.</p></li>
</ol>
<p>To compute the <dfn>parent directionality</dfn> given an element <var>element</var>:</p>
<ol>
<li><p>Let <var>parentNode</var> be <var>element</var>'s parent node.</p></li>
<li><p>If <var>parentNode</var> is a <span>shadow root</span>, then return the <span data-x="the
directionality">directionality</span> of <var>parentNode</var>'s <span
data-x="concept-DocumentFragment-host">host</span>.</p></li>
<li><p>If <var>parentNode</var> is an element, then return the <span data-x="the
directionality">directionality</span> of <var>parentNode</var>.</p></li>
<li><p>Return '<span data-x="concept-ltr">ltr</span>'.</p></li>
</ol>
<div w-nodev>
<p class="note">This attribute <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<hr>
<p>The <dfn data-x="directionality of the attribute">directionality of an attribute</dfn> of an
<span data-x="HTML elements">HTML element</span>, which is used when the text of that attribute is
to be included in the rendering in some manner, is determined as per the first appropriate set of
steps from the following list:</p>
<dl class="switch">
<dt>If the attribute is a <span>directionality-capable attribute</span> and the element's <code
data-x="attr-dir">dir</code> attribute is in the <span data-x="attr-dir-auto-state">auto</span>
state</dt>
<dd>
<p>Find the first character (in logical order) of the attribute's value that is of bidirectional
character type L, AL, or R. <ref>BIDI</ref></p>
<p>If such a character is found and it is of bidirectional character type AL or R, the
<span>directionality of the attribute</span> is '<span data-x="concept-rtl">rtl</span>'.</p>
<p>Otherwise, the <span>directionality of the attribute</span> is '<span
data-x="concept-ltr">ltr</span>'.</p>
</dd>
<dt>Otherwise</dt>
<dd>The <span>directionality of the attribute</span> is the same as <span data-x="the
directionality">the element's directionality</span>.</dd>
</dl>
<p>The following attributes are <dfn data-x="directionality-capable
attribute">directionality-capable attributes</dfn>:</p>
<ul class="brief">
<li><code data-x="attr-th-abbr">abbr</code> on <code>th</code> elements</li>
<li><code data-x="">alt</code> on <code data-x="attr-area-alt">area</code>,
<code data-x="attr-img-alt">img</code>, and
<code data-x="attr-input-alt">input</code> elements</li>
<li><code data-x="attr-meta-content">content</code> on <code>meta</code> elements, if the <code data-x="attr-meta-name">name</code> attribute specifies a metadata name whose value is primarily intended to be human-readable rather than machine-readable</li>
<li><code data-x="">label</code> on <code data-x="attr-optgroup-label">optgroup</code>,
<code data-x="attr-option-label">option</code>, and
<code data-x="attr-track-label">track</code> elements</li>
<li><code data-x="">placeholder</code> on <code data-x="attr-input-placeholder">input</code> and
<code data-x="attr-textarea-placeholder">textarea</code> elements</li>
<li><code data-x="attr-title">title</code> on all <span>HTML elements</span></li>
</ul>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-dir">dir</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns <span>the <code>html</code> element</span>'s <code data-x="attr-dir">dir</code>
attribute's value, if any.</p>
<p>Can be set, to either "<code data-x="">ltr</code>", "<code data-x="">rtl</code>", or "<code
data-x="">auto</code>" to replace <span>the <code>html</code> element</span>'s <code
data-x="attr-dir">dir</code> attribute's value.</p>
<p>If there is no <span data-x="the html element"><code>html</code> element</span>, returns the
empty string and ignores new values.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-dir">dir</code></dfn> IDL attribute on
an element must <span>reflect</span> the <code data-x="attr-dir">dir</code> content attribute of
that element, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-dir">dir</code></dfn> IDL
attribute on <code>Document</code> objects must <span>reflect</span> the <code
data-x="attr-dir">dir</code> content attribute of <span>the <code>html</code> element</span>, if
any, <span>limited to only known values</span>. If there is no such element, then the attribute
must return the empty string and do nothing on setting.</p>
</div>
<p class="note">Authors are strongly encouraged to use the <code data-x="attr-dir">dir</code>
attribute to indicate text direction rather than using CSS, since that way their documents will
continue to render correctly even in the absence of CSS (e.g. as interpreted by search
engines).</p>
<div class="example">
<p>This markup fragment is of an IM conversation.</p>
<pre><code class="html"><p dir=auto class="u1"><b><bdi>Student</bdi>:</b> How do you write "What's your name?" in Arabic?</p>
<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> ما اسمك؟</p>
<p dir=auto class="u1"><b><bdi>Student</bdi>:</b> Thanks.</p>
<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> That's written "شكرًا".</p>
<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> Do you know how to write "Please"?</p>
<p dir=auto class="u1"><b><bdi>Student</bdi>:</b> "من فضلك", right?</p></code></pre>
<!--
<!DOCTYPE html>
<style>
div { border: groove #FFFF99; padding: 0.25em; width: 22em; background: #FFFFEE; color: black; }
p { margin: 0.25em 0; font: 1em/1 InaiMathi; color: purple; }
.u1 { color: teal; }
</style>
<div>
<p dir=ltr class="u1"><b><bdi>Student</bdi>:</b> How do you write "What's your name?" in Arabic?</p>
<p dir=rtl class="u2"><b><bdi>Teacher</bdi>:</b> ما اسمك؟</p>
<p dir=ltr class="u1"><b><bdi>Student</bdi>:</b> Thanks.</p>
<p dir=ltr class="u2"><b><bdi>Teacher</bdi>:</b> That's written "شكرًا".</p>
<p dir=ltr class="u2"><b><bdi>Teacher</bdi>:</b> Do you know how to write "Please"?</p>
<p dir=rtl class="u1"><b><bdi>Student</bdi>:</b> "من فضلك", right?</p>
-->
<p>Given a suitable style sheet and the default alignment styles for the <code>p</code> element,
namely to align the text to the <i>start edge</i> of the paragraph, the resulting rendering could
be as follows:</p>
<p><img src="/images/im.png" alt="Each paragraph rendered as a separate block, with the paragraphs left-aligned except the second paragraph and the last one, which would be right aligned, with the usernames ('Student' and 'Teacher' in this example) flush right, with a colon to their left, and the text first to the left of that." width=366 height=157></p>
<p>As noted earlier, the <code data-x="attr-dir-auto">auto</code> value is not a panacea. The
final paragraph in this example is misinterpreted as being right-to-left text, since it begins
with an Arabic character, which causes the "right?" to be to the left of the Arabic text.</p>
</div>
<h5>The <code data-x="attr-style">style</code> attribute</h5>
<p>All <span>HTML elements</span> may have the <dfn element-attr for="html-global"><code
data-x="attr-style">style</code></dfn> content attribute set. This is a <span
data-x="css-styling-attribute">style attribute</span> as defined by <cite>CSS Style
Attributes</cite>. <ref>CSSATTR</ref></p>
<div w-nodev>
<p>In user agents that support CSS, the attribute's value must be parsed when the attribute is
added or has its value changed<!-- so dynamic changes to the base URL don't affect the CSS -->,
according to the rules given for <span data-x="css-styling-attribute">style attributes</span>.
<ref>CSSATTR</ref></p>
<p>However, if the <span>Should element's inline behavior be blocked by Content Security
Policy?</span> algorithm returns "<code data-x="">Blocked</code>" when executed upon the
attribute's <span>element</span>, "<code data-x="">style attribute</code>", and the attribute's
value, then the style rules defined in the attribute's value must not be applied to the
<span>element</span>. <ref>CSP</ref></p>
</div>
<p>Documents that use <code data-x="attr-style">style</code> attributes on any of their elements
must still be comprehensible and usable if those attributes were removed.</p>
<p class="note">In particular, using the <code data-x="attr-style">style</code> attribute to hide
and show content, or to convey meaning that is otherwise not included in the document, is
non-conforming. (To hide and show content, use the <code data-x="attr-hidden">hidden</code>
attribute.)</p>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-style">style</span></code></dt>
<dd><p>Returns a <code>CSSStyleDeclaration</code> object for the element's <code
data-x="attr-style">style</code> attribute.</p></dd>
</dl>
<div w-nodev>
<p>The <code data-x="dom-style">style</code> IDL attribute is defined in <cite>CSS Object
Model</cite>. <ref>CSSOM</ref></p>
</div>
<div class="example">
<p>In the following example, the words that refer to colors are marked up using the
<code>span</code> element and the <code data-x="attr-style">style</code> attribute to make those
words show up in the relevant colors in visual media.</p>
<pre><code class="html"><p>My sweat suit is <span style="color: green; background:
transparent">green</span> and my eyes are <span style="color: blue;
background: transparent">blue</span>.</p></code></pre>
</div>
<h5><dfn>Embedding custom non-visible data</dfn> with the <code data-x="attr-data-*">data-*</code> attributes</h5>
<p>A <dfn>custom data attribute</dfn> is an attribute in no namespace whose name starts with the
string "<dfn><code data-x="attr-data-*">data-</code></dfn>", has at least one character after the
hyphen, is <span>XML-compatible</span>, and contains no <span data-x="ASCII upper alpha">ASCII
upper alphas</span>.</p>
<p class="note">All attribute names on <span>HTML elements</span> in <span>HTML documents</span>
get ASCII-lowercased automatically, so the restriction on ASCII uppercase letters doesn't affect
such documents.</p>
<p><span data-x="custom data attribute">Custom data attributes</span> are intended to store custom
data, state, annotations, and similar, private to the page or application, for which there are no
more appropriate attributes or elements.</p>
<p>These attributes are not intended for use by software that is not known to the administrators
of the site that uses the attributes. For generic extensions that are to be used by multiple
independent tools, either this specification should be extended to provide the feature explicitly,
or a technology like <span>microdata</span> should be used (with a standardized vocabulary).</p>
<div class="example">
<p>For instance, a site about music could annotate list items representing tracks in an album
with custom data attributes containing the length of each track. This information could then be
used by the site itself to allow the user to sort the list by track length, or to filter the list
for tracks of certain lengths.</p>
<pre><code class="html"><ol>
<li data-length="2m11s">Beyond The Sea</li>
...
</ol></code></pre>
<p>It would be inappropriate, however, for the user to use generic software not associated with
that music site to search for tracks of a certain length by looking at this data.</p>
<p>This is because these attributes are intended for use by the site's own scripts, and are not a
generic extension mechanism for publicly-usable metadata.</p>
</div>
<div class="example">
<p>Similarly, a page author could write markup that provides information for a translation tool
that they are intending to use:</p>
<pre><code class="html"><p>The third <span data-mytrans-de="Anspruch">claim</span> covers the case of <span
translate="no">HTML</span> markup.</p></code></pre>
<p>In this example, the "<code data-x="">data-mytrans-de</code>" attribute gives specific text
for the MyTrans product to use when translating the phrase "claim" to German. However, the
standard <code data-x="attr-translate">translate</code> attribute is used to tell it that in all
languages, "HTML" is to remain unchanged. When a standard attribute is available, there is no
need for a <span>custom data attribute</span> to be used.</p>
</div>
<div class="example">
<p>In this example, custom data attributes are used to store the result of a feature detection
for <code>PaymentRequest</code>, which could be used in CSS to style a checkout page
differently.</p>
<pre><code class="html"><script>
if ('PaymentRequest' in window) {
document.documentElement.dataset.hasPaymentRequest = '';
}
</script></code></pre>
<p>Here, the <code data-x="">data-has-payment-request</code> attribute is effectively being used
as a <span>boolean attribute</span>; it is enough to check the presence of the attribute.
However, if the author so wishes, it could later be populated with some value, maybe to indicate
limited functionality of the feature.</p>
</div>
<p>Every <span data-x="HTML elements">HTML element</span> may have any number of <span
data-x="custom data attribute">custom data attributes</span> specified, with any value.</p>
<p>Authors should carefully design such extensions so that when the attributes are ignored and any
associated CSS dropped, the page is still usable.</p>
<div w-nodev>
<p>User agents must not derive any implementation behavior from these attributes or values.
Specifications intended for user agents must not define these attributes to have any meaningful
values.</p>
</div>
<p>JavaScript libraries may use the <span data-x="custom data attribute">custom data
attributes</span>, as they are considered to be part of the page on which they are used. Authors
of libraries that are reused by many authors are encouraged to include their name in the attribute
names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to
make the exact name used in the attribute names customizable, so that libraries whose authors
unknowingly picked the same name can be used on the same page, and so that multiple versions of a
particular library can be used on the same page even when those versions are not mutually
compatible.</p>
<div class="example">
<p>For example, a library called "DoQuery" could use attribute names like <code
data-x="">data-doquery-range</code>, and a library called "jJo" could use attributes names like
<code data-x="">data-jjo-range</code>. The jJo library could also provide an API to set which
prefix to use (e.g. <code data-x="">J.setDataPrefix('j2')</code>, making the attributes have names
like <code data-x="">data-j2-range</code>).</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-dataset">dataset</span></code></dt>
<dd>
<p>Returns a <code>DOMStringMap</code> object for the element's <code
data-x="attr-data-*">data-*</code> attributes.</p>
<p>Hyphenated names become camel-cased. For example, <code data-x="">data-foo-bar=""</code>
becomes <code data-x="">element.dataset.fooBar</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLOrSVGElement"><code data-x="dom-dataset">dataset</code></dfn> IDL
attribute provides convenient accessors for all the <code data-x="attr-data-*">data-*</code>
attributes on an element. On getting, the <code data-x="dom-dataset">dataset</code> IDL attribute
must return a <code>DOMStringMap</code> whose associated element is this element.</p>
</div>
<p>The <code>DOMStringMap</code> interface is used for the <code
data-x="dom-dataset">dataset</code> attribute. Each <code>DOMStringMap</code> has an <dfn
data-x="concept-DOMStringMap-element">associated element</dfn>.</p>
<pre><code class="idl">[Exposed=Window,
<span>LegacyOverrideBuiltIns</span>]
interface <dfn interface>DOMStringMap</dfn> {
<a href="#dom-domstringmap-nameditem">getter</a> DOMString (DOMString name);
[<span>CEReactions</span>] <a href="#dom-domstringmap-setitem">setter</a> undefined (DOMString name, DOMString value);
[<span>CEReactions</span>] <a href="#dom-domstringmap-removeitem">deleter</a> undefined (DOMString name);
};</code></pre>
<div w-nodev>
<p>To <dfn data-x="concept-DOMStringMap-pairs">get a <code>DOMStringMap</code>'s name-value
pairs</dfn>, run the following algorithm:</p>
<ol>
<li><p>Let <var>list</var> be an empty list of name-value pairs.</p></li>
<li><p>For each content attribute on the <code>DOMStringMap</code>'s <span
data-x="concept-DOMStringMap-element">associated element</span> whose first five characters are
the string "<code data-x="">data-</code>" and whose remaining characters (if any) do not include
any <span data-x="ASCII upper alpha">ASCII upper alphas</span>, in the order that those
attributes are listed in the element's <span>attribute list</span>, add a name-value pair to
<var>list</var> whose name is the attribute's name with the first five characters removed and
whose value is the attribute's value.</p></li>
<li><p>For each name in <var>list</var>, for each U+002D HYPHEN-MINUS character (-) in the name
that is followed by an <span>ASCII lower alpha</span>, remove the U+002D HYPHEN-MINUS character
(-) and replace the character that followed it by the same character <span>converted to ASCII
uppercase</span>.</p></li>
<li><p>Return <var>list</var>.</p></li>
</ol>
<p>The <span>supported property names</span> on a <code>DOMStringMap</code> object at any instant
are the names of each pair returned from <span data-x="concept-DOMStringMap-pairs">getting the
<code>DOMStringMap</code>'s name-value pairs</span> at that instant, in the order returned.</p>
<p id="dom-domstringmap-nameditem">To <span>determine the value of a named property</span>
<var>name</var> for a <code>DOMStringMap</code>, return the value component of the name-value pair
whose name component is <var>name</var> in the list returned from <span
data-x="concept-DOMStringMap-pairs">getting the <code>DOMStringMap</code>'s name-value
pairs</span>.</p>
<p id="dom-domstringmap-setitem">To <span>set the value of a new named property</span> or
<span>set the value of an existing named property</span> for a <code>DOMStringMap</code>, given a
property name <var>name</var> and a new value <var>value</var>, run the following steps:</p>
<ol>
<li><p>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by an <span>ASCII
lower alpha</span>, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>For each <span>ASCII upper alpha</span> in <var>name</var>, insert a U+002D HYPHEN-MINUS
character (-) before the character and replace the character with the same character
<span>converted to ASCII lowercase</span>.</p></li>
<li><p>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</p></li>
<li><p>If <var>name</var> does not match the XML <code data-x="xml-Name">Name</code> production,
throw an <span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span> for the
<code>DOMStringMap</code>'s <span data-x="concept-DOMStringMap-element">associated element</span>
using <var>name</var> and <var>value</var>.</p></li>
</ol>
<p id="dom-domstringmap-removeitem">To <span>delete an existing named property</span>
<var>name</var> for a <code>DOMStringMap</code>, run the following steps:</p>
<ol>
<!--(can't happen while the DOMStringMap deleter has no name)
<li><p>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by an <span>ASCII
lower alpha</span>, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
-->
<li><p>For each <span>ASCII upper alpha</span> in <var>name</var>, insert a U+002D HYPHEN-MINUS
character (-) before the character and replace the character with the same character
<span>converted to ASCII lowercase</span>.</p></li>
<li><p>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</p></li>
<li><p><span data-x="concept-element-attributes-remove">Remove an attribute by name</span> given
<var>name</var> and the <code>DOMStringMap</code>'s <span
data-x="concept-DOMStringMap-element">associated element</span>.</p></li>
</ol>
<p class="note">This algorithm will only get invoked by <cite>Web IDL</cite> for names that
are given by the earlier algorithm for <span data-x="concept-DOMStringMap-pairs">getting the
<code>DOMStringMap</code>'s name-value pairs</span>. <ref>WEBIDL</ref></p>
</div>
<div class="example">
<p>If a web page wanted an element to represent a space ship, e.g. as part of a game, it would
have to use the <code data-x="attr-class">class</code> attribute along with <code
data-x="attr-data-*">data-*</code> attributes:</p>
<pre><code class="html"><div class="spaceship" data-ship-id="92432"
data-weapons="laser 2" data-shields="50%"
data-<!---->x="30" data-y="10" data-z="90">
<button class="fire"
onclick="spaceships[this.parentNode.dataset.shipId].fire()">
Fire
</button>
</div></code></pre>
<p>Notice how the hyphenated attribute name becomes camel-cased in the API.</p>
</div>
<div class="example">
<p>Given the following fragment and elements with similar constructions:</p>
<pre><code class="html"><img class="tower" id="tower5" data-<!---->x="12" data-y="5"
data-ai="robotarget" data-hp="46" data-ability="flames"
src="towers/rocket.png" alt="Rocket Tower"></code></pre>
<p>...one could imagine a function <code
data-x="">splashDamage()</code> that takes some arguments, the first
of which is the element to process:</p>
<pre><code class="js">function splashDamage(node, x, y, damage) {
if (node.classList.contains('tower') && // checking the 'class' attribute
node.dataset.x == x && // reading the 'data-x' attribute
node.dataset.y == y) { // reading the 'data-y' attribute
var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
hp = hp - damage;
if (hp < 0) {
hp = 0;
node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
delete node.dataset.ability; // removing the 'data-ability' attribute
}
node.dataset.hp = hp; // setting the 'data-hp' attribute
}
}</code></pre>
</div>
<h4 id="the-innertext-idl-attribute">The <code data-x="dom-innerText">innerText</code> and <code
data-x="dom-outerText">outerText</code> properties</h4>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-innerText">innerText</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the element's text content "as rendered".</p>
<p>Can be set, to replace the element's children with the given value, but with line breaks
converted to <code>br</code> elements.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-outerText">outerText</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the element's text content "as rendered".</p>
<p>Can be set, to replace the element with the given value, but with line breaks converted to
<code>br</code> elements.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn export>get the text steps</dfn>, given an <span>HTMLElement</span>
<var>element</var>, are:</p>
<ol>
<li>
<p>If <var>element</var> is not <span>being rendered</span> or if the user agent is a non-CSS
user agent, then return <var>element</var>'s <span>descendant text content</span>.</p>
<p class="note">This step can produce surprising results, as when the <code
data-x="dom-innerText">innerText</code> getter is invoked on an element not <span>being
rendered</span>, its text contents are returned, but when accessed on an element that is
<span>being rendered</span>, all of its children that are not <span>being rendered</span> have
their text contents ignored.</p>
</li>
<li><p>Let <var>results</var> be a new empty <span>list</span>.</p></li>
<li>
<p>For each child node <var>node</var> of <var>element</var>:</p>
<ol>
<li><p>Let <var>current</var> be the <span>list</span> resulting in running the <span>rendered
text collection steps</span> with <var>node</var>. Each item in <var>results</var> will either
be a <span>string</span> or a positive integer (a <i>required line break count</i>).</p>
<p class="note">Intuitively, a <i>required line break count</i> item means that a certain
number of line breaks appear at that point, but they can be collapsed with the line breaks
induced by adjacent <i>required line break count</i> items, reminiscent to CSS
margin-collapsing.</p>
<li><p>For each item <var>item</var> in <var>current</var>, append <var>item</var> to
<var>results</var>.</p></li>
</ol>
</li>
<li><p><span data-x="list remove">Remove</span> any items from <var>results</var> that are the
empty string.</p></li>
<li><p><span data-x="list remove">Remove</span> any runs of consecutive <i>required line break
count</i> items at the start or end of <var>results</var>.</p></li>
<li><p><span data-x="list replace">Replace</span> each remaining run of consecutive <i>required
line break count</i> items with a string consisting of as many U+000A LF code points as the
maximum of the values in the <i>required line break count</i> items.</p></li>
<li><p>Return the concatenation of the string items in <var>results</var>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-innerText">innerText</code></dfn> and
<dfn attribute for="HTMLElement"><code data-x="dom-outerText">outerText</code></dfn> getter steps
are to return the result of running <span>get the text steps</span> with <span>this</span>.</p>
<p>The <dfn>rendered text collection steps</dfn>, given a <span>node</span> <var>node</var>,
are as follows:</p>
<ol>
<li><p>Let <var>items</var> be the result of running the <span>rendered text collection
steps</span> with each child node of <var>node</var> in <span>tree order</span>, and then
concatenating the results to a single <span>list</span>.</p></li>
<li><p>If <var>node</var>'s <span>computed value</span> of <span>'visibility'</span> is not
'visible', then return <var>items</var>.</p></li>
<li>
<p>If <var>node</var> is not <span>being rendered</span>, then return <var>items</var>. For the
purpose of this step, the following elements must act as described if the
<span>computed value</span> of the <span>'display'</span> property is not 'none':</p>
<ul>
<li><p><code>select</code> elements have an associated non-replaced inline <span>CSS box</span>
whose child boxes include only those of <code>optgroup</code> and <code>option</code> element
child nodes;</p></li>
<li><p><code>optgroup</code> elements have an associated non-replaced block-level <span>CSS
box</span> whose child boxes include only those of <code>option</code> element child nodes;
and</p></li>
<li><p><code>option</code> element have an associated non-replaced block-level <span>CSS
box</span> whose child boxes are as normal for non-replaced block-level <span data-x="CSS
box">CSS boxes</span>.</p></li>
</ul>
<p class="note"><var>items</var> can be non-empty due to 'display:contents'.</p>
</li>
<li><p>If <var>node</var> is a <code>Text</code> node, then for each CSS text box produced by
<var>node</var>, in content order, compute the text of the box after application of the CSS
<span>'white-space'</span> processing rules and <span>'text-transform'</span> rules, set
<var>items</var> to the <span>list</span> of the resulting strings, and return <var>items</var>.
The CSS <span>'white-space'</span> processing rules are slightly modified: collapsible spaces at
the end of lines are always collapsed, but they are only removed if the line is the last line of
the block, or it ends with a <code>br</code> element. Soft hyphens should be preserved.
<ref>CSSTEXT</ref></p></li>
<li><p>If <var>node</var> is a <code>br</code> element, then <span data-x="list
append">append</span> a string containing a single U+000A LF code point to
<var>items</var>.</p></li>
<li><p>If <var>node</var>'s <span>computed value</span> of <span>'display'</span> is
<span>'table-cell'</span>, and <var>node</var>'s <span>CSS box</span> is not the last
<span>'table-cell'</span> box of its enclosing <span>'table-row'</span> box, then <span
data-x="list append">append</span> a string containing a single U+0009 TAB code point to
<var>items</var>.</p></li>
<li><p>If <var>node</var>'s <span>computed value</span> of <span>'display'</span> is
<span>'table-row'</span>, and <var>node</var>'s <span>CSS box</span> is not the last
<span>'table-row'</span> box of the nearest ancestor <span>'table'</span> box, then <span
data-x="list append">append</span> a string containing a single U+000A LF code point to
<var>items</var>.</p></li>
<li><p>If <var>node</var> is a <code>p</code> element, then <span data-x="list
append">append</span> 2 (a <i>required line break count</i>) at the beginning and end of
<var>items</var>.</p></li>
<li>
<p>If <var>node</var>'s <span>used value</span> of <span>'display'</span> is
<span>block-level</span> or <span>'table-caption'</span>, then <span data-x="list
append">append</span> 1 (a <i>required line break count</i>) at the beginning and end of
<var>items</var>. <ref>CSSDISPLAY</ref></p>
<p class="note">Floats and absolutely-positioned elements fall into this category.</p>
</li>
<li><p>Return <var>items</var>.</p></li>
</ol>
<p class="note">Note that descendant nodes of most replaced elements (e.g., <code>textarea</code>,
<code>input</code>, and <code>video</code> — but not <code>button</code>) are not rendered
by CSS, strictly speaking, and therefore have no <span data-x="CSS box">CSS boxes</span> for the
purposes of this algorithm.</p>
<p class="XXX">This algorithm is amenable to being generalized to work on <span
data-x="concept-range">ranges</span>. Then we can use it as the basis for <code>Selection</code>'s
stringifier and maybe expose it directly on <span data-x="concept-range">ranges</span>. See <a
href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=10583">Bugzilla bug 10583</a>.</p>
<hr>
<p>The <dfn export>set the inner text steps</dfn>, given an <span>HTMLElement</span>
<var>element</var>, and a string <var>value</var> are:</p>
<ol>
<li><p>Let <var>fragment</var> be the <span>rendered text fragment</span> for <var>value</var>
given <var>element</var>'s <span>node document</span>.</p></li>
<li><p><span data-x="concept-node-replace-all">Replace all</span> with <var>fragment</var>
within <var>element</var>.</p></li>
</ol>
<p>The <code data-x="dom-innerText">innerText</code> setter steps are to run <span>set the inner
text steps</span>.</p>
<p>The <code data-x="dom-outerText">outerText</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s parent is null, then throw a
<span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>next</var> be <span>this</span>'s <span>next sibling</span>.</p></li>
<li><p>Let <var>previous</var> be <span>this</span>'s <span>previous sibling</span>.</p></li>
<li><p>Let <var>fragment</var> be the <span>rendered text fragment</span> for the given value
given <span>this</span>'s <span>node document</span>.</p></li>
<li><p>If <var>fragment</var> has no <span data-x="concept-tree-child">children</span>, then
<span data-x="concept-node-append">append</span> a new <code>Text</code> node whose <span
data-x="concept-cd-data">data</span> is the empty string and <span>node document</span> is
<span>this</span>'s <span>node document</span> to <var>fragment</var>.</p></li>
<li><p><span data-x="concept-node-replace">Replace</span> <span>this</span> with
<var>fragment</var> within <span>this</span>'s parent.</p></li>
<li><p>If <var>next</var> is non-null and <var>next</var>'s <span>previous sibling</span> is a
<code>Text</code> node, then <span>merge with the next text node</span> given <var>next</var>'s
<span>previous sibling</span>.</p></li>
<li><p>If <var>previous</var> is a <code>Text</code> node, then <span>merge with the next text
node</span> given <var>previous</var>.</p></li>
</ol>
<p>The <dfn>rendered text fragment</dfn> for a string <var>input</var> given a
<code>Document</code> <var>document</var> is the result of running the following steps:</p>
<ol>
<li><p>Let <var>fragment</var> be a new <code>DocumentFragment</code> whose <span>node
document</span> is <var>document</var>.</p></li>
<li><p>Let <var>position</var> be a <span>position variable</span> for <var>input</var>,
initially pointing at the start of <var>input</var>.</p></li>
<li><p>Let <var>text</var> be the empty string.</p></li>
<li>
<p>While <var>position</var> is not past the end of <var>input</var>:</p>
<ol>
<li><p><span>Collect a sequence of code points</span> that are not U+000A LF or U+000D CR from
<var>input</var> given <var>position</var>, and set <var>text</var> to the result.</p></li>
<li><p>If <var>text</var> is not the empty string, then <span
data-x="concept-node-append">append</span> a new <code>Text</code> node whose <span
data-x="concept-cd-data">data</span> is <var>text</var> and <span>node document</span> is
<var>document</var> to <var>fragment</var>.</p></li>
<li>
<p>While <var>position</var> is not past the end of <var>input</var>, and the code point at
<var>position</var> is either U+000A LF or U+000D CR:</p>
<ol>
<li><p>If the code point at <var>position</var> is U+000D CR and the next code point is
U+000A LF, then advance <var>position</var> to the next code point in
<var>input</var>.</p></li>
<li><p>Advance <var>position</var> to the next code point in <var>input</var>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> the result of <span data-x="create an
element">creating an element</span> given <var>document</var>, "<code data-x="">br</code>",
and the <span>HTML namespace</span> to <var>fragment</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>fragment</var>.</p></li>
</ol>
<p>To <dfn>merge with the next text node</dfn> given a <code>Text</code> node <var>node</var>:</p>
<ol>
<li><p>Let <var>next</var> be <var>node</var>'s <span>next sibling</span>.</p></li>
<li><p>If <var>next</var> is not a <code>Text</code> node, then return.</p></li>
<li><p><span>Replace data</span> with <var>node</var>, <var>node</var>'s <span
data-x="concept-cd-data">data</span>'s <span>length</span>, 0, and <var>next</var>'s <span
data-x="concept-cd-data">data</span>.</p></li>
<li><p><span data-x="concept-node-remove">Remove</span> <var>next</var>.</p></li>
</ol>
</div>
<h4>Requirements relating to the bidirectional algorithm</h4>
<div w-nodev>
<h5>Authoring conformance criteria for bidirectional-algorithm formatting characters</h5>
</div>
<p><span>Text content</span> in <span>HTML elements</span> with <code>Text</code> nodes in their
<span data-x="concept-html-contents">contents</span>, and text in attributes of <span>HTML
elements</span> that allow free-form text, may contain characters in the ranges U+202A to U+202E
and U+2066 to U+2069 (the bidirectional-algorithm formatting characters). <ref>BIDI</ref></p>
<p class="note">Authors are encouraged to use the <code data-x="attr-dir">dir</code> attribute, the
<code>bdo</code> element, and the <code>bdi</code> element, rather than maintaining the
bidirectional-algorithm formatting characters manually. The bidirectional-algorithm formatting
characters interact poorly with CSS.</p>
<div w-nodev>
<h5>User agent conformance criteria</h5>
<p>User agents must implement the Unicode bidirectional algorithm to determine the proper ordering
of characters when rendering documents and parts of documents. <ref>BIDI</ref></p>
<p>The mapping of HTML to the Unicode bidirectional algorithm must be done in one of three ways.
Either the user agent must implement CSS, including in particular the CSS
<span>'unicode-bidi'</span>, <span>'direction'</span>, and <span>'content'</span> properties, and
must have, in its user agent style sheet, the rules using those properties given in this
specification's <a href="#rendering">rendering</a> section, or, alternatively, the user agent must
act as if it implemented just the aforementioned properties and had a user agent style sheet that
included all the aforementioned rules, but without letting style sheets specified in documents
override them, or, alternatively, the user agent must implement another styling language with
equivalent semantics. <ref>CSSGC</ref></p>
<p id="bidireq">The following elements and attributes have requirements defined by the <a
href="#rendering">rendering</a> section that, due to the requirements in this section, are
requirements on all user agents (not just those that <a href="#renderingUA">support the suggested
default rendering</a>):</p>
<ul class="brief">
<li><code data-x="attr-dir">dir</code> attribute</li>
<li><code>bdi</code> element</li>
<li><code>bdo</code> element</li>
<li><code>br</code> element</li>
<li><code>pre</code> element</li>
<li><code>textarea</code> element</li>
<li><code>wbr</code> element</li>
</ul>
</div>
<div w-nodev>
<h4 id="wai-aria">Requirements related to ARIA and to platform accessibility APIs</h4>
<p>User agent requirements for implementing Accessibility API semantics on <span>HTML
elements</span> are defined in <cite>HTML Accessibility API Mappings</cite>. In addition to the
rules there, for a <span>custom element</span> <var>element</var>, the default ARIA role semantics
are determined as follows: <ref>HTMLAAM</ref></p>
<ol>
<li><p>Let <var>map</var> be <var>element</var>'s <span>internal content attribute
map</span>.</p></li>
<li><p>If <var>map</var>["<code data-x="">role</code>"] <span data-x="map exists">exists</span>,
then return it.</p></li>
<li><p>Return no role.</p></li>
</ol>
<p>Similarly, for a <span>custom element</span> <var>element</var>, the default ARIA state and
property semantics, for a state or property named <var>stateOrProperty</var>, are determined as
follows:</p>
<ol>
<li>
<p>If <var>element</var>'s <span>attached internals</span> is non-null:</p>
<ol>
<li><p>If <var>element</var>'s <span>attached internals</span>'s <span data-x="get the
attr-associated element">get the <var>stateOrProperty</var>-associated element</span> exists,
then return the result of running it.</p></li>
<li><p>If <var>element</var>'s <span>attached internals</span>'s <span data-x="get the
attr-associated elements">get the <var>stateOrProperty</var>-associated elements</span> exists,
then return the result of running it.</p></li>
</ol>
<!-- We check these first as they end up being redundantly stored in element's internal content
attribute map with an empty string value. -->
<li><p>If <var>element</var>'s <span>internal content attribute
map</span>[<var>stateOrProperty</var>] <span data-x="map exists">exists</span>, then return
it.</p></li>
<li><p>Return the default value for <var>stateOrProperty</var>.</p></li>
</ol>
<p class="note">The "default semantics" referred to here are sometimes also called "native",
"implicit", or "host language" semantics in <cite>ARIA</cite>. <ref>ARIA</ref></p>
<p class="note">One implication of these definitions is that the default semantics can change over
time. This allows custom elements the same expressivity as built-in elements; e.g., compare to how
the default ARIA role semantics of an <code>a</code> element change as the <code
data-x="attr-hyperlink-href">href</code> attribute is added or removed.</p>
<p>For an example of this in action, see <a href="#custom-elements-accessibility-example">the
custom elements section</a>.</p>
<hr>
<p>Conformance checker requirements for checking use of ARIA <code
data-x="attr-aria-role">role</code> and <code data-x="attr-aria-*">aria-*</code> attributes on
<span>HTML elements</span> are defined in <cite>ARIA in HTML</cite>. <ref>ARIAHTML</ref></p>
</div>
<h2 split-filename="semantics" id="semantics">The elements of HTML</h2>
<h3 id="the-root-element">The document element</h3>
<h4 id="the-html-element">The <dfn element><code>html</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As document's <span>document element</span>.</dd>
<dd>Wherever a subdocument fragment is allowed in a compound document.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>A <code>head</code> element followed by a <code>body</code> element.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-html">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-html">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLHtmlElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLHtmlElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLHtmlElement</code>.</dd>
</dl>
<p>The <code>html</code> element <span>represents</span> the root of an HTML document.</p>
<p>Authors are encouraged to specify a <code data-x="attr-lang">lang</code> attribute on the root
<code>html</code> element, giving the document's language. This aids speech synthesis tools to
determine what pronunciations to use, translation tools to determine what rules to use, and so
forth.</p>
<div class="example">
<p>The <code>html</code> element in the following example declares that the document's language
is English.</p>
<pre><code class="html"><!DOCTYPE html>
<strong><html lang="en"></strong>
<head>
<title>Swapping Songs</title>
</head>
<body>
<h1>Swapping Songs</h1>
<p>Tonight I swapped some of the songs I wrote with some friends, who
gave me some of the songs they wrote. I love sharing my music.</p>
</body>
<strong></html></strong></code></pre>
</div>
<h3>Document metadata</h3>
<h4 id="the-head-element">The <dfn element><code>head</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the first element in an <code>html</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the document is <span>an <code>iframe</code> <code data-x="attr-iframe-srcdoc">srcdoc</code> document</span> or if title information is available from a higher-level protocol: Zero or more elements of <span>metadata content</span>, of which no more than one is a <code>title</code> element and no more than one is a <code>base</code> element.</dd>
<dd>Otherwise: One or more elements of <span>metadata content</span>, of which exactly one is a <code>title</code> element and no more than one is a <code>base</code> element.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-head">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-head">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLHeadElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLHeadElement</code>.</dd>
</dl>
<p>The <code>head</code> element <span>represents</span> a collection of metadata for the
<code>Document</code>.</p>
<div class="example">
<p>The collection of metadata in a <code>head</code> element can be large or small. Here is an
example of a very short one:</p>
<pre><code class="html"><!doctype html>
<html lang=en>
<head>
<title>A document with a short head</title>
</head>
<body>
...</code></pre>
<p>Here is an example of a longer one:</p>
<pre><code class="html"><!DOCTYPE HTML>
<HTML LANG="EN">
<HEAD>
<META CHARSET="UTF-8">
<BASE HREF="https://www.example.com/">
<TITLE>An application with a long head</TITLE>
<LINK REL="STYLESHEET" HREF="default.css">
<LINK REL="STYLESHEET ALTERNATE" HREF="big.css" TITLE="Big Text">
<SCRIPT SRC="support.js"></SCRIPT>
<META NAME="APPLICATION-NAME" CONTENT="Long headed application">
</HEAD>
<BODY>
...</code></pre>
</div>
<p class="note">The <code>title</code> element is a required child in most situations, but when a
higher-level protocol provides title information, e.g., in the subject line of an email when HTML
is used as an email authoring format, the <code>title</code> element can be omitted.</p>
<h4 id="the-title-element">The <dfn element><code>title</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>In a <code>head</code> element containing no other <code>title</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="text content">Text</span> that is not <span>inter-element whitespace</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-title">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-title">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTitleElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-title-text">text</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTitleElement</code>.</dd>
</dl>
<p>The <code>title</code> element <span>represents</span> the document's title or name. Authors
should use titles that identify their documents even when they are used out of context, for
example in a user's history or bookmarks, or in search results. The document's title is often
different from its first heading, since the first heading does not have to stand alone when taken
out of context.</p>
<p>There must be no more than one <code>title</code> element per document.</p>
<p class="note">If it's reasonable for the <code>Document</code> to have no title, then the
<code>title</code> element is probably not required. See the <code>head</code> element's content
model for a description of when the element is required.</p>
<dl class="domintro">
<dt><code data-x=""><var>title</var>.<span subdfn data-x="dom-title-text">text</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>child text content</span> of the element.</p>
<p>Can be set, to replace the element's children with the given value.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLTitleElement"><code data-x="dom-title-text">text</code></dfn>
attribute's getter must return this <code>title</code> element's <span>child text
content</span>.</p>
<p>The <code data-x="dom-title-text">text</code> attribute's setter must <span>string replace
all</span> with the given value within this <code>title</code> element.</p>
</div>
<div class="example">
<p>Here are some examples of appropriate titles, contrasted with the top-level headings that
might be used on those same pages.</p>
<pre><code class="html"> <title>Introduction to The Mating Rituals of Bees</title>
...
<h1>Introduction</h1>
<p>This companion guide to the highly successful
<cite>Introduction to Medieval Bee-Keeping</cite> book is...</code></pre>
<p>The next page might be a part of the same site. Note how the title describes the subject
matter unambiguously, while the first heading assumes the reader knows what the context is and
therefore won't wonder if the dances are Salsa or Waltz:</p>
<pre><code class="html"> <title>Dances used during bee mating rituals</title>
...
<h1>The Dances</h1></code></pre>
</div>
<p>The string to use as the document's title is given by the <code
data-x="dom-document-title">document.title</code> IDL attribute.</p>
<div w-nodev>
<p>User agents should use the document's title when referring to the document in their user
interface. When the contents of a <code>title</code> element are used in this way, <span>the
directionality</span> of that <code>title</code> element should be used to set the directionality
of the document's title in the user interface.</p>
</div>
<h4>The <dfn element><code>base</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>In a <code>head</code> element containing no other <code>base</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-base-href">href</code></dd>
<dd><code data-x="attr-base-target">target</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-base">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-base">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLBaseElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-base-href">href</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-base-target">target</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLBaseElement</code>.</dd>
</dl>
<p>The <code>base</code> element allows authors to specify the <span>document base URL</span> for
the purposes of parsing <span data-x="URL">URLs</span>, and the name of the default
<span>navigable</span> for the purposes of <span>following hyperlinks</span>. The element does not
<span data-x="represents">represent</span> any content beyond this information.</p>
<p>There must be no more than one <code>base</code> element per document.</p>
<p>A <code>base</code> element must have either an <code data-x="attr-base-href">href</code>
attribute, a <code data-x="attr-base-target">target</code> attribute, or both.</p>
<p>The <dfn element-attr for="base"><code data-x="attr-base-href">href</code></dfn> content
attribute, if specified, must contain a <span>valid URL potentially surrounded by
spaces</span>.</p>
<p>A <code>base</code> element, if it has an <code data-x="attr-base-href">href</code> attribute,
must come before any other elements in the tree that have attributes defined as taking <span
data-x="URL">URLs</span>.</p>
<div w-nodev>
<p class="note">If there are multiple <code>base</code> elements with <code
data-x="attr-base-href">href</code> attributes, all but the first are ignored.</p>
</div>
<p>The <dfn element-attr for="base"><code data-x="attr-base-target">target</code></dfn> attribute,
if specified, must contain a <span>valid navigable target name or keyword</span>, which specifies
which <span>navigable</span> is to be used as the default when <span
data-x="hyperlink">hyperlinks</span> and <span data-x="form">forms</span> in the
<code>Document</code> cause <span data-x="navigate">navigation</span>.</p>
<p>A <code>base</code> element, if it has a <code data-x="attr-base-target">target</code>
attribute, must come before any elements in the tree that represent <span
data-x="hyperlink">hyperlinks</span>.</p>
<div w-nodev>
<p class="note">If there are multiple <code>base</code> elements with <code
data-x="attr-base-target">target</code> attributes, all but the first are ignored.</p>
<p>To <dfn>get an element's target</dfn>, given an <code>a</code>, <code>area</code>, or
<code>form</code> element <var>element</var>, and an optional string-or-null <var>target</var>
(default null), run these steps:
<ol>
<li>
<p>If <var>target</var> is null, then:</p>
<ol>
<li><p>If <var>element</var> has a <code data-x="">target</code> attribute, then set
<var>target</var> to that attribute's value.</p></li>
<li><p>Otherwise, if <var>element</var>'s <span>node document</span> contains a
<code>base</code> element with a <code data-x="attr-base-target">target</code> attribute, set
<var>target</var> to the value of the <code data-x="attr-base-target">target</code> attribute
of the first such <code>base</code> element.</p></li>
</ol>
</li>
<li><p>If <var>target</var> is not null, and contains an <span>ASCII tab or newline</span> and a
U+003C (<), then set <var>target</var> to "<code data-x="">_blank</code>".</p></li>
<li><p>Return <var>target</var>.</p></li>
</ol>
<hr>
<p>A <code>base</code> element that is the first <code>base</code> element with an <code
data-x="attr-base-href">href</code> content attribute <span>in a document tree</span> has a
<dfn>frozen base URL</dfn>. The <span>frozen base URL</span> must be <span>immediately</span>
<span data-x="set the frozen base URL">set</span> for an element whenever any of the following
situations occur:</p>
<ul>
<li><p>The <code>base</code> element becomes the first <code>base</code> element in <span>tree
order</span> with an <code data-x="attr-base-href">href</code> content attribute in its
<code>Document</code>.</p></li>
<li><p>The <code>base</code> element is the first <code>base</code> element in <span>tree
order</span> with an <code data-x="attr-base-href">href</code> content attribute in its
<code>Document</code>, and its <code data-x="attr-base-href">href</code> content attribute is
changed.</p></li>
</ul>
<p>To <dfn export>set the frozen base URL</dfn> for an element <var>element</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>element</var>'s <span>node document</span>.
<li><p>Let <var>urlRecord</var> be the result of <span data-x="URL parser">parsing</span> the
value of <var>element</var>'s <code data-x="attr-base-href">href</code> content attribute with
<var>document</var>'s <span>fallback base URL</span>, and <var>document</var>'s <span
data-x="document's character encoding">character encoding</span>. (Thus, the <code>base</code>
element isn't affected by itself.)</p></li>
<!-- This uses the URL parser rather than encoding-parse a URL since otherwise we'd have to
unnecessarily complicate the latter for two callsites. -->
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>urlRecord</var> is failure;</p></li>
<li><p><var>urlRecord</var>'s <span data-x="concept-url-scheme">scheme</span> is "<code
data-x="">data</code>" or "<code data-x="">javascript</code>"; or</p></li>
<li><p>running <span>Is base allowed for Document?</span> on <var>urlRecord</var> and
<var>document</var> returns "<code data-x="">Blocked</code>",</p></li>
</ul>
<p>then set <var>element</var>'s <span>frozen base URL</span> to <var>document</var>'s
<span>fallback base URL</span> and return.</p>
</li>
<li><p>Set <var>element</var>'s <span>frozen base URL</span> to <var>urlRecord</var>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLBaseElement"><code data-x="dom-base-href">href</code></dfn> IDL
attribute, on getting, must return the result of running the following algorithm:
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1715
https://github.com/whatwg/html/issues/1060#issuecomment-211221664 -->
<ol>
<li><p>Let <var>document</var> be <var>element</var>'s <span>node document</span>.
<li><p>Let <var>url</var> be the value of the <code data-x="attr-base-href">href</code>
attribute of this element, if it has one, and the empty string otherwise.</p></li>
<li><p>Let <var>urlRecord</var> be the result of <span data-x="URL parser">parsing</span>
<var>url</var> with <var>document</var>'s <span>fallback base URL</span>, and
<var>document</var>'s <span data-x="document's character encoding">character encoding</span>.
(Thus, the <code>base</code> element isn't affected by other <code>base</code> elements or
itself.)</p></li>
<!-- This uses the URL parser rather than encoding-parse a URL since otherwise we'd have to
unnecessarily complicate the latter for two callsites. -->
<li><p>If <var>urlRecord</var> is failure, return <var>url</var>.</p></li>
<li><p>Return the <span data-x="concept-url-serializer">serialization</span> of
<var>urlRecord</var>.</p></li>
</ol>
<p>The <code data-x="dom-base-href">href</code> IDL attribute, on setting, must set the <code
data-x="attr-base-href">href</code> content attribute to the given new value.</p>
<p>The <dfn attribute for="HTMLBaseElement"><code data-x="dom-base-target">target</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>
</div>
<div class="example">
<p>In this example, a <code>base</code> element is used to set the <span>document base
URL</span>:</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<head>
<title>This is an example for the &lt;base&gt; element</title>
<base href="https://www.example.com/news/index.html">
</head>
<body>
<p>Visit the <a href="archives.html">archives</a>.</p>
</body>
</html></code></pre>
<p>The link in the above example would be a link to "<code
data-x="">https://www.example.com/news/archives.html</code>".</p>
</div>
<h4>The <dfn element><code>link</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dd>If the element is <span>allowed in the body</span>: <span>flow content</span>.</dd>
<dd>If the element is <span>allowed in the body</span>: <span>phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>metadata content</span> is expected.</dd>
<dd>In a <code>noscript</code> element that is a child of a <code>head</code> element.</dd>
<dd>If the element is <span>allowed in the body</span>: where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-link-href">href</code></dd>
<dd><code data-x="attr-link-crossorigin">crossorigin</code></dd>
<dd><code data-x="attr-link-rel">rel</code></dd>
<dd><code data-x="attr-link-media">media</code></dd>
<dd><code data-x="attr-link-integrity">integrity</code></dd>
<dd><code data-x="attr-link-hreflang">hreflang</code></dd>
<dd><code data-x="attr-link-type">type</code></dd>
<dd><code data-x="attr-link-referrerpolicy">referrerpolicy</code></dd>
<dd><code data-x="attr-link-sizes">sizes</code></dd>
<dd><code data-x="attr-link-imagesrcset">imagesrcset</code></dd>
<dd><code data-x="attr-link-imagesizes">imagesizes</code></dd>
<dd><code data-x="attr-link-as">as</code></dd>
<dd><code data-x="attr-link-blocking">blocking</code></dd>
<dd><code data-x="attr-link-color">color</code></dd>
<dd><code data-x="attr-link-disabled">disabled</code></dd>
<dd><code data-x="attr-link-fetchpriority">fetchpriority</code></dd>
<dd>Also, the <code data-x="attr-link-title">title</code> attribute <span data-x="attr-link-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-link">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-link">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLLinkElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-link-href">href</span>;
[<span>CEReactions</span>] attribute DOMString? <span data-x="dom-link-crossOrigin">crossOrigin</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-rel">rel</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-as">as</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-link-relList">relList</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-media">media</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-integrity">integrity</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-hreflang">hreflang</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-type">type</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-link-sizes">sizes</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-link-imageSrcset">imageSrcset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-imageSizes">imageSizes</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-referrerPolicy">referrerPolicy</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-link-blocking">blocking</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-link-disabled">disabled</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-fetchPriority">fetchPriority</span>;
// <a href="#HTMLLinkElement-partial">also has obsolete members</a>
};
<span>HTMLLinkElement</span> includes <span>LinkStyle</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLLinkElement</code>.</dd>
</dl>
<p>The <code>link</code> element allows authors to link their document to other resources.</p>
<p>The address of the link(s) is given by the <dfn element-attr for="link"><code
data-x="attr-link-href">href</code></dfn> attribute. If the <code
data-x="attr-link-href">href</code> attribute is present, then its value must be a <span>valid
non-empty URL potentially surrounded by spaces</span>. One or both of the <code
data-x="attr-link-href">href</code> or <code data-x="attr-link-imagesrcset">imagesrcset</code>
attributes must be present.</p>
<p w-nodev>If both the <code data-x="attr-link-href">href</code> and <code
data-x="attr-link-imagesrcset">imagesrcset</code> attributes are absent, then the element does not
define a link.</p>
<p>The types of link indicated (the relationships) are given by the value of the <dfn element-attr
for="link"><code data-x="attr-link-rel">rel</code></dfn> attribute, which, if present, must have a
value that is a <span>unordered set of unique space-separated tokens</span>. The <a
href="#linkTypes">allowed keywords and their meanings</a> are defined in a later section. <span
w-nodev>If the <code data-x="attr-link-rel">rel</code> attribute is absent, has no keywords, or if
none of the keywords used are allowed according to the definitions in this specification, then the
element does not create any links.</span></p>
<div w-nodev>
<p><code data-x="attr-link-rel">rel</code>'s
<span data-x="concept-supported-tokens">supported tokens</span> are the keywords defined in
<a href="#linkTypes">HTML link types</a> which are allowed on <code>link</code> elements, impact
the processing model, and are supported by the user agent. The possible <span
data-x="concept-supported-tokens">supported tokens</span> are
<code data-x="rel-alternate">alternate</code>,
<code data-x="rel-dns-prefetch">dns-prefetch</code>,
<code data-x="rel-expect">expect</code>,
<code data-x="rel-icon">icon</code>,
<code data-x="rel-manifest">manifest</code>,
<code data-x="rel-modulepreload">modulepreload</code>,
<code data-x="rel-next">next</code>,
<code data-x="rel-pingback">pingback</code>,
<code data-x="rel-preconnect">preconnect</code>,
<code data-x="rel-prefetch">prefetch</code>,
<code data-x="rel-preload">preload</code>,
<code data-x="rel-search">search</code>, and
<code data-x="rel-stylesheet">stylesheet</code>.
<code data-x="attr-link-rel">rel</code>'s <span data-x="concept-supported-tokens">supported
tokens</span> must only include the tokens from this list that the user agent implements the
processing model for.</p>
<p class="note">Theoretically a user agent could support the processing model for the <code
data-x="rel-canonical">canonical</code> keyword — if it were a search engine that executed
JavaScript. But in practice that's quite unlikely. So in most cases, <code
data-x="rel-canonical">canonical</code> ought not be included in <code
data-x="attr-link-rel">rel</code>'s <span data-x="concept-supported-tokens">supported
tokens</span>.</p>
</div>
<p>A <code>link</code> element must have either a <code data-x="attr-link-rel">rel</code>
attribute or an <code data-x="attr-itemprop">itemprop</code> attribute, but not both.</p>
<p>If a <code>link</code> element has an <code data-x="attr-itemprop">itemprop</code> attribute,
or has a <code data-x="attr-link-rel">rel</code> attribute that contains only keywords that are
<span>body-ok</span>, then the element is said to be <dfn>allowed in the body</dfn>. This means
that the element can be used where <span>phrasing content</span> is expected.</p>
<p class="note">If the <code data-x="attr-link-rel">rel</code> attribute is used, the element can
only sometimes be used in the <code>body</code> of the page. When used with the <code
data-x="attr-itemprop">itemprop</code> attribute, the element can be used both in the
<code>head</code> element and in the <code>body</code> of the page, subject to the constraints of
the microdata model.</p>
<hr>
<p>Two categories of links can be created using the <code>link</code> element: <span
data-x="external resource link">links to external resources</span> and <span
data-x="hyperlink">hyperlinks</span>. The <a href="#linkTypes">link types section</a> defines
whether a particular link type is an external resource or a hyperlink. One <code>link</code>
element can create multiple links (of which some might be <span data-x="external resource
link">external resource links</span> and some might be <span
data-x="hyperlink">hyperlinks</span>); exactly which and how many links are created depends on the
keywords given in the <code data-x="attr-link-rel">rel</code> attribute. User agents must process
the links on a per-link basis, not a per-element basis.</p>
<p class="note">Each link created for a <code>link</code> element is handled separately. For
instance, if there are two <code>link</code> elements with <code data-x="">rel="stylesheet"</code>,
they each count as a separate external resource, and each is affected by its own attributes
independently. Similarly, if a single <code>link</code> element has a <code
data-x="attr-link-rel">rel</code> attribute with the value <code data-x="">next stylesheet</code>,
it creates both a <span>hyperlink</span> (for the <code data-x="rel-next">next</code> keyword) and
an <span>external resource link</span> (for the <code data-x="rel-stylesheet">stylesheet</code>
keyword), and they are affected by other attributes (such as <code
data-x="attr-link-media">media</code> or <code data-x="attr-link-title">title</code>)
differently.</p>
<div class="example">
<p>For example, the following <code>link</code> element creates two <span
data-x="hyperlink">hyperlinks</span> (to the same page):</p>
<pre><code class="html"><link rel="author license" href="/about"></code></pre>
<p>The two links created by this element are one whose semantic is that the target page has
information about the current page's author, and one whose semantic is that the target page has
information regarding the license under which the current page is provided.</p>
</div>
<p><span data-x="hyperlink">Hyperlinks</span> created with the <code>link</code> element and its
<code data-x="attr-link-rel">rel</code> attribute apply to the whole document. This contrasts with
the <code data-x="attr-hyperlink-rel">rel</code> attribute of <code>a</code> and <code>area</code>
elements, which indicates the type of a link whose context is given by the link's location within
the document.</p>
<p>Unlike those created by <code>a</code> and <code>area</code> elements, <span
data-x="hyperlink">hyperlinks</span> created by <code>link</code> elements are not displayed as
part of the document by default, in user agents that <a href="#renderingUA">support the suggested
default rendering</a>. And even if they are force-displayed using CSS, they have no
<span>activation behavior</span>. Instead, they primarily provide semantic information which might
be used by the page or by other software that consumes the page's contents. Additionally, the user
agent can <a
href="#providing-users-with-a-means-to-follow-hyperlinks-created-using-the-link-element">provide
its own UI for following such hyperlinks</a>.</p>
<p>The exact behavior for <span data-x="external resource link">links to external resources</span>
depends on the exact relationship, as defined for the relevant <a href="#linkTypes">link
type</a>.</p>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-crossorigin">crossorigin</code></dfn>
attribute is a <span>CORS settings attribute</span>. It is intended for use with <span
data-x="external resource link">external resource links</span>.</p>
<p>The <dfn element-attr for="link"><code data-x="attr-link-media">media</code></dfn> attribute
says which media the resource applies to. The value must be a <span>valid media query
list</span>.</p>
<p>The <dfn for="link" element-attr><code data-x="attr-link-integrity">integrity</code></dfn>
attribute represents the <span data-x="concept-request-integrity-metadata">integrity
metadata</span> for requests which this element is responsible for. The value is text. The
attribute must only be specified on <code>link</code> elements that have a <code
data-x="attr-link-rel">rel</code> attribute that contains the <code
data-x="rel-stylesheet">stylesheet</code>, <code data-x="rel-preload">preload</code>, or <code
data-x="rel-modulepreload">modulepreload</code> keyword. <ref>SRI</ref></p>
<p>The <dfn element-attr for="link"><code data-x="attr-link-hreflang">hreflang</code></dfn>
attribute on the <code>link</code> element has the same semantics as the <span
data-x="attr-hyperlink-hreflang"><code>hreflang</code> attribute on the <code>a</code>
element</span>.</p>
<p>The <dfn element-attr for="link"><code data-x="attr-link-type">type</code></dfn> attribute
gives the <span>MIME type</span> of the linked resource. It is purely advisory. The value must be
a <span>valid MIME type string</span>.</p>
<p>For <span data-x="external resource link">external resource links</span>, the <code
data-x="attr-link-type">type</code> attribute is used as a hint to user agents so that they can
avoid fetching resources they do not support.</p>
<p>The <dfn element-attr for="link"><code
data-x="attr-link-referrerpolicy">referrerpolicy</code></dfn> attribute is a <span>referrer policy
attribute</span>. It is intended for use with <span data-x="external resource link">external
resource links</span>, where it helps set the <span>referrer policy</span> used when <span
data-x="fetch and process the linked resource">fetching and processing the linked resource</span>.
<ref>REFERRERPOLICY</ref></p>
<p>The <dfn element-attr for="link"><code data-x="attr-link-title">title</code></dfn> attribute
gives the title of the link. With one exception, it is purely advisory. The value is text. The
exception is for style sheet links that are <span>in a document tree</span>, for which the <code
data-x="attr-link-title">title</code> attribute defines <span data-x="CSS style sheet set">CSS
style sheet sets</span>.</p>
<p class="note">The <code data-x="attr-link-title">title</code> attribute on <code>link</code>
elements differs from the global <code data-x="attr-title">title</code> attribute of most other
elements in that a link without a title does not inherit the title of the parent element: it
merely has no title.</p>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-imagesrcset">imagesrcset</code></dfn>
attribute may be present, and is a <span>srcset attribute</span>.</p>
<p>The <code data-x="attr-link-imagesrcset">imagesrcset</code> and <code
data-x="attr-link-href">href</code> attributes (if <span data-x="width descriptor">width
descriptors</span> are not used) together contribute the <span data-x="image source">image
sources</span> to the <span>source set</span>.</p>
<p>If the <code data-x="attr-link-imagesrcset">imagesrcset</code> attribute is present and has any
<span data-x="image candidate string">image candidate strings</span> using a <span>width
descriptor</span>, the <dfn element-attr for="link"><code
data-x="attr-link-imagesizes">imagesizes</code></dfn> attribute must also be present, and is a
<span>sizes attribute</span>. The <code data-x="attr-link-imagesizes">imagesizes</code> attribute
contributes the <span>source size</span> to the <span>source set</span>.</p>
<p>The <code data-x="attr-link-imagesrcset">imagesrcset</code> and <code
data-x="attr-link-imagesizes">imagesizes</code> attributes must only be specified on
<code>link</code> elements that have both a <code data-x="attr-link-rel">rel</code> attribute that
specifies the <code data-x="rel-preload">preload</code> keyword, as well as an <code
data-x="attr-link-as">as</code> attribute in the "<code data-x="">image</code>" state.</p>
<div class="example">
<p>These attributes allow preloading the appropriate resource that is later used by an
<code>img</code> element that has the corresponding values for its <code
data-x="attr-img-srcset">srcset</code> and <code data-x="attr-img-sizes">sizes</code>
attributes:</p>
<pre><code class="html"><link rel="preload" as="image"
imagesrcset="wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w"
imagesizes="50vw">
<!-- ... later, or perhaps inserted dynamically ... -->
<img src="wolf.jpg" alt="A rad wolf"
srcset="wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w"
sizes="50vw"></code></pre>
<p>Note how we omit the <code data-x="attr-link-href">href</code> attribute, as it would only
be relevant for browsers that do not support <code
data-x="attr-link-imagesrcset">imagesrcset</code>, and in those cases it would likely cause the
incorrect image to be preloaded.</p>
</div>
<div class="example">
<p>The <code data-x="attr-link-imagesrcset">imagesrcset</code> attribute can be combined with the
<code data-x="attr-link-media">media</code> attribute to preload the appropriate resource
selected from a <code>picture</code> element's sources, for <span>art direction</span>:</p>
<pre><code class="html"><link rel="preload" as="image"
imagesrcset="dog-cropped-1x.jpg, dog-cropped-2x.jpg 2x"
media="(max-width: 800px)">
<link rel="preload" as="image"
imagesrcset="dog-wide-1x.jpg, dog-wide-2x.jpg 2x"
media="(min-width: 801px)">
<!-- ... later, or perhaps inserted dynamically ... -->
<picture>
<source srcset="dog-cropped-1x.jpg, dog-cropped-2x.jpg 2x"
media="(max-width: 800px)">
<img src="dog-wide-1x.jpg" srcset="dog-wide-2x.jpg 2x"
alt="An awesome dog">
</picture></code></pre>
</div>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-sizes">sizes</code></dfn> attribute
gives the sizes of icons for visual media. Its value, if present, is merely advisory.<span
w-nodev> User agents may use the value to decide which icon(s) to use if multiple icons are
available.</span> If specified, the attribute must have a value that is an <span>unordered set of
unique space-separated tokens</span> which are <span>ASCII case-insensitive</span>. Each value
must be either an <span>ASCII case-insensitive</span> match for the string "<code
data-x="attr-link-sizes-any">any</code>", or a value that consists of two <span data-x="valid
non-negative integer">valid non-negative integers</span> that do not have a leading U+0030 DIGIT
ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN
CAPITAL LETTER X character. The attribute must only be specified on <code>link</code> elements
that have a <code data-x="attr-link-rel">rel</code> attribute that specifies the <code
data-x="rel-icon">icon</code> keyword or the <code data-x="">apple-touch-icon</code> keyword.</p>
<p class="note">The <code data-x="">apple-touch-icon</code> keyword is a registered <span
data-x="concept-rel-extensions">extension to the predefined set of link types</span>, but user
agents are not required to support it in any way.</p>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-as">as</code></dfn> attribute
specifies the <span data-x="concept-potential-destination">potential destination</span> for a
preload request for the resource given by the <code data-x="attr-link-href">href</code> attribute.
It is an <span>enumerated attribute</span>. Each <span
data-x="concept-potential-destination">potential destination</span> is a keyword for this
attribute, mapping to a state of the same name. The attribute must be specified on
<code>link</code> elements that have a <code data-x="attr-link-rel">rel</code> attribute that
contains the <code data-x="rel-preload">preload</code> keyword. It may be specified on
<code>link</code> elements that have a <code data-x="attr-link-rel">rel</code> attribute that
contains the <code data-x="rel-modulepreload">modulepreload</code> keyword; in such cases it must
have a value which is a <span data-x="concept-script-like-destination">script-like
destination</span>. For other <code>link</code> elements, it must not be specified.</p>
<p w-nodev>The processing model for how the <code data-x="attr-link-as">as</code> attribute is
used is given in an individual link type's <span>fetch and process the linked resource</span>
algorithm.</p>
<p class="note">The attribute does not have a <i data-x="missing value default">missing value
default</i> or <i data-x="invalid value default">invalid value default</i>, meaning that invalid
or missing values for the attribute map to no state. This is accounted for in the processing
model. For <code data-x="rel-preload">preload</code> links, both conditions are an error; for
<code data-x="rel-modulepreload">modulepreload</code> links, a missing value will be treated as
"<code data-x="">script</code>".</p>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-blocking">blocking</code></dfn>
attribute is a <span>blocking attribute</span>. It is used by link types <code
data-x="rel-stylesheet">stylesheet</code> and <code
data-x="rel-expect">expect</code>, and it must only be specified on link elements
that have a <code data-x="attr-link-rel">rel</code> attribute containing those keywords.</p>
<hr>
<p>The <dfn element-attr for="link"><code data-x="attr-link-color">color</code></dfn> attribute is
used with the <code data-x="">mask-icon</code> link type. The attribute must only be specified on
<code>link</code> elements that have a <code data-x="attr-link-rel">rel</code> attribute that
contains the <code data-x="">mask-icon</code> keyword. The value must be a string that matches the
CSS <span><color></span> production, defining a suggested color that user agents can use to
customize the display of the icon that the user sees when they pin your site.</p>
<p class="note">This specification does not have any user agent requirements for the <code
data-x="attr-link-color">color</code> attribute.</p>
<p class="note">The <code data-x="">mask-icon</code> keyword is a registered <span
data-x="concept-rel-extensions">extension to the predefined set of link types</span>, but user
agents are not required to support it in any way.</p>
<hr>
<p><code>link</code> elements have an associated <dfn>explicitly enabled</dfn> boolean. It is
initially false.
<p>The <dfn element-attr for="link"><code data-x="attr-link-disabled">disabled</code></dfn>
attribute is a <span>boolean attribute</span> that is used with the <code
data-x="rel-stylesheet">stylesheet</code> link type. The attribute must only be specified on
<code>link</code> elements that have a <code data-x="attr-link-rel">rel</code> attribute that
contains the <code data-x="rel-stylesheet">stylesheet</code> keyword.</p>
<p>Whenever the <code data-x="attr-link-disabled">disabled</code> attribute is removed, set the
<code>link</code> element's <span>explicitly enabled</span> attribute to true.</p>
<div class="example">
<p>Removing the <code data-x="attr-link-disabled">disabled</code> attribute dynamically, e.g.,
using <code data-x="">document.querySelector("link").removeAttribute("disabled")</code>, will
fetch and apply the style sheet:</p>
<pre><code class="html"><link disabled rel="alternate stylesheet" href="css/pooh"></code></pre>
</div>
<p>The <dfn element-attr for="link"
data-x="attr-link-fetchpriority"><code>fetchpriority</code></dfn> attribute is a <span>fetch
priority attribute</span> that is intended for use with <span
data-x="external resource link">external resource links</span>, where it is used to set the <span
data-x="concept-request-priority">priority</span> used when <span
data-x="fetch and process the linked resource">fetching and processing the linked
resource</span>.</p>
<div w-nodev>
<hr>
<p>The IDL attributes
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-href">href</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-hreflang">hreflang</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-integrity">integrity</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-media">media</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-rel">rel</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-sizes">sizes</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-type">type</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-blocking">blocking</code></dfn>, and
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-disabled">disabled</code></dfn>
each must <span>reflect</span> the respective content attributes of the same name.</p>
<p class="note">There is no reflecting IDL attribute for the <code
data-x="attr-link-color">color</code> attribute, but this might be added later.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code data-x="dom-link-as">as</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-link-as">as</code> content attribute,
<span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code
data-x="dom-link-crossOrigin">crossOrigin</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-link-crossorigin">crossorigin</code> content attribute, <span>limited to only
known values</span>.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code
data-x="dom-link-referrerPolicy">referrerPolicy</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-link-referrerpolicy">referrerpolicy</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code
data-x="dom-link-fetchPriority">fetchPriority</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-link-fetchpriority">fetchpriority</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code
data-x="dom-link-imageSrcset">imageSrcset</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-link-imagesrcset">imagesrcset</code> content attribute.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code
data-x="dom-link-imageSizes">imageSizes</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-link-imagesizes">imagesizes</code> content attribute.</p>
<p>The <dfn attribute for="HTMLLinkElement"><code data-x="dom-link-rellist">relList</code></dfn>
IDL attribute must <span data-x="reflect">reflect</span> the <code
data-x="attr-link-rel">rel</code> content attribute.</p>
<p class="note">The <code data-x="dom-link-rellist">relList</code> attribute can be used for
feature detection, by calling its <code data-x="dom-DOMTokenList-supports">supports()</code>
method to check which <a href="#linkTypes">types of links</a> are supported.</p>
<h5>Processing the <code data-x="attr-link-media">media</code> attribute</h5>
<p>If the link is a <span>hyperlink</span> then the <code data-x="attr-link-media">media</code>
attribute is purely advisory, and describes for which media the document in question was
designed.</p>
<p>However, if the link is an <span>external resource link</span>, then the <code
data-x="attr-link-media">media</code> attribute is prescriptive. The user agent must apply the
external resource when the <code data-x="attr-link-media">media</code> attribute's value
<span>matches the environment</span> and the other relevant conditions apply, and must not apply
it otherwise.</p><!-- note similar text in <style> element section -->
<p id="default-media">The default, if the <code data-x="attr-link-media">media</code> attribute is
omitted, is "<code data-x="">all</code>", meaning that by default links apply to all media.</p>
<p class="note">The external resource might have further restrictions defined within that limit
its applicability. For example, a CSS style sheet might have some <code data-x="">@media</code>
blocks. This specification does not override such further restrictions or requirements.</p><!--
note similar text in <style> element section -->
<h5>Processing the <code data-x="attr-link-type">type</code> attribute</h5>
<p>If the <code data-x="attr-link-type">type</code> attribute is present, then the user agent must
assume that the resource is of the given type (even if that is not a <span>valid MIME type
string</span>, e.g. the empty string). If the attribute is omitted, but the <span>external
resource link</span> type has a default type defined, then the user agent must assume that the
resource is of that type. If the UA does not support the given <span>MIME type</span> for the
given link relationship, then the UA should not <span>fetch and process the linked
resource</span>; if the UA does support the given <span>MIME type</span> for the given link
relationship, then the UA should <span>fetch and process the linked resource</span> at the
appropriate time as specified for the <span>external resource link</span>'s particular type.
If the attribute is omitted, and the <span>external resource link</span> type does not have a
default type defined, but the user agent would <span>fetch and process the linked resource</span>
if the type was known and supported, then the user agent should <span>fetch and process the linked
resource</span> under the assumption that it will be supported.</p>
<p>User agents must not consider the <code data-x="attr-link-type">type</code> attribute
authoritative — upon fetching the resource, user agents must not use the <code
data-x="attr-link-type">type</code> attribute to determine its actual type. Only the actual type
(as defined in the next paragraph) is used to determine whether to <em>apply</em> the resource,
not the aforementioned assumed type.</p>
<p id="concept-link-type-sniffing">If the <span>external resource link</span> type defines rules
for processing the resource's <span data-x="Content-Type">Content-Type metadata</span>, then those
rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the
<span data-x="Content-Type sniffing: image">image sniffing rules</span>, with the <var>official
type</var> being the type determined from the resource's <span data-x="Content-Type">Content-Type
metadata</span>, and use the resulting <span data-x="Content-Type sniffing">computed type of the
resource</span> as if it was the actual type. Otherwise, if neither of these conditions apply or
if the user agent opts not to apply the image sniffing rules, then the user agent must use the
resource's <span data-x="Content-Type">Content-Type metadata</span> to determine the type of the
resource. If there is no type metadata, but the <span>external resource link</span> type has a
default type defined, then the user agent must assume that the resource is of that type.</p>
<p class="note">The <code data-x="rel-stylesheet">stylesheet</code> link type defines rules for
processing the resource's <span data-x="Content-Type">Content-Type metadata</span>.</p>
<p>Once the user agent has established the type of the resource, the user agent must apply the
resource if it is of a supported type and the other relevant conditions apply, and must ignore the
resource otherwise.</p>
<div class="example">
<p>If a document contains style sheet links labeled as follows:</p>
<pre><code class="html"><link rel="stylesheet" href="A" type="text/plain">
<link rel="stylesheet" href="B" type="text/css">
<link rel="stylesheet" href="C"></code></pre>
<p>...then a compliant UA that supported only CSS style sheets would fetch the B and C files, and
skip the A file (since <code>text/plain</code> is not the <span>MIME type</span> for CSS style
sheets).</p>
<p>For files B and C, it would then check the actual types returned by the server. For those that
are sent as <code>text/css</code>, it would apply the styles, but for those labeled as
<code>text/plain</code>, or any other type, it would not.</p>
<p>If one of the two files was returned without a <span>Content-Type</span> metadata, or with a
syntactically incorrect type like <code data-x="">Content-Type: "null"</code>, then the
default type for <code data-x="rel-stylesheet">stylesheet</code> links would kick in. Since that
default type is <code>text/css</code>, the style sheet <em>would</em> nonetheless be applied.</p>
</div>
<h5><span id="obtaining-a-resource-from-a-link-element"></span>Fetching and processing a resource
from a <code>link</code> element</h5>
<p id="concept-link-obtain">All <span data-x="external resource link">external resource
links</span> have a <dfn>fetch and process the linked resource</dfn> algorithm, which takes a
<code>link</code> element <var>el</var>. They also have <dfn>linked resource fetch setup
steps</dfn> which take a <code>link</code> element <var>el</var> and <span
data-x="concept-request">request</span> <var>request</var>. Individual link types may provide
their own <span>fetch and process the linked resource</span> algorithm, but unless explicitly
stated, they use the <span>default fetch and process the linked resource</span> algorithm.
Similarly, individual link types may provide their own <span>linked resource fetch setup
steps</span>, but unless explicitly stated, these steps just return true.</p>
<p>The <dfn>default fetch and process the linked resource</dfn>, given a <code>link</code> element
<var>el</var>, is as follows:</p>
<ol>
<li><p>Let <var>options</var> be the result of <span data-x="create link options from
element">creating link options</span> from <var>el</var>.</p></li>
<li><p>Let <var>request</var> be the result of <span data-x="create a link request">creating a
link request</span> given <var>options</var>.</p></li>
<li><p>If <var>request</var> is null, then return.</p></li>
<li><p>Set <var>request</var>'s <span>synchronous flag</span>.</p></li>
<li><p>Run the <span>linked resource fetch setup steps</span>, given <var>el</var> and
<var>request</var>. If the result is false, then return.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to "<code data-x="">css</code>" if <var>el</var>'s <code
data-x="attr-link-rel">rel</code> attribute contains the keyword <code
data-x="rel-stylesheet">stylesheet</code>; "<code data-x="">link</code>" otherwise.</p></li>
<li>
<p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var> with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to the following steps
given <span data-x="concept-response">response</span> <var>response</var> and null, failure, or
a <span>byte sequence</span> <var>bodyBytes</var>:</p>
<ol>
<li><p>Let <var>success</var> be true.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>bodyBytes</var> is null or failure; or</p></li>
<li><p><var>response</var>'s <span data-x="concept-response-status">status</span> is not an
<span>ok status</span>,</p></li>
</ul>
<p>then set <var>success</var> to false.</p>
<p class="note">Note that content-specific errors, e.g., CSS parse errors or PNG decoding
errors, do not affect <var>success</var>.</p>
</li>
<li>
<p>Otherwise, wait for the <span data-x="external resource link">link
resource</span>'s <span>critical subresources</span> to finish loading.</p>
<p class="XXX">The specification that defines a link type's <span>critical subresources</span>
(e.g., CSS) is expected to describe how these subresources are fetched and processed. However,
since this is not currently explicit, this specification describes waiting for a <span
data-x="external resource link">link resource</span>'s <span>critical subresources</span> to
be fetched and processed, with the expectation that this will be done correctly.</p>
</li>
<li><p><span>Process the linked resource</span> given <var>el</var>, <var>success</var>,
<var>response</var>, and <var>bodyBytes</var>.</li>
</ol>
</li>
</ol>
<p>To <dfn>create a link request</dfn> given a <span>link processing options</span>
<var>options</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>options</var>'s <span data-x="link options href">href</span> is
not the empty string.</p></li>
<li><p>If <var>options</var>'s <span data-x="link options destination">destination</span> is
null, then return null.</p></li>
<li>
<p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>options</var>'s <span data-x="link options href">href</span>, relative to
<var>options</var>'s <span data-x="link options base url">base URL</span>.</p>
<p class="XXX">Passing the base URL instead of a document or environment is tracked by <a
href="https://github.com/whatwg/html/issues/9715">issue #9715</a>.</p>
</li>
<li><p>If <var>url</var> is failure, then return null.</p></li>
<li><p>Let <var>request</var> be the result of <span data-x="create a potential-CORS
request">creating a potential-CORS request</span> given <var>url</var>, <var>options</var>'s
<span data-x="link options destination">destination</span>, and <var>options</var>'s <span
data-x="link options crossorigin">crossorigin</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-policy-container">policy
container</span> to <var>options</var>'s <span data-x="link options policy container">policy
container</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-integrity-metadata">integrity
metadata</span> to <var>options</var>'s <span data-x="link options
integrity">integrity</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-nonce-metadata">cryptographic
nonce metadata</span> to <var>options</var>'s <span data-x="link options nonce">cryptographic
nonce metadata</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-referrer-policy">referrer
policy</span> to <var>options</var>'s <span data-x="link options referrer policy">referrer
policy</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to
<var>options</var>'s <span data-x="link options environment">environment</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-priority">priority</span> to
<var>options</var>'s <span data-x="link options fetch priority">fetch priority</span>.</p></li>
<li><p>Return <var>request</var>.</p></li>
</ol>
<p>User agents may opt to only try to <span data-x="fetch and process the linked resource">fetch
and process</span> such resources when they are needed, instead of pro-actively fetching all the
<span data-x="external resource link">external resources</span> that are not applied.</p>
<!-- the next few paragraphs are similar to text in the <style> element section -->
<!-- TODO: integrate this better with Fetch's process response definition -->
<p>Similar to the <span>fetch and process the linked resource</span> algorithm, all <span
data-x="external resource link">external resource links</span> have a <dfn>process the linked
resource</dfn> algorithm which takes a <code>link</code> element <var>el</var>, boolean
<var>success</var>, a <span data-x="concept-response">response</span> <var>response</var>, and a
<span>byte sequence</span> <var>bodyBytes</var>. Individual link types may provide their own
<span>process the linked resource</span> algorithm, but unless explicitly stated, that algorithm
does nothing.</p>
<p>Unless otherwise specified for a given <code data-x="attr-link-rel">rel</code> keyword, the
element must <span>delay the load event</span> of the element's <span>node document</span> until
all the attempts to <span>fetch and process the linked resource</span> and its <span>critical
subresources</span> are complete. (Resources that the user agent has not yet attempted to fetch
and process, e.g., because it is waiting for the resource to be needed, do not <span>delay the
load event</span>.)</p>
<h5>Processing `<code data-x="http-link">Link</code>` headers</h5>
<p>All link types that can be <span data-x="external resource link">external resource
links</span> define a <dfn>process a link header</dfn> algorithm, which takes a <span>link
processing options</span>. This algorithm defines whether and how they react to appearing in an
HTTP `<code data-x="http-link">Link</code>` response header.</p>
<p class="note">For most link types, this algorithm does nothing. The <a
href="#table-link-relations">summary table</a> is a good reference to quickly know whether a link
type has defined <span>process a link header</span> steps.</p>
<p>A <dfn>link processing options</dfn> is a <span>struct</span>. It has the following
<span data-x="struct item">items</span>:</p>
<dl>
<dt><dfn data-x="link options href">href</dfn> (default the empty string)</dt>
<dt><dfn data-x="link options destination">destination</dfn> (default the empty string)</dt>
<dt><dfn data-x="link options initiator">initiator</dfn> (default "<code
data-x="">link</code>")</dt>
<dt><dfn data-x="link options integrity">integrity</dfn> (default the empty string)</dt>
<dt><dfn data-x="link options type">type</dfn> (default the empty string)</dt>
<dt><dfn data-x="link options nonce">cryptographic nonce metadata</dfn> (default the empty
string)</dt>
<dd>A string</dd>
<dt><dfn data-x="link options crossorigin">crossorigin</dfn> (default <span
data-x="attr-crossorigin-none">No CORS</span>)</dt>
<dd>A <span>CORS settings attribute</span> state</dd>
<dt><dfn data-x="link options referrer policy">referrer policy</dfn> (default the empty
string)</dt>
<dd>A <span>referrer policy</span></dd>
<dt><dfn data-x="link options source set">source set</dfn> (default null)</dt>
<dd>Null or a <span>source set</span></dd>
<dt><dfn data-x="link options base URL">base URL</dfn></dt>
<dd>A <span>URL</span></dd>
<dt><dfn data-x="link options origin">origin</dfn></dt>
<dd>An <span>origin</span></dd>
<dt><dfn data-x="link options environment">environment</dfn></dt>
<dd>An <span>environment</span></dd>
<dt><dfn data-x="link options policy container">policy container</dfn></dt>
<dd>A <span>policy container</span></dd>
<dt><dfn data-x="link options document">document</dfn> (default null)</dt>
<dd>Null or a <code>Document</code></dd>
<dt><dfn data-x="link options on document ready">on document ready</dfn> (default null)</dt>
<dd>Null or an algorithm accepting a <code>Document</code></dd>
<dt><dfn data-x="link options fetch priority">fetch priority</dfn> (default <code
data-x="attr-fetchpriority-auto-state">auto</code>)</dt>
<dd>A <span>fetch priority attribute</span> state</dd>
</dl>
<p class="note">A <span>link processing options</span> has a <span
data-x="link options base URL">base URL</span> and an <span data-x="link options href">href</span>
rather than a parsed URL because the URL could be a result of the options's <span
data-x="link options source set">source set</span>.</p>
<p>To <dfn>create link options from element</dfn> given a <code>link</code> element
<var>el</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>el</var>'s <span>node document</span>.</p></li>
<li>
<p>Let <var>options</var> be a new <span>link processing options</span> with</p>
<dl class="props">
<dt><span data-x="link options destination">destination</span></dt>
<dd>the result of <span
data-x="translate a preload destination">translating</span> the state of <var>el</var>'s <code
data-x="attr-link-as">as</code> attribute.</dd>
<dt><span data-x="link options crossorigin">crossorigin</span></dt>
<dd>the state of <var>el</var>'s <code data-x="attr-link-crossorigin">crossorigin</code>
content attribute</dd>
<dt><span data-x="link options referrer policy">referrer policy</span></dt>
<dd>the state of <var>el</var>'s <code data-x="attr-link-referrerpolicy">referrerpolicy</code>
content attribute</dd>
<dt><span data-x="link options source set">source set</span></dt>
<dd><var>el</var>'s <span>source set</span></dd>
<dt><span data-x="link options base URL">base URL</span></dt>
<dd><var>document</var>'s <span>document base URL</span></dd>
<dt><span data-x="link options origin">origin</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="link options environment">environment</span></dt>
<dd><var>document</var>'s <span>relevant settings object</span></dd>
<dt><span data-x="link options policy container">policy container</span></dt>
<dd><var>document</var>'s <span
data-x="concept-document-policy-container">policy container</span></dd>
<dt><span data-x="link options document">document</span></dt>
<dd><var>document</var></dd>
<dt><span data-x="link options nonce">cryptographic nonce metadata</span></dt>
<dd>The current value of <var>el</var>'s <span>[[CryptographicNonce]]</span> internal slot</dd>
<dt><span data-x="link options fetch priority">fetch priority</span></dt>
<dd>the state of <var>el</var>'s <code data-x="attr-link-fetchpriority">fetchpriority</code>
content attribute</dd>
</dl>
</li>
<li><p>If <var>el</var> has an <code data-x="attr-link-href">href</code> attribute, then set
<var>options</var>'s <span data-x="link options href">href</span> to the value of
<var>el</var>'s <code data-x="attr-link-href">href</code> attribute.</p></li>
<li><p>If <var>el</var> has an <code data-x="attr-link-integrity">integrity</code> attribute,
then set <var>options</var>'s <span data-x="link options integrity">integrity</span> to the
value of <var>el</var>'s <code data-x="attr-link-integrity">integrity</code> content
attribute.</p></li>
<li><p>If <var>el</var> has a <code data-x="attr-link-type">type</code> attribute, then set
<var>options</var>'s <span data-x="link options type">type</span> to the value of
<var>el</var>'s <code data-x="attr-link-type">type</code> attribute.</p></li>
<li>
<p><span>Assert</span>: <var>options</var>'s <span data-x="link options href">href</span> is not
the empty string, or <var>options</var>'s <span data-x="link options source set">source
set</span> is not null.</p>
<p>A <code>link</code> element with neither an <code data-x="attr-link-href">href</code> or an
<code data-x="attr-link-imagesrcset">imagesrcset</code> does not represent a link.</p>
</li>
<li><p>Return <var>options</var>.</p></li>
</ol>
<p>To <dfn>extract links from headers</dfn> given a <span data-x="concept-header-list">header
list</span> <var>headers</var>:</p>
<ol>
<li><p>Let <var>links</var> be a new <span>list</span>.</p></li>
<li><p>Let <var>rawLinkHeaders</var> be the result of <span
data-x="concept-header-list-get-decode-split">getting, decoding, and splitting</span>
`<code>Link</code>` from <var>headers</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>linkHeader</var> of
<var>rawLinkHeaders</var>:</p>
<ol>
<li><p>Let <var>linkObject</var> be the result of <span data-x="parsing a link field
value">parsing</span> <var>linkHeader</var>. <ref>WEBLINK</ref></p></li>
<li><p>If <var>linkObject</var>["<code data-x="">target_uri</code>"] does not
<span data-x="map exists">exist</span>, then <span>continue</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>linkObject</var> to
<var>links</var>.</p></li>
</ol>
</li>
<li><p>Return <var>links</var>.</p></li>
</ol>
<p>To <dfn>process link headers</dfn> given a <code>Document</code> <var>doc</var>,
a <span data-x="concept-response">response</span> <var>response</var>, and a
"<code data-x="">pre-media</code>" or "<code data-x="">media</code>" <var>phase</var>:</p>
<ol>
<li><p>Let <var>links</var> be the result of <span data-x="extract links from
headers">extracting links</span> from <var>response</var>'s <span
data-x="concept-response-header-list">header list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>linkObject</var> in <var>links</var>:</p>
<ol>
<li><p>Let <var>rel</var> be <var>linkObject</var>["<code
data-x="">relation_type</code>"].</p></li>
<li><p>Let <var>attribs</var> be <var>linkObject</var>["<code
data-x="">target_attributes</code>"].</p></li>
<li><p>Let <var>expectedPhase</var> be "<code data-x="">media</code>" if either "<code
data-x="attr-img-srcset">srcset</code>", "<code
data-x="attr-link-imagesrcset">imagesrcset</code>", or "<code
data-x="attr-link-media">media</code>" <span data-x="map exists">exist</span> in
<var>attribs</var>; otherwise "<code data-x="">pre-media</code>".</p></li>
<li><p>If <var>expectedPhase</var> is not <var>phase</var>, then
<span>continue</span>.</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-media">media</code>"] <span data-x="map
exists">exists</span> and <var>attribs</var>["<code data-x="attr-link-media">media</code>"]
does not <span data-x="matches the environment">match the environment</span>, then
<span>continue</span>.</p></li>
<li>
<p>Let <var>options</var> be a new <span>link processing options</span> with</p>
<dl class="props">
<dt><span data-x="link options href">href</span></dt>
<dd><var>linkObject</var>["<code data-x="">target_uri</code>"]</dd>
<dt><span data-x="link options base URL">base URL</span></dt>
<dd><var>doc</var>'s <span>document base URL</span></dd>
<dt><span data-x="link options origin">origin</span></dt>
<dd><var>doc</var>'s <span data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="link options environment">environment</span></dt>
<dd><var>doc</var>'s <span>relevant settings object</span></dd>
<dt><span data-x="link options policy container">policy container</span></dt>
<dd><var>doc</var>'s <span data-x="concept-document-policy-container">policy
container</span></dd>
<dt><span data-x="link options document">document</span></dt>
<dd><var>doc</var></dd>
</dl>
</li>
<li><p><span>Apply link options from parsed header attributes</span> to <var>options</var>
given <var>attribs</var>.</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-imagesrcset">imagesrcset</code>"] <span
data-x="map exists">exists</span> and <var>attribs</var>["<code
data-x="attr-link-imagesizes">imagesizes</code>"] <span data-x="map exists">exists</span>,
then set <var>options</var>'s <span data-x="link options source set">source set</span> to the
result of <span data-x="create a source set">creating a source set</span> given
<var>linkObject</var>["<code data-x="">target_uri</code>"], <var>attribs</var>["<code
data-x="attr-link-imagesrcset">imagesrcset</code>"], <var>attribs</var>["<code
data-x="attr-link-imagesizes">imagesizes</code>"], and null.</p></li>
<li><p>Run the <span>process a link header</span> steps for <var>rel</var> given
<var>options</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>apply link options from parsed header attributes</dfn> to a <span>link processing
options</span> <var>options</var> given <var>attribs</var>:</p>
<ol>
<li><p>If <var>attribs</var>["<code data-x="attr-link-as">as</code>"] <span data-x="map
exists">exists</span>, then set <var>options</var>'s <span data-x="link options
destination">destination</span> to the result of <span
data-x="translate a preload destination">translating</span> <var>attribs</var>["<code
data-x="attr-link-as">as</code>"].</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-crossorigin">crossorigin</code>"] <span
data-x="map exists">exists</span> and is an <span>ASCII case-insensitive</span> match for one of
the <span>CORS settings attribute</span> <span data-x="enumerated attribute">keywords</span>,
then set <var>options</var>'s <span data-x="link options crossorigin">crossorigin</span> to the
<span>CORS settings attribute</span> state corresponding to that keyword.</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-integrity">integrity</code>"] <span
data-x="map exists">exists</span>, then set <var>options</var>'s <span data-x="link options
integrity">integrity</span> to <var>attribs</var>["<code
data-x="attr-link-integrity">integrity</code>"].</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-referrerpolicy">referrerpolicy</code>"]
<span data-x="map exists">exists</span> and is an <span>ASCII case-insensitive</span> match for
some <span>referrer policy</span>, then set <var>options</var>'s <span data-x="link options
referrer policy">referrer policy</span> to that <span>referrer policy</span>.</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-nonce">nonce</code>"]
<span data-x="map exists">exists</span>, then set <var>options</var>'s <span data-x="link
options nonce">nonce</span> to <var>attribs</var>["<code
data-x="attr-nonce">nonce</code>"].</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-type">type</code>"] <span data-x="map
exists">exists</span>, then set <var>options</var>'s <span data-x="link options
type">type</span> to <var>attribs</var>["<code data-x="attr-link-type">type</code>"].</p></li>
<li><p>If <var>attribs</var>["<code data-x="attr-link-fetchpriority">fetchpriority</code>"]
<span data-x="map exists">exists</span> and is an <span>ASCII case-insensitive</span> match for
a <span>fetch priority attribute</span> keyword, then set <var>options</var>'s <span
data-x="link options fetch priority">fetch priority</span> to that <span>fetch priority
attribute</span> keyword.</p></li>
</ol>
<h5>Early hints</h5>
<p><dfn>Early hints</dfn> allow user-agents to perform some operations, such as to speculatively
load resources that are likely to be used by the document, before the navigation request is fully
handled by the server and a response code is served. Servers can indicate early hints by serving a
<span data-x="concept-response">response</span> with a 103 status code before serving the final
<span data-x="concept-response">response</span>.<ref>RFC8297</ref></p>
<p class="note">For compatibility reasons <a
href="https://httpwg.org/specs/rfc8297.html#security-considerations">early hints are typically
delivered over HTTP/2 or above</a>, but for readability we use HTTP/1.1-style notation below.</p>
<div class="example">
<p>For example, given the following sequence of responses:</p>
<pre>103 Early Hint
Link: </image.png>; <span data-x="attr-link-rel">rel</span>=<span
data-x="rel-preload">preload</span>; <span data-x="attr-link-as">as</span>=image</pre>
<pre>200 OK
Content-Type: text/html
<!DOCTYPE html>
...
<img src="/image.png"></pre>
<p>the image will start loading before the HTML content arrives.</p>
</div>
<p class="note">Only the first early hint response served during the navigation is handled, and it
is discarded if it is succeeded by a cross-origin redirect.</p>
<p>In addition to the `<code data-x="http-link">Link</code>` headers, it is possible that the 103
response contains a <span>Content Security Policy</span> header, which is enforced when processing
the early hint.</p>
<div class="example">
<p>For example, given the following sequence of responses:</p>
<pre>103 Early Hint
Content-Security-Policy: style-src: self;
Link: </style.css>; <span data-x="attr-link-rel">rel</span>=<span
data-x="rel-preload">preload</span>; <span data-x="attr-link-as">as</span>=style</pre>
<pre>103 Early Hint
Link: </image.png>; <span data-x="attr-link-rel">rel</span>=<span
data-x="rel-preload">preload</span>; <span data-x="attr-link-as">as</span>=image</pre>
<pre>302 Redirect
Location: /alternate.html</pre>
<pre>200 OK
Content-Security-Policy: style-src: none;
Link: </font.ttf>; <span data-x="attr-link-rel">rel</span>=<span
data-x="rel-preload">preload</span>; <span data-x="attr-link-as">as</span>=font</pre>
<p>The font and style would be loaded, and the image will be discarded, as only the first early
hint response in the final redirect chain is respected. The late <span>Content Security
Policy</span> header comes after the request to fetch the style has already been performed, but
the style will not be accessible to the document.</p>
</div>
<p>To <dfn>process early hint headers</dfn> given a <span
data-x="concept-response">response</span> <var>response</var> and an <span>environment</span>
<var>reservedEnvironment</var>:</p>
<p class="note">Early-hint `<code data-x="http-link">Link</code>` headers are always processed
before `<code data-x="http-link">Link</code>` headers from the final <span
data-x="concept-response">response</span>, followed by <code>link</code> elements. This is
equivalent to prepending the contents of the early and final `<code
data-x="http-link">Link</code>` headers to the <code>Document</code>'s <code>head</code> element,
in respective order.</p>
<ol>
<li>
<p>Let <var>earlyPolicyContainer</var> be the result of <span>creating a policy container from
a fetch response</span> given <var>response</var> and <var>reservedEnvironment</var>.</p>
<p class="note">This allows the early hint <span data-x="concept-response">response</span> to
include a <span>Content Security Policy</span> which would be <span data-x="enforce the
policy">enforced</span> when fetching the early hint <span
data-x="concept-request">request</span>.</p>
</li>
<li><p>Let <var>links</var> be the result of <span data-x="extract links from
headers">extracting links</span> from <var>response</var>'s <span
data-x="concept-response-header-list">header list</span>.</p></li>
<li><p>Let <var>earlyHints</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>linkObject</var> in <var>links</var>:</p>
<p class="note">The moment we receive the early hint link header, we begin <span
data-x="concept-fetch">fetching</span> <var>earlyRequest</var>. If it comes back before the
<code>Document</code> is created, we set <var>earlyResponse</var> to the <span
data-x="concept-response">response</span> of that <span data-x="concept-fetch">fetch</span> and
once the <code>Document</code> is created we commit it (by making it available in the <span>map
of preloaded resources</span> as if it was a <code>link</code> element). If the
<code>Document</code> is created first, the <span data-x="concept-response">response</span> is
committed as soon as it becomes available.</p>
<ol>
<li><p>Let <var>rel</var> be <var>linkObject</var>["<code
data-x="">relation_type</code>"].</p></li>
<li>
<p>Let <var>options</var> be a new <span>link processing options</span> with</p>
<dl class="props">
<dt><span data-x="link options href">href</span></dt>
<dd><var>linkObject</var>["<code data-x="">target_uri</code>"]</dd>
<dt><span data-x="link options initiator">initiator</span></dt>
<dd>"<code data-x="">early-hint</code>"</dd>
<dt><span data-x="link options base URL">base URL</span></dt>
<dd><var>response</var>'s <span data-x="concept-response-url">URL</span></dd>
<dt><span data-x="link options origin">origin</span></dt>
<dd><var>response</var>'s <span data-x="concept-response-url">URL</span>'s <span
data-x="concept-url-origin">origin</span></dd>
<dt><span data-x="link options environment">environment</span></dt>
<dd><var>reservedEnvironment</var></dd>
<dt><span data-x="link options policy container">policy container</span></dt>
<dd><var>earlyPolicyContainer</var></dd>
</dl>
</li>
<li>
<p>Let <var>attribs</var> be <var>linkObject</var>["<code
data-x="">target_attributes</code>"].</p>
<p class="note">Only the <code data-x="attr-link-as">as</code>, <code
data-x="attr-link-crossorigin">crossorigin</code>, <code
data-x="attr-link-integrity">integrity</code>, and <code data-x="attr-link-type">type</code>
attributes are handled as part of early hint processing. The other ones, in particular <code
data-x="attr-link-blocking">blocking</code>, <code
data-x="attr-link-imagesrcset">imagesrcset</code>, <code
data-x="attr-link-imagesizes">imagesizes</code>, and <code
data-x="attr-link-media">media</code> are only applicable once a <code>Document</code> is
created.</p>
</li>
<li><p><span>Apply link options from parsed header attributes</span> to <var>options</var>
given <var>attribs</var>.</p></li>
<li><p>Run the <span>process a link header</span> steps for <var>rel</var> given
<var>options</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>options</var> to
<var>earlyHints</var>.</p></li>
</ol>
</li>
<li>
<p>Return the following substeps given <code>Document</code> <var>doc</var>: <span
data-x="list iterate">for each</span> <var>options</var> in <var>earlyHints</var>:</p>
<ol>
<li><p>If <var>options</var>'s <span
data-x="link options on document ready">on document ready</span> is null, then set
<var>options</var>'s <span data-x="link options document">document</span> to
<var>doc</var>.</p></li>
<li><p>Otherwise, call <var>options</var>'s <span
data-x="link options on document ready">on document ready</span> with <var>doc</var>.</p></li>
</ol>
</li>
</ol>
</div>
<h5>Providing users with a means to follow hyperlinks created using the <code>link</code>
element</h5>
<p id="linkui">Interactive user agents may provide users with a means to <span data-x="following
hyperlinks">follow the hyperlinks</span> created using the <code>link</code> element, somewhere
within their user interface. Such invocations of the <span data-x="following hyperlinks">follow
the hyperlink</span> algorithm must set the <i
data-x="following-userInvolvement">userInvolvement</i> argument to "<code
data-x="uni-browser-ui">browser UI</code>". The exact interface is not defined by this
specification, but it could include the following information (obtained from the element's
attributes, again as defined below), in some form or another (possibly simplified), for each
<span>hyperlink</span> created with each <code>link</code> element in the document:</p>
<ul> <!-- the order here is the order that makes most sense for a UI -->
<li>The relationship between this document and the resource (given by the <code
data-x="attr-link-rel">rel</code> attribute)</li>
<li>The title of the resource (given by the <code data-x="attr-link-title">title</code>
attribute).</li>
<li>The address of the resource (given by the <code data-x="attr-link-href">href</code>
attribute).</li>
<li>The language of the resource (given by the <code data-x="attr-link-hreflang">hreflang</code>
attribute).</li>
<li>The optimum media for the resource (given by the <code data-x="attr-link-media">media</code>
attribute).</li>
</ul>
<p>User agents could also include other information, such as the type of the resource (as given by
the <code data-x="attr-link-type">type</code> attribute).</p>
<h4 id="the-meta-element">The <dfn element id="meta"><code>meta</code></dfn>
element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dd>If the <code data-x="attr-itemprop">itemprop</code> attribute is present: <span>flow content</span>.</dd>
<dd>If the <code data-x="attr-itemprop">itemprop</code> attribute is present: <span>phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>If the <code data-x="attr-meta-charset">charset</code> attribute is present, or if the element's <code data-x="attr-meta-http-equiv">http-equiv</code> attribute is in the <span data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span>: in a <code>head</code> element.</dd>
<dd>If the <code data-x="attr-meta-http-equiv">http-equiv</code> attribute is present but not in the <span data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span>: in a <code>head</code> element.</dd>
<dd>If the <code data-x="attr-meta-http-equiv">http-equiv</code> attribute is present but not in the <span data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span>: in a <code>noscript</code> element that is a child of a <code>head</code> element.</dd>
<dd>If the <code data-x="attr-meta-name">name</code> attribute is present: where <span>metadata content</span> is expected.</dd>
<dd>If the <code data-x="attr-itemprop">itemprop</code> attribute is present: where <span>metadata content</span> is expected.</dd>
<dd>If the <code data-x="attr-itemprop">itemprop</code> attribute is present: where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-meta-name">name</code></dd>
<dd><code data-x="attr-meta-http-equiv">http-equiv</code></dd>
<dd><code data-x="attr-meta-content">content</code></dd>
<dd><code data-x="attr-meta-charset">charset</code></dd>
<dd><code data-x="attr-meta-media">media</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-meta">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-meta">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLMetaElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-meta-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-meta-httpEquiv">httpEquiv</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-meta-content">content</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-meta-media">media</span>;
// <a href="#HTMLMetaElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLMetaElement</code>.</dd>
</dl>
<p>The <code>meta</code> element <span>represents</span> various kinds of metadata that cannot be
expressed using the <code>title</code>, <code>base</code>, <code>link</code>, <code>style</code>,
and <code>script</code> elements.</p>
<p>The <code>meta</code> element can represent document-level metadata with the <code
data-x="attr-meta-name">name</code> attribute, pragma directives with the <code
data-x="attr-meta-http-equiv">http-equiv</code> attribute, and the file's <span>character encoding
declaration</span> when an HTML document is serialized to string form (e.g. for transmission over
the network or for disk storage) with the <code data-x="attr-meta-charset">charset</code>
attribute.</p>
<p>Exactly one of the <code data-x="attr-meta-name">name</code>, <code
data-x="attr-meta-http-equiv">http-equiv</code>, <code data-x="attr-meta-charset">charset</code>,
and <code data-x="attr-itemprop">itemprop</code> attributes must be specified.</p>
<p>If either <code data-x="attr-meta-name">name</code>, <code
data-x="attr-meta-http-equiv">http-equiv</code>, or <code data-x="attr-itemprop">itemprop</code> is
specified, then the <code data-x="attr-meta-content">content</code> attribute must also be
specified. Otherwise, it must be omitted.</p>
<p>The <dfn element-attr for="meta"><code data-x="attr-meta-charset">charset</code></dfn>
attribute specifies the <span data-x="encoding">character encoding</span> used by the document.
This is a <span>character encoding declaration</span>. If the attribute is present, its value must
be an <span>ASCII case-insensitive</span> match for the string "<code data-x="">utf-8</code>".</p>
<p class="note">The <code data-x="attr-meta-charset">charset</code> attribute on the
<code>meta</code> element has no effect in XML documents, but is allowed in XML documents in order
to facilitate migration to and from XML.</p>
<p>There must not be more than one <code>meta</code> element with a <code
data-x="attr-meta-charset">charset</code> attribute per document.</p>
<p>The <dfn for="meta" element-attr><code data-x="attr-meta-content">content</code></dfn>
attribute gives the value of the document metadata or pragma directive when the element is used
for those purposes. The allowed values depend on the exact context, as described in subsequent
sections of this specification.</p>
<p>If a <code>meta</code> element has a <dfn element-attr for="meta"><code
data-x="attr-meta-name">name</code></dfn> attribute, it sets document metadata. Document metadata
is expressed in terms of name-value pairs, the <code data-x="attr-meta-name">name</code> attribute
on the <code>meta</code> element giving the name, and the <code
data-x="attr-meta-content">content</code> attribute on the same element giving the value. The name
specifies what aspect of metadata is being set; valid names and the meaning of their values are
described in the following sections. If a <code>meta</code> element has no <code
data-x="attr-meta-content">content</code> attribute, then the value part of the metadata
name-value pair is the empty string.</p>
<p>The <dfn element-attr for="meta"><code data-x="attr-meta-media">media</code></dfn> attribute
says which media the metadata applies to. The value must be a <span>valid media query list</span>.
Unless the <code data-x="attr-meta-name">name</code> is <code
data-x="meta-theme-color">theme-color</code>, the <code data-x="attr-meta-media">media</code>
attribute has no effect on the processing model and must not be used by authors.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLMetaElement"><code data-x="dom-meta-name">name</code></dfn>, <dfn
attribute for="HTMLMetaElement"><code data-x="dom-meta-content">content</code></dfn>, and <dfn
attribute for="HTMLMetaElement"><code data-x="dom-meta-media">media</code></dfn> IDL attributes
must <span>reflect</span> the respective content attributes of the same name. The IDL attribute
<dfn attribute for="HTMLMetaElement"><code data-x="dom-meta-httpEquiv">httpEquiv</code></dfn> must
<span>reflect</span> the content attribute <code
data-x="attr-meta-http-equiv">http-equiv</code>.</p>
</div>
<h5>Standard metadata names</h5>
<p>This specification defines a few names for the <code data-x="attr-meta-name">name</code>
attribute of the <code>meta</code> element.</p>
<p>Names are case-insensitive<span class=impl>, and must be compared in an <span>ASCII
case-insensitive</span> manner</span>.</p>
<dl>
<dt><dfn attr-value for="meta/name"><code
data-x="meta-application-name">application-name</code></dfn></dt>
<dd>
<p>The value must be a short free-form string giving the name of the web application that the
page represents. If the page is not a web application, the <code
data-x="meta-application-name">application-name</code> metadata name must not be used.
Translations of the web application's name may be given, using the <code
data-x="attr-lang">lang</code> attribute to specify the language of each name.</p>
<p>There must not be more than one <code>meta</code> element with a given <span>language</span>
and where the <code data-x="attr-meta-name">name</code> attribute value is an
<span>ASCII case-insensitive</span> match for
<code data-x="meta-application-name">application-name</code> per document.</p>
<div w-nodev>
<p>User agents may use the application name in UI in preference to the page's
<code>title</code>, since the title might include status messages and the like relevant to the
status of the page at a particular moment in time instead of just being the name of the
application.</p>
<p>To find the application name to use given an ordered list of languages (e.g. British English,
American English, and English), user agents must run the following steps:</p>
<ol>
<li><p>Let <var>languages</var> be the list of languages.</p></li>
<li><p>Let <var>default language</var> be the <span>language</span> of the
<code>Document</code>'s <span>document element</span>, if any, and if that language is not
unknown.</p>
<li><p>If there is a <var>default language</var>, and if it is not the same language
as any of the languages in <var>languages</var>, append it to <var>languages</var>.</p></li>
<li>
<p>Let <var>winning language</var> be the first language in <var>languages</var> for which
there is a <code>meta</code> element in the <code>Document</code> where the
<code data-x="attr-meta-name">name</code> attribute value is an
<span>ASCII case-insensitive</span> match for
<code data-x="meta-application-name">application-name</code> and whose
<span>language</span> is the language in question.</p>
<p>If none of the languages have such a <code>meta</code> element, then return;
there's no given application name.</p>
</li>
<li>
<p>Return the value of the <code data-x="attr-meta-content">content</code> attribute of the
first <code>meta</code> element in the <code>Document</code> in <span>tree order</span> where the
<code data-x="attr-meta-name">name</code> attribute value is an
<span>ASCII case-insensitive</span> match for <code data-x="meta-application-name">application-name</code>
and whose <span>language</span> is <var>winning language</var>.</p>
</li>
</ol>
<p class="note">This algorithm would be used by a browser when it needs a name for the page, for
instance, to label a bookmark. The languages it would provide to the algorithm would be the
user's preferred languages.</p>
</div>
</dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-author">author</code></dfn></dt>
<dd><p>The value must be a free-form string giving the name of one of the page's
authors.</p></dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-description">description</code></dfn></dt>
<dd><p>The value must be a free-form string that describes the page. The value must be
appropriate for use in a directory of pages, e.g. in a search engine. There must not be more than
one <code>meta</code> element where the <code data-x="attr-meta-name">name</code> attribute value
is an <span>ASCII case-insensitive</span> match for
<code data-x="meta-description">description</code> per document.</p></dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-generator">generator</code></dfn></dt>
<dd>
<p>The value must be a free-form string that identifies one of the software packages used to
generate the document. This value must not be used on pages whose markup is not generated by
software, e.g. pages whose markup was written by a user in a text editor.</p>
<div class="example">
<p>Here is what a tool called "Frontweaver" could include in its output, in the page's
<code>head</code> element, to identify itself as the tool used to generate the page:</p>
<pre><code class="html"><meta name=generator content="Frontweaver 8.2"></code></pre>
</div>
</dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-keywords">keywords</code></dfn></dt>
<dd>
<p>The value must be a <span>set of comma-separated tokens</span>, each of which is a keyword
relevant to the page.</p>
<div class="example">
<p>This page about typefaces on British motorways uses a <code>meta</code> element to specify
some keywords that users might use to look for the page:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en-GB">
<head>
<title>Typefaces on UK motorways</title>
<meta name="keywords" content="british,type face,font,fonts,highway,highways">
</head>
<body>
...</code></pre>
</div>
<p class="note">Many search engines do not consider such keywords, because this feature has
historically been used unreliably and even misleadingly as a way to spam search engine results
in a way that is not helpful for users.</p>
<div w-nodev>
<p>To obtain the list of keywords that the author has specified as applicable to the page, the
user agent must run the following steps:</p>
<ol>
<li><p>Let <var>keywords</var> be an empty list.</p></li>
<li>
<p>For each <code>meta</code> element with a <code data-x="attr-meta-name">name</code>
attribute and a <code data-x="attr-meta-content">content</code> attribute and where the <code
data-x="attr-meta-name">name</code> attribute value is an <span>ASCII case-insensitive</span>
match for <code data-x="meta-keywords">keywords</code>:</p>
<ol>
<li><p><span data-x="split a string on commas">Split the value of the element's <code
data-x="attr-meta-content">content</code> attribute on commas</span>.</p></li>
<li><p>Add the resulting tokens, if any, to <var>keywords</var>.</p></li>
</ol>
</li>
<li><p>Remove any duplicates from <var>keywords</var>.</p></li>
<li><p>Return <var>keywords</var>. This is the list of keywords that the author has
specified as applicable to the page.</p></li>
</ol>
<p>User agents should not use this information when there is insufficient confidence in the
reliability of the value.</p>
<p class="example">For instance, it would be reasonable for a content management system to use
the keyword information of pages within the system to populate the index of a site-specific
search engine, but a large-scale content aggregator that used this information would likely find
that certain users would try to game its ranking mechanism through the use of inappropriate
keywords.</p>
</div>
</dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-referrer">referrer</code></dfn></dt>
<dd>
<p>The value must be a <span>referrer policy</span>, which defines the default <span>referrer
policy</span> for the <code>Document</code>. <ref>REFERRERPOLICY</ref></p>
<div w-nodev>
<p>If any <code>meta</code> element <var>element</var> is <span data-x="node is inserted into a
document">inserted into the document</span>, or has its <code
data-x="attr-meta-name">name</code> or <code data-x="attr-meta-content">content</code>
attributes changed, user agents must run the following algorithm:</p>
<ol>
<li><p>If <var>element</var> is not <span>in a document tree</span>, then return.</p></li>
<li><p>If <var>element</var> does not have a <code data-x="attr-meta-name">name</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for "<code
data-x="meta-referrer">referrer</code>", then return.</p></li>
<li><p>If <var>element</var> does not have a <code data-x="attr-meta-content">content</code>
attribute, or that attribute's value is the empty string, then return.</p></li>
<li><p>Let <var>value</var> be the value of <var>element</var>'s <code
data-x="attr-meta-content">content</code> attribute, <span>converted to ASCII
lowercase</span>.</p></li>
<li>
<p>If <var>value</var> is one of the values given in the first column of the following table,
then set <var>value</var> to the value given in the second column:</p>
<table>
<thead>
<tr>
<th>Legacy value
<th>Referrer policy
<tbody>
<tr>
<td><code data-x="">never</code>
<td><code data-x="referrer-policy-no-referrer">no-referrer</code>
<tr>
<td><code data-x="">default</code>
<td>the <span>default referrer policy</span>
<tr>
<td><code data-x="">always</code>
<td><code data-x="referrer-policy-unsafe-url">unsafe-url</code>
<tr>
<td><code data-x="">origin-when-crossorigin</code>
<td><code data-x="referrer-policy-origin-when-cross-origin">origin-when-cross-origin</code>
</table>
</li>
<li><p>If <var>value</var> is a <span>referrer policy</span>, then set <var>element</var>'s
<span>node document</span>'s <span data-x="concept-document-policy-container">policy
container</span>'s <span data-x="policy-container-referrer-policy">referrer policy</span> to
<var>policy</var>.</p></li>
</ol>
<p class="note">For historical reasons, unlike other standard metadata names, the processing
model for <code data-x="meta-referrer">referrer</code> is not responsive to element removals,
and does not use <span>tree order</span>. Only the most-recently-inserted or
most-recently-modified <code>meta</code> element in this state has an effect.</p>
</div>
</dd>
<dt><dfn attr-value for="meta/name"><code data-x="meta-theme-color">theme-color</code></dfn></dt>
<dd>
<p>The value must be a string that matches the CSS <span><color></span> production, defining
a suggested color that user agents should use to customize the display of the page or of the
surrounding user interface. For example, a browser might color the page's title bar with the
specified value, or use it as a color highlight in a tab bar or task switcher.</p>
<p>Within an HTML document, the <code data-x="attr-meta-media">media</code> attribute value must
be unique amongst all the <code>meta</code> elements with their <code
data-x="attr-meta-name">name</code> attribute value set to an <span>ASCII
case-insensitive</span> match for <code data-x="meta-theme-color">theme-color</code>.</p>
<div class="example">
<p>This standard itself uses "WHATWG green" as its theme color:</p>
<pre><code class="html"><!DOCTYPE HTML>
<title>HTML Standard</title>
<meta name="theme-color" content="#3c790a">
...</code></pre>
</div>
<p>The <code data-x="attr-meta-media">media</code> attribute may be used to describe the context
in which the provided color should be used.</p>
<div class="example">
<p>If we only wanted to use "WHATWG green" as this standard's theme color in dark mode,
we could use the <code data-x="">prefers-color-scheme</code> media feature:</p>
<pre><code class="html"><!DOCTYPE HTML>
<title>HTML Standard</title>
<meta name="theme-color" content="#3c790a" media="(prefers-color-scheme: dark)">
...</code></pre>
</div>
<div w-nodev>
<p>To obtain a page's theme color, user agents must run the following steps:</p>
<ol>
<li>
<p>Let <var>candidate elements</var> be the list of all <code>meta</code> elements that
meet the following criteria, in <span>tree order</span>:</p>
<ul>
<li><p>the element is <span>in a document tree</span>;</p></li>
<li><p>the element has a <code data-x="attr-meta-name">name</code> attribute, whose value
is an <span>ASCII case-insensitive</span> match for <code
data-x="meta-theme-color">theme-color</code>; and</p></li>
<li><p>the element has a <code data-x="attr-meta-content">content</code> attribute.</p></li>
</ul>
</li>
<li>
<p>For each <var>element</var> in <var>candidate elements</var>:</p>
<ol>
<li><p>If <var>element</var> has a <code data-x="attr-link-media">media</code> attribute
and the value of <var>element</var>'s <code data-x="attr-meta-media">media</code>
attribute does not <span data-x="matches the environment">match the environment</span>, then
<span>continue</span>.</p></li>
<li><p>Let <var>value</var> be the result of <span data-x="strip leading and trailing ASCII
whitespace">stripping leading and trailing ASCII whitespace</span> from the value of
<var>element</var>'s <code data-x="attr-meta-content">content</code> attribute.</p></li>
<li><p>Let <var>color</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> <var>value</var>.</p></li>
<li><p>If <var>color</var> is not failure, then return <var>color</var>.</p></li>
</ol>
</li>
<li><p>Return nothing (the page has no theme color).</p></li>
</ol>
<p>If any <code>meta</code> elements are <span data-x="node is inserted into a
document">inserted into the document</span> or <span data-x="node is removed from a
document">removed from the document</span>, or existing <code>meta</code> elements have their
<code data-x="attr-meta-name">name</code>, <code data-x="attr-meta-content">content</code>, or
<code data-x="attr-link-media">media</code> attributes changed, or if the environment changes
such that any <code>meta</code> element's <code data-x="attr-link-media">media</code>
attribute's value may now or may no longer <span data-x="matches the environment">match the
environment</span>, user agents must re-run the above algorithm and apply the result to any
affected UI.</p>
</div>
<p>When using the theme color in UI, user agents may adjust it in implementation-specific ways
to make it more suitable for the UI in question. For example, if a user agent intends to use
the theme color as a background and display white text over it, it might use a darker variant of
the theme color in that part of the UI, to ensure adequate contrast.</p>
</dd>
<dt><dfn attr-value for="meta/name"><code
data-x="meta-color-scheme">color-scheme</code></dfn></dt>
<dd>
<p>To aid user agents in rendering the page background with the desired color scheme immediately
(rather than waiting for all CSS in the page to load), a <span>'color-scheme'</span> value can
be provided in a <code>meta</code> element.</p>
<p>The value must be a string that matches the syntax for the CSS <span>'color-scheme'</span>
property value. It determines the <span>page's supported color-schemes</span>.</p>
<p>There must not be more than one <code>meta</code> element with its <code
data-x="attr-meta-name">name</code> attribute value set to an
<span>ASCII case-insensitive</span> match for <code
data-x="meta-color-scheme">color-scheme</code> per document.</p>
<div class="example">
<p>The following declaration indicates that the page is aware of and can handle a color scheme
with dark background colors and light foreground colors:</p>
<pre><code class="html"><meta name="color-scheme" content="dark"></code></pre>
</div>
<div w-nodev>
<p>To obtain a <span>page's supported color-schemes</span>, user agents must run the following steps:</p>
<ol>
<li>
<p>Let <var>candidate elements</var> be the list of all <code>meta</code> elements that
meet the following criteria, in <span>tree order</span>:</p>
<ul>
<li><p>the element is <span>in a document tree</span>;</p></li>
<li><p>the element has a <code data-x="attr-meta-name">name</code> attribute, whose value
is an <span>ASCII case-insensitive</span> match for <code
data-x="meta-color-scheme">color-scheme</code>; and</p></li>
<li><p>the element has a <code data-x="attr-meta-content">content</code> attribute.</p></li>
</ul>
</li>
<li>
<p>For each <var>element</var> in <var>candidate elements</var>:</p>
<ol>
<li>Let <var>parsed</var> be the result of <span data-x="parse a list of component
values">parsing a list of component values</span> given the value of <var>element</var>'s
<code data-x="attr-meta-content">content</code> attribute.</li>
<li>If <var>parsed</var> is a valid CSS <span>'color-scheme'</span> property value, then
return <var>parsed</var>.</li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<p>If any <code>meta</code> elements are <span data-x="node is inserted into a
document">inserted into the document</span> or <span data-x="node is removed from a
document">removed from the document</span>, or existing <code>meta</code> elements have their
<code data-x="attr-meta-name">name</code> or <code data-x="attr-meta-content">content</code>
attributes changed, user agents must re-run the above algorithm.</p>
</div>
<p class="note">Because these rules check successive elements until they find a match, an
author can provide multiple such values to handle fallback for legacy user agents. Opposite to
how CSS fallback works for properties, the multiple meta elements needs to be arranged with the
legacy values after the newer values.</p>
</dd>
</dl>
<h5>Other metadata names</h5>
<p>Anyone can create and use their own <dfn data-x="concept-meta-extensions">extensions to the
predefined set of metadata names</dfn>. There is no requirement to register such extensions.</p>
<p>However, a new metadata name should not be created in any of the following cases:</p>
<ul>
<li><p>If either the name is a <span>URL</span>, or the value of its accompanying <code
data-x="attr-meta-content">content</code> attribute is a <span>URL</span>; in those cases,
registering it as an <span data-x="concept-rel-extensions">extension to the predefined set of
link types</span> is encouraged (rather than creating a new metadata name).</p></li>
<li><p>If the name is for something expected to have processing requirements in user agents; in
that case it ought to be standardized.</p></li>
</ul>
<p>Also, before creating and using a new metadata name, consulting the <a
href="https://wiki.whatwg.org/wiki/MetaExtensions">WHATWG Wiki MetaExtensions page</a> is
encouraged — to avoid choosing a metadata name that's already in use, and to avoid duplicating the
purpose of any metadata names that are already in use, and to avoid new standardized names
clashing with your chosen name. <ref>WHATWGWIKI</ref></p>
<p>Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a metadata name.
New metadata names can be specified with the following information:</p>
<dl>
<dt>Keyword</dt>
<dd><p>The actual name being defined. The name should not be confusingly similar to any other
defined name (e.g. differing only in case).</p></dd>
<dt>Brief description</dt>
<dd><p>A short non-normative description of what the metadata name's meaning is, including the
format the value is required to be in.</p></dd>
<dt>Specification</dt>
<dd>A link to a more detailed description of the metadata name's semantics and requirements. It
could be another page on the wiki, or a link to an external page.</dd>
<dt>Synonyms</dt>
<dd><p>A list of other names that have exactly the same processing requirements. Authors should
not use the names defined to be synonyms (they are only intended to allow user agents to support
legacy content). Anyone may remove synonyms that are not used in practice; only names that need to
be processed as synonyms for compatibility with legacy content are to be registered in this
way.</p></dd>
<dt>Status</dt>
<dd>
<p>One of the following:</p>
<dl>
<dt>Proposed</dt>
<dd>The name has not received wide peer review and approval. Someone has proposed it and is, or
soon will be, using it.</dd>
<dt>Ratified</dt>
<dd>The name has received wide peer review and approval. It has a specification that
unambiguously defines how to handle pages that use the name, including when they use it in
incorrect ways.</dd>
<dt>Discontinued</dt>
<dd>The metadata name has received wide peer review and it has been found wanting. Existing
pages are using this metadata name, but new pages should avoid it. The "brief description" and
"specification" entries will give details of what authors should use instead, if anything.</dd>
</dl>
<p>If a metadata name is found to be redundant with existing values, it should be removed and
listed as a synonym for the existing value.</p>
<p>If a metadata name is added in the "proposed" state for a period of a month or more without
being used or specified, then it may be removed from the WHATWG Wiki MetaExtensions page.</p>
<p>If a metadata name is added with the "proposed" status and found to be redundant with
existing values, it should be removed and listed as a synonym for the existing value. If a
metadata name is added with the "proposed" status and found to be harmful, then it should be
changed to "discontinued" status.</p>
<p>Anyone can change the status at any time, but should only do so in accordance with the
definitions above.</p>
</dd>
</dl>
<h5>Pragma directives</h5>
<p>When the <dfn for="meta" element-attr><code
data-x="attr-meta-http-equiv">http-equiv</code></dfn> attribute is specified on a
<code>meta</code> element, the element is a pragma directive.</p>
<p>The <code data-x="attr-meta-http-equiv">http-equiv</code> attribute is an <span>enumerated
attribute</span> with the following keywords and states:</p>
<table class="yesno" id="table-http-equiv">
<thead>
<tr>
<th>Keyword
<th w-nodev>Conforming
<th>State
<th>Brief description
<tbody>
<tr w-nodev>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-content-language">content-language</code></dfn>
<td class="no">No
<td><span data-x="attr-meta-http-equiv-content-language">Content language</span>
<td>Sets the <span data-x="pragma-set default language">pragma-set default language</span>.
<tr>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-content-type">content-type</code></dfn>
<td w-nodev>
<td><span data-x="attr-meta-http-equiv-content-type">Encoding declaration</span>
<td>An alternative form of setting the <code data-x="attr-meta-charset">charset</code>.
<tr>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-default-style">default-style</code></dfn>
<td w-nodev>
<td><span data-x="attr-meta-http-equiv-default-style">Default style</span>
<td>Sets the <span data-x="CSS style sheet set name">name</span> of the default
<span>CSS style sheet set</span>.
<tr>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-refresh">refresh</code></dfn>
<td w-nodev>
<td><span data-x="attr-meta-http-equiv-refresh">Refresh</span>
<td>Acts as a timed redirect.
<tr w-nodev>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-set-cookie">set-cookie</code></dfn>
<td class="no">No
<td><span data-x="attr-meta-http-equiv-set-cookie">Set-Cookie</span>
<td>Has no effect.
<tr>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-x-ua-compatible">x-ua-compatible</code></dfn>
<td w-nodev>
<td><span data-x="attr-meta-http-equiv-x-ua-compatible">X-UA-Compatible</span>
<td>In practice, encourages Internet Explorer to more closely follow the specifications.
<tr>
<td><dfn attr-value for="meta/http-equiv"><code
data-x="attr-meta-http-equiv-keyword-content-security-policy">content-security-policy</code></dfn>
<td w-nodev>
<td><span data-x="attr-meta-http-equiv-content-security-policy">Content security policy</span>
<td><span data-x="enforce the policy">Enforces</span> a <span>Content Security
Policy</span> on a <code>Document</code>.
</table>
<!--
Content-Script-Type and Content-Style-Type don't do anything (and are non-conforming).
DATA: According to Henri's validator stats, here are common
non-conforming values used by people who validate (sample of 400
pages):
COUNT ERROR
20 Bad value "Content-Language" for attribute "http-equiv" on element "meta".
17 Bad value "Content-Style-Type" for attribute "http-equiv" on element "meta".
12 Bad value "Expires" for attribute "http-equiv" on element "meta".
11 Bad value "Pragma" for attribute "http-equiv" on element "meta".
11 Bad value "imagetoolbar" for attribute "http-equiv" on element "meta".
10 Bad value "Content-Script-Type" for attribute "http-equiv" on element "meta".
10 Bad value "content-language" for attribute "http-equiv" on element "meta".
[...]
https://hsivonen.com/test/moz/analysis.txt
Here's some more data, this time from Philip`, on a sample of 15k pages.
COUNT VALUE
1181 Content-Language
430 Content-Style-Type
342 imagetoolbar
276 content-language
269 Pragma
260 expires
227 Expires
211 pragma
146 Content-Script-Type
132 keywords
119 Page-Enter
116 description
106 reply-to
102 Cache-Control
[...]
https://philip.html5.org/data/meta-http-equiv.txt
These numbers are low; further study is required to establish what
people expect to have work and what is necessary.
-->
<div w-nodev>
<p>When a <code>meta</code> element is <span data-x="node is inserted into a document">inserted
into the document</span>, if its <code data-x="attr-meta-http-equiv">http-equiv</code> attribute is
present and represents one of the above states, then the user agent must run the algorithm
appropriate for that state, as described in the following list:</p>
</div>
<dl>
<dt w-nodev><dfn data-x="attr-meta-http-equiv-content-language">Content language state</dfn>
(<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-content-language">content-language</code>"</code>)
<dd w-nodev>
<p class="note">This feature is non-conforming. Authors are encouraged to use the <code
data-x="attr-lang">lang</code> attribute instead.</p>
<p>This pragma sets the <dfn>pragma-set default language</dfn>. Until such a pragma is
successfully processed, there is no <span>pragma-set default language</span>.</p>
<!-- https://www.hixie.ch/tests/adhoc/html/meta/content-language/ -->
<ol>
<li><p>If the <code>meta</code> element has no <code data-x="attr-meta-content">content</code>
attribute, then return.</p></li>
<li><p>If the element's <code data-x="attr-meta-content">content</code> attribute contains a
U+002C COMMA character (,) then return.</p></li><!-- if you remove this,
un-comment-out the corresponding bits in the step below. -->
<li><p>Let <var>input</var> be the value of the element's <code
data-x="attr-meta-content">content</code> attribute.</p></li>
<li><p>Let <var>position</var> point at the first character of <var>input</var>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are not <span>ASCII
whitespace</span> from <var>input</var> given <var>position</var>.</p></li>
<li><p>Let <var>candidate</var> be the string that resulted from the previous
step.</p></li>
<li><p>If <var>candidate</var> is the empty string, return.</p></li>
<li>
<p>Set the <span>pragma-set default language</span> to <var>candidate</var>.</p>
<p class="note">If the value consists of multiple space-separated tokens, tokens after the
first are ignored.</p>
</li>
</ol>
<p class="note">This pragma is almost, but not quite, entirely unlike the HTTP `<code
data-x="http-content-language">Content-Language</code>` header of the same name.
<ref>HTTP</ref></p>
</dd>
<dt><dfn data-x="attr-meta-http-equiv-content-type">Encoding declaration state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-content-type">content-type</code>"</code>)
<dd>
<p>The <span data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span> is
just an alternative form of setting the <code data-x="attr-meta-charset">charset</code>
attribute: it is a <span>character encoding declaration</span>. <span w-nodev>This state's user
agent requirements are all handled by the parsing section of the specification.</span></p>
<p>For <code>meta</code> elements with an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute in the <span data-x="attr-meta-http-equiv-content-type">Encoding declaration
state</span>, the <code data-x="attr-meta-content">content</code> attribute must have a value
that is an <span>ASCII case-insensitive</span> match for a string that consists of:
"<code data-x="">text/html;</code>", optionally followed by any number of <span>ASCII
whitespace</span>, followed by "<code data-x="">charset=utf-8</code>".</p>
<p>A document must not contain both a <code>meta</code> element with an <code
data-x="attr-meta-http-equiv">http-equiv</code> attribute in the <span
data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span> and a
<code>meta</code> element with the <code data-x="attr-meta-charset">charset</code> attribute
present.</p>
<p>The <span data-x="attr-meta-http-equiv-content-type">Encoding declaration state</span> may be
used in <span>HTML documents</span>, but elements with an <code
data-x="attr-meta-http-equiv">http-equiv</code> attribute in that state must not be used in
<span>XML documents</span>.</p>
</dd>
<dt><dfn data-x="attr-meta-http-equiv-default-style">Default style state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-default-style">default-style</code>"</code>)
<dd>
<p>This pragma sets the <span data-x="CSS style sheet set name">name</span> of the default
<span>CSS style sheet set</span>.</p>
<div w-nodev>
<ol>
<li><p>If the <code>meta</code> element has no <code data-x="attr-meta-content">content</code>
attribute, or if that attribute's value is the empty string, then return.</p></li>
<li><p><span>Change the preferred CSS style sheet set name</span> with the name being the value
of the element's <code data-x="attr-meta-content">content</code> attribute.
<ref>CSSOM</ref></p></li>
</ol>
</div>
</dd>
<dt><dfn data-x="attr-meta-http-equiv-refresh">Refresh state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-refresh">refresh</code>"</code>)
<dd>
<p>This pragma acts as a timed redirect.</p>
<p>A <code>Document</code> object has an associated <dfn for="Document">will declaratively
refresh</dfn> (a boolean). It is initially false.</p>
<div w-nodev>
<ol>
<li><p>If the <code>meta</code> element has no <code data-x="attr-meta-content">content</code>
attribute, or if that attribute's value is the empty string, then return.</p></li>
<li><p>Let <var>input</var> be the value of the element's <code
data-x="attr-meta-content">content</code> attribute.</p></li>
<li><p>Run the <span>shared declarative refresh steps</span> with the <code>meta</code>
element's <span>node document</span>, <var>input</var>, and the <code>meta</code>
element.</p></li>
</ol>
<p>The <dfn>shared declarative refresh steps</dfn>, given a <code>Document</code> object
<var>document</var>, string <var>input</var>, and optionally a <code>meta</code> element
<var>meta</var>, are as follows:</p>
<ol>
<li><p>If <var>document</var>'s <span>will declaratively refresh</span> is true, then
return.</p></li>
<li><p>Let <var>position</var> point at the first <span>code point</span> of
<var>input</var>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>Let <var>time</var> be 0.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and let the result be
<var>timeString</var>.</p></li>
<li>
<p>If <var>timeString</var> is the empty string, then:</p>
<ol>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is not U+002E (.), then return.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>time</var> to the result of parsing <var>timeString</var> using the
<span>rules for parsing non-negative integers</span>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> and
U+002E FULL STOP characters (.) from <var>input</var> given <var>position</var>. Ignore any
collected characters.</p></li>
<li><p>Let <var>urlRecord</var> be <var>document</var>'s <span
data-x="concept-document-URL">URL</span>.</p></li>
<li>
<p>If <var>position</var> is not past the end of <var>input</var>, then:</p>
<ol>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is not U+003B (;), U+002C (,), or <span>ASCII whitespace</span>, then return.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is U+003B (;) or U+002C (,), then advance <var>position</var> to the next <span>code
point</span>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>position</var> is not past the end of <var>input</var>, then:</p>
<ol>
<li><p>Let <var>urlString</var> be the substring of <var>input</var> from the
<span>code point</span> at <var>position</var> to the end of the string.</p></li>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is U+0055 (U) or U+0075 (u), then advance <var>position</var> to the next <span>code
point</span>. Otherwise, jump to the step labeled <i>skip quotes</i>.</p></li>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is U+0052 (R) or U+0072 (r), then advance <var>position</var> to the next <span>code
point</span>. Otherwise, jump to the step labeled <i>parse</i>.</p></li>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is U+004C (L) or U+006C (l), then advance <var>position</var> to the next <span>code
point</span>. Otherwise, jump to the step labeled <i>parse</i>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If the <span>code point</span> in <var>input</var> pointed to by <var>position</var>
is U+003D (=), then advance <var>position</var> to the next <span>code point</span>.
Otherwise, jump to the step labeled <i>parse</i>.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p><i>Skip quotes</i>: If the <span>code point</span> in <var>input</var> pointed to by
<var>position</var> is U+0027 (') or U+0022 ("), then let <var>quote</var> be that <span>code
point</span>, and advance <var>position</var> to the next <span>code point</span>. Otherwise,
let <var>quote</var> be the empty string.</p></li>
<li><p>Set <var>urlString</var> to the substring of <var>input</var> from the <span>code
point</span> at <var>position</var> to the end of the string.</p></li>
<li><p>If <var>quote</var> is not the empty string, and there is a <span>code point</span> in
<var>urlString</var> equal to <var>quote</var>, then truncate <var>urlString</var> at that
<span>code point</span>, so that it and all subsequent <span data-x="code point">code
points</span> are removed.</p>
<li><p><i>Parse</i>: Set <var>urlRecord</var> to the result of <span>encoding-parsing a
URL</span> given <var>urlString</var>, relative to <var>document</var>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then return.</p></li>
</ol>
</li>
<li><p>Set <var>document</var>'s <span>will declaratively refresh</span> to true.</p></li>
<li>
<p>Perform one or more of the following steps:</p>
<ul>
<li>
<p>After the refresh has come due (as defined below), if the user has not canceled the
redirect and, if <var>meta</var> is given, <var>document</var>'s <span>active sandboxing
flag set</span> does not have the <span>sandboxed automatic features browsing context
flag</span> set, then <span data-x="navigate">navigate</span><!--DONAV meta refresh-->
<var>document</var>'s <span>node navigable</span> to <var>urlRecord</var> using
<var>document</var>, with <i data-x="navigation-hh">historyHandling</i> set to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
<p>For the purposes of the previous paragraph, a refresh is said to have come due as soon as
the <em>later</em> of the following two conditions occurs:</p>
<ul>
<li>At least <var>time</var> seconds have elapsed since <var>document</var>'s
<span>completely loaded time</span>, adjusted to take into account user or user agent
preferences.</li>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=774 -->
<li>If <var>meta</var> is given, at least <var>time</var> seconds have elapsed since
<var>meta</var> was <span data-x="node is inserted into a document">inserted into the
document</span> <var>document</var>, adjusted to take into account user or user agent
preferences.</li>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=772 -->
</ul>
<p class="note">It is important to use <var>document</var> here, and not <var>meta</var>'s
<span>node document</span>, as that might have changed between the initial set of steps and
the refresh coming due and <var>meta</var> is not always given (in case of the HTTP
`<code>Refresh</code>` header).</p>
</li>
<li><p>Provide the user with an interface that, when selected, <span
data-x="navigate">navigates</span><!--DONAV meta refresh--> <var>document</var>'s <span>node
navigable</span> to <var>urlRecord</var> using <var>document</var>.</p></li>
<li><p>Do nothing.</p></li>
</ul>
<p>In addition, the user agent may, as with anything, inform the user of any and all aspects
of its operation, including the state of any timers, the destinations of any timed redirects,
and so forth.</p>
</li>
</ol>
</div>
<p id="conformance-attr-meta-http-equiv-refresh">For <code>meta</code> elements with an <code
data-x="attr-meta-http-equiv">http-equiv</code> attribute in the <span
data-x="attr-meta-http-equiv-refresh">Refresh state</span>, the <code
data-x="attr-meta-content">content</code> attribute must have a value consisting either of:</p>
<ul>
<li>just a <span>valid non-negative integer</span>, or</li>
<li>a <span>valid non-negative integer</span>, followed by a U+003B SEMICOLON character
(;)<!--(add this at some point once the browsers all support it) or a U+002C COMMA character
(,)-->, followed by one or more <span>ASCII whitespace</span>, followed by a substring that is
an <span>ASCII case-insensitive</span> match for the string "<code data-x="">URL</code>",
followed by a U+003D EQUALS SIGN character (=), followed by a <span>valid URL string</span>
that does not start with a literal U+0027 APOSTROPHE (') or U+0022 QUOTATION MARK (")
character.</li>
</ul>
<p>In the former case, the integer represents a number of seconds before the page is to be
reloaded; in the latter case the integer represents a number of seconds before the page is to be
replaced by the page at the given <span>URL</span>.</p>
<div class="example">
<p>A news organization's front page could include the following markup in the page's
<code>head</code> element, to ensure that the page automatically reloads from the server every
five minutes:</p>
<pre><code class="html"><meta http-equiv="Refresh" content="300"></code></pre>
</div>
<div class="example">
<p>A sequence of pages could be used as an automated slide show by making each page refresh to
the next page in the sequence, using markup such as the following:</p>
<pre><code class="html"><meta http-equiv="Refresh" content="20; URL=page4.html"></code></pre>
</div>
</dd>
<dt w-nodev><dfn data-x="attr-meta-http-equiv-set-cookie">Set-Cookie state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-set-cookie">set-cookie</code>"</code>)
<dd w-nodev>
<p>This pragma is non-conforming and has no effect.</p>
<p>User agents are required to ignore this pragma.</p>
</dd>
<dt><dfn data-x="attr-meta-http-equiv-x-ua-compatible">X-UA-Compatible state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-x-ua-compatible">x-ua-compatible</code>"</code>)
<dd>
<p>In practice, this pragma encourages Internet Explorer to more closely follow the
specifications.</p>
<p>For <code>meta</code> elements with an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute in the <span data-x="attr-meta-http-equiv-x-ua-compatible">X-UA-Compatible state</span>, the
<code data-x="attr-meta-content">content</code> attribute must have a value that is an
<span>ASCII case-insensitive</span> match for the string "<code data-x="">IE=edge</code>".</p>
<p>User agents are required to ignore this pragma.</p>
</dd>
<dt><dfn export data-x="attr-meta-http-equiv-content-security-policy">Content security policy state</dfn> (<code data-x="">http-equiv="<code data-x="attr-meta-http-equiv-keyword-content-security-policy">content-security-policy</code>"</code>)
<dd>
<p>This pragma <span data-x="enforce the policy">enforces</span> a <span>Content Security
Policy</span> on a <code>Document</code>. <ref>CSP</ref></p>
<div w-nodev>
<ol>
<li><p>If the <code>meta</code> element is not a child of a <code>head</code> element,
return.</p></li>
<li><p>If the <code>meta</code> element has no <code data-x="attr-meta-content">content</code>
attribute, or if that attribute's value is the empty string, then return.</p></li>
<li><p>Let <var>policy</var> be the result of executing Content Security Policy's <span>parse
a serialized Content Security Policy</span> algorithm on the <code>meta</code> element's
<code data-x="attr-meta-content">content</code> attribute's value, with a source of "meta",
and a disposition of "enforce".</p></li>
<li><p>Remove all occurrences of the <code
data-x="report-uri directive">report-uri</code>, <code
data-x="frame-ancestors directive">frame-ancestors</code>, and <code
data-x="sandbox directive">sandbox</code> <span data-x="Content Security Policy
directive">directives</span> from <var>policy</var>.</p></li>
<li><p><span>Enforce the policy</span> <var>policy</var>.</p></li>
</ol>
</div>
<p>For <code>meta</code> elements with an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute in the <span data-x="attr-meta-http-equiv-content-security-policy">Content security
policy state</span>, the <code data-x="attr-meta-content">content</code> attribute must have a
value consisting of a <span data-x="Content Security Policy syntax">valid Content Security
Policy</span>, but must not contain any <code data-x="report-uri directive">report-uri</code>,
<code data-x="frame-ancestors directive">frame-ancestors</code>, or <code data-x="sandbox
directive">sandbox</code> <span data-x="Content Security Policy directive">directives</span>.
The <span>Content Security Policy</span> given in the <code
data-x="attr-meta-content">content</code> attribute will be <span data-x="enforce the
policy">enforced</span> upon the current document. <ref>CSP</ref></p>
<p class="note">At the time of inserting the <code>meta</code> element to the document, it is
possible that some resources have already been fetched. For example, images might be stored in
the <span>list of available images</span> prior to dynamically inserting a <code>meta</code>
element with an <code data-x="attr-meta-http-equiv">http-equiv</code> attribute in the <span
data-x="attr-meta-http-equiv-content-security-policy">Content security policy state</span>.
Resources that have already been fetched are not guaranteed to be blocked by a <span>Content
Security Policy</span> that's <span data-x="enforce the policy">enforced</span> late.</p>
<div class="example">
<p>A page might choose to mitigate the risk of cross-site scripting attacks by preventing the
execution of inline JavaScript, as well as blocking all plugin content, using a policy such
as the following:
<pre><code class="html"><meta http-equiv="Content-Security-Policy" content="script-src 'self'; object-src 'none'"></code></pre>
</div>
</dd>
</dl>
<p>There must not be more than one <code>meta</code> element with any particular state in the
document at a time.</p>
<h5 id="charset">Specifying the document's character encoding</h5>
<!-- READ ME WHEN EDITING: if we ever move this to the "writing HTML" section, then we have to
duplicate the requirements in the parsing section for conformance checkers, and we have to make
sure that the requirements for charset="" apply even in XML, for the <meta charset=""> polyglot
hack. -->
<p>A <dfn>character encoding declaration</dfn> is a mechanism by which the <span
data-x="encoding">character encoding</span> used to store or transmit a document is specified.</p>
<p>The Encoding standard requires use of the <span>UTF-8</span> <span data-x="encoding">character
encoding</span> and requires use of the "<code data-x="">utf-8</code>" <span>encoding label</span>
to identify it. Those requirements necessitate that the document's <span>character encoding
declaration</span>, if it exists, specifies an <span>encoding label</span> using an <span>ASCII
case-insensitive</span> match for "<code data-x="">utf-8</code>". Regardless of whether a
<span>character encoding declaration</span> is present or not, the actual <span data-x="document's
character encoding">character encoding</span> used to encode the document must be
<span>UTF-8</span>. <ref>ENCODING</ref></p>
<p w-nodev>To enforce the above rules, authoring tools must default to using <span>UTF-8</span>
for newly-created documents.</p>
<p>The following restrictions also apply:</p>
<ul>
<li>The character encoding declaration must be serialized without the use of <span
data-x="syntax-charref">character references</span> or character escapes of any kind.</li>
<li id="charset1024"><span data-x="" id="charset512">The element containing the character encoding
declaration must be serialized completely within the first 1024 bytes of the
document.</span></li> <!-- span is for historical reasons, to keep an old ID alive -->
</ul>
<p>In addition, due to a number of restrictions on <code>meta</code> elements, there can only be
one <code>meta</code>-based character encoding declaration per document.</p> <!-- conformance
criteria for this one are given in the XML spec, the <meta> section just after defining
charset="", and the character encoding pragma section. Note that you _can_ have two character
encoding declarations per document, if the document is an XML document and one is an XML
declaration, the other is <meta charset>, and the encoding is UTF-8. -->
<p>If an <span data-x="HTML documents">HTML document</span> does not start with a BOM, and its
<span>encoding</span> is not explicitly given by <span data-x="Content-Type">Content-Type
metadata</span>, and the document is not <span>an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span>, then the encoding must be specified
using a <code>meta</code> element with a <code data-x="attr-meta-charset">charset</code> attribute
or a <code>meta</code> element with an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute in the <span data-x="attr-meta-http-equiv-content-type">Encoding declaration
state</span>.</p>
<div class="note">
<p>A character encoding declaration is required (either in the <span
data-x="Content-Type">Content-Type metadata</span> or explicitly in the file) even when all
characters are in the ASCII range, because a character encoding is needed to process non-ASCII
characters entered by the user in forms, in URLs generated by scripts, and so forth.</p>
<p>Using non-UTF-8 encodings can have unexpected results on form submission and URL encodings,
which use the <span>document's character encoding</span> by default.</p>
</div>
<p>If the document is <span>an <code>iframe</code> <code data-x="attr-iframe-srcdoc">srcdoc</code>
document</span>, the document must not have a <span>character encoding declaration</span>. (In
this case, the source is already decoded, since it is part of the document that contained the
<code>iframe</code>.)</p>
<p>In XML, the XML declaration should be used for inline character encoding information, if
necessary.</p>
<div class="example">
<p>In HTML, to declare that the character encoding is <span>UTF-8</span>, the author could
include the following markup near the top of the document (in the <code>head</code> element):</p>
<pre><code class="html"><meta charset="utf-8"></code></pre>
<p>In XML, the XML declaration would be used instead, at the very top of the markup:</p>
<pre><code class="html"><?xml version="1.0" encoding="utf-8"?></code></pre>
</div>
<h4>The <dfn element><code>style</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>metadata content</span> is expected.</dd>
<dd>In a <code>noscript</code> element that is a child of a <code>head</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="text content">Text</span> that gives a <span>conformant style sheet</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-style-media">media</code></dd>
<dd><code data-x="attr-style-blocking">blocking</code></dd>
<dd>Also, the <code data-x="attr-style-title">title</code> attribute <span data-x="attr-style-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-style">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-style">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLStyleElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
attribute boolean <span data-x="dom-style-disabled">disabled</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-style-media">media</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-style-blocking">blocking</span>;
// <a href="#HTMLStyleElement-partial">also has obsolete members</a>
};
<span>HTMLStyleElement</span> includes <span>LinkStyle</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLStyleElement</code>.</dd>
</dl>
<p>The <code>style</code> element allows authors to embed CSS style sheets in their documents.
The <code>style</code> element is one of several inputs to the styling processing
model. The element does not <span data-x="represents">represent</span> content for the
user.</p>
<p>The <dfn attribute for="HTMLStyleElement"><code
data-x="dom-style-disabled">disabled</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span> does not have an <span>associated CSS style sheet</span>, return
false.</p></li>
<li><p>If <span>this</span>'s <span>associated CSS style sheet</span>'s <span
data-x="concept-css-style-sheet-disabled-flag">disabled flag</span> is set, return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>The <code data-x="dom-style-disabled">disabled</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span> does not have an <span>associated CSS style sheet</span>,
return.</p></li>
<li><p>If the given value is true, set <span>this</span>'s <span>associated CSS style
sheet</span>'s <span data-x="concept-css-style-sheet-disabled-flag">disabled flag</span>.
Otherwise, unset <span>this</span>'s <span>associated CSS style sheet</span>'s <span
data-x="concept-css-style-sheet-disabled-flag">disabled flag</span>.</p></li>
</ol>
<div class="example">
<p>Importantly, <code data-x="dom-style-disabled">disabled</code> attribute assignments only take
effect when the <code>style</code> element has an <span>associated CSS style sheet</span>:</p>
<pre><code class="js">const style = document.createElement('style');
style.disabled = true;
style.textContent = 'body { background-color: red; }';
document.body.append(style);
console.log(style.disabled); // false</code></pre>
</div>
<p>The <dfn element-attr for="style"><code data-x="attr-style-media">media</code></dfn> attribute
says which media the styles apply to. The value must be a <span>valid media query list</span>.
<span w-nodev>The user agent must apply the styles when the <code
data-x="attr-style-media">media</code> attribute's value <span>matches the environment</span> and
the other relevant conditions apply, and must not apply them otherwise.</span></p><!-- note
similar text in <link> element section -->
<div w-nodev>
<p class="note">The styles might be further limited in scope, e.g. in CSS with the use of <code
data-x="">@media</code> blocks. This specification does not override such further restrictions or
requirements.</p><!-- note similar text in <link> element section -->
</div>
<p id="style-default-media">The default, if the <code data-x="attr-style-media">media</code>
attribute is omitted, is "<code data-x="">all</code>", meaning that by default styles apply to all
media.</p>
<p>The <dfn element-attr for="style"><code data-x="attr-style-blocking">blocking</code></dfn>
attribute is a <span>blocking attribute</span>.</p>
<p id="title-on-style">The <dfn element-attr for="style"><code
data-x="attr-style-title">title</code></dfn> attribute on <code>style</code> elements defines
<span data-x="CSS style sheet set">CSS style sheet sets</span>. If the <code>style</code> element
has no <code data-x="attr-style-title">title</code> attribute, then it has no title; the <code
data-x="attr-title">title</code> attribute of ancestors does not apply to the <code>style</code>
element. If the <code>style</code> element is not <span>in a document tree</span>, then the <code
data-x="attr-style-title">title</code> attribute is ignored. <ref>CSSOM</ref></p>
<p class="note">The <code data-x="attr-style-title">title</code> attribute on <code>style</code>
elements, like the <code data-x="attr-link-title">title</code> attribute on <code>link</code>
elements, differs from the global <code data-x="attr-title">title</code> attribute in that a
<code>style</code> block without a title does not inherit the title of the parent element: it
merely has no title.</p>
<p>The <span>child text content</span> of a <code>style</code> element must be that of a
<span>conformant style sheet</span>.</p>
<p>A <code>style</code> element is <span>implicitly potentially render-blocking</span> if the
element was created by its <span>node document</span>'s parser.</p>
<hr>
<div w-nodev>
<p>The user agent must run the <span>update a <code>style</code> block</span> algorithm whenever
any of the following conditions occur:</p>
<!-- note that a browsing context isn't needed:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2739 -->
<ul>
<li><p>The element is popped off the <span>stack of open elements</span> of an <span>HTML
parser</span> or <span>XML parser</span>.</p></li>
<li><p>The element is not on the <span>stack of open elements</span> of an <span>HTML
parser</span> or <span>XML parser</span>, and it <span>becomes connected</span> or <span
data-x="becomes disconnected">disconnected</span>.</p></li>
<li><p>The element's <span>children changed steps</span> run.</p></li>
</ul>
<p>The <dfn export>update a <code>style</code> block</dfn> algorithm is as follows:</p>
<ol>
<li><p>Let <var>element</var> be the <code>style</code> element.</p></li>
<li><p>If <var>element</var> has an <span>associated CSS style sheet</span>, <span
data-x="remove a CSS style sheet">remove the CSS style sheet</span> in question.</p></li>
<li><p>If <var>element</var> is not <span>connected</span>, then return.</p></li>
<!-- See:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2740
https://github.com/w3c/csswg-drafts/issues/3096 -->
<li>
<p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is present and
its value is neither the empty string nor an <span>ASCII case-insensitive</span> match for
"<code>text/css</code>", then return.</p>
<p class="note">In particular, a <code data-x="attr-style-type">type</code> value with
parameters, such as "<code data-x="">text/css; charset=utf-8</code>", will cause this algorithm
to return early.</p>
</li>
<li><p>If the <span>Should element's inline behavior be blocked by Content Security
Policy?</span> algorithm returns "<code data-x="">Blocked</code>" when executed upon the
<code>style</code> element, "<code data-x="">style</code>", and the <code>style</code> element's
<span>child text content</span>, then return. <ref>CSP</ref></p></li>
<li>
<p><span>Create a CSS style sheet</span> with the following properties:</p>
<dl>
<dt><span data-x="concept-css-style-sheet-type">type</span></dt>
<dd><p><code>text/css</code></p></dd>
<dt><span data-x="concept-css-style-sheet-owner-node">owner node</span></dt>
<dd><p><var>element</var></p></dd>
<dt><span data-x="concept-css-style-sheet-media">media</span></dt>
<dd>
<p>The <code data-x="attr-style-media">media</code> attribute of <var>element</var>.</p>
<p class="note">This is a reference to the (possibly absent at this time) attribute, rather
than a copy of the attribute's current value. <cite>CSSOM</cite> defines what happens
when the attribute is dynamically set, changed, or removed.</p>
</dd>
<dt><span data-x="concept-css-style-sheet-title">title</span></dt>
<dd>
<p>The <code data-x="attr-style-title">title</code> attribute of <var>element</var>, if
<var>element</var> is <span>in a document tree</span>, or the empty string otherwise.</p>
<p class="note">Again, this is a <em>reference</em> to the attribute.</p>
</dd>
<dt><span data-x="concept-css-style-sheet-alternate-flag">alternate flag</span></dt>
<dd><p>Unset.</p></dd>
<dt><span data-x="concept-css-style-sheet-origin-clean-flag">origin-clean flag</span></dt>
<dd><p>Set.</p></dd>
<dt><span data-x="concept-css-style-sheet-location">location</span></dt>
<dt><span data-x="concept-css-style-sheet-parent-CSS-style-sheet">parent CSS style sheet</span></dt>
<dt><span data-x="concept-css-style-sheet-owner-CSS-rule">owner CSS rule</span></dt>
<dd><p>null</p></dd>
<dt><span data-x="concept-css-style-sheet-disabled-flag">disabled flag</span></dt>
<dd><p>Left at its default value.</p></dd>
<dt><span data-x="concept-css-style-sheet-CSS-rules">CSS rules</span></dt>
<dd>
<p>Left uninitialized.</p>
<p class="XXX">This doesn't seem right. Presumably we should be using the element's
<span>child text content</span>? Tracked as <a
href="https://github.com/whatwg/html/issues/2997">issue #2997</a>.</p>
</dd>
</dl>
</li>
<li><p>If <var>element</var> <span>contributes a script-blocking style sheet</span>, <span
data-x="set append">append</span> <var>element</var> to its <span>node document</span>'s
<span>script-blocking style sheet set</span>.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-style-media">media</code> attribute's value
<span>matches the environment</span> and <var>element</var> is
<span>potentially render-blocking</span>, then <span>block rendering</span> on
<var>element</var>.</p></li>
</ol>
<!-- the following steps are similar to the text in the <link> element's default process the
linked resource algorithm -->
<p>Once the attempts to obtain the style sheet's <span>critical subresources</span>, if any, are
complete, or, if the style sheet has no <span>critical subresources</span>, once the style sheet
has been parsed and processed, the user agent must run these steps:</p>
<p class="XXX">Fetching the <span>critical subresources</span> is not well-defined; probably <a
href="https://github.com/whatwg/html/issues/968">issue #968</a> is the best resolution for that.
In the meantime, any <span data-x="critical subresources">critical subresource</span> <span
data-x="concept-request">request</span> should have its <span
data-x="concept-request-render-blocking">render-blocking</span> set to whether or not the
<code>style</code> element is currently <span>render-blocking</span>.</p>
<ol>
<li><p>Let <var>element</var> be the <code>style</code> element associated with the style sheet
in question.</p></li>
<li><p>Let <var>success</var> be true.</p></li>
<li>
<p>If the attempts to obtain any of the style sheet's <span>critical subresources</span> failed
for any reason (e.g., DNS error, HTTP 404 response, a connection being prematurely closed,
unsupported Content-Type), set <var>success</var> to false.</p>
<p class="note">Note that content-specific errors, e.g., CSS parse errors or PNG decoding
errors, do not affect <var>success</var>.</p>
</li>
<li>
<p><span>Queue an element task</span> on the <span>networking task source</span> given
<var>element</var> and the following steps:</p>
<ol>
<li><p>If <var>success</var> is true, <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-load">load</code> at <var>element</var>.</p></li>
<li><p>Otherwise, <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at <var>element</var>.</p></li>
<li>
<p>If <var>element</var> <span>contributes a script-blocking style sheet</span>:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var>'s <span>node document</span>'s
<span>script-blocking style sheet set</span> <span data-x="list contains">contains</span>
<var>element</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>element</var> from its <span>node
document</span>'s <span>script-blocking style sheet set</span>.</p></li>
</ol>
</li>
<li><p><span>Unblock rendering</span> on <var>element</var>.</p></li>
</ol>
</li>
</ol>
<p>The element must <span>delay the load event</span> of the element's <span>node document</span> until all the
attempts to obtain the style sheet's <span>critical subresources</span>, if any, are complete.</p>
</div>
<p class="note">This specification does not specify a style system, but CSS is expected to be
supported by most web browsers. <ref>CSS</ref></p>
<div w-nodev>
<p>The <dfn attribute for="HTMLStyleElement"><code data-x="dom-style-media">media</code></dfn> and
<dfn attribute for="HTMLStyleElement"><code data-x="dom-style-blocking">blocking</code></dfn> IDL
attributes must each <span>reflect</span> the respective content attributes of the same name.</p>
</div>
<p>The <code>LinkStyle</code> interface is also implemented by this element. <ref>CSSOM</ref></p>
<div class="example">
<p>The following document has its stress emphasis styled as bright red text rather than italics
text, while leaving titles of works and Latin words in their default italics. It shows how using
appropriate elements enables easier restyling of documents.</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en-US">
<head>
<title>My favorite book</title>
<style>
body { color: black; background: white; }
em { font-style: normal; color: red; }
</style>
</head>
<body>
<p>My <em>favorite</em> book of all time has <em>got</em> to be
<cite>A Cat's Life</cite>. It is a book by P. Rahmel that talks
about the <i lang="la">Felis catus</i> in modern human society.</p>
</body>
</html></code></pre>
</div>
<div w-nodev>
<h4>Interactions of styling and scripting</h4>
<p>If the style sheet referenced no other resources (e.g., it was an internal style sheet given by
a <code>style</code> element with no <code data-x="">@import</code> rules), then the style rules
must be <span>immediately</span> made available to script; otherwise, the style rules must only be
made available to script once the <span>event loop</span> reaches its <span>update the
rendering</span> step.</p>
<p id="a-style-sheet-that-is-blocking-scripts">An element <var>el</var> in the context of a
<code>Document</code> of an <span>HTML parser</span> or <span>XML parser</span> <dfn>contributes a
script-blocking style sheet</dfn> if all of the following are true:</p>
<ul>
<li><p><var>el</var> was created by that <code>Document</code>'s parser.</p></li>
<li><p><var>el</var> is either a <code>style</code> element or a <code>link</code> element that
was an <span data-x="rel-stylesheet">external resource link that contributes to the styling
processing model</span> when the <var>el</var> was created by the parser.</p></li>
<li><p><var>el</var>'s <code data-x="">media</code> attribute's value
<span>matches the environment</span>.</p></li>
<li><p><var>el</var>'s style sheet was enabled when the element was created by the
parser.</p></li>
<li><p>The last time the <span>event loop</span> reached <a href="#step1">step 1</a>,
<var>el</var>'s <span>root</span> was that <code>Document</code>.</p></li>
<li>
<p>The user agent hasn't given up on loading that particular style sheet yet. A user agent
may give up on loading a style sheet at any time.</p>
<p class="note">Giving up on a style sheet before the style sheet loads, if the style sheet
eventually does still load, means that the script might end up operating with incorrect
information. For example, if a style sheet sets the color of an element to green, but a script
that inspects the resulting style is executed before the sheet is loaded, the script will find
that the element is black (or whatever the default color is), and might thus make poor choices
(e.g., deciding to use black as the color elsewhere on the page, instead of green). Implementers
have to balance the likelihood of a script using incorrect information with the performance impact
of doing nothing while waiting for a slow network request to finish.</p>
</li>
</ul>
<p class="XXX">It is expected that counterparts to the above rules also apply to
<code><?xml-stylesheet?></code> PIs. However, this has not yet been thoroughly
investigated.</p>
<p>A <code>Document</code> has a <dfn>script-blocking style sheet set</dfn>, which is an <span
data-x="set">ordered set</span>, initially empty.</p>
<p>A <code>Document</code> <var>document</var> <dfn>has a style sheet that is blocking
scripts</dfn> if the following steps return true:</p>
<ol>
<li><p>If <var>document</var>'s <span>script-blocking style sheet set</span> is not <span
data-x="list is empty">empty</span>, then return true.</p></li>
<li><p>If <var>document</var>'s <span>node navigable</span> is null, then return false.</p></li>
<li><p>Let <var>containerDocument</var> be <var>document</var>'s <span>node navigable</span>'s
<span data-x="nav-container">container document</span>.</p></li>
<li><p>If <var>containerDocument</var> is non-null and <var>containerDocument</var>'s
<span>script-blocking style sheet set</span> is not <span data-x="list is empty">empty</span>,
then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>A <code>Document</code> <dfn>has no style sheet that is blocking scripts</dfn> if it does not
<span data-x="has a style sheet that is blocking scripts">have a style sheet that is blocking
scripts</span>.</p>
</div>
<h3 split-filename="sections">Sections</h3>
<h4 id="the-body-element">The <dfn element><code>body</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the second element in an <code>html</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="handler-window-onafterprint">onafterprint</code></dd>
<dd><code data-x="handler-window-onbeforeprint">onbeforeprint</code></dd>
<dd><code data-x="handler-window-onbeforeunload">onbeforeunload</code></dd>
<dd><code data-x="handler-window-onhashchange">onhashchange</code></dd>
<dd><code data-x="handler-window-onlanguagechange">onlanguagechange</code></dd>
<dd><code data-x="handler-window-onmessage">onmessage</code></dd>
<dd><code data-x="handler-window-onmessageerror">onmessageerror</code></dd>
<dd><code data-x="handler-window-onoffline">onoffline</code></dd>
<dd><code data-x="handler-window-ononline">ononline</code></dd>
<dd><code data-x="handler-window-onpageswap">onpageswap</code></dd>
<dd><code data-x="handler-window-onpagehide">onpagehide</code></dd>
<dd><code data-x="handler-window-onpagereveal">onpagereveal</code></dd>
<dd><code data-x="handler-window-onpageshow">onpageshow</code></dd>
<dd><code data-x="handler-window-onpopstate">onpopstate</code></dd>
<dd><code data-x="handler-window-onrejectionhandled">onrejectionhandled</code></dd>
<dd><code data-x="handler-window-onstorage">onstorage</code></dd>
<dd><code data-x="handler-window-onunhandledrejection">onunhandledrejection</code></dd>
<dd><code data-x="handler-window-onunload">onunload</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-body">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-body">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLBodyElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLBodyElement-partial">also has obsolete members</a>
};
<span>HTMLBodyElement</span> includes <span>WindowEventHandlers</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLBodyElement</code>.</dd>
</dl>
<p>The <code>body</code> element <span>represents</span> the contents of the document.</p>
<p>In conforming documents, there is only one <code>body</code> element. The <code
data-x="dom-document-body">document.body</code> IDL attribute provides scripts with easy access to
a document's <code>body</code> element.</p>
<div w-nodev>
<p class="note">Some DOM operations (for example, parts of the <span>drag and drop</span> model)
are defined in terms of "<span>the body element</span>". This refers to a particular element in
the DOM, as per the definition of the term, and not any arbitrary <code>body</code> element.</p>
</div>
<p>The <code>body</code> element exposes as <span>event handler content attributes</span> a number
of the <span>event handlers</span> of the <code>Window</code> object. It also mirrors their
<span>event handler IDL attributes</span>.</p>
<p>The <span>event handlers</span> of the <code>Window</code> object named by the
<span><code>Window</code>-reflecting body element event handler set</span>, exposed on the
<code>body</code> element, replace the generic <span>event handlers</span> with the same names
normally supported by <span>HTML elements</span>.</p>
<p class="example">Thus, for example, a bubbling <code data-x="event-error">error</code> event
dispatched on a child of <span>the body element</span> of a <code>Document</code> would first
trigger the <code data-x="handler-onerror">onerror</code> <span>event handler content
attributes</span> of that element, then that of the root <code>html</code> element, and only
<em>then</em> would it trigger the <code data-x="handler-onerror">onerror</code> <span
data-x="event handler content attributes">event handler content attribute</span> on the
<code>body</code> element. This is because the event would bubble from the target, to the
<code>body</code>, to the <code>html</code>, to the <code>Document</code>, to the
<code>Window</code>, and the <span data-x="event handlers">event handler</span> on the
<code>body</code> is watching the <code>Window</code> not the <code>body</code>. A regular event
listener attached to the <code>body</code> using <code data-x="">addEventListener()</code>,
however, would be run when the event bubbled through the <code>body</code> and not when it reaches
the <code>Window</code> object.</p>
<div class="example">
<p>This page updates an indicator to show whether or not the user is online:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Online or offline?</title>
<script>
function update(online) {
document.getElementById('status').textContent =
online ? 'Online' : 'Offline';
}
</script>
</head>
<body ononline="update(true)"
onoffline="update(false)"
onload="update(navigator.onLine)">
<p>You are: <span id="status">(Unknown)</span></p>
</body>
</html></code></pre>
</div>
<h4>The <dfn element><code>article</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Sectioning content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>sectioning content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-article">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-article">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>article</code> element <span>represents</span> a complete, or self-contained,
composition in a document, page, application, or site and that is, in principle, independently
distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or
newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any
other independent item of content.</p>
<!-- for context regarding "site", see https://krijnhoetmer.nl/irc-logs/whatwg/20130306#l-152 -->
<p>When <code>article</code> elements are nested, the inner <code>article</code> elements
represent articles that are in principle related to the contents of the outer article. For
instance, a blog entry on a site that accepts user-submitted comments could represent the comments
as <code>article</code> elements nested within the <code>article</code> element for the blog
entry.</p>
<p>Author information associated with an <code>article</code> element (q.v. the
<code>address</code> element) does not apply to nested <code>article</code> elements.</p>
<p class="note">When used specifically with content to be redistributed in syndication, the
<code>article</code> element is similar in purpose to the <code data-x="">entry</code> element in
Atom. <ref>ATOM</ref>
<p class="note">The schema.org microdata vocabulary can be used to provide the publication date
for an <code>article</code> element, using one of the CreativeWork subtypes.</p>
<p>When the main content of the page (i.e. excluding footers, headers, navigation blocks, and
sidebars) is all one single self-contained composition, that content may be marked with an
<code>article</code>, but it is technically redundant in that case (since it's self-evident that
the page is a single composition, as it is a single document).</p>
<div id="article-example" class="example">
<p>This example shows a blog post using the <code>article</code> element, with some schema.org
annotations:</p>
<pre><code class="html"><article itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h2 itemprop="headline">The Very First Rule of Life</h2>
<p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
<link itemprop="url" href="?comments=0">
</header>
<p>If there's a microphone anywhere near you, assume it's hot and
sending whatever you're saying to the world. Seriously.</p>
<p><em>...</em></p>
<footer>
<a itemprop="discussionUrl" href="?comments=1">Show comments...</a>
</footer>
</article></code></pre>
<p>Here is that same blog post, but showing some of the comments:</p>
<pre><code class="html"><article itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h2 itemprop="headline">The Very First Rule of Life</h2>
<p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
<link itemprop="url" href="?comments=0">
</header>
<p>If there's a microphone anywhere near you, assume it's hot and
sending whatever you're saying to the world. Seriously.</p>
<p><em>...</em></p>
<section>
<h1>Comments</h1>
<article itemprop="comment" itemscope itemtype="http://schema.org/Comment" id="c1">
<link itemprop="url" href="#c1">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">George Washington</span>
</span></p>
<p><time itemprop="dateCreated" datetime="2009-10-10">15 minutes ago</time></p>
</footer>
<p>Yeah! Especially when talking about your lobbyist friends!</p>
</article>
<article itemprop="comment" itemscope itemtype="http://schema.org/Comment" id="c2">
<link itemprop="url" href="#c2">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">George Hammond</span>
</span></p>
<p><time itemprop="dateCreated" datetime="2009-10-10">5 minutes ago</time></p>
</footer>
<p>Hey, you have the same first name as me.</p>
</article>
</section>
</article></code></pre>
<p>Notice the use of <code>footer</code> to give the information for each comment (such as who
wrote it and when): the <code>footer</code> element <em>can</em> appear at the start of its
section when appropriate, such as in this case. (Using <code>header</code> in this case wouldn't
be wrong either; it's mostly a matter of authoring preference.)</p>
</div>
<div class="example">
<p>In this example, <code>article</code> elements are used to host widgets on a portal page. The
widgets are implemented as <span data-x="customized built-in element">customized built-in
elements</span> in order to get specific styling and scripted behavior.</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en>
<title>eHome Portal</title>
<script src="/scripts/widgets.js"></script>
<link rel=stylesheet href="/styles/main.css">
<article is="stock-widget">
<h2>Stocks</h2>
<table>
<thead> <tr> <th> Stock <th> Value <th> Delta
<tbody> <template> <tr> <td> <td> <td> </template>
</table>
<p> <input type=button value="Refresh" onclick="this.parentElement.refresh()">
</article>
<article is="news-widget">
<h2>News</h2>
<ul>
<template>
<li>
<p><img> <strong></strong>
<p>
</template>
</ul>
<p> <input type=button value="Refresh" onclick="this.parentElement.refresh()">
</article></code></pre>
</div>
<h4>The <dfn element><code>section</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Sectioning content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>sectioning content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-section">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-section">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>section</code> element <span>represents</span> a generic section of a document or
application. A section, in this context, is a thematic grouping of content, typically with a
heading.</p>
<p class="example">Examples of sections would be chapters, the various tabbed pages in a tabbed
dialog box, or the numbered sections of a thesis. A web site's home page could be split into
sections for an introduction, news items, and contact information.</p>
<p class="note">Authors are encouraged to use the <code>article</code> element instead of the
<code>section</code> element when it would make sense to syndicate the contents of the
element.</p>
<p class="note" id="use-div-for-wrappers">The <code>section</code> element is not a generic
container element. When an element is needed only for styling purposes or as a convenience for
scripting, authors are encouraged to use the <code>div</code> element instead. A general rule is
that the <code>section</code> element is appropriate only if the element's contents would be
listed explicitly in the document's <span>outline</span>.</p>
<div class="example">
<p>In the following example, we see an article (part of a larger web page) about apples,
containing two short sections.</p>
<pre><code class="html"><article>
<hgroup>
<h2>Apples</h2>
<p>Tasty, delicious fruit!</p>
</hgroup>
<p>The apple is the pomaceous fruit of the apple tree.</p>
<section>
<h3>Red Delicious</h3>
<p>These bright red apples are the most common found in many
supermarkets.</p>
</section>
<section>
<h3>Granny Smith</h3>
<p>These juicy, green apples make a great filling for
apple pies.</p>
</section>
</article></code></pre>
</div>
<div class="example">
<p>Here is a graduation programme with two sections, one for the list of people graduating, and
one for the description of the ceremony. (The markup in this example features an uncommon style
sometimes used to minimize the amount of <span>inter-element whitespace</span>.)</p>
<pre><code class="html"><!DOCTYPE Html>
<Html Lang=En
><Head
><Title
>Graduation Ceremony Summer 2022</Title
></Head
><Body
><H1
>Graduation</H1
><Section
><H2
>Ceremony</H2
><P
>Opening Procession</P
><P
>Speech by Valedictorian</P
><P
>Speech by Class President</P
><P
>Presentation of Diplomas</P
><P
>Closing Speech by Headmaster</P
></Section
><Section
><H2
>Graduates</H2
><Ul
><Li
>Molly Carpenter</Li
><Li
>Anastasia Luccio</Li
><Li
>Ebenezar McCoy</Li
><Li
>Karrin Murphy</Li
><Li
>Thomas Raith</Li
><Li
>Susan Rodriguez</Li
></Ul
></Section
></Body
></Html></code></pre>
</div>
<div class="example">
<p>In this example, a book author has marked up some sections as chapters and some as appendices,
and uses CSS to style the headers in these two classes of section differently.</p>
<pre><code class="html"><style>
section { border: double medium; margin: 2em; }
section.chapter h2 { font: 2em Roboto, Helvetica Neue, sans-serif; }
section.appendix h2 { font: small-caps 2em Roboto, Helvetica Neue, sans-serif; }
</style>
<header>
<hgroup>
<h1>My Book</h1>
<p>A sample with not much content</p>
</hgroup>
<p><small>Published by Dummy Publicorp Ltd.</small></p>
</header>
<section class="chapter">
<h2>My First Chapter</h2>
<p>This is the first of my chapters. It doesn't say much.</p>
<p>But it has two paragraphs!</p>
</section>
<section class="chapter">
<h2>It Continues: The Second Chapter</h2>
<p>Bla dee bla, dee bla dee bla. Boom.</p>
</section>
<section class="chapter">
<h2>Chapter Three: A Further Example</h2>
<p>It's not like a battle between brightness and earthtones would go
unnoticed.</p>
<p>But it might ruin my story.</p>
</section>
<section class="appendix">
<h2>Appendix A: Overview of Examples</h2>
<p>These are demonstrations.</p>
</section>
<section class="appendix">
<h2>Appendix B: Some Closing Remarks</h2>
<p>Hopefully this long example shows that you <em>can</em> style
sections, so long as they are used to indicate actual sections.</p>
</section></code></pre>
</div>
<h4>The <dfn element><code>nav</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Sectioning content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>sectioning content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-nav">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-nav">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>nav</code> element <span>represents</span> a section of a page that links to other
pages or to parts within the page: a section with navigation links.</p>
<p class="note">Not all groups of links on a page need to be in a <code>nav</code> element —
the element is primarily intended for sections that consist of major navigation blocks. In
particular, it is common for footers to have a short list of links to various pages of a site,
such as the terms of service, the home page, and a copyright page. The <code>footer</code> element
alone is sufficient for such cases; while a <code>nav</code> element can be used in such cases, it
is usually unnecessary.</p>
<p class="note">User agents (such as screen readers) that are targeted at users who can benefit
from navigation information being omitted in the initial rendering, or who can benefit from
navigation information being immediately available, can use this element as a way to determine
what content on the page to initially skip or provide on request (or both).</p>
<div class="example">
<p>In the following example, there are two <code>nav</code> elements, one for primary navigation
around the site, and one for secondary navigation around the page itself.</p>
<pre><code class="html"><body>
<h1>The Wiki Center Of Exampland</h1>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/events">Current Events</a></li>
<em>...more...</em>
</ul>
</nav>
<article>
<header>
<h2>Demos in Exampland</h2>
<p>Written by A. N. Other.</p>
</header>
<nav>
<ul>
<li><a href="#public">Public demonstrations</a></li>
<li><a href="#destroy">Demolitions</a></li>
<em>...more...</em>
</ul>
</nav>
<div>
<section id="public">
<h2>Public demonstrations</h2>
<p><em>...more...</em></p>
</section>
<section id="destroy">
<h2>Demolitions</h2>
<p><em>...more...</em></p>
</section>
<em>...more...</em>
</div>
<footer>
<p><a href="?edit">Edit</a> | <a href="?delete">Delete</a> | <a href="?Rename">Rename</a></p>
</footer>
</article>
<footer>
<p><small>© copyright 1998 Exampland Emperor</small></p>
</footer>
</body></code></pre>
</div>
<div class="example">
<p>In the following example, the page has several places where links are present, but only one of
those places is considered a navigation section.</p>
<pre><code class="html"><body itemscope itemtype="http://schema.org/Blog">
<header>
<h1>Wake up sheeple!</h1>
<p><a href="news.html">News</a> -
<a href="blog.html">Blog</a> -
<a href="forums.html">Forums</a></p>
<p>Last Modified: <span itemprop="dateModified">2009-04-01</span></p>
<nav>
<h2>Navigation</h2>
<ul>
<li><a href="articles.html">Index of all articles</a></li>
<li><a href="today.html">Things sheeple need to wake up for today</a></li>
<li><a href="successes.html">Sheeple we have managed to wake</a></li>
</ul>
</nav>
</header>
<main>
<article itemprop="blogPosts" itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h2 itemprop="headline">My Day at the Beach</h2>
</header>
<div itemprop="articleBody">
<p>Today I went to the beach and had a lot of fun.</p>
<em>...more content...</em>
</div>
<footer>
<p>Posted <time itemprop="datePublished" datetime="2009-10-10">Thursday</time>.</p>
</footer>
</article>
<em>...more blog posts...</em>
</main>
<footer>
<p>Copyright ©
<span itemprop="copyrightYear">2010</span>
<span itemprop="copyrightHolder">The Example Company</span>
</p>
<p><a href="about.html">About</a> -
<a href="policy.html">Privacy Policy</a> -
<a href="contact.html">Contact Us</a></p>
</footer>
</body></code></pre>
<p>You can also see microdata annotations in the above example that use the schema.org vocabulary
to provide the publication date and other metadata about the blog post.</p>
</div>
<div class="example">
<p>A <code>nav</code> element doesn't have to contain a list, it can contain other kinds of
content as well. In this navigation block, links are provided in prose:</p>
<pre><code class="html"><nav>
<h1>Navigation</h1>
<p>You are on my home page. To the north lies <a href="/blog">my
blog</a>, from whence the sounds of battle can be heard. To the east
you can see a large mountain, upon which many <a
href="/school">school papers</a> are littered. Far up thus mountain
you can spy a little figure who appears to be me, desperately
scribbling a <a href="/school/thesis">thesis</a>.</p>
<p>To the west are several exits. One fun-looking exit is labeled <a
href="https://games.example.com/">"games"</a>. Another more
boring-looking exit is labeled <a
href="https://isp.example.net/">ISP™</a>.</p>
<p>To the south lies a dark and dank <a href="/about">contacts
page</a>. Cobwebs cover its disused entrance, and at one point you
see a rat run quickly out of the page.</p>
</nav></code></pre>
</div>
<div class="example">
<p>In this example, <code>nav</code> is used in an email application, to let the user switch
folders:</p>
<pre><code class="html"><p><input type=button value="Compose" onclick="compose()"></p>
<nav>
<h1>Folders</h1>
<ul>
<li> <a href="/inbox" onclick="return openFolder(this.href)">Inbox</a> <span class=count></span>
<li> <a href="/sent" onclick="return openFolder(this.href)">Sent</a>
<li> <a href="/drafts" onclick="return openFolder(this.href)">Drafts</a>
<li> <a href="/trash" onclick="return openFolder(this.href)">Trash</a>
<li> <a href="/customers" onclick="return openFolder(this.href)">Customers</a>
</ul>
</nav></code></pre>
</div>
<h4>The <dfn element><code>aside</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Sectioning content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>sectioning content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-aside">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-aside">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>aside</code> element <span>represents</span> a section of a page that consists of
content that is tangentially related to the content around the <code>aside</code> element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.</p>
<p>The element can be used for typographical effects like pull quotes or sidebars, for
advertising, for groups of <code>nav</code> elements, and for other content that is considered
separate from the main content of the page.</p>
<p class="note">It's not appropriate to use the <code>aside</code> element just for
parentheticals, since those are part of the main flow of the document.</p>
<div class="example">
<p>The following example shows how an aside is used to mark up background material on Switzerland
in a much longer news story on Europe.</p>
<pre><code class="html"><aside>
<h2>Switzerland</h2>
<p>Switzerland, a land-locked country in the middle of geographic
Europe, has not joined the geopolitical European Union, though it is
a signatory to a number of European treaties.</p>
</aside></code></pre>
</div>
<div class="example">
<p>The following example shows how an aside is used to mark up a pull quote in a longer
article.</p>
<pre><code class="html">...
<p>He later joined a large company, continuing on the same work.
<q>I love my job. People ask me what I do for fun when I'm not at
work. But I'm paid to do my hobby, so I never know what to
answer. Some people wonder what they would do if they didn't have to
work... but I know what I would do, because I was unemployed for a
year, and I filled that time doing exactly what I do now.</q></p>
<aside>
<q>People ask me what I do for fun when I'm not at work. But I'm
paid to do my hobby, so I never know what to answer.</q>
</aside>
<p>Of course his work — or should that be hobby? —
isn't his only passion. He also enjoys other pleasures.</p>
...</code></pre>
</div>
<div class="example">
<p>The following extract shows how <code>aside</code> can be used for blogrolls and other side
content on a blog:</p>
<pre><code class="html"><body>
<header>
<h1>My wonderful blog</h1>
<p>My tagline</p>
</header>
<aside>
<!-- <em>this aside contains two sections that are tangentially related
to the page, namely, links to other blogs, and links to blog posts
from this blog</em> -->
<nav>
<h2>My blogroll</h2>
<ul>
<li><a href="https://blog.example.com/">Example Blog</a>
</ul>
</nav>
<nav>
<h2>Archives</h2>
<ol reversed>
<li><a href="/last-post">My last post</a>
<li><a href="/first-post">My first post</a>
</ol>
</nav>
</aside>
<aside>
<!-- <em>this aside is tangentially related to the page also, it
contains twitter messages from the blog author</em> -->
<h1>Twitter Feed</h1>
<blockquote cite="https://twitter.example.net/t31351234">
I'm on vacation, writing my blog.
</blockquote>
<blockquote cite="https://twitter.example.net/t31219752">
I'm going to go on vacation soon.
</blockquote>
</aside>
<article>
<!-- <em>this is a blog post</em> -->
<h2>My last post</h2>
<p>This is my last post.</p>
<footer>
<p><a href="/last-post" rel=bookmark>Permalink</a>
</footer>
</article>
<article>
<!-- <em>this is also a blog post</em> -->
<h2>My first post</h2>
<p>This is my first post.</p>
<aside>
<!-- <em>this aside is about the blog post, since it's inside the
<article> element; it would be wrong, for instance, to put the
blogroll here, since the blogroll isn't really related to this post
specifically, only to the page as a whole</em> -->
<h2>Posting</h2>
<p>While I'm thinking about it, I wanted to say something about
posting. Posting is fun!</p>
</aside>
<footer>
<p><a href="/first-post" rel=bookmark>Permalink</a>
</footer>
</article>
<footer>
<p><a href="/archives">Archives</a> -
<a href="/about">About me</a> -
<a href="/copyright">Copyright</a></p>
</footer>
</body></code></pre>
</div>
<h4>The <dfn id="the-h1-element" element><code>h1</code></dfn>, <dfn id="the-h2-element"
element><code>h2</code></dfn>, <dfn id="the-h3-element" element><code>h3</code></dfn>, <dfn
id="the-h4-element" element><code>h4</code></dfn>, <dfn id="the-h5-element"
element><code>h5</code></dfn>, and <dfn id="the-h6-element" element><code>h6</code></dfn>
elements</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Heading content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of an <code>hgroup</code> element.</dd>
<dd>Where <span>heading content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-h1-h6">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-h1-h6">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLHeadingElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLHeadingElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLHeadingElement</code>.</dd>
</dl>
<p>These elements <span data-x="represents">represent</span> headings for their sections.</p>
<p>The semantics and meaning of these elements are defined in the section on <a
href="#headings-and-outlines">headings and outlines</a>.</p>
<p>These elements have a <span>heading level</span> given by the number in their name. The
<span>heading level</span> corresponds to the levels of nested sections. The <code>h1</code>
element is for a top-level section, <code>h2</code> for a subsection, <code>h3</code> for a
sub-subsection, and so on.</p>
<div class="example">
<p>As far as their respective document outlines (their heading and section structures) are
concerned, these two snippets are semantically equivalent:</p>
<pre><code class="html"><body>
<h1>Let's call it a draw(ing surface)</h1>
<h2>Diving in</h2>
<h2>Simple shapes</h2>
<h2>Canvas coordinates</h2>
<h3>Canvas coordinates diagram</h3>
<h2>Paths</h2>
</body></code></pre>
<pre><code class="html"><body>
<h1>Let's call it a draw(ing surface)</h1>
<section>
<h2>Diving in</h2>
</section>
<section>
<h2>Simple shapes</h2>
</section>
<section>
<h2>Canvas coordinates</h2>
<section>
<h3>Canvas coordinates diagram</h3>
</section>
</section>
<section>
<h2>Paths</h2>
</section>
</body></code></pre>
<p>Authors might prefer the former style for its terseness, or the latter style for its
additional styling hooks. Which is best is purely an issue of preferred authoring style.</p>
</div>
<h4>The <dfn element><code>hgroup</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Heading content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>heading content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>p</code> elements, followed by one <code>h1</code>, <code>h2</code>,
<code>h3</code>, <code>h4</code>, <code>h5</code>, or <code>h6</code> element, followed by zero
or more <code>p</code> elements, optionally intermixed with <span>script-supporting
elements</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-hgroup">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-hgroup">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>hgroup</code> element <span>represents</span> a heading and related content. The
element may be used to group an <code>h1</code>–<code>h6</code> element with one or more
<code>p</code> elements containing content representing a subheading, alternative title, or
tagline.</p>
<div class="example">
<p>Here are some examples of valid headings contained within an <code>hgroup</code> element.</p>
<pre><code class="html"><hgroup>
<h1>The reality dysfunction</h1>
<p>Space is not the only void</p>
</hgroup></code></pre>
<pre><code class="html"><hgroup>
<h1>Dr. Strangelove</h1>
<p>Or: How I Learned to Stop Worrying and Love the Bomb</p>
</hgroup></code></pre>
</div>
<h4>The <dfn element><code>header</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>header</code> or <code>footer</code> element
descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If there is an ancestor <span>sectioning content</span> element: <a
href="https://w3c.github.io/html-aria/#el-header">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-header">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-header">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-header-ancestorbody">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>header</code> element <span>represents</span> a group of introductory or navigational
aids.</p>
<p class="note">A <code>header</code> element is intended to usually contain a heading
(an <code>h1</code>–<code>h6</code> element or an <code>hgroup</code> element), but this is
not required. The <code>header</code> element can also be used to wrap a section's table of
contents, a search form, or any relevant logos.</p>
<div class="example">
<p>Here are some sample headers. This first one is for a game:</p>
<pre><code class="html"><header>
<p>Welcome to...</p>
<h1>Voidwars!</h1>
</header></code></pre>
<p>The following snippet shows how the element can be used to mark
up a specification's header:</p>
<pre><code class="html"><header>
<hgroup>
<h1>Fullscreen API</h1>
<p>Living Standard — Last Updated 19 October 2015<p>
</hgroup>
<dl>
<dt>Participate:</dt>
<dd><a href="https://github.com/whatwg/fullscreen">GitHub whatwg/fullscreen</a></dd>
<dt>Commits:</dt>
<dd><a href="https://github.com/whatwg/fullscreen/commits">GitHub whatwg/fullscreen/commits</a></dd>
</dl>
</header></code></pre>
</div>
<p class="note">The <code>header</code> element is not <span>sectioning content</span>; it doesn't
introduce a new section.</p>
<div class="example">
<p>In this example, the page has a page heading given by the <code>h1</code> element, and two
subsections whose headings are given by <code>h2</code> elements. The content after the
<code>header</code> element is still part of the last subsection started in the
<code>header</code> element, because the <code>header</code> element doesn't take part in the
<span>outline</span> algorithm.</p>
<pre><code class="html"><body>
<header>
<h1>Little Green Guys With Guns</h1>
<nav>
<ul>
<li><a href="/games">Games</a>
<li><a href="/forum">Forum</a>
<li><a href="/download">Download</a>
</ul>
</nav>
<h2>Important News</h2> <!-- this starts a second subsection -->
<!-- this is part of the subsection entitled "Important News" -->
<p>To play today's games you will need to update your client.</p>
<h2>Games</h2> <!-- this starts a third subsection -->
</header>
<p>You have three active games:</p>
<!-- this is still part of the subsection entitled "Games" -->
...</code></pre>
</div>
<h4>The <dfn element><code>footer</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>header</code> or <code>footer</code> element
descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If there is an ancestor <span>sectioning content</span> element: <a
href="https://w3c.github.io/html-aria/#el-footer">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-footer">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-footer">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-footer-ancestorbody">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>footer</code> element <span>represents</span> a footer for its nearest ancestor
<span>sectioning content</span> element, or for <span>the body element</span> if there is no such
ancestor. A footer typically contains information about its section such as who wrote it, links
to related documents, copyright data, and the like.</p>
<p>When the <code>footer</code> element contains entire sections, they <span
data-x="represents">represent</span> appendices, indices, long colophons, verbose license
agreements, and other such content.</p>
<p class="note">Contact information for the author or editor of a section belongs in an
<code>address</code> element, possibly itself inside a <code>footer</code>. Bylines and other
information that could be suitable for both a <code>header</code> or a <code>footer</code> can be
placed in either (or neither). The primary purpose of these elements is merely to help the author
write self-explanatory markup that is easy to maintain and style; they are not intended to impose
specific structures on authors.</p>
<p>Footers don't necessarily have to appear at the <em>end</em> of a section, though they usually
do.</p>
<p>When there is no ancestor <span>sectioning content</span> element, then it applies to the whole
page.</p>
<p class="note">The <code>footer</code> element is not itself <span>sectioning content</span>; it
doesn't introduce a new section.</p>
<div class="example">
<p>Here is a page with two footers, one at the top and one at the bottom, with the same
content:</p>
<pre><code class="html"><body>
<footer><a href="../">Back to index...</a></footer>
<hgroup>
<h1>Lorem ipsum</h1>
<p>The ipsum of all lorems</p>
</hgroup>
<p>A dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in
voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.</p>
<footer><a href="../">Back to index...</a></footer>
</body></code></pre>
</div>
<div class="example">
<p>Here is an example which shows the <code>footer</code> element being used both for a site-wide
footer and for a section footer.</p>
<pre><code class="html"><!DOCTYPE HTML>
<HTML LANG="en"><HEAD>
<TITLE>The Ramblings of a Scientist</TITLE>
<BODY>
<H1>The Ramblings of a Scientist</H1>
<ARTICLE>
<H1>Episode 15</H1>
<VIDEO SRC="/fm/015.ogv" CONTROLS PRELOAD>
<P><A HREF="/fm/015.ogv">Download video</A>.</P>
</VIDEO>
<FOOTER> <!-- footer for article -->
<P>Published <TIME DATETIME="2009-10-21T18:26-07:00">on 2009/10/21 at 6:26pm</TIME></P>
</FOOTER>
</ARTICLE>
<ARTICLE>
<H1>My Favorite Trains</H1>
<P>I love my trains. My favorite train of all time is a Köf.</P>
<P>It is fun to see them pull some coal cars because they look so
dwarfed in comparison.</P>
<FOOTER> <!-- footer for article -->
<P>Published <TIME DATETIME="2009-09-15T14:54-07:00">on 2009/09/15 at 2:54pm</TIME></P>
</FOOTER>
</ARTICLE>
<FOOTER> <!-- site wide footer -->
<NAV>
<P><A HREF="/credits.html">Credits</A> —
<A HREF="/tos.html">Terms of Service</A> —
<A HREF="/index.html">Blog Index</A></P>
</NAV>
<P>Copyright © 2009 Gordon Freeman</P>
</FOOTER>
</BODY>
</HTML></code></pre>
</div>
<div class="example">
<p>Some site designs have what is sometimes referred to as "fat footers" — footers that
contain a lot of material, including images, links to other articles, links to pages for sending
feedback, special offers... in some ways, a whole "front page" in the footer.</p>
<p>This fragment shows the bottom of a page on a site with a "fat footer":</p>
<pre><code class="html">...
<footer>
<nav>
<section>
<h1>Articles</h1>
<p><img src="images/somersaults.jpeg" alt=""> Go to the gym with
our somersaults class! Our teacher Jim takes you through the paces
in this two-part article. <a href="articles/somersaults/1">Part
1</a> · <a href="articles/somersaults/2">Part 2</a></p>
<p><img src="images/kindplus.jpeg"> Tired of walking on the edge of
a clif<!-- sic -->? Our guest writer Lara shows you how to bumble
your way through the bars. <a href="articles/kindplus/1">Read
more...</a></p>
<p><img src="images/crisps.jpeg"> The chips are down, now all
that's left is a potato. What can you do with it? <a
href="articles/crisps/1">Read more...</a></p>
</section>
<ul>
<li> <a href="/about">About us...</a>
<li> <a href="/feedback">Send feedback!</a>
<li> <a href="/sitemap">Sitemap</a>
</ul>
</nav>
<p><small>Copyright © 2015 The Snacker —
<a href="/tos">Terms of Service</a></small></p>
</footer>
</body></code></pre>
</div>
<h4>The <dfn element><code>address</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <span>heading
content</span> descendants, no <span>sectioning content</span>
descendants, and no <code>header</code>, <code>footer</code>, or
<code>address</code> element descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-address">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-address">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>address</code> element <span>represents</span> the contact information for its
nearest <code>article</code> or <code>body</code> element ancestor. If that is <span>the body
element</span>, then the contact information applies to the document as a whole.</p>
<div class="example">
<p>For example, a page at the W3C web site related to HTML might
include the following contact information:</p>
<pre><code class="html"><ADDRESS>
<A href="../People/Raggett/">Dave Raggett</A>,
<A href="../People/Arnaud/">Arnaud Le Hors</A>,
contact persons for the <A href="Activity">W3C HTML Activity</A>
</ADDRESS></code></pre>
</div>
<p>The <code>address</code> element must not be used to represent arbitrary addresses (e.g. postal
addresses), unless those addresses are in fact the relevant contact information. (The
<code>p</code> element is the appropriate element for marking up postal addresses in general.)</p>
<p>The <code>address</code> element must not contain information other than contact
information.</p>
<div class="example">
<p>For example, the following is non-conforming use of the
<code>address</code> element:</p>
<pre class="bad"><code class="html"><ADDRESS>Last Modified: 1999/12/24 23:37:50</ADDRESS></code></pre>
</div>
<p>Typically, the <code>address</code> element would be included along with other information in a
<code>footer</code> element.</p>
<div w-nodev>
<p>The contact information for a node <var>node</var> is a collection of
<code>address</code> elements defined by the first applicable entry from the following list:</p>
<dl class="switch">
<dt>If <var>node</var> is an <code>article</code> element</dt>
<dt>If <var>node</var> is a <code>body</code> element</dt>
<dd>
<p>The contact information consists of all the <code>address</code> elements that have <var>node</var> as an ancestor and do not have another <code>body</code> or
<code>article</code> element ancestor that is a descendant of <var>node</var>.</p>
</dd>
<dt>If <var>node</var> has an ancestor element that is an <code>article</code> element</dt>
<dt>If <var>node</var> has an ancestor element that is a <code>body</code> element</dt>
<dd>
<p>The contact information of <var>node</var> is the same as the contact information of
the nearest <code>article</code> or <code>body</code> element ancestor, whichever is
nearest.</p>
</dd>
<dt>If <var>node</var>'s <span>node document</span> has <span data-x="the body element">a body
element</span></dt>
<dd>
<p>The contact information of <var>node</var> is the same as the contact information of
<span>the body element</span> of the <code>Document</code>.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>There is no contact information for <var>node</var>.</p>
</dd>
</dl>
<p>User agents may expose the contact information of a node to the user, or use it for other
purposes, such as indexing sections based on the sections' contact information.</p>
</div>
<div class="example">
<p>In this example the footer contains contact information and a copyright notice.</p>
<pre><code class="html"><footer>
<address>
For more details, contact
<a href="mailto:js@example.com">John Smith</a>.
</address>
<p><small>© copyright 2038 Example Corp.</small></p>
</footer></code></pre>
</div>
<h4><span id="headings-and-outlines"></span><span id="outlines"></span>Headings and outlines</h4>
<p><code>h1</code>–<code>h6</code> elements have a <dfn>heading level</dfn>, which is given
by the number in the element's name.</p>
<p>These elements <span data-x="represents">represent</span> <dfn
data-x="concept-heading">headings</dfn>. The lower a <span
data-x="concept-heading">heading</span>'s <span>heading level</span> is, the fewer ancestor
sections the <span data-x="concept-heading">heading</span> has.</p>
<p>The <dfn>outline</dfn> is all <span data-x="concept-heading">headings</span> in a
document, in <span>tree order</span>.</p>
<p>The <span>outline</span> should be used for generating document outlines, for example when
generating tables of contents. When creating an interactive table of contents, entries should
jump the user to the relevant <span data-x="concept-heading">heading</span>.</p>
<p>If a document has one or more <span data-x="concept-heading">headings</span>, at least a
single <span data-x="concept-heading">heading</span> within the <span>outline</span> should have
a <span>heading level</span> of 1.</p>
<p>Each <span data-x="concept-heading">heading</span> following another <span
data-x="concept-heading">heading</span> <var>lead</var> in the <span>outline</span> must
have a <span>heading level</span> that is less than, equal to, or 1 greater than <var>lead</var>'s
<span>heading level</span>.</p>
<div class="example">
<p>The following example is non-conforming:</p>
<pre class="bad"><code class="html"><body>
<h1>Apples</h1>
<p>Apples are fruit.</p>
<section>
<h3>Taste</h3>
<p>They taste lovely.</p>
</section>
</body></code></pre>
<p>It could be written as follows and then it would be conforming:</p>
<pre><code class="html"><body>
<h1>Apples</h1>
<p>Apples are fruit.</p>
<section>
<h2>Taste</h2>
<p>They taste lovely.</p>
</section>
</body></code></pre>
</div>
<h5>Sample outlines</h5>
<div class="example">
<p>The following markup fragment:</p>
<pre><code class="html"><body>
<hgroup id="document-title">
<h1>HTML: Living Standard</h1>
<p>Last Updated 12 August 2016</p>
</hgroup>
<p>Some intro to the document.</p>
<h2>Table of contents</h2>
<ol id=toc>...</ol>
<h2>First section</h2>
<p>Some intro to the first section.</p>
</body></code></pre>
<p>...results in 3 document headings:</p>
<ol class="brief">
<li><p><code data-x=""><h1>HTML: Living Standard</h1></code></li>
<li><p><code data-x=""><h2>Table of contents</h2></code>.</p></li>
<li><p><code data-x=""><h2>First section</h2></code>.</p></li>
</ol>
<p>A rendered view of the <span>outline</span> might look like:</p>
<p><img src="/images/outline.svg" width="465" height="120" alt="Top-level section with the heading "HTML: Living Standard" and two subsections; "Table of contents" and "First section"." class="darkmode-aware"></p>
</div>
<div class="example">
<p>First, here is a document, which is a book with very short chapters and subsections:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en>
<title>The Tax Book (all in one page)</title>
<h1>The Tax Book</h1>
<h2>Earning money</h2>
<p>Earning money is good.</p>
<h3>Getting a job</h3>
<p>To earn money you typically need a job.</p>
<h2>Spending money</h2>
<p>Spending is what money is mainly used for.</p>
<h3>Cheap things</h3>
<p>Buying cheap things often not cost-effective.</p>
<h3>Expensive things</h3>
<p>The most expensive thing is often not the most cost-effective either.</p>
<h2>Investing money</h2>
<p>You can lend your money to other people.</p>
<h2>Losing money</h2>
<p>If you spend money or invest money, sooner or later you will lose money.
<h3>Poor judgement</h3>
<p>Usually if you lose money it's because you made a mistake.</p></code></pre>
<p>Its <span>outline</span> could be presented as follows:</p>
<ol class="brief">
<li>
The Tax Book
<ol class="brief">
<li>
Earning money
<ol class="brief">
<li>Getting a job</li>
</ol>
</li>
<li>
Spending money
<ol class="brief">
<li>Cheap things</li>
<li>Expensive things</li>
</ol>
</li>
<li>Investing money</li>
<li>
Losing money
<ol class="brief">
<li>Poor judgement</li>
</ol>
</li>
</ol>
</ol>
<p>Notice that the <code>title</code> element is not a <span
data-x="concept-heading">heading</span>.</p>
</div>
<div class="example">
<p>A document can contain multiple top-level headings:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en>
<title>Alphabetic Fruit</title>
<h1>Apples</h1>
<p>Pomaceous.</p>
<h1>Bananas</h1>
<p>Edible.</p>
<h1>Carambola</h1>
<p>Star.</p></code></pre>
<p>The document's <span>outline</span> could be presented as follows:</p>
<ol class="brief">
<li>Apples</li>
<li>Bananas</li>
<li>Carambola</li>
</ol>
</div>
<div class="example">
<p><code>header</code> elements do not influence the <span>outline</span> of a
document:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<title>We're adopting a child! — Ray's blog</title>
<h1>Ray's blog</h1>
<article>
<header>
<nav>
<a href="?t=-1d">Yesterday</a>;
<a href="?t=-7d">Last week</a>;
<a href="?t=-1m">Last month</a>
</nav>
<h2>We're adopting a child!</h2>
</header>
<p>As of today, Janine and I have signed the papers to become
the proud parents of baby Diane! We've been looking forward to
this day for weeks.</p>
</article>
</html></code></pre>
<p>The document's <span>outline</span> could be presented as follows:</p>
<ol class="brief">
<li> Ray's blog
<ol class="brief">
<li> We're adopting a child!
</ol>
</ol>
</div>
<hr>
<div class="example">
<p>The following example is conforming, but not encouraged as it has no <span
data-x="concept-heading">heading</span> whose <span>heading level</span> is 1:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en>
<title>Alphabetic Fruit</title>
<section>
<h2>Apples</h2>
<p>Pomaceous.</p>
</section>
<section>
<h2>Bananas</h2>
<p>Edible.</p>
</section>
<section>
<h2>Carambola</h2>
<p>Star.</p>
</section></code></pre>
<p>The document's <span>outline</span> could be presented as follows:</p>
<ol class="brief">
<li>
<ol class="brief">
<li>Apples</li>
<li>Bananas</li>
<li>Carambola</li>
</ol>
</li>
</ol>
</div>
<div class="example">
<p>The following example is conforming, but not encouraged as the first <span
data-x="concept-heading">heading</span>'s <span>heading level</span> is not 1:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang=en>
<title>Feathers on The Site of Encyclopedic Knowledge</title>
<h2>A plea from our caretakers</h2>
<p>Please, we beg of you, send help! We're stuck in the server room!</p>
<h1>Feathers</h1>
<p>Epidermal growths.</p></code></pre>
<p>The document's <span>outline</span> could be presented as follows:</p>
<ol class="brief">
<li>
<ol class="brief">
<li>A plea from our caretakers</li>
</ol>
</li>
<li>Feathers</li>
</ol>
</div>
<h5>Exposing outlines to users</h5>
<p>User agents are encouraged to expose page <span data-x="outline">outlines</span> to users to
aid in navigation. This is especially true for non-visual media, e.g. screen readers.</p>
<div class="example">
<p>For instance, a user agent could map the arrow keys as follows:</p>
<dl>
<dt><kbd><kbd>Shift</kbd> + <kbd>← Left</kbd></kbd></dt>
<dd>Go to previous heading</dd>
<dt><kbd><kbd>Shift</kbd> + <kbd>→ Right</kbd></kbd></dt>
<dd>Go to next heading</dd>
<dt><kbd><kbd>Shift</kbd> + <kbd>↑ Up</kbd></kbd></dt>
<dd>Go to next heading whose <span data-x="heading level">level</span> is one less than the
current heading's level</dd>
<dt><kbd><kbd>Shift</kbd> + <kbd>↓ Down</kbd></kbd></dt>
<dd>Go to next heading whose <span data-x="heading level">level</span> is the same as the
current heading's level</dd>
</dl>
</div>
<h4>Usage summary</h4>
<!-- NON-NORMATIVE SECTION -->
<table class="vertical-summary-table">
<thead>
<tr>
<th rowspan=2>Element
<th>Purpose
<tr>
<th>Example
<tbody>
<tr>
<td rowspan=2><code>body</code>
<td><!--REPRESENTS body-->
<tr>
<td><pre class="example"><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head> <title>Steve Hill's Home Page</title> </head>
<strong><body></strong> <p>Hard Trance is My Life.</p> <strong></body></strong>
</html></code></pre>
<tr>
<td rowspan=2><code>article</code>
<td><!--REPRESENTS article-->
<tr>
<td><pre class="example"><code class="html"><strong><article></strong>
<img src="/tumblr_masqy2s5yn1rzfqbpo1_500.jpg" alt="Yellow smiley face with the caption 'masif'">
<p>My fave Masif tee so far!</p>
<footer>Posted 2 days ago</footer>
<strong></article></strong>
<strong><article></strong>
<img src="/tumblr_m9tf6wSr6W1rzfqbpo1_500.jpg" alt="">
<p>Happy 2nd birthday Masif Saturdays!!!</p>
<footer>Posted 3 weeks ago</footer>
<strong></article></strong></code></pre>
<tr>
<td rowspan=2><code>section</code>
<td><!--REPRESENTS section-->
<tr>
<td><pre class="example"><code class="html"><h1>Biography</h1>
<strong><section></strong>
<h1>The facts</h1>
<p>1500+ shows, 14+ countries</p>
<strong></section></strong>
<strong><section></strong>
<h1>2010/2011 figures per year</h1>
<p>100+ shows, 8+ countries</p>
<strong></section></strong></code></pre>
<tr>
<td rowspan=2><code>nav</code>
<td><!--REPRESENTS nav-->
<tr>
<td><pre class="example"><code class="html"><strong><nav></strong>
<p><a href="/">Home</a>
<p><a href="/biog.html">Bio</a>
<p><a href="/discog.html">Discog</a>
<strong></nav></strong></code></pre>
<tr>
<td rowspan=2><code>aside</code>
<td><!--REPRESENTS aside-->
<tr>
<td><pre class="example"><code class="html"><h1>Music</h1>
<p>As any burner can tell you, the event has a lot of trance.</p>
<strong><aside></strong>You can buy the music we played at our <a href="buy.html">playlist page</a>.<strong></aside></strong>
<p>This year we played a kind of trance that originated in Belgium, Germany, and the Netherlands in the mid-90s.</p></code></pre>
<tr>
<td rowspan=2><code>h1</code>–<code>h6</code>
<td>A heading
<tr>
<td><pre class="example"><code class="html"><strong><h1></strong>The Guide To Music On The Playa<strong></h1></strong>
<strong><h2></strong>The Main Stage<strong></h2></strong>
<p>If you want to play on a stage, you <!--non-normative-->should bring one.</p>
<strong><h2></strong>Amplified Music<strong></h2></strong>
<p>Amplifiers up to 300W or 90dB are welcome.</p></code></pre>
<tr>
<td rowspan=2><code>hgroup</code>
<td><!--REPRESENTS hgroup-->
<tr>
<td><pre class="example"><code class="html"><strong><hgroup></strong>
<h1>Burning Music</h1>
<p>The Guide To Music On The Playa</p>
<strong></hgroup></strong>
<section>
<strong><hgroup></strong>
<h1>Main Stage</h1>
<p>The Fiction Of A Music Festival</p>
<strong></hgroup></strong>
<p>If you want to play on a stage, you <!--non-normative-->should bring one.</p>
</section>
<section>
<strong><hgroup></strong>
<h1>Loudness!</h1>
<p>Questions About Amplified Music</p>
<strong></hgroup></strong>
<p>Amplifiers up to 300W or 90dB are welcome.</p>
</section></code></pre>
<tr>
<td rowspan=2><code>header</code>
<td><!--REPRESENTS header-->
<tr>
<td><pre class="example"><code class="html"><article>
<strong><header></strong>
<h1>Hard Trance is My Life</h1>
<p>By DJ Steve Hill and Technikal</p>
<strong></header></strong>
<p>The album with the amusing punctuation has red artwork.</p>
</article></code></pre>
<tr>
<td rowspan=2><code>footer</code>
<td><!--REPRESENTS footer-->
<tr>
<td><pre class="example"><code class="html"><article>
<h1>Hard Trance is My Life</h1>
<p>The album with the amusing punctuation has red artwork.</p>
<strong><footer></strong>
<p>Artists: DJ Steve Hill and Technikal</p>
<strong></footer></strong>
</article></code></pre>
</table>
<h5>Article or section?</h5>
<!-- NON-NORMATIVE SECTION -->
<p>A <code>section</code> forms part of something else. An <code>article</code> is its own thing.
But how does one know which is which? Mostly the real answer is "it depends on author intent".</p>
<p>For example, one could imagine a book with a "Granny Smith" chapter that just said "These
juicy, green apples make a great filling for apple pies."; that would be a <code>section</code>
because there'd be lots of other chapters on (maybe) other kinds of apples.</p>
<p>On the other hand, one could imagine a tweet or reddit comment or tumblr post or newspaper
classified ad that just said "Granny Smith. These juicy, green apples make a great filling for
apple pies."; it would then be <code>article</code>s because that was the whole thing.</p>
<p>A comment on an article is not part of the <code>article</code> on which it is commenting,
therefore it is its own <code>article</code>.</p>
<h3 split-filename="grouping-content">Grouping content</h3>
<h4>The <dfn element><code>p</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-p">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-p">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLParagraphElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLParagraphElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLParagraphElement</code>.</dd>
</dl>
<p>The <code>p</code> element <span>represents</span> a <span>paragraph</span>.</p>
<p class="note">While paragraphs are usually represented in visual media by blocks of text that
are physically separated from adjacent blocks through blank lines, a style sheet or user agent
would be equally justified in presenting paragraph breaks in a different manner, for instance
using inline pilcrows (¶).</p>
<div class="example">
<p>The following examples are conforming HTML fragments:</p>
<pre><code class="html"><p>The little kitten gently seated herself on a piece of
carpet. Later in her life, this would be referred to as the time the
cat sat on the mat.</p></code></pre>
<pre><code class="html"><fieldset>
<legend>Personal information</legend>
<p>
<label>Name: <input name="n"></label>
<label><input name="anon" type="checkbox"> Hide from other users</label>
</p>
<p><label>Address: <textarea name="a"></textarea></label></p>
</fieldset></code></pre>
<pre><code class="html"><p>There was once an example from Femley,<br>
Whose markup was of dubious quality.<br>
The validator complained,<br>
So the author was pained,<br>
To move the error from the markup to the rhyming.</p></code></pre>
</div>
<p>The <code>p</code> element should not be used when a more specific element is more
appropriate.</p>
<div class="example">
<p>The following example is technically correct:</p>
<pre><code class="html"><section>
<!-- ... -->
<p>Last modified: 2001-04-23</p>
<p>Author: fred@example.com</p>
</section></code></pre>
<p>However, it would be better marked-up as:</p>
<pre><code class="html"><section>
<!-- ... -->
<footer>Last modified: 2001-04-23</footer>
<address>Author: fred@example.com</address>
</section></code></pre>
<p>Or:</p>
<pre><code class="html"><section>
<!-- ... -->
<footer>
<p>Last modified: 2001-04-23</p>
<address>Author: fred@example.com</address>
</footer>
</section></code></pre>
</div>
<div class="note">
<p>List elements (in particular, <code>ol</code> and <code>ul</code> elements) cannot be children
of <code>p</code> elements. When a sentence contains a bulleted list, therefore, one might wonder
how it should be marked up.</p>
<div class="example">
<p>For instance, this fantastic sentence has bullets relating to</p>
<ul>
<li>wizards,
<li>faster-than-light travel, and
<li>telepathy,
</ul>
<p>and is further discussed below.</p>
</div>
<p>The solution is to realize that a <i data-x="paragraph">paragraph</i>, in HTML terms, is not a
logical concept, but a structural one. In the fantastic example above, there are actually
<em>five</em> <span data-x="paragraph">paragraphs</span> as defined by this specification: one
before the list, one for each bullet, and one after the list.</p>
<div class="example">
<p>The markup for the above example could therefore be:</p>
<pre><code class="html"><p>For instance, this fantastic sentence has bullets relating to</p>
<ul>
<li>wizards,
<li>faster-than-light travel, and
<li>telepathy,
</ul>
<p>and is further discussed below.</p></code></pre>
</div>
<p>Authors wishing to conveniently style such "logical" paragraphs consisting of multiple
"structural" paragraphs can use the <code>div</code> element instead of the <code>p</code>
element.</p>
<div class="example">
<p>Thus for instance the above example could become the following:</p>
<pre><code class="html"><div>For instance, this fantastic sentence has bullets relating to
<ul>
<li>wizards,
<li>faster-than-light travel, and
<li>telepathy,
</ul>
and is further discussed below.</div></code></pre>
<p>This example still has five structural paragraphs, but now the author can style just the
<code>div</code> instead of having to consider each part of the example separately.</p>
</div>
</div>
<h4>The <dfn element><code>hr</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dd>As a child of a <code>select</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-hr">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-hr">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLHRElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLHRElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLHRElement</code>.</dd>
</dl>
<p>The <code>hr</code> element <span>represents</span> a <span>paragraph</span>-level thematic
break, e.g., a scene change in a story, or a transition to another topic within a section of a
reference book; alternatively, it represents a separator between a set of options of a
<code>select</code> element.</p>
<div class="example">
<p>The following fictional extract from a project manual shows two sections that use the
<code>hr</code> element to separate topics within the section.</p>
<pre><code class="html"><section>
<h1>Communication</h1>
<p>There are various methods of communication. This section
covers a few of the important ones used by the project.</p>
<strong><hr></strong>
<p>Communication stones seem to come in pairs and have mysterious
properties:</p>
<ul>
<li>They can transfer thoughts in two directions once activated
if used alone.</li>
<li>If used with another device, they can transfer one's
consciousness to another body.</li>
<li>If both stones are used with another device, the
consciousnesses switch bodies.</li>
</ul>
<strong><hr></strong>
<p>Radios use the electromagnetic spectrum in the meter range and
longer.</p>
<strong><hr></strong>
<p>Signal flares use the electromagnetic spectrum in the
nanometer range.</p>
</section>
<section>
<h1>Food</h1>
<p>All food at the project is rationed:</p>
<dl>
<dt>Potatoes</dt>
<dd>Two per day</dd>
<dt>Soup</dt>
<dd>One bowl per day</dd>
</dl>
<strong><hr></strong>
<p>Cooking is done by the chefs on a set rotation.</p>
</section></code></pre>
<p>There is no need for an <code>hr</code> element between the sections themselves, since the
<code>section</code> elements and the <code>h1</code> elements imply thematic changes
themselves.</p>
</div>
<div class="example">
<p>The following extract from <cite>Pandora's Star</cite> by Peter F. Hamilton shows two
paragraphs that precede a scene change and the paragraph that follows it. The scene change,
represented in the printed book by a gap containing a solitary centered star between the second
and third paragraphs, is here represented using the <code>hr</code> element.</p>
<!-- ISBN 1-4050-0020-1; bottom of page 14 -->
<pre lang="en-GB"><code class="html"><p>Dudley was ninety-two, in his second life, and fast approaching
time for another rejuvenation. Despite his body having the physical
age of a standard fifty-year-old, the prospect of a long degrading
campaign within academia was one he regarded with dread. For a
supposedly advanced civilization, the Intersolar Commonwealth could be
appallingly backward at times, not to mention cruel.</p>
<p><i>Maybe it won't be that bad</i>, he told himself. The lie was
comforting enough to get him through the rest of the night's
shift.</p>
<strong><hr></strong>
<p>The Carlton AllLander drove Dudley home just after dawn. Like the
astronomer, the vehicle was old and worn, but perfectly capable of
doing its job. It had a cheap diesel engine, common enough on a
semi-frontier world like Gralmond, although its drive array was a
thoroughly modern photoneural processor. With its high suspension and
deep-tread tyres it could plough along the dirt track to the
observatory in all weather and seasons, including the metre-deep snow
of Gralmond's winters.</p></code></pre>
</div>
<p class="note">The <code>hr</code> element does not affect the document's
<span>outline</span>.</p>
<h4>The <dfn element><code>pre</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-pre">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-pre">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLPreElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLPreElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLPreElement</code>.</dd>
</dl>
<p>The <code>pre</code> element <span>represents</span> a block of preformatted text, in which
structure is represented by typographic conventions rather than by elements.</p>
<p class="note">In <span>the HTML syntax</span>, a leading newline character immediately following
the <code>pre</code> element start tag is stripped.</p>
<p>Some examples of cases where the <code>pre</code> element could be used:</p>
<ul>
<li>Including an email, with paragraphs indicated by blank lines, lists indicated by lines
prefixed with a bullet, and so on.</li>
<li>Including fragments of computer code, with structure indicated according to the conventions
of that language.</li>
<li>Displaying ASCII art.</li>
</ul>
<p class="note">Authors are encouraged to consider how preformatted text will be experienced when
the formatting is lost, as will be the case for users of speech synthesizers, braille displays,
and the like. For cases like ASCII art, it is likely that an alternative presentation, such as a
textual description, would be more universally accessible to the readers of the document.</p>
<p>To represent a block of computer code, the <code>pre</code> element can be used with a
<code>code</code> element; to represent a block of computer output the <code>pre</code> element
can be used with a <code>samp</code> element. Similarly, the <code>kbd</code> element can be used
within a <code>pre</code> element to indicate text that the user is to enter.</p>
<div w-nodev>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<div class="example">
<p>In the following snippet, a sample of computer code is presented.</p>
<pre><code class="html"><p>This is the <code>Panel</code> constructor:</p>
<pre><code>function Panel(element, canClose, closeHandler) {
this.element = element;
this.canClose = canClose;
this.closeHandler = function () { if (closeHandler) closeHandler() };
}</code></pre></code></pre>
</div>
<div class="example">
<p>In the following snippet, <code>samp</code> and <code>kbd</code> elements are mixed in the
contents of a <code>pre</code> element to show a session of Zork I.</p>
<pre><code class="html"><pre><samp>You are in an open field west of a big white house with a boarded
front door.
There is a small mailbox here.
></samp> <kbd>open mailbox</kbd>
<samp>Opening the mailbox reveals:
A leaflet.
></samp></pre></code></pre>
</div>
<div class="example">
<p>The following shows a contemporary poem that uses the <code>pre</code> element to preserve its
unusual formatting, which forms an intrinsic part of the poem itself.</p>
<pre><code class="html"><pre> maxling
it is with a heart
heavy
that i admit loss of a feline
so loved
a friend lost to the
unknown
(night)
~cdr 11dec07</pre></code></pre>
</div>
<h4>The <dfn element><code>blockquote</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-blockquote-cite">cite</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-blockquote">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-blockquote">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLQuoteElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-quote-cite">cite</span>;
};</code></pre>
<p class="note">The <code>HTMLQuoteElement</code> interface is
also used by the <code>q</code> element.</p>
</dd>
<dd w-dev>Uses <code>HTMLQuoteElement</code>.</dd>
</dl>
<p>The <code>blockquote</code> element <span>represents</span> a section that is quoted from
another source.</p>
<p>Content inside a <code>blockquote</code> must be quoted from another source, whose address, if
it has one, may be cited in the <dfn element-attr for="blockquote"><code
data-x="attr-blockquote-cite">cite</code></dfn> attribute.</p>
<p>If the <code data-x="attr-blockquote-cite">cite</code> attribute is present, it must be a
<span>valid URL potentially surrounded by spaces</span>. <span w-nodev>To obtain the
corresponding citation link, the value of the attribute must be <span data-x="encoding-parsing a
URL">parsed</span> relative to the element's <span>node document</span>.</span> User agents may
allow users to follow such citation links, but they are primarily intended for private use (e.g.,
by server-side scripts collecting statistics about a site's use of quotations), not for
readers.</p>
<p>The content of a <code>blockquote</code> may be abbreviated or may have context added in the
conventional manner for the text's language.</p>
<div class="example">
<p>For example, in English this is traditionally done using square brackets. Consider a page with
the sentence "Jane ate the cracker. She then said she liked apples and fish."; it could be quoted
as follows:</p>
<pre><code class="html"><blockquote>
<p>[Jane] then said she liked [...] fish.</p>
</blockquote></code></pre>
</div>
<p>Attribution for the quotation, if any, must be placed outside the <code>blockquote</code>
element.</p> <!-- Eventually someone is going to ask about quotes that are self-attributing, e.g.
someone quoting an email with full headers... -->
<div class="example">
<p>For example, here the attribution is given in a paragraph after the quote:</p>
<pre><code class="html"><blockquote>
<p>I contend that we are both atheists. I just believe in one fewer
god than you do. When you understand why you dismiss all the other
possible gods, you will understand why I dismiss yours.</p>
</blockquote>
<p>— Stephen Roberts</p></code></pre>
<p>The other examples below show other ways of showing attribution.</p>
</div>
<div w-nodev>
<p>The <dfn attribute for="HTMLQuoteElement"><code data-x="dom-quote-cite">cite</code></dfn> IDL
attribute must <span>reflect</span> the element's <code data-x="">cite</code> content
attribute.</p>
</div>
<div class="example">
<p>Here a <code>blockquote</code> element is used in conjunction with a <code>figure</code>
element and its <code>figcaption</code> to clearly relate a quote to its attribution (which is
not part of the quote and therefore doesn't belong inside the <code>blockquote</code>
itself):</p>
<pre><code class="html"><figure>
<blockquote>
<p>The truth may be puzzling. It may take some work to grapple with.
It may be counterintuitive. It may contradict deeply held
prejudices. It may not be consonant with what we desperately want to
be true. But our preferences do not determine what's true. We have a
method, and that method helps us to reach not absolute truth, only
asymptotic approaches to the truth — never there, just closer
and closer, always finding vast new oceans of undiscovered
possibilities. Cleverly designed experiments are the key.</p>
</blockquote>
<figcaption>Carl Sagan, in "<cite>Wonder and Skepticism</cite>", from
the <cite>Skeptical Inquirer</cite> Volume 19, Issue 1 (January-February
1995)</figcaption>
</figure></code></pre>
</div>
<div class="example">
<p>This next example shows the use of <code>cite</code> alongside <code>blockquote</code>:</p>
<pre><code class="html"><p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p>
<blockquote cite="https://quotes.example.org/s/sonnet130.html">
<p>My mistress' eyes are nothing like the sun,<br>
Coral is far more red, than her lips red,<br>
...</code></pre>
</div>
<div class="example">
<p>This example shows how a forum post could use <code>blockquote</code> to show what post a user
is replying to. The <code>article</code> element is used for each post, to mark up the
threading.</p>
<pre><code class="html"><article>
<h1><a href="https://bacon.example.com/?blog=109431">Bacon on a crowbar</a></h1>
<article>
<header><strong>t3yw</strong> 12 points 1 hour ago</header>
<p>I bet a narwhal would love that.</p>
<footer><a href="?pid=29578">permalink</a></footer>
<article>
<header><strong>greg</strong> 8 points 1 hour ago</header>
<blockquote><p>I bet a narwhal would love that.</p></blockquote>
<p>Dude narwhals don't eat bacon.</p>
<footer><a href="?pid=29579">permalink</a></footer>
<article>
<header><strong>t3yw</strong> 15 points 1 hour ago</header>
<blockquote>
<blockquote><p>I bet a narwhal would love that.</p></blockquote>
<p>Dude narwhals don't eat bacon.</p>
</blockquote>
<p>Next thing you'll be saying they don't get capes and wizard
hats either!</p>
<footer><a href="?pid=29580">permalink</a></footer>
<article>
<article>
<header><strong>boing</strong> -5 points 1 hour ago</header>
<p>narwhals are worse than ceiling cat</p>
<footer><a href="?pid=29581">permalink</a></footer>
</article>
</article>
</article>
</article>
<article>
<header><strong>fred</strong> 1 points 23 minutes ago</header>
<blockquote><p>I bet a narwhal would love that.</p></blockquote>
<p>I bet they'd love to peel a banana too.</p>
<footer><a href="?pid=29582">permalink</a></footer>
</article>
</article>
</article></code></pre>
</div>
<div class="example">
<p>This example shows the use of a <code>blockquote</code> for short snippets, demonstrating that
one does not have to use <code>p</code> elements inside <code>blockquote</code> elements:</p>
<pre><code class="html"><p>He began his list of "lessons" with the following:</p>
<blockquote>One should never assume that his side of
the issue will be recognized, let alone that it will
be conceded to have merits.</blockquote>
<p>He continued with a number of similar points, ending with:</p>
<blockquote>Finally, one should be prepared for the threat
of breakdown in negotiations at any given moment and not
be cowed by the possibility.</blockquote>
<p>We shall now discuss these points...</code></pre>
</div>
<p class="note"><a href="#conversations">Examples of how to represent a conversation</a> are shown
in a later section; it is not appropriate to use the <code>cite</code> and <code>blockquote</code>
elements for this purpose.</p>
<h4>The <dfn element><code>ol</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd>If the element's children include at least one <code>li</code> element: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>li</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-ol-reversed">reversed</code></dd>
<dd><code data-x="attr-ol-start">start</code></dd>
<dd><code data-x="attr-ol-type">type</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-ol">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-ol">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLOListElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-ol-reversed">reversed</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-ol-start">start</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-ol-type">type</span>;
// <a href="#HTMLOListElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLOListElement</code>.</dd>
</dl>
<p>The <code>ol</code> element <span>represents</span> a list of items, where the items have been
intentionally ordered, such that changing the order would change the meaning of the document.</p>
<p>The items of the list are the <code>li</code> element child nodes of the <code>ol</code>
element, in <span>tree order</span>.</p>
<p>The <dfn element-attr for="ol"><code data-x="attr-ol-reversed">reversed</code></dfn> attribute
is a <span>boolean attribute</span>. If present, it indicates that the list is a descending list
(..., 3, 2, 1). If the attribute is omitted, the list is an ascending list (1, 2, 3, ...).</p>
<p>The <dfn element-attr for="ol"><code data-x="attr-ol-start">start</code></dfn> attribute, if
present, must be a <span>valid integer</span>. It is used to determine the <span
data-x="concept-ol-start">starting value</span> of the list.</p>
<div w-nodev>
<!-- https://github.com/whatwg/html/issues/1617
https://github.com/whatwg/html/issues/1911 -->
<p>An <code>ol</code> element has a <dfn data-x="concept-ol-start">starting value</dfn>, which is
an integer determined as follows:</p>
<ol>
<li>
<p>If the <code>ol</code> element has a <code data-x="attr-ol-start">start</code> attribute,
then:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span data-x="rules for parsing integers">parsing
the value of the attribute as an integer</span>.</p></li>
<li><p>If <var>parsed</var> is not an error, then return <var>parsed</var>.</p></li>
</ol>
</li>
<li><p>If the <code>ol</code> element has a <code data-x="attr-ol-reversed">reversed</code>
attribute, then return the number of <span data-x="list owner">owned <code>li</code>
elements</span>.</p></li>
<li><p>Return 1.</p></li>
</ol>
</div>
<p>The <dfn element-attr for="ol"><code data-x="attr-ol-type">type</code></dfn> attribute can be
used to specify the kind of marker to use in the list, in the cases where that matters (e.g.
because items are to be <span>referenced</span> by their number/letter). The attribute, if
specified, must have a value that is <span>identical to</span> one of the characters given in the
first cell of one of the rows of the following table. <span w-nodev>The <code
data-x="attr-ol-type">type</code> attribute represents the state given in the cell in the second
column of the row whose first cell matches the attribute's value; if none of the cells match, or
if the attribute is omitted, then the attribute represents the <span
data-x="attr-ol-type-state-decimal">decimal</span> state.</span></p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Description
<th colspan=8>Examples for values 1-3 and 3999-4001
<tbody>
<tr>
<td><dfn attr-value for="ol/type"><code data-x="attr-ol-type-keyword-decimal">1</code></dfn>
(U+0031)
<td><dfn data-x="attr-ol-type-state-decimal">decimal</dfn>
<td>Decimal numbers
<td class="eg"><samp>1.</samp> <td class="eg"><samp>2.</samp> <td class="eg"><samp>3.</samp> <td class="eg">... <td class="eg"><samp>3999.</samp> <td class="eg"><samp>4000.</samp> <td class="eg"><samp>4001.</samp> <td class="eg">...
<tr>
<td><dfn attr-value for="ol/type"><code
data-x="attr-ol-type-keyword-lower-alpha">a</code></dfn> (U+0061)
<td><dfn data-x="attr-ol-type-state-lower-alpha">lower-alpha</dfn>
<td>Lowercase latin alphabet
<td class="eg"><samp>a.</samp> <td class="eg"><samp>b.</samp> <td class="eg"><samp>c.</samp> <td class="eg">... <td class="eg"><samp>ewu.</samp> <td class="eg"><samp>ewv.</samp> <td class="eg"><samp>eww.</samp> <td class="eg">...
<tr>
<td><dfn attr-value for="ol/type"><code
data-x="attr-ol-type-keyword-upper-alpha">A</code></dfn> (U+0041)
<td><dfn data-x="attr-ol-type-state-upper-alpha">upper-alpha</dfn>
<td>Uppercase latin alphabet
<td class="eg"><samp>A.</samp> <td class="eg"><samp>B.</samp> <td class="eg"><samp>C.</samp> <td class="eg">... <td class="eg"><samp>EWU.</samp> <td class="eg"><samp>EWV.</samp> <td class="eg"><samp>EWW.</samp> <td class="eg">...
<tr>
<td><dfn attr-value for="ol/type"><code data-x="attr-ol-type-keyword-lower-roman">i</code></dfn> (U+0069)
<td><dfn data-x="attr-ol-type-state-lower-roman">lower-roman</dfn>
<td>Lowercase roman numerals
<td class="eg"><samp>i.</samp> <td class="eg"><samp>ii.</samp> <td class="eg"><samp>iii.</samp> <td class="eg">... <td class="eg"><samp>mmmcmxcix.</samp> <td class="eg"><samp>i̅v̅.</samp> <td class="eg"><samp>i̅v̅i.</samp> <td class="eg">...
<tr>
<td><dfn attr-value for="ol/type"><code
data-x="attr-ol-type-keyword-upper-roman">I</code></dfn> (U+0049)
<td><dfn data-x="attr-ol-type-state-upper-roman">upper-roman</dfn>
<td>Uppercase roman numerals
<td class="eg"><samp>I.</samp> <td class="eg"><samp>II.</samp> <td class="eg"><samp>III.</samp> <td class="eg">... <td class="eg"><samp>MMMCMXCIX.</samp> <td class="eg"><samp>I̅V̅.</samp> <td class="eg"><samp>I̅V̅I.</samp> <td class="eg">...
</table>
<div w-nodev>
<p>User agents should render the items of the list in a manner consistent with the state of the
<code data-x="attr-ol-type">type</code> attribute of the <code>ol</code> element. Numbers less than
or equal to zero should always use the decimal system regardless of the <code
data-x="attr-ol-type">type</code> attribute.</p>
<p class="note">For CSS user agents, a mapping for this attribute to the
<span>'list-style-type'</span> CSS property is given <a href="#decohints">in the Rendering
section</a> (the mapping is straightforward: the states above have the same names as their
corresponding CSS values).</p>
</div>
<p class="note">It is possible to redefine the default CSS list styles used to implement this
attribute in CSS user agents; doing so will affect how list items are rendered.</p>
<!-- v2: resuming numbering of lists from previous lists? -->
<div w-nodev>
<p>The <dfn attribute for="HTMLOListElement"><code data-x="dom-ol-reversed">reversed</code></dfn>
and <dfn attribute for="HTMLOListElement"><code data-x="dom-ol-type">type</code></dfn> IDL
attributes must <span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLOListElement"><code data-x="dom-ol-start">start</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name, with a <span>default
value</span> of 1.</p>
<p class="note">This means that the <code data-x="dom-ol-start">start</code> IDL attribute does
not necessarily match the list's <span data-x="concept-ol-start">starting value</span>, in cases
where the <code data-x="attr-ol-start">start</code> content attribute is omitted and the <code
data-x="attr-ol-reversed">reversed</code> content attribute is specified.</p>
</div>
<div class="example">
<p>The following markup shows a list where the order matters, and where the <code>ol</code>
element is therefore appropriate. Compare this list to the equivalent list in the <code>ul</code>
section to see an example of the same items using the <code>ul</code> element.</p>
<pre><code class="html"><p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
<li>Switzerland
<li>United Kingdom
<li>United States
<li>Norway
</ol></code></pre>
<p>Note how changing the order of the list changes the meaning of the document. In the following
example, changing the relative order of the first two items has changed the birthplace of the
author:</p>
<pre><code class="html"><p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
<li>United Kingdom
<li>Switzerland
<li>United States
<li>Norway
</ol></code></pre>
</div>
<h4>The <dfn element><code>ul</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd>If the element's children include at least one <code>li</code> element: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>li</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-ul">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-ul">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLUListElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLUListElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLUListElement</code>.</dd>
</dl>
<p>The <code>ul</code> element <span>represents</span> a list of items, where the order of the
items is not important — that is, where changing the order would not materially change the
meaning of the document.</p>
<p>The items of the list are the <code>li</code> element child nodes of the <code>ul</code>
element.</p>
<div class="example">
<p>The following markup shows a list where the order does not matter, and where the
<code>ul</code> element is therefore appropriate. Compare this list to the equivalent list in the
<code>ol</code> section to see an example of the same items using the <code>ol</code>
element.</p>
<pre><code class="html"><p>I have lived in the following countries:</p>
<ul>
<li>Norway
<li>Switzerland
<li>United Kingdom
<li>United States
</ul></code></pre>
<p>Note that changing the order of the list does not change the meaning of the document. The
items in the snippet above are given in alphabetical order, but in the snippet below they are
given in order of the size of their current account balance in 2007, without changing the meaning
of the document whatsoever:</p>
<pre><code class="html"><p>I have lived in the following countries:</p>
<ul>
<li>Switzerland
<li>Norway
<li>United Kingdom
<li>United States
</ul></code></pre>
</div>
<h4 id="the-menu-element">The <dfn element id="menus"><code>menu</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd>If the element's children include at least one <code>li</code> element: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>li</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-menu">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-menu">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLMenuElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLMenuElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLMenuElement</code>.</dd>
</dl>
<p>The <code>menu</code> element <span>represents</span> a toolbar consisting of its contents, in
the form of an unordered list of items (represented by <code>li</code> elements), each of
which represents a command that the user can perform or activate.</p>
<p class="note">The <code>menu</code> element is simply a semantic alternative to <code>ul</code>
to express an unordered list of commands (a "toolbar").</p>
<div class="example">
<p>In this example, a text-editing application uses a <code>menu</code> element to provide a
series of editing commands:</p>
<pre><code class="html"><menu>
<li><button onclick="copy()"><img src="copy.svg" alt="Copy"></button></li>
<li><button onclick="cut()"><img src="cut.svg" alt="Cut"></button></li>
<li><button onclick="paste()"><img src="paste.svg" alt="Paste"></button></li>
</menu></code></pre>
<p>Note that the styling to make this look like a conventional toolbar menu is up to the
application.</p>
</div>
<h4>The <dfn element><code>li</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Inside <code>ol</code> elements.</dd>
<dd>Inside <code>ul</code> elements.</dd>
<dd>Inside <code>menu</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd>If the element is not a child of an <code>ul</code> or <code>menu</code> element: <code data-x="attr-li-value">value</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-li">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-li">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLLIElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute long <span data-x="dom-li-value">value</span>;
// <a href="#HTMLLIElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLLIElement</code>.</dd>
</dl>
<p>The <code>li</code> element <span>represents</span> a list item. If its parent element is an
<code>ol</code>, <code>ul</code>, or <code>menu</code> element, then the element is an item of the
parent element's list, as defined for those elements. Otherwise, the list item has no defined
list-related relationship to any other <code>li</code> element.</p>
<p>The <dfn element-attr for="li"><code data-x="attr-li-value">value</code></dfn> attribute, if
present, must be a <span>valid integer</span>. It is used to determine the <span>ordinal
value</span> of the list item, when the <code>li</code>'s <span>list owner</span> is an
<code>ol</code> element.</p>
<div w-nodev>
<hr>
<p>Any element whose <span>computed value</span> of <span>'display'</span> is 'list-item' has a
<dfn>list owner</dfn>, which is determined as follows:</p>
<ol>
<li><p>If the element is not <span>being rendered</span>, return null; the element has no
<span>list owner</span>.</p>
<li><p>Let <var>ancestor</var> be the element's parent.</p></li>
<li><p>If the element has an <code>ol</code>, <code>ul</code>, or <code>menu</code> ancestor, set
<var>ancestor</var> to the closest such ancestor element.</p></li>
<li>
<p>Return the closest inclusive ancestor of <var>ancestor</var> that produces a <span>CSS
box</span>.</p>
<p class="note">Such an element will always exist, as at the very least the <span>document
element</span> will always produce a <span>CSS box</span>.</p>
</li>
</ol>
<p>To determine the <dfn>ordinal value</dfn> of each element owned by a given <span>list
owner</span> <var>owner</var>, perform the following steps:</p>
<ol>
<li><p>Let <var>i</var> be 1.</p></li>
<li><p>If <var>owner</var> is an <code>ol</code> element, let <var>numbering</var> be
<var>owner</var>'s <span data-x="concept-ol-start">starting value</span>. Otherwise, let
<var>numbering</var> be 1.</p></li>
<li><p><i>Loop</i>: If <var>i</var> is greater than the number of <span
data-x="list owner">list items that <var>owner</var> owns</span>, then return; all
of <var>owner</var>'s <span data-x="list owner">owned list items</span> have been assigned <span
data-x="ordinal value">ordinal values</span>.</p></li>
<li><p>Let <var>item</var> be the <var>i</var>th of <var>owner</var>'s <span data-x="list
owner">owned list items</span>, in <span>tree order</span>.</p>
<li>
<p>If <var>item</var> is an <code>li</code> element that has a <code
data-x="attr-li-value">value</code> attribute, then:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span data-x="rules for parsing integers">parsing
the value of the attribute as an integer</span>.</p></li>
<li><p>If <var>parsed</var> is not an error, then set <var>numbering</var> to
<var>parsed</var>.</p></li>
</ol>
</li>
<li><p>The <span>ordinal value</span> of <var>item</var> is <var>numbering</var>.</p></li>
<li><p>If <var>owner</var> is an <code>ol</code> element, and <var>owner</var> has a <code
data-x="attr-ol-reversed">reversed</code> attribute, decrement <var>numbering</var> by 1;
otherwise, increment <var>numbering</var> by 1.</p></li>
<li><p>Increment <var>i</var> by 1.</p></li>
<li><p>Go to the step labeled <i>loop</i>.</p>
</ol>
<hr>
<p>The <dfn attribute for="HTMLLIElement"><code data-x="dom-li-value">value</code></dfn> IDL
attribute must <span>reflect</span> the value of the <code data-x="attr-li-value">value</code>
content attribute.</p>
<div class="example">
<p>The element's <code data-x="dom-li-value">value</code> IDL attribute does not directly
correspond to its <span>ordinal value</span>; it simply <span data-x="reflect">reflects</span>
the content attribute. For example, given this list:
<pre><code class="html"><ol>
<li>Item 1
<li value="3">Item 3
<li>Item 4
</ol></code></pre>
<p>The <span data-x="ordinal value">ordinal values</span> are 1, 3, and 4, whereas the <code
data-x="dom-li-value">value</code> IDL attributes return 0, 3, 0 on getting.</p>
</div>
</div>
<div class="example">
<p>The following example, the top ten movies are listed (in reverse order). Note the way the list
is given a title by using a <code>figure</code> element and its <code>figcaption</code>
element.</p>
<pre><code class="html"><figure>
<figcaption>The top 10 movies of all time</figcaption>
<ol>
<li value="10"><cite>Josie and the Pussycats</cite>, 2001</li>
<li value="9"><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
<li value="8"><cite>A Bug's Life</cite>, 1998</li>
<li value="7"><cite>Toy Story</cite>, 1995</li>
<li value="6"><cite>Monsters, Inc</cite>, 2001</li>
<li value="5"><cite>Cars</cite>, 2006</li>
<li value="4"><cite>Toy Story 2</cite>, 1999</li>
<li value="3"><cite>Finding Nemo</cite>, 2003</li>
<li value="2"><cite>The Incredibles</cite>, 2004</li>
<li value="1"><cite>Ratatouille</cite>, 2007</li>
</ol>
</figure></code></pre>
<p>The markup could also be written as follows, using the <code
data-x="attr-ol-reversed">reversed</code> attribute on the <code>ol</code> element:</p>
<pre><code class="html"><figure>
<figcaption>The top 10 movies of all time</figcaption>
<ol reversed>
<li><cite>Josie and the Pussycats</cite>, 2001</li>
<li><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
<li><cite>A Bug's Life</cite>, 1998</li>
<li><cite>Toy Story</cite>, 1995</li>
<li><cite>Monsters, Inc</cite>, 2001</li>
<li><cite>Cars</cite>, 2006</li>
<li><cite>Toy Story 2</cite>, 1999</li>
<li><cite>Finding Nemo</cite>, 2003</li>
<li><cite>The Incredibles</cite>, 2004</li>
<li><cite>Ratatouille</cite>, 2007</li>
</ol>
</figure></code></pre>
</div>
<p class="note">While it is conforming to include heading elements (e.g. <code>h1</code>) inside
<code>li</code> elements, it likely does not convey the semantics that the author intended. A
heading starts a new section, so a heading in a list implicitly splits the list into spanning
multiple sections.</p>
<h4>The <dfn element><code>dl</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd>If the element's children include at least one name-value group: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Either: Zero or more groups each consisting of one or more <code>dt</code> elements followed by one or more <code>dd</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dd>Or: One or more <code>div</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-dl">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-dl">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDListElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLDListElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDListElement</code>.</dd>
</dl>
<p>The <code>dl</code> element <span>represents</span> an association list consisting of zero or
more name-value groups (a description list). A name-value group consists of one or more names
(<code>dt</code> elements, possibly as children of a <code>div</code> element child) followed by
one or more values (<code>dd</code> elements, possibly as children of a <code>div</code> element
child), ignoring any nodes other than <code>dt</code> and <code>dd</code> element children, and
<code>dt</code> and <code>dd</code> elements that are children of <code>div</code> element
children. Within a single <code>dl</code> element, there should not be more than one
<code>dt</code> element for each name.</p>
<p>Name-value groups may be terms and definitions, metadata topics and values, questions and
answers, or any other groups of name-value data.</p>
<p>The values within a group are alternatives; multiple paragraphs forming part of the same value
must all be given within the same <code>dd</code> element.</p>
<p>The order of the list of groups, and of the names and values within each group, may be
significant.</p>
<p>In order to annotate groups with <span>microdata</span> attributes, or other <span>global
attributes</span> that apply to whole groups, or just for styling purposes, each group in a
<code>dl</code> element can be wrapped in a <code>div</code> element. This does not change the
semantics of the <code>dl</code> element.</p>
<div w-nodev>
<p>The name-value groups of a <code>dl</code> element <var>dl</var> are determined using the
following algorithm. A name-value group has a name (a list of <code>dt</code> elements, initially
empty) and a value (a list of <code>dd</code> elements, initially empty).</p>
<ol>
<li><p>Let <var>groups</var> be an empty list of name-value groups.</p></li>
<li><p>Let <var>current</var> be a new name-value group.</p></li>
<li><p>Let <var>seenDd</var> be false.</p></li>
<li><p>Let <var>child</var> be <var>dl</var>'s <span>first child</span>.</p></li>
<li><p>Let <var>grandchild</var> be null.</p></li>
<li>
<p>While <var>child</var> is not null:</p>
<ol>
<li>
<p>If <var>child</var> is a <code>div</code> element, then:</p>
<ol>
<li><p>Let <var>grandchild</var> be <var>child</var>'s <span>first child</span>.</p></li>
<li>
<p>While <var>grandchild</var> is not null:</p>
<ol>
<li><p><span>Process <code>dt</code> or <code>dd</code></span> for
<var>grandchild</var>.</p></li>
<li><p>Set <var>grandchild</var> to <var>grandchild</var>'s <span>next
sibling</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Otherwise, <span>process <code>dt</code> or <code>dd</code></span> for
<var>child</var>.</p></li>
<li><p>Set <var>child</var> to <var>child</var>'s <span>next sibling</span>.</p></li>
</ol>
</li>
<li><p>If <var>current</var> is not empty, then append <var>current</var> to
<var>groups</var>.</p></li>
<li><p>Return <var>groups</var>.</p></li>
</ol>
<p>To <dfn>process <code>dt</code> or <code>dd</code></dfn> for a node <var>node</var> means to
follow these steps:</p>
<ol>
<li><p>Let <var>groups</var>, <var>current</var>, and <var>seenDd</var> be the same variables as
those of the same name in the algorithm that invoked these steps.</p></li>
<li>
<p>If <var>node</var> is a <code>dt</code> element, then:</p>
<ol>
<li><p>If <var>seenDd</var> is true, then append <var>current</var> to <var>groups</var>, set
<var>current</var> to a new name-value group, and set <var>seenDd</var> to false.</p></li>
<li><p>Append <var>node</var> to <var>current</var>'s name.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>node</var> is a <code>dd</code> element, then append <var>node</var> to
<var>current</var>'s value and set <var>seenDd</var> to true.</p></li>
</ol>
<p class="note">When a name-value group has an empty list as name or value, it is often due to
accidentally using <code>dd</code> elements in the place of <code>dt</code> elements and vice
versa. Conformance checkers can spot such mistakes and might be able to advise authors how to
correctly use the markup.</p>
</div>
<div class="example">
<p>In the following example, one entry ("Authors") is linked to two values ("John" and
"Luke").</p>
<pre><code class="html"><dl>
<dt> Authors
<dd> John
<dd> Luke
<dt> Editor
<dd> Frank
</dl></code></pre>
</div>
<div class="example">
<p>In the following example, one definition is linked to two terms.</p>
<pre><code class="html"><dl>
<dt lang="en-US"> <dfn>color</dfn> </dt>
<span lang="en-GB"><dt lang="en-GB"> <dfn>colour</dfn> </dt></span>
<dd> A sensation which (in humans) derives from the ability of
the fine structure of the eye to distinguish three differently
filtered analyses of a view. </dd>
</dl></code></pre>
</div>
<div class="example">
<p>The following example illustrates the use of the <code>dl</code> element to mark up metadata
of sorts. At the end of the example, one group has two metadata labels ("Authors" and "Editors")
and two values ("Robert Rothman" and "Daniel Jackson"). This example also uses the
<code>div</code> element around the groups of <code>dt</code> and <code>dd</code> element, to aid
with styling.</p>
<pre><code class="html"><dl>
<div>
<dt> Last modified time </dt>
<dd> 2004-12-23T23:33Z </dd>
</div>
<div>
<dt> Recommended update interval </dt>
<dd> 60s </dd>
</div>
<div>
<dt> Authors </dt>
<dt> Editors </dt>
<dd> Robert Rothman </dd>
<dd> Daniel Jackson </dd>
</div>
</dl></code></pre>
</div>
<div class="example">
<p>The following example shows the <code>dl</code> element used to give a set of instructions.
The order of the instructions here is important (in the other examples, the order of the blocks
was not important).</p>
<pre><code class="html"><p>Determine the victory points as follows (use the
first matching case):</p>
<dl>
<dt> If you have exactly five gold coins </dt>
<dd> You get five victory points </dd>
<dt> If you have one or more gold coins, and you have one or more silver coins </dt>
<dd> You get two victory points </dd>
<dt> If you have one or more silver coins </dt>
<dd> You get one victory point </dd>
<dt> Otherwise </dt>
<dd> You get no victory points </dd>
</dl></code></pre>
</div>
<div class="example">
<p>The following snippet shows a <code>dl</code> element being used as a glossary. Note the use
of <code>dfn</code> to indicate the word being defined.</p>
<pre><code class="html"><dl>
<dt><dfn>Apartment</dfn>, n.</dt>
<dd>An execution context grouping one or more threads with one or
more COM objects.</dd>
<dt><dfn>Flat</dfn>, n.</dt>
<dd>A deflated tire.</dd>
<dt><dfn>Home</dfn>, n.</dt>
<dd>The user's login directory.</dd>
</dl></code></pre>
</div>
<div class="example">
<p>This example uses <span>microdata</span> attributes in a <code>dl</code> element, together
with the <code>div</code> element, to annotate the ice cream desserts at a French restaurant.</p>
<!-- https://commons.wikimedia.org/wiki/File:Carte_des_desserts_2012_des_cafétérias_Toquenelle_(1).jpg -->
<pre lang="fr"><code class="html"><dl>
<div itemscope itemtype="http://schema.org/Product">
<dt itemprop="name">Café ou Chocolat Liégeois
<dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
<span itemprop="price">3.50</span>
<data itemprop="priceCurrency" value="EUR">€</data>
<dd itemprop="description">
2 boules Café ou Chocolat, 1 boule Vanille, sauce café ou chocolat, chantilly
</div>
<div itemscope itemtype="http://schema.org/Product">
<dt itemprop="name">Américaine
<dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
<span itemprop="price">3.50</span>
<data itemprop="priceCurrency" value="EUR">€</data>
<dd itemprop="description">
1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
</div>
</dl></code></pre>
<p>Without the <code>div</code> element the markup would need to use the <code
data-x="attr-itemref">itemref</code> attribute to link the data in the <code>dd</code> elements
with the item, as follows.</p>
<pre lang="fr"><code class="html"><dl>
<dt itemscope itemtype="http://schema.org/Product" itemref="1-offer 1-description">
<span itemprop="name">Café ou Chocolat Liégeois</span>
<dd id="1-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
<span itemprop="price">3.50</span>
<data itemprop="priceCurrency" value="EUR">€</data>
<dd id="1-description" itemprop="description">
2 boules Café ou Chocolat, 1 boule Vanille, sauce café ou chocolat, chantilly
<dt itemscope itemtype="http://schema.org/Product" itemref="2-offer 2-description">
<span itemprop="name">Américaine</span>
<dd id="2-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
<span itemprop="price">3.50</span>
<data itemprop="priceCurrency" value="EUR">€</data>
<dd id="2-description" itemprop="description">
1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
</dl></code></pre>
</div>
<p class="note">The <code>dl</code> element is inappropriate for marking up dialogue. See some <a
href="#conversations">examples of how to mark up dialogue</a>.</p>
<h4>The <dfn element><code>dt</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Before <code>dd</code> or <code>dt</code> elements inside <code>dl</code> elements.</dd>
<dd>Before <code>dd</code> or <code>dt</code> elements inside <code>div</code> elements that are children of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>header</code>, <code>footer</code>, <span>sectioning content</span>, or <span>heading content</span> descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-dt">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-dt">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>dt</code> element <span>represents</span> the term, or name, part of a
term-description group in a description list (<code>dl</code> element).</p>
<p class="note">The <code>dt</code> element itself, when used in a <code>dl</code> element, does
not indicate that its contents are a term being defined, but this can be indicated using the
<code>dfn</code> element.</p>
<div class="example">
<p>This example shows a list of frequently asked questions (a FAQ) marked up using the
<code>dt</code> element for questions and the <code>dd</code> element for answers.</p>
<pre><code class="html"><article>
<h1>FAQ</h1>
<dl>
<dt>What do we want?</dt>
<dd>Our data.</dd>
<dt>When do we want it?</dt>
<dd>Now.</dd>
<dt>Where is it?</dt>
<dd>We are not sure.</dd>
</dl>
</article></code></pre>
</div>
<h4>The <dfn element><code>dd</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>After <code>dt</code> or <code>dd</code> elements inside <code>dl</code> elements.</dd>
<dd>After <code>dt</code> or <code>dd</code> elements inside <code>div</code> elements that are children of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-dd">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-dd">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>dd</code> element <span>represents</span> the description, definition, or value, part
of a term-description group in a description list (<code>dl</code> element).</p>
<div class="example">
<p>A <code>dl</code> can be used to define a vocabulary list, like in a dictionary. In the
following example, each entry, given by a <code>dt</code> with a <code>dfn</code>, has several
<code>dd</code>s, showing the various parts of the definition.</p>
<pre><code class="html"><dl>
<dt><dfn>happiness</dfn></dt>
<dd class="pronunciation">/ˈhæpinəs/</dd>
<dd class="part-of-speech"><i><abbr>n.</abbr></i></dd>
<dd>The state of being happy.</dd>
<dd>Good fortune; success. <q>Oh <b>happiness</b>! It worked!</q></dd>
<dt><dfn>rejoice</dfn></dt>
<dd class="pronunciation">/rɪˈdʒɔɪs/</dd>
<dd><i class="part-of-speech"><abbr>v.intr.</abbr></i> To be delighted oneself.</dd>
<dd><i class="part-of-speech"><abbr>v.tr.</abbr></i> To cause one to be delighted.</dd>
</dl></code></pre>
</div>
<h4>The <dfn element><code>figure</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Either: one <code>figcaption</code> element followed by <span>flow content</span>.</dd>
<dd>Or: <span>flow content</span> followed by one <code>figcaption</code> element.</dd>
<dd>Or: <span>flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-figure">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-figure">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>figure</code> element <span>represents</span> some <span>flow content</span>,
optionally with a caption, that is self-contained (like a complete sentence) and is typically
<span>referenced</span> as a single unit from the main flow of the document.</p>
<p class="note">"Self-contained" in this context does not necessarily mean independent. For
example, each sentence in a paragraph is self-contained; an image that is part of a sentence would
be inappropriate for <code>figure</code>, but an entire sentence made of images would be
fitting.</p>
<p>The element can thus be used to annotate illustrations, diagrams, photos, code listings,
etc.</p>
<div class="note" id="figure-note-about-references">
<p>When a <code>figure</code> is referred to from the main content of the document by identifying
it by its caption (e.g., by figure number), it enables such content to be easily moved away from
that primary content, e.g., to the side of the page, to dedicated pages, or to an appendix,
without affecting the flow of the document.</p>
<p>If a <code>figure</code> element is <span>referenced</span> by its relative position, e.g.,
"in the photograph above" or "as the next figure shows", then moving the figure would disrupt the
page's meaning. Authors are encouraged to consider using labels to refer to figures, rather than
using such relative references, so that the page can easily be restyled without affecting the
page's meaning.</p>
</div>
<p>The <span w-nodev>first</span> <code>figcaption</code> element child of the element, if any,
represents the caption of the <code>figure</code> element's contents. If there is no child
<code>figcaption</code> element, then there is no caption.</p>
<p>A <code>figure</code> element's contents are part of the surrounding flow. If the purpose of
the page is to display the figure, for example a photograph on an image sharing site, the
<code>figure</code> and <code>figcaption</code> elements can be used to explicitly provide a
caption for that figure. For content that is only tangentially related, or that serves a separate
purpose than the surrounding flow, the <code>aside</code> element should be used (and can itself
wrap a <code>figure</code>). For example, a pull quote that repeats content from an
<code>article</code> would be more appropriate in an <code>aside</code> than in a
<code>figure</code>, because it isn't part of the content, it's a repetition of the content for
the purposes of enticing readers or highlighting key topics.</p>
<div class="example">
<p>This example shows the <code>figure</code> element to mark up a code listing.</p>
<pre><code class="html"><p>In <a href="#l4">listing 4</a> we see the primary core interface
API declaration.</p>
<figure id="l4">
<figcaption>Listing 4. The primary core interface API declaration.</figcaption>
<pre><code>interface PrimaryCore {
boolean verifyDataLine();
undefined sendData(sequence&lt;byte> data);
undefined initSelfDestruct();
}</code></pre>
</figure>
<p>The API is designed to use UTF-8.</p></code></pre>
</div>
<div class="example">
<p>Here we see a <code>figure</code> element to mark up a photo that is the main content of the
page (as in a gallery).</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<title>Bubbles at work — My Gallery™</title>
<figure>
<img src="bubbles-work.jpeg"
alt="Bubbles, sitting in his office chair, works on his
latest project intently.">
<figcaption>Bubbles at work</figcaption>
</figure>
<nav><a href="19414.html">Prev</a> — <a href="19416.html">Next</a></nav></code></pre>
</div>
<div class="example">
<p>In this example, we see an image that is <em>not</em> a figure, as well as an image and a
video that are. The first image is literally part of the example's second sentence, so it's not a
self-contained unit, and thus <code>figure</code> would be inappropriate.</p>
<pre><code class="html"><h2>Malinko's comics</h2>
<p>This case centered on some sort of "intellectual property"
infringement related to a comic (see Exhibit A). The suit started
after a trailer ending with these words:
<blockquote>
<img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!">
</blockquote>
<p>...was aired. A lawyer, armed with a Bigger Notebook, launched a
preemptive strike using snowballs. A complete copy of the trailer is
included with Exhibit B.
<figure>
<img src="ex-a.png" alt="Two squiggles on a dirty piece of paper.">
<figcaption>Exhibit A. The alleged <cite>rough copy</cite> comic.</figcaption>
</figure>
<figure>
<video src="ex-b.mov"></video>
<figcaption>Exhibit B. The <cite>Rough Copy</cite> trailer.</figcaption>
</figure>
<p>The case was resolved out of court.</code></pre>
</div>
<div class="example">
<p>Here, a part of a poem is marked up using <code>figure</code>.</p>
<pre><code class="html"><figure>
<p>'Twas brillig, and the slithy toves<br>
Did gyre and gimble in the wabe;<br>
All mimsy were the borogoves,<br>
And the mome raths outgrabe.</p>
<figcaption><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</figcaption>
</figure></code></pre>
</div>
<div class="example">
<p>In this example, which could be part of a much larger work discussing a castle, nested
<code>figure</code> elements are used to provide both a group caption and individual captions for
each figure in the group:</p>
<pre><code class="html"><figure>
<figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
<figure>
<figcaption>Etching. Anonymous, ca. 1423.</figcaption>
<img src="castle1423.jpeg" alt="The castle has one tower, and a tall wall around it.">
</figure>
<figure>
<figcaption>Oil-based paint on canvas. Maria Towle, 1858.</figcaption>
<img src="castle1858.jpeg" alt="The castle now has two towers and two walls.">
</figure>
<figure>
<figcaption>Film photograph. Peter Jankle, 1999.</figcaption>
<img src="castle1999.jpeg" alt="The castle lies in ruins, the original tower all that remains in one piece.">
</figure>
</figure></code></pre>
</div>
<div class="example">
<p>The previous example could also be more succinctly written as follows (using <code
data-x="attr-title">title</code> attributes in place of the nested
<code>figure</code>/<code>figcaption</code> pairs):</p>
<pre><code class="html"><figure>
<img src="castle1423.jpeg" title="Etching. Anonymous, ca. 1423."
alt="The castle has one tower, and a tall wall around it.">
<img src="castle1858.jpeg" title="Oil-based paint on canvas. Maria Towle, 1858."
alt="The castle now has two towers and two walls.">
<img src="castle1999.jpeg" title="Film photograph. Peter Jankle, 1999."
alt="The castle lies in ruins, the original tower all that remains in one piece.">
<figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
</figure></code></pre>
</div>
<div class="example">
<p>The figure is sometimes <span>referenced</span> only implicitly from the content:</p>
<!-- from http://www.reuters.com/article/us-usa-fiscal-idUSBRE98N11220131017 -->
<pre><code class="html"><article>
<h1>Fiscal negotiations stumble in Congress as deadline nears</h1>
<figure>
<img src="obama-reid.jpeg" alt="Obama and Reid sit together smiling in the Oval Office.">
<figcaption>Barack Obama and Harry Reid. White House press photograph.</figcaption>
</figure>
<p>Negotiations in Congress to end the fiscal impasse sputtered on Tuesday, leaving both chambers
grasping for a way to reopen the government and raise the country's borrowing authority with a
Thursday deadline drawing near.</p>
...
</article></code></pre>
</div>
<h4>The <dfn element><code>figcaption</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the first or last child of a <code>figure</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-figcaption">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-figcaption">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>figcaption</code> element <span>represents</span> a caption or legend for the rest of
the contents of the <code>figcaption</code> element's parent <code>figure</code> element<span
w-nodev>, if any</span>.</p>
<div class="example">
<p>The element can contain additional information about the source:</p>
<pre><code class="html"><figcaption>
<p>A duck.</p>
<p><small>Photograph courtesy of 🌟 News.</small></p>
</figcaption></code></pre>
<pre><code class="html"><figcaption>
<p>Average rent for 3-room apartments, excluding non-profit apartments</p>
<p>Zürich’s Statistics Office — <time datetime=2017-11-14>14 November 2017</time></p>
</figcaption></code></pre>
</div>
<h4>The <dfn element><code>main</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected, but only if it is a <span>hierarchically correct
<code>main</code> element</span>.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-main">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-main">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>main</code> element <span>represents</span> the dominant contents of the
document.</p>
<p>A document must not have more than one <code>main</code> element that does not have the <code
data-x="attr-hidden">hidden</code> attribute specified.</p>
<p>A <dfn>hierarchically correct <code>main</code> element</dfn> is one whose ancestor elements
are limited to <code>html</code>, <code>body</code>, <code>div</code>, <code>form</code> without
an <span data-x="concept-accessible-name">accessible name</span>, and <span data-x="autonomous
custom element">autonomous custom elements</span>. Each <code>main</code> element must be a
<span>hierarchically correct <code>main</code> element</span>.</p>
<div class="example">
<p>In this example, the author has used a presentation where each component of the page is
rendered in a box. To wrap the main content of the page (as opposed to the header, the footer,
the navigation bar, and a sidebar), the <code>main</code> element is used.</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<title>RPG System 17</title>
<style>
header, nav, aside, main, footer {
margin: 0.5em; border: thin solid; padding: 0.5em;
background: #EFF; color: black; box-shadow: 0 0 0.25em #033;
}
h1, h2, p { margin: 0; }
nav, main { float: left; }
aside { float: right; }
footer { clear: both; }
</style>
<header>
<h1>System Eighteen</h1>
</header>
<nav>
<a href="../16/">← System 17</a>
<a href="../18/">RPXIX →</a>
</nav>
<aside>
<p>This system has no HP mechanic, so there's no healing.
</aside>
<main>
<h2>Character creation</h2>
<p>Attributes (magic, strength, agility) are purchased at the cost of one point per level.</p>
<h2>Rolls</h2>
<p>Each encounter, roll the dice for all your skills. If you roll more than the opponent, you win.</p>
</main>
<footer>
<p>Copyright © 2013
</footer>
</html></code></pre>
<p>In the following example, multiple <code>main</code> elements are used and script is used to
make navigation work without a server roundtrip and to set the <code
data-x="attr-hidden">hidden</code> attribute on those that are not current:
<pre><code class="html"><!doctype html>
<html lang=en-CA>
<meta charset=utf-8>
<title> … </title>
<link rel=stylesheet href=spa.css>
<script src=spa.js async></script>
<nav>
<a href=/>Home</a>
<a href=/about>About</a>
<a href=/contact>Contact</a>
</nav>
<main>
<h1>Home</h1>
…
</main>
<main hidden>
<h1>About</h1>
…
</main>
<main hidden>
<h1>Contact</h1>
…
</main>
<footer>Made with ❤️ by <a href=https://example.com/>Example 👻</a>.</footer></code></pre>
</div>
<h4>The <dfn element><code>search</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-search">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-search">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>search</code> element <span>represents</span> a part of a document or application
that contains a set of form controls or other content related to performing a search or filtering
operation. This could be a search of the web site or application; a way of searching or filtering
search results on the current web page; or a global or Internet-wide search function.</p>
<p class="note">It's not appropriate to use the <code>search</code> element just for presenting
search results, though suggestions and links as part of "quick search" results can be
included as part of a search feature. Rather, a returned web page of search results would instead
be expected to be presented as part of the main content of that web page.</p>
<div class="example">
<p>In the following example, the author is including a search form within the
<code>header</code> of the web page:</p>
<pre><code class="html"><header>
<h1><a href="/">My fancy blog</a></h1>
...
<search>
<form action="search.php">
<label for="query">Find an article</label>
<input id="query" name="q" type="search">
<button type="submit">Go!</button>
</form>
</search>
</header></code></pre>
</div>
<div class="example">
<p>In this example, the author has implemented their web application's search functionality
entirely with JavaScript. There is no use of the <code>form</code> element to perform
server-side submission, but the containing <code>search</code> element semantically identifies
the purpose of the descendant content as representing search capabilities.</p>
<pre><code class="html"><search>
<label>
Find and filter your query
<input type="search" id="query">
</label>
<label>
<input type="checkbox" id="exact-only">
Exact matches only
</label>
<section>
<h3>Results found:</h3>
<ul id="results">
<li>
<p><a href="services/consulting">Consulting services</a></p>
<p>
Find out how can we help you improve your business with our integrated consultants, Bob and Bob.
</p>
</li>
...
</ul>
<!--
when a query returns or filters out all results
render the no results message here
-->
<output id="no-results"></output>
</section>
</search></code></pre>
</div>
<div class="example">
<p>In the following example, the page has two search features. The first is located in the web page's
<code>header</code> and serves as a global mechanism to search the web site's content. Its purpose is
indicated by its specified <code>title</code> attribute. The second is included as part of the main content
of the page, as it represents a mechanism to search and filter the content of the current page. It contains
a heading to indicate its purpose.</p>
<pre><code class="html"><body>
<header>
...
<search title="Website">
...
</search>
</header>
<main>
<h1>Hotels near your location</h1>
<search>
<h2>Filter results</h2>
...
</search>
<article>
<!-- search result content -->
</article>
</main>
</body></code></pre>
</div>
<h4>The <dfn element><code>div</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dd>As a child of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the element is a child of a <code>dl</code> element: one or more <code>dt</code> elements followed by one or more <code>dd</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dd>If the element is not a child of a <code>dl</code> element: <span>flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-div">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-div">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDivElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLDivElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDivElement</code>.</dd>
</dl>
<p>The <code>div</code> element has no special meaning at all. It <span>represents</span> its
children. It can be used with the <code data-x="attr-class">class</code>, <code
data-x="attr-lang">lang</code>, and <code data-x="attr-title">title</code> attributes to mark up
semantics common to a group of consecutive elements. It can also be used in a <code>dl</code>
element, wrapping groups of <code>dt</code> and <code>dd</code> elements.</p>
<p class="note">Authors are strongly encouraged to view the <code>div</code> element as an element
of last resort, for when no other element is suitable. Use of more appropriate elements instead of
the <code>div</code> element leads to better accessibility for readers and easier maintainability
for authors.</p>
<div class="example">
<p>For example, a blog post would be marked up using <code>article</code>, a chapter using
<code>section</code>, a page's navigation aids using <code>nav</code>, and a group of form
controls using <code>fieldset</code>.</p>
<p>On the other hand, <code>div</code> elements can be useful for stylistic purposes or to wrap
multiple paragraphs within a section that are all to be annotated in a similar way. In the
following example, we see <code>div</code> elements used as a way to set the language of two
paragraphs at once, instead of setting the language on the two paragraph elements separately:</p>
<pre><code class="html"><article lang="en-US">
<h1>My use of language and my cats</h1>
<p>My cat's behavior hasn't changed much since her absence, except
that she plays her new physique to the neighbors regularly, in an
attempt to get pets.</p>
<div lang="en-GB">
<p>My other cat, <!--en-GB-->coloured black and white, is a sweetie. He followed
us to the pool today, walking down the pavement with us. Yesterday
he apparently visited our neighbours. I wonder if he <!--en-GB-->recognises that
their flat is a mirror image of ours.</p>
<p>Hm, I just noticed that in the last paragraph I used British
English. But I'm supposed to write in American English. So I
shouldn't say "pavement" or "flat" or <!--en-GB-->"colour"...</p>
</div>
<p>I should say "sidewalk" and "apartment" and "color"!</p>
</article></code></pre>
</div>
<h3 split-filename="text-level-semantics">Text-level semantics</h3>
<h4>The <dfn element><code>a</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd>If the element has an <code data-x="attr-hyperlink-href">href</code> attribute: <span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>, but there must be no <span>interactive content</span> descendant,
<code>a</code> element descendant, or descendant with the <code
data-x="attr-tabindex">tabindex</code> attribute specified.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-hyperlink-href">href</code></dd>
<dd><code data-x="attr-hyperlink-target">target</code></dd>
<dd><code data-x="attr-hyperlink-download">download</code></dd>
<dd><code data-x="attr-hyperlink-ping">ping</code></dd>
<dd><code data-x="attr-hyperlink-rel">rel</code></dd>
<dd><code data-x="attr-hyperlink-hreflang">hreflang</code></dd>
<dd><code data-x="attr-hyperlink-type">type</code></dd>
<dd><code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If the element has an <code data-x="attr-hyperlink-href">href</code> attribute: <a
href="https://w3c.github.io/html-aria/#el-a">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-a">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-a-no-href">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-a-no-href">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLAnchorElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-target">target</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-download">download</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-a-ping">ping</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-rel">rel</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-a-relList">relList</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-hreflang">hreflang</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-text">text</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-referrerPolicy">referrerPolicy</span>;
// <a href="#HTMLAnchorElement-partial">also has obsolete members</a>
};
<span>HTMLAnchorElement</span> includes <span>HTMLHyperlinkElementUtils</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLAnchorElement</code>.</dd>
</dl>
<p>If the <code>a</code> element has an <code data-x="attr-hyperlink-href">href</code> attribute,
then it <span>represents</span> a <span>hyperlink</span> (a hypertext anchor) labeled by its
contents.</p>
<!-- v2: Eric Meyer requests the ability to nest links so that a big hyperlink, e.g. representing
a calendar event, can be clickable, while within it there are subareas that represent links to
distinct areas, e.g. a link to see photos of the event, or to edit the event, or some such. -->
<p>If the <code>a</code> element has no <code data-x="attr-hyperlink-href">href</code> attribute,
then the element <span>represents</span> a placeholder for where a link might otherwise have been
placed, if it had been relevant, consisting of just the element's contents.</p>
<p>The <code data-x="attr-hyperlink-target">target</code>, <code
data-x="attr-hyperlink-download">download</code>, <code data-x="attr-hyperlink-ping">ping</code>,
<code data-x="attr-hyperlink-rel">rel</code>, <code
data-x="attr-hyperlink-hreflang">hreflang</code>, <code data-x="attr-hyperlink-type">type</code>,
and <code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code> attributes must be omitted
if the <code data-x="attr-hyperlink-href">href</code> attribute is not present.</p>
<p>If the <code data-x="attr-itemprop">itemprop</code> attribute is specified on an <code>a</code> element,
then the <code data-x="attr-hyperlink-href">href</code> attribute must also be specified.</p>
<div class="example">
<p>If a site uses a consistent navigation toolbar on every page, then the link that would
normally link to the page itself could be marked up using an <code>a</code> element:</p>
<pre><code class="html"><nav>
<ul>
<li> <a href="/">Home</a> </li>
<li> <a href="/news">News</a> </li>
<li> <a>Examples</a> </li>
<li> <a href="/legal">Legal</a> </li>
</ul>
</nav></code></pre>
</div>
<div w-nodev>
<p>The <code data-x="attr-hyperlink-href">href</code>, <code
data-x="attr-hyperlink-target">target</code>, <code
data-x="attr-hyperlink-download">download</code>, <code data-x="attr-hyperlink-ping">ping</code>,
and <code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code> attributes affect what
happens when users <span data-x="following hyperlinks">follow hyperlinks</span> or <span
data-x="downloading hyperlinks">download hyperlinks</span> created using the <code>a</code>
element. The <code data-x="attr-hyperlink-rel">rel</code>, <code
data-x="attr-hyperlink-hreflang">hreflang</code>, and <code data-x="attr-hyperlink-type">type</code>
attributes may be used to indicate to the user the likely nature of the target resource before the
user follows the link.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>a</var>.<span subdfn data-x="dom-a-text">text</span></code></dt>
<dd><p>Same as <code>textContent</code>.</p></dd>
</dl>
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-download">download</code></dfn>, <dfn for="HTMLAnchorElement" attribute><code
data-x="dom-a-ping">ping</code></dfn>, <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-target">target</code></dfn>, <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-rel">rel</code></dfn>, <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-hreflang">hreflang</code></dfn>, and <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-type">type</code></dfn>, must <span>reflect</span> the respective content attributes
of the same name.</p>
<p>The IDL attribute <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-rellist">relList</code></dfn> must <span>reflect</span> the <code
data-x="attr-hyperlink-rel">rel</code> content attribute.</p>
<p>The IDL attribute <dfn attribute for="HTMLAnchorElement"><code
data-x="dom-a-referrerPolicy">referrerPolicy</code></dfn> must <span>reflect</span> the <code
data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code> content attribute, <span>limited to
only known values</span>.</p>
<p>The <dfn attribute for="HTMLAnchorElement"><code data-x="dom-a-text">text</code></dfn>
attribute's getter must return this element's <span>descendant text content</span>.</p>
<p>The <code data-x="dom-a-text">text</code> attribute's setter must <span>string replace
all</span> with the given value within this element.</p>
</div>
<div class="example">
<p>The <code>a</code> element can be wrapped around entire paragraphs, lists, tables, and so
forth, even entire sections, so long as there is no interactive content within (e.g., buttons or
other links). This example shows how this can be used to make an entire advertising block into a
link:</p>
<pre><code class="html"><aside class="advertising">
<h1>Advertising</h1>
<a href="https://ad.example.com/?adid=1929&amp;pubid=1422">
<section>
<h1>Mellblomatic 9000!</h1>
<p>Turn all your widgets into mellbloms!</p>
<p>Only $9.99 plus shipping and handling.</p>
</section>
</a>
<a href="https://ad.example.com/?adid=375&amp;pubid=1422">
<section>
<h1>The Mellblom Browser</h1>
<p>Web browsing at the speed of light.</p>
<p>No other browser goes faster!</p>
</section>
</a>
</aside></code></pre>
</div>
<div class="example">
<p>The following example shows how a bit of script can be used to effectively make an entire row
in a job listing table a hyperlink:</p>
<pre><code class="html"><table>
<tr>
<th>Position
<th>Team
<th>Location
<tr>
<td><a href="/jobs/manager">Manager</a>
<td>Remotees
<td>Remote
<tr>
<td><a href="/jobs/director">Director</a>
<td>Remotees
<td>Remote
<tr>
<td><a href="/jobs/astronaut">Astronaut</a>
<td>Architecture
<td>Remote
</table>
<script>
document.querySelector("table").onclick = ({ target }) => {
if (target.parentElement.localName === "tr") {
const link = target.parentElement.querySelector("a");
if (link) {
link.click();
}
}
}
</script></code></pre>
</div>
<h4>The <dfn element><code>em</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-em">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-em">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>em</code> element <span>represents</span> stress emphasis of its contents.</p>
<p>The level of stress that a particular piece of content has is given by its number of ancestor
<code>em</code> elements.</p>
<p>The placement of stress emphasis changes the meaning of the sentence. The element thus forms an
integral part of the content. The precise way in which stress is used in this way depends on the
language.</p>
<div class="example">
<p>These examples show how changing the stress emphasis changes the meaning. First, a general
statement of fact, with no stress:</p>
<pre><code class="html"><p>Cats are cute animals.</p></code></pre>
<p>By emphasizing the first word, the statement implies that the kind of animal under discussion
is in question (maybe someone is asserting that dogs are cute):</p>
<pre><code class="html"><p><em>Cats</em> are cute animals.</p></code></pre>
<p>Moving the stress to the verb, one highlights that the truth of the entire sentence is in
question (maybe someone is saying cats are not cute):</p>
<pre><code class="html"><p>Cats <em>are</em> cute animals.</p></code></pre>
<p>By moving it to the adjective, the exact nature of the cats is reasserted (maybe someone
suggested cats were <em>mean</em> animals):</p>
<pre><code class="html"><p>Cats are <em>cute</em> animals.</p></code></pre>
<p>Similarly, if someone asserted that cats were vegetables, someone correcting this might
emphasize the last word:</p>
<pre><code class="html"><p>Cats are cute <em>animals</em>.</p></code></pre>
<p>By emphasizing the entire sentence, it becomes clear that the speaker is fighting hard to get
the point across. This kind of stress emphasis also typically affects the punctuation, hence the
exclamation mark here.</p>
<pre><code class="html"><p><em>Cats are cute animals!</em></p></code></pre>
<p>Anger mixed with emphasizing the cuteness could lead to markup such as:</p>
<pre><code class="html"><p><em>Cats are <em>cute</em> animals!</em></p></code></pre>
</div>
<div class="note">
<p>The <code>em</code> element isn't a generic "italics" element. Sometimes, text is intended to
stand out from the rest of the paragraph, as if it was in a different mood or voice. For this,
the <code>i</code> element is more appropriate.</p>
<p>The <code>em</code> element also isn't intended to convey importance; for that purpose, the
<code>strong</code> element is more appropriate.</p>
<!--
Thus the following is a bad use of <em>:
<p><em>Note</em>: ...</p>
You should use <strong> or <i> for this instead (depending on
exactly what you're doing).
-->
</div>
<h4>The <dfn element><code>strong</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-strong">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-strong">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>strong</code> element <span>represents</span> strong importance, seriousness, or
urgency for its contents.</p>
<p><strong>Importance</strong>: the <code>strong</code> element can be used in a heading, caption,
or paragraph to distinguish the part that really matters from other parts that might be more
detailed, more jovial, or merely boilerplate. (This is distinct from marking up subheadings, for
which the <code>hgroup</code> element is appropriate.)</p>
<p class="example">For example, the first word of the previous paragraph is marked up with
<code>strong</code> to distinguish it from the more detailed text in the rest of the
paragraph.</p>
<p><strong>Seriousness</strong>: the <code>strong</code> element can be used to mark up a warning
or caution notice.</p>
<p><strong>Urgency</strong>: the <code>strong</code> element can be used to denote contents that
the user needs to see sooner than other parts of the document.</p>
<p>The relative level of importance of a piece of content is given by its number of ancestor
<code>strong</code> elements; each <code>strong</code> element increases the importance of its
contents.</p>
<p>Changing the importance of a piece of text with the <code>strong</code> element does not change
the meaning of the sentence.</p>
<div class="example">
<p>Here, the word "chapter" and the actual chapter number are mere boilerplate, and the actual
name of the chapter is marked up with <code>strong</code>:</p>
<pre><code class="html"><h1>Chapter 1: <strong>The Praxis</strong></h1></code></pre>
<p>In the following example, the name of the diagram in the caption is marked up with
<code>strong</code>, to distinguish it from boilerplate text (before) and the description
(after):</p>
<pre><code class="html"><figcaption>Figure 1. <strong>Ant colony dynamics</strong>. The ants in this colony are
affected by the heat source (upper left) and the food source (lower right).</figcaption></code></pre>
<p>In this example, the heading is really "Flowers, Bees, and Honey", but the author has added a
light-hearted addition to the heading. The <code>strong</code> element is thus used to mark up
the first part to distinguish it from the latter part.</p>
<pre><code class="html"><h1><strong>Flowers, Bees, and Honey</strong> and other things I don't understand</h1></code></pre>
</div>
<div class="example">
<p>Here is an example of a warning notice in a game, with the
various parts marked up according to how important they are:</p>
<!-- DO NOT REFLOW THIS EXAMPLE it has been carefully balanced -->
<pre><code class="html"><p><strong>Warning.</strong> This dungeon is dangerous.
<strong>Avoid the ducks.</strong> Take any gold you find.
<strong><strong>Do not take any of the diamonds</strong>,
they are explosive and <strong>will destroy anything within
ten meters.</strong></strong> You have been warned.</p></code></pre>
</div>
<div class="example">
<p>In this example, the <code>strong</code> element is used to denote the part of the text that
the user is intended to read first.</p>
<pre><code class="html"><p>Welcome to Remy, the reminder system.</p>
<p>Your tasks for today:</p>
<ul>
<li><p><strong>Turn off the oven.</strong></p></li>
<li><p>Put out the trash.</p></li>
<li><p>Do the laundry.</p></li>
</ul></code></pre>
</div>
<h4>The <dfn element><code>small</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-small">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-small">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>small</code> element <span>represents</span> side comments such as small print.</p>
<p class="note">Small print typically features disclaimers, caveats, legal restrictions, or
copyrights. Small print is also sometimes used for attribution, or for satisfying licensing
requirements.</p>
<p class="note">The <code>small</code> element does not "de-emphasize" or lower the importance of
text emphasized by the <code>em</code> element or marked as important with the <code>strong</code>
element. To mark text as not emphasized or important, simply do not mark it up with the
<code>em</code> or <code>strong</code> elements respectively.</p>
<p>The <code>small</code> element should not be used for extended spans of text, such as multiple
paragraphs, lists, or sections of text. It is only intended for short runs of text. The text of a
page listing terms of use, for instance, would not be a suitable candidate for the
<code>small</code> element: in such a case, the text is not a side comment, it is the main content
of the page.</p>
<p>The <code>small</code> element must not be used for subheadings; for that purpose, use the
<code>hgroup</code> element.</p>
<div class="example">
<p>In this example, the <code>small</code> element is used to indicate that value-added tax is
not included in a price of a hotel room:</p>
<pre class="example"><code class="html"><dl>
<dt>Single room
<dd>199 € <small>breakfast included, VAT not included</small>
<dt>Double room
<dd>239 € <small>breakfast included, VAT not included</small>
</dl></code></pre>
</div>
<div class="example">
<p>In this second example, the <code>small</code> element is used for a side comment in an
article.</p>
<pre><code class="html"><p>Example Corp today announced record profits for the
second quarter <small>(Full Disclosure: Foo News is a subsidiary of
Example Corp)</small>, leading to speculation about a third quarter
merger with Demo Group.</p></code></pre>
<p>This is distinct from a sidebar, which might be multiple paragraphs long and is removed from
the main flow of text. In the following example, we see a sidebar from the same article. This
sidebar also has small print, indicating the source of the information in the sidebar.</p>
<pre><code class="html"><aside>
<h1>Example Corp</h1>
<p>This company mostly creates small software and Web
sites.</p>
<p>The Example Corp company mission is "To provide entertainment
and news on a sample basis".</p>
<p><small>Information obtained from <a
href="https://example.com/about.html">example.com</a> home
page.</small></p>
</aside></code></pre>
</div>
<div class="example">
<p>In this last example, the <code>small</code> element is marked as being <em>important</em>
small print.</p>
<pre><code class="html"><p><strong><small>Continued use of this service will result in a kiss.</small></strong></p></code></pre>
</div>
<h4>The <dfn element><code>s</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-s">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-s">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>s</code> element <span>represents</span> contents that are no longer accurate or no
longer relevant.</p>
<p class="note">The <code>s</code> element is not appropriate when indicating document edits; to
mark a span of text as having been removed from a document, use the <code>del</code> element.</p>
<div class="example">
<p>In this example a recommended retail price has been marked as no longer relevant as the
product in question has a new sale price.</p>
<pre><code class="html"><p>Buy our Iced Tea and Lemonade!</p>
<p><s>Recommended retail price: $3.99 per bottle</s></p>
<p><strong>Now selling for just $2.99 a bottle!</strong></p></code></pre>
</div>
<h4>The <dfn element><code>cite</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-cite">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-cite">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>cite</code> element <span>represents</span> the title of a work (e.g.
a book,
a paper,
an essay,
a poem,
a score,
a song,
a script,
a film,
a TV show,
a game,
a sculpture,
a painting,
a theatre production,
a play,
an opera,
a musical,
an exhibition,
a legal case report,
a computer program, <!-- "a software package" ? -->
etc.). This can be a work that is being quoted or <span>referenced</span> in detail (i.e., a
citation), or it can just be a work that is mentioned in passing.</p>
<p>A person's name is not the title of a work — even if people call that person a piece of
work — and the element must therefore not be used to mark up people's names. (In some cases,
the <code>b</code> element might be appropriate for names; e.g. in a gossip article where the
names of famous people are keywords rendered with a different style to draw attention to them. In
other cases, if an element is <em>really</em> needed, the <code>span</code> element can be
used.)</p>
<!--(some people argue a ship is a work)
<p>A ship is similarly not a work, and the element must not be used to mark up ship names (the
<code>i</code> element can be used for that purpose).</p>
-->
<div class="example">
<p>This next example shows a typical use of the <code>cite</code> element:</p>
<pre><code class="html"><p>My favorite book is <cite>The Reality Dysfunction</cite> by
Peter F. Hamilton. My favorite comic is <cite>Pearls Before
Swine</cite> by Stephan Pastis. My favorite track is <cite>Jive
Samba</cite> by the Cannonball Adderley Sextet.</p></code></pre>
</div>
<div class="example">
<p>This is correct usage:</p>
<pre><code class="html"><p>According to the Wikipedia article <cite>HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe. This is obviously an over-simplification.</p></code></pre>
<p>The following, however, is incorrect usage, as the <code>cite</code> element here is
containing far more than the title of the work:</p>
<pre class="bad"><code class="html"><!-- do not copy this example, it is an example of bad usage! -->
<p>According to <cite>the Wikipedia article on HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe. This is obviously an over-simplification.</p></code></pre>
</div>
<div class="example">
<p>The <code>cite</code> element is a key part of any citation in a bibliography, but it is only
used to mark the title:</p>
<pre><code class="html"><p><cite>Universal Declaration of Human Rights</cite>, United Nations,
December 1948. Adopted by General Assembly resolution 217 A (III).</p></code></pre>
</div>
<p class="note">A <em>citation</em> is not a <em>quote</em> (for which the <code>q</code> element
is appropriate).</p>
<div class="example">
<p>This is incorrect usage, because <code>cite</code> is not for quotes:</p>
<pre class="bad"><code class="html"><p><cite>This is wrong!</cite>, said Ian.</p></code></pre>
<p>This is also incorrect usage, because a person is not a work:</p>
<pre class="bad"><code class="html"><p><q>This is still wrong!</q>, said <cite>Ian</cite>.</p></code></pre>
<p>The correct usage does not use a <code>cite</code> element:</p>
<pre><code class="html"><p><q>This is correct</q>, said Ian.</p></code></pre>
<p>As mentioned above, the <code>b</code> element might be relevant for marking names as being
keywords in certain kinds of documents:</p>
<pre><code class="html"><p>And then <b>Ian</b> said <q>this might be right, in a
gossip column, maybe!</q>.</p></code></pre>
</div>
<h4>The <dfn element><code>q</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-q-cite">cite</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-q">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-q">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLQuoteElement</code>.</dd>
</dl>
<p>The <code>q</code> element <span>represents</span> some <span data-x="phrasing content">phrasing
content</span> quoted from another source.</p>
<p>Quotation punctuation (such as quotation marks) that is quoting the contents of the element
must not appear immediately before, after, or inside <code>q</code> elements; they will be
inserted into the rendering by the user agent.</p>
<p>Content inside a <code>q</code> element must be quoted from another source, whose address, if
it has one, may be cited in the <dfn element-attr for="q"><code
data-x="attr-q-cite">cite</code></dfn> attribute. The source may be fictional, as when quoting
characters in a novel or screenplay.</p>
<p>If the <code data-x="attr-q-cite">cite</code> attribute is present, it must be a <span>valid
URL potentially surrounded by spaces</span>. <span w-nodev>To obtain the corresponding citation
link, the value of the attribute must be <span data-x="encoding-parsing a URL">parsed</span>
relative to the element's <span>node document</span>.</span> User agents may allow users to follow
such citation links, but they are primarily intended for private use (e.g., by server-side scripts
collecting statistics about a site's use of quotations), not for readers.</p>
<p>The <code>q</code> element must not be used in place of quotation marks that do not represent
quotes; for example, it is inappropriate to use the <code>q</code> element for marking up
sarcastic statements.</p>
<p>The use of <code>q</code> elements to mark up quotations is entirely optional; using explicit
quotation punctuation without <code>q</code> elements is just as correct.</p>
<div class="example">
<p>Here is a simple example of the use of the <code>q</code> element:</p>
<pre><code class="html"><p>The man said <q>Things that are impossible just take
longer</q>. I disagreed with him.</p></code></pre>
</div>
<div class="example">
<p>Here is an example with both an explicit citation link in the <code>q</code> element, and an
explicit citation outside:</p>
<pre><code class="html"><p>The W3C page <cite>About W3C</cite> says the W3C's
mission is <q cite="https://www.w3.org/Consortium/">To lead the
World Wide Web to its full potential by developing protocols and
guidelines that ensure long-term growth for the Web</q>. I
disagree with this mission.</p></code></pre>
</div>
<div class="example">
<p>In the following example, the quotation itself contains a quotation:</p>
<pre><code class="html"><p>In <cite>Example One</cite>, he writes <q>The man
said <q>Things that are impossible just take longer</q>. I
disagreed with him</q>. Well, I disagree even more!</p></code></pre>
</div>
<div class="example">
<p>In the following example, quotation marks are used instead of the <code>q</code> element:</p>
<pre><code class="html"><p>His best argument was ❝I disagree❞, which
I thought was laughable.</p></code></pre>
</div>
<div class="example">
<p>In the following example, there is no quote — the quotation marks are used to name a
word. Use of the <code>q</code> element in this case would be inappropriate.</p>
<pre><code class="html"><p>The word "ineffable" could have been used to describe the disaster
resulting from the campaign's mismanagement.</p></code></pre>
</div>
<h4>The <dfn element><code>dfn</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, but there must be no <code>dfn</code> element descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd>Also, the <code data-x="attr-dfn-title">title</code> attribute <span data-x="attr-dfn-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-dfn">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-dfn">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>dfn</code> element <span>represents</span> the defining instance of a term. The <span
data-x="paragraph">paragraph</span>, <span data-x="dl">description list group</span>, or <span
data-x="sectioning content">section</span> that is the nearest ancestor of the <code>dfn</code>
element must also contain the definition(s) for the <span data-x="defining term">term</span> given
by the <code>dfn</code> element.</p>
<p><dfn>Defining term</dfn>: if the <code>dfn</code> element has a <dfn element-attr
for="dfn"><code data-x="attr-dfn-title">title</code></dfn> attribute, then the exact value of that
attribute is the term being defined. Otherwise, if it contains exactly one element child node and
no child <code>Text</code> nodes, and that child element is an <code>abbr</code> element with a
<code data-x="attr-abbr-title">title</code> attribute, then the exact value of <em>that</em>
attribute is the term being defined. Otherwise, it is the <span>descendant text content</span> of
the <code>dfn</code> element that gives the term being defined.</p>
<!-- note that this means <dfn>x \n x</dfn> won't match <span>x x</span> -->
<p>If the <code data-x="attr-dfn-title">title</code> attribute of the <code>dfn</code> element is
present, then it must contain only the term being defined.</p>
<p class="note">The <code data-x="attr-title">title</code> attribute of ancestor elements does not
affect <code>dfn</code> elements.</p>
<p>An <code>a</code> element that links to a <code>dfn</code> element represents an instance of
the term defined by the <code>dfn</code> element.</p>
<div class="example">
<p>In the following fragment, the term "Garage Door Opener" is first defined in the first
paragraph, then used in the second. In both cases, its abbreviation is what is actually
displayed.</p>
<pre><code class="html"><p>The <strong><dfn><abbr title="Garage Door Opener">GDO</abbr></dfn></strong>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <strong><abbr title="Garage Door Opener">GDO</abbr></strong>
and so Hammond ordered the iris to be opened.</p></code></pre>
<p>With the addition of an <code>a</code> element, the <span data-x="referenced">reference</span>
can be made explicit:</p>
<pre><code class="html"><p>The <dfn <strong>id=gdo</strong>><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <strong><a href=#gdo></strong><abbr title="Garage Door Opener">GDO</abbr><strong></a></strong>
and so Hammond ordered the iris to be opened.</p></code></pre>
</div>
<h4>The <dfn element><code>abbr</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd>Also, the <code data-x="attr-abbr-title">title</code> attribute <span data-x="attr-abbr-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-abbr">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-abbr">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>abbr</code> element <span>represents</span> an abbreviation or acronym, optionally
with its expansion. The <dfn element-attr for="abbr"><code
data-x="attr-abbr-title">title</code></dfn> attribute may be used to provide an expansion of the
abbreviation. The attribute, if specified, must contain an expansion of the abbreviation, and
nothing else.</p>
<div class="example">
<p>The paragraph below contains an abbreviation marked up with the <code>abbr</code> element.
This paragraph <span data-x="defining term">defines the term</span> "Web Hypertext Application
Technology Working Group".</p>
<pre><code class="html"><p>The <dfn id=whatwg><abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr></dfn>
is a loose unofficial collaboration of web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</p></code></pre>
<p>An alternative way to write this would be:</p>
<pre><code class="html"><p>The <dfn id=whatwg>Web Hypertext Application Technology
Working Group</dfn> (<abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr>)
is a loose unofficial collaboration of web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</p></code></pre>
</div>
<div class="example">
<p>This paragraph has two abbreviations. Notice how only one is defined; the other, with no
expansion associated with it, does not use the <code>abbr</code> element.</p>
<pre><code class="html"><p>The
<abbr title="Web Hypertext Application Technology Working Group">WHATWG</abbr>
started working on HTML5 in 2004.</p></code></pre>
</div>
<div class="example">
<p>This paragraph links an abbreviation to its definition.</p>
<pre><code class="html"><p>The <a href="#whatwg"><abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr></a>
community does not have much representation from Asia.</p></code></pre>
</div>
<div class="example">
<p>This paragraph marks up an abbreviation without giving an expansion, possibly as a hook to
apply styles for abbreviations (e.g. smallcaps).</p>
<pre><code class="html"><p>Philip` and Dashiva both denied that they were going to
get the issue counts from past revisions of the specification to
backfill the <abbr>WHATWG</abbr> issue graph.</p></code></pre>
</div>
<p>If an abbreviation is pluralized, the expansion's grammatical number (plural vs singular) must
match the grammatical number of the contents of the element.</p>
<div class="example">
<p>Here the plural is outside the element, so the expansion is in the singular:</p>
<pre><code class="html"><p>Two <abbr title="Working Group">WG</abbr>s worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>HTMLWG</abbr>.</p></code></pre>
<p>Here the plural is inside the element, so the expansion is in the plural:</p>
<pre><code class="html"><p>Two <abbr title="Working Groups">WGs</abbr> worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>HTMLWG</abbr>.</p></code></pre>
</div>
<p>Abbreviations do not have to be marked up using this element. It is expected to be useful in
the following cases:</p>
<ul>
<li>Abbreviations for which the author wants to give expansions, where using the
<code>abbr</code> element with a <code data-x="attr-title">title</code> attribute is an
alternative to including the expansion inline (e.g. in parentheses).</li>
<li>Abbreviations that are likely to be unfamiliar to the document's readers, for which authors
are encouraged to either mark up the abbreviation using an <code>abbr</code> element with a <code
data-x="attr-title">title</code> attribute or include the expansion inline in the text the first
time the abbreviation is used.</li>
<li>Abbreviations whose presence needs to be semantically annotated, e.g. so that they can be
identified from a style sheet and given specific styles, for which the <code>abbr</code> element
can be used without a <code data-x="attr-title">title</code> attribute.</li>
</ul>
<p class="note">Providing an expansion in a <code data-x="attr-title">title</code> attribute once
will not necessarily cause other <code>abbr</code> elements in the same document with the same
contents but without a <code data-x="attr-title">title</code> attribute to behave as if they had
the same expansion. Every <code>abbr</code> element is independent.</p>
<h4>The <dfn element><code>ruby</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>See prose.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-ruby">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-ruby">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>ruby</code> element allows one or more spans of phrasing content to be marked with
ruby annotations. Ruby annotations are short runs of text presented alongside base text, primarily
used in East Asian typography as a guide for pronunciation or to include other annotations. In
Japanese, this form of typography is also known as <i>furigana</i>.</p>
<p>The content model of <code>ruby</code> elements consists of one or more of the following
sequences:</p>
<ol>
<li>
<p>One or the other of the following:</p>
<ul>
<li><p><span>Phrasing content</span>, but with no <code>ruby</code> elements and with no
<code>ruby</code> element descendants</p></li>
<li><p>A single <code>ruby</code> element that itself has no <code>ruby</code> element
descendants</p></li>
</ul>
<li>
<p>One or the other of the following:</p>
<ul>
<li><p>One or more <code>rt</code> elements</p>
<li><p>An <code>rp</code> element followed by one or more <code>rt</code> elements, each of
which is itself followed by an <code>rp</code> element</p></li>
</ul>
</ol>
<!-- ( ( phrasing-content | <ruby> ) ( <rt>+ | <rp> ( <rt> <rp> )+ ) )+ // with further ruby descendant restrictions -->
<p>The <code>ruby</code> and <code>rt</code> elements can be used for a variety of kinds of
annotations, including in particular (though by no means limited to) those described below. For
more details on Japanese Ruby in particular, and how to render Ruby for Japanese, see
<cite>Requirements for Japanese Text Layout</cite>. <ref>JLREQ</ref></p>
<p class="note">At the time of writing, CSS does not yet provide a way to fully control the
rendering of the HTML <code>ruby</code> element. It is hoped that CSS will be extended to support
the styles described below in due course.</p>
<!-- examples in the following list are mostly based on those in https://www.w3.org/International/datespace/2010/02/jlreq-examples/ -->
<dl>
<dt>Mono-ruby for individual base characters in Japanese
<dd>
<p>One or more hiragana or katakana characters (the ruby annotation) are placed with each
ideographic character (the base text). This is used to provide readings of kanji characters.
<div class="example"> <!-- B as in BASE -->
<pre><code class="html"><ruby>B<rt>annotation</ruby></code></pre>
</div>
<div class="example">
<p>In this example, notice how each annotation corresponds to a single base character.
<pre><code class="html"><ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。</code></pre>
<p lang=ja><ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。
<p>This example can also be written as follows, using one <code>ruby</code> element with two
segments of base text and two annotations (one for each) rather than two back-to-back
<code>ruby</code> elements each with one base text segment and annotation (as in the markup
above):
<pre><code class="html"><ruby>君<rt>くん</rt>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。</code></pre>
</div>
</dd>
<dt>Mono-ruby for compound words (jukugo)
<dd>
<p>This is similar to the previous case: each ideographic character in the compound word (the
base text) has its reading given in hiragana or katakana characters (the ruby annotation). The
difference is that the base text segments form a compound word rather than being separate from
each other.
<div class="example"> <!-- B as in BASE -->
<pre><code class="html"><ruby>B<rt>annotation</rt>B<rt>annotation</ruby></code></pre>
</div>
<div class="example">
<p>In this example, notice again how each annotation corresponds to a single base character. In this example, each compound word (jukugo) corresponds to a single <code>ruby</code> element.</p>
<p>The rendering here is expected to be that each annotation be placed over (or next to, in vertical text) the corresponding base character, with the annotations not overhanging any of the adjacent characters.</p>
<pre><code class="html"><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</code></pre>
<p lang=ja><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
</div>
</dd>
<dt>Jukugo-ruby
<dd>
<p>This is semantically identical to the previous case (each individual ideographic character in
the base compound word has its reading given in an annotation in hiragana or katakana
characters), but the rendering is the more complicated Jukugo Ruby rendering.
<div class="example">
<p>This is the same example as above for mono-ruby for compound words. The different rendering is expected to be achieved using different styling (e.g. in CSS), and is not shown here.</p>
<pre><code class="html"><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</code></pre>
<!-- Once CSS is updated to describe this, invoke the CSS and unhide this -->
<!--
<p lang=ja><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
-->
</div>
<p class="note">For more details on <a
href="https://www.w3.org/TR/jlreq/#positioning_of_jukugoruby">Jukugo Ruby rendering</a>, see
Appendix F in the <cite>Requirements for Japanese Text Layout</cite>. <ref>JLREQ</ref></p>
</dd>
<dt>Group ruby for describing meanings
<dd>
<p>The annotation describes the meaning of the base text, rather than (or in addition to) the
pronunciation. As such, both the base text and the annotation can be multiple characters long.
<div class="example"> <pre><code class="html"><ruby>BASE<rt>annotation</ruby></code></pre> </div>
<div class="example">
<p>Here a compound ideographic word has its corresponding katakana given as an annotation.
<pre><code class="html"><ruby>境界面<rt>インターフェース</ruby></code></pre>
<p lang=ja><ruby>境界面<rt>インターフェース</ruby>
</div>
<div class="example">
<p>Here a compound ideographic word has its translation in English provided as an annotation.
<pre><code class="html"><ruby lang="ja">編集者<rt lang="en">editor</ruby></code></pre>
<p><ruby lang="ja">編集者<rt lang="en">editor</ruby>
</div>
</dd>
<dt>Group ruby for Jukuji readings
<dd>
<p>A phonetic reading that corresponds to multiple base characters, because a one-to-one mapping
would be difficult. (In English, the words "Colonel" and "Lieutenant" are examples of words
where a direct mapping of pronunciation to individual letters is, in some dialects, rather
unclear.)
<div class="example">
<p>In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
<pre><code class="html"><ruby>紫陽花<rt>あじさい</ruby></code></pre>
<p lang=ja><ruby>紫陽花<rt>あじさい</ruby>
</div>
</dd>
<dt>Text with both phonetic and semantic annotations (double-sided ruby)
<dd>
<p>Sometimes, ruby styles described above are combined.
<p>If this results in two annotations covering the same single base segment, then the
annotations can just be placed back to back.
<div class="example">
<pre><code class="html"><ruby>BASE<rt>annotation 1<rt>annotation 2</ruby></code></pre>
</div>
<div class="example">
<pre><code class="html"><ruby>B<rt>a<rt>a</ruby><ruby>A<rt>a<rt>a</ruby><ruby>S<rt>a<rt>a</ruby><ruby>E<rt>a<rt>a</ruby></code></pre>
</div>
<div class="example">
<p>In this contrived example, some symbols are given names in English and French.
<pre><code class="html"><ruby>
♥ <rt> Heart <rt lang=fr> Cœur </rt>
☘ <rt> Shamrock <rt lang=fr> Trèfle </rt>
✶ <rt> Star <rt lang=fr> Étoile </rt>
</ruby></code></pre>
</div>
<p>In more complicated situations such as the following examples, a nested <code>ruby</code>
element is used to give the inner annotations, and then that whole <code>ruby</code> is then
given an annotation at the "outer" level.
<div class="example">
<pre><code class="html"><ruby><ruby>B<rt>a</rt>A<rt>n</rt>S<rt>t</rt>E<rt>n</rt></ruby><rt>annotation</ruby></code></pre>
</div>
<div class="example">
<p>Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested <code>ruby</code> element gives a mono-ruby phonetic annotation for each base character, while the annotation in the <code>rt</code> element that is a child of the outer <code>ruby</code> element gives the meaning using hiragana.
<pre><code class="html"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角</code></pre>
<p lang=ja><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角
</div>
<div class="example">
<p>This is the same example, but the meaning is given in English instead of Japanese:
<pre><code class="html"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角</code></pre>
<p lang=ja><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角
</div>
</dd>
</dl>
<hr>
<p>Within a <code>ruby</code> element that does not have a <code>ruby</code> element ancestor,
content is segmented and segments are placed into three categories: base text segments, annotation
segments, and ignored segments. Ignored segments do not form part of the document's semantics
(they consist of some <span>inter-element whitespace</span> and <code>rp</code> elements, the
latter of which are used for legacy user agents that do not support ruby at all). Base text
segments can overlap (with a limit of two segments overlapping any one position in the DOM, and
with any segment having an earlier start point than an overlapping segment also having an equal or
later end point, and any segment have a later end point than an overlapping segment also having an
equal or earlier start point<!-- if anyone can find a better way of phrasing this parenthetical,
do let me know! -->). Annotation segments correspond to <code>rt</code> elements. Each annotation
segment can be associated with a base text segment, and each base text segment can have annotation
segments associated with it. (In a conforming document, each base text segment is associated with
at least one annotation segment, and each annotation segment is associated with one base text
segment.) A <code>ruby</code> element <span>represents</span> the union of the segments of base
text it contains, along with the mapping from those base text segments to annotation segments.
<span w-nodev>Segments are described in terms of DOM ranges; annotation segment ranges always
consist of exactly one element. <ref>DOM</ref></span></p>
<div w-nodev>
<p>At any particular time, the segmentation and categorization of content of a <code>ruby</code>
element is the result that would be obtained from running the following algorithm:</p>
<ol>
<li><p>Let <var>base text segments</var> be an empty list of base text segments, each
potentially with a list of base text subsegments.</p></li>
<li><p>Let <var>annotation segments</var> be an empty list of annotation segments, each
potentially being associated with a base text segment or subsegment.</p></li>
<li><p>Let <var>root</var> be the <code>ruby</code> element for which the algorithm is
being run.</p></li>
<li><p>If <var>root</var> has a <code>ruby</code> element ancestor, then jump to the
step labeled <i>end</i>.</p></li>
<li><p>Let <var>current parent</var> be <var>root</var>.</p></li>
<li><p>Let <var>index</var> be 0.</p></li>
<li><p>Let <var>start index</var> be null.</p></li>
<li><p>Let <var>saved start index</var> be null.</p></li>
<li><p>Let <var>current base text</var> be null.</p></li>
<!-- This is spaghetti code. If someone can work out a way to phrase this that is as unambiguous
but maps more cleanly to structured code, please let me know. -->
<li><p><i>Start mode</i>: If <var>index</var> is greater than or equal to the number of child
nodes in <var>current parent</var>, then jump to the step labeled <i>end mode</i>.</p>
<li><p>If the <var>index</var>th node in <var>current parent</var> is an
<code>rt</code> or <code>rp</code> element, jump to the step labeled <i>annotation
mode</i>.</p></li>
<!-- if we get here then the first node in a ruby element or after an <rt> or <rp> is something
we want in a base text -->
<li><p>Set <var>start index</var> to the value of <var>index</var>.</p></li>
<li><p><i>Base mode</i>: If the <var>index</var>th node in <var>current
parent</var> is a <code>ruby</code> element, and if <var>current parent</var> is the
same element as <var>root</var>, then <span>push a ruby level</span> and then jump to
the step labeled <i>start mode</i>.</p></li>
<li><p>If the <var>index</var>th node in <var>current parent</var> is an
<code>rt</code> or <code>rp</code> element, then <span>set the current base text</span> and then
jump to the step labeled <i>annotation mode</i>.</p></li>
<li><p>Increment <var>index</var> by one.</p></li>
<li><p><i>Base mode post-increment</i>: If <var>index</var> is greater than or equal to the
number of child nodes in <var>current parent</var>, then jump to the step labeled <i>end
mode</i>.</p></li>
<li><p>Jump back to the step labeled <i>base mode</i>.</p></li>
<li><p><i>Annotation mode</i>: If the <var>index</var>th node in <var>current
parent</var> is an <code>rt</code> element, then <span>push a ruby annotation</span> and jump to
the step labeled <i>annotation mode increment</i>.</p></li>
<li><p>If the <var>index</var>th node in <var>current parent</var> is an
<code>rp</code> element, jump to the step labeled <i>annotation mode increment</i>.</p></li>
<li><p>If the <var>index</var>th node in <var>current parent</var> is not a
<code>Text</code> node, or is a <code>Text</code> node that is not <span>inter-element
whitespace</span>, then jump to the step labeled <i>base mode</i>.</p></li>
<!-- index points at whitespace -->
<li><p><i>Annotation mode increment</i>: Let <var>lookahead index</var> be <var>index</var> plus one.</p></li>
<li><p><i>Annotation mode white-space skipper</i>: If <var>lookahead index</var> is
equal to the number of child nodes in <var>current parent</var> then jump to the step
labeled <i>end mode</i>.</p></li>
<li><p>If the <var>lookahead index</var>th node in <var>current parent</var> is
an <code>rt</code> element or an <code>rp</code> element, then set <var>index</var> to
<var>lookahead index</var> and jump to the step labeled <i>annotation mode</i>.</p></li>
<li><p>If the <var>lookahead index</var>th node in <var>current parent</var> is
not a <code>Text</code> node, or is a <code>Text</code> node that is not <span>inter-element
whitespace</span>, then jump to the step labeled <i>base mode</i> (without further incrementing
<var>index</var>, so the <span>inter-element whitespace</span> seen so far becomes part
of the next base text segment).</p></li>
<li><p>Increment <var>lookahead index</var> by one.</p></li>
<li><p>Jump to the step labeled <i>annotation mode white-space skipper</i>.</p></li>
<li><p><i>End mode</i>: If <var>current parent</var> is not the same element as <var>root</var>, then <span>pop a ruby level</span> and jump to the step labeled <i>base mode
post-increment</i>.</p></li>
<li><p><i>End</i>: Return <var>base text segments</var> and <var>annotation
segments</var>. Any content of the <code>ruby</code> element not described by segments in either
of those lists is implicitly in an <i>ignored segment</i>.</p></li>
</ol>
<p>When the steps above say to <dfn>set the current base text</dfn>, it means to run the following
steps at that point in the algorithm:</p>
<ol>
<li><p>Let <var>text range</var> be a DOM range whose <span
data-x="concept-range-start">start</span> is the <span data-x="concept-range-bp">boundary
point</span> (<var>current parent</var>, <var>start index</var>) and whose
<span data-x="concept-range-end">end</span> is the <span data-x="concept-range-bp">boundary
point</span> (<var>current parent</var>, <var>index</var>).</p></li>
<li><p>Let <var>new text segment</var> be a base text segment described by the range
<var>text range</var>.</p>
<li><p>Add <var>new text segment</var> to <var>base text
segments</var>.</p></li>
<li><p>Let <var>current base text</var> be <var>new text
segment</var>.</p></li>
<li><p>Let <var>start index</var> be null.</p></li>
</ol>
<p>When the steps above say to <dfn>push a ruby level</dfn>, it means to run the following steps
at that point in the algorithm:</p>
<ol>
<li><p>Let <var>current parent</var> be the <var>index</var>th node in <var>current parent</var>.</p></li>
<li><p>Let <var>index</var> be 0.</p></li>
<li><p>Set <var>saved start index</var> to the value of <var>start
index</var>.</p></li>
<li><p>Let <var>start index</var> be null.</p></li>
</ol>
<p>When the steps above say to <dfn>pop a ruby level</dfn>, it means to run the following steps at
that point in the algorithm:</p>
<ol>
<li><p>Let <var>index</var> be the position of <var>current parent</var> in
<var>root</var>.</p></li>
<li><p>Let <var>current parent</var> be <var>root</var>.</p></li>
<li><p>Increment <var>index</var> by one.</p></li>
<li><p>Set <var>start index</var> to the value of <var>saved start
index</var>.</p></li>
<li><p>Let <var>saved start index</var> be null.</p></li>
</ol>
<p>When the steps above say to <dfn>push a ruby annotation</dfn>, it means to run the following
steps at that point in the algorithm:</p>
<ol>
<li><p>Let <var>rt</var> be the <code>rt</code> element that is the <var>index</var>th node of <var>current parent</var>.</p></li>
<li><p>Let <var>annotation range</var> be a DOM range whose <span
data-x="concept-range-start">start</span> is the <span data-x="concept-range-bp">boundary
point</span> (<var>current parent</var>, <var>index</var>) and whose <span
data-x="concept-range-end">end</span> is the <span data-x="concept-range-bp">boundary point</span>
(<var>current parent</var>, <var>index</var> plus one) (i.e. that contains only
<var>rt</var>).</p></li>
<li><p>Let <var>new annotation segment</var> be an annotation segment described by the
range <var>annotation range</var>.</p></li>
<li><p>If <var>current base text</var> is not null, associate <var>new
annotation segment</var> with <var>current base text</var>.</p></li>
<li><p>Add <var>new annotation segment</var> to <var>annotation
segments</var>.</p></li>
</ol>
</div>
<div class="example">
<!-- this is the hiragana for the word "kanji" ("Chinese character") in Japanese -->
<!-- in Japanese, ruby-like typography is called "furigana" -->
<p>In this example, each ideograph in the Japanese text <span data-x=""
lang="ja">漢字</span> is annotated with its reading in hiragana.</p>
<pre lang="ja"><code class="html">...
<ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
...</code></pre>
<p>This might be rendered as:</p>
<p><img src="/images/sample-ruby-ja.png" width="171" height="78"
alt="The two main ideographs, each with its annotation in hiragana rendered in a smaller font above it."></p>
</div>
<div class="example">
<!-- this is the zhuyin fuhao (aka bopomofo) for the word "hanzi" ("Chinese character") in traditional Chinese, as used in Taiwan -->
<p>In this example, each ideograph in the traditional Chinese text <span data-x=""
lang="zh-TW">漢字</span> is annotated with its bopomofo reading.</p>
<pre lang="zh-TW"><code class="html"><ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby></code></pre>
<p>This might be rendered as:</p>
<p><img src="/images/sample-ruby-bopomofo.png" width="78" height="100"
alt="The two main ideographs, each with its bopomofo annotation rendered in a smaller font next to it."></p>
</div>
<div class="example">
<!-- this is the pinyin for the word "hanzi" ("Chinese character") in simplified Chinese, as used in mainland China -->
<p>In this example, each ideograph in the simplified Chinese text <span data-x=""
lang="zh-CN">汉字</span> is annotated with its pinyin reading.</p>
<pre lang="zh-CN"><code class="html">...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...</code></pre>
<p>This might be rendered as:</p>
<p><img src="/images/sample-ruby-pinyin.png" width="173" height="79"
alt="The two main ideographs, each with its pinyin annotation rendered in a smaller font above it."></p>
</div>
<!-- Note: Examples are 32px/16px Stone Sans Sem ITC TT -->
<div class="example">
<p>In this more contrived example, the acronym "HTML" has four annotations: one for the whole
acronym, briefly describing what it is, one for the letters "HT" expanding them to "Hypertext",
one for the letter "M" expanding it to "Markup", and one for the letter "L" expanding it to
"Language".</p>
<pre><code class="html"><ruby>
<ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
<rt>An abstract language for describing documents and applications
</ruby></code></pre>
</div>
<h4>The <dfn element><code>rt</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>ruby</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-rt">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-rt">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>rt</code> element marks the ruby text component of a ruby annotation. When it is the
child of a <code>ruby</code> element, it doesn't <span data-x="represents">represent</span>
anything itself, but the <code>ruby</code> element uses it as part of determining what <em>it</em>
<span>represents</span>.</p>
<div w-nodev>
<p>An <code>rt</code> element that is not a child of a <code>ruby</code> element
<span>represents</span> the same thing as its children.</p>
</div>
<h4>The <dfn element><code>rp</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>ruby</code> element, either immediately before or immediately after an <code>rt</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="text content">Text</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-rp">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-rp">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>rp</code> element can be used to provide parentheses or other content around a ruby
text component of a ruby annotation, to be shown by user agents that don't support ruby
annotations.</p>
<p>An <code>rp</code> element <span w-nodev>that is a child of a <code>ruby</code>
element</span> <span>represents</span> nothing. <span w-nodev>An <code>rp</code> element
whose parent element is not a <code>ruby</code> element <span>represents</span> its
children.</span></p>
<div class="example">
<p>The example above, in which each ideograph in the text <span data-x=""
lang="ja">漢字</span> is annotated with its phonetic reading, could be expanded to
use <code>rp</code> so that in legacy user agents the readings are in parentheses:</p>
<pre lang="ja"><code class="html">...
<ruby>漢<rp>（</rp><rt>かん</rt><rp>）</rp>字<rp>（</rp><rt>じ</rt><rp>）</rp></ruby>
...</code></pre>
<p>In conforming user agents the rendering would be as above, but in user agents that do not
support ruby, the rendering would be:</p>
<pre lang="ja">... 漢（かん）字（じ）...</pre>
</div>
<div class="example">
<p>When there are multiple annotations for a segment, <code>rp</code> elements can also be placed
between the annotations. Here is another copy of an earlier contrived example showing some
symbols with names given in English and French, but this time with <code>rp</code> elements as
well:
<pre><code class="html"><ruby>
♥<rp>: </rp><rt>Heart</rt><rp>, </rp><rt lang=fr>Cœur</rt><rp>.</rp>
☘<rp>: </rp><rt>Shamrock</rt><rp>, </rp><rt lang=fr>Trèfle</rt><rp>.</rp>
✶<rp>: </rp><rt>Star</rt><rp>, </rp><rt lang=fr>Étoile</rt><rp>.</rp>
</ruby></code></pre>
<p>This would make the example render as follows in non-ruby-capable user agents:
<pre>♥: Heart, <span lang=fr>Cœur</span>. ☘: Shamrock, <span lang=fr>Trèfle</span>. ✶: Star, <span lang=fr>Étoile</span>.</pre>
</div>
<h4>The <dfn element><code>data</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-data-value">value</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-data">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-data">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDataElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-data-value">value</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDataElement</code>.</dd>
</dl>
<p>The <code>data</code> element <span>represents</span> its contents, along with a
machine-readable form of those contents in the <code data-x="attr-data-value">value</code>
attribute.</p>
<p>The <dfn element-attr for="data"><code data-x="attr-data-value">value</code></dfn> attribute
must be present. Its value must be a representation of the element's contents in a
machine-readable format.</p>
<p class="note">When the value is date- or time-related, the more specific <code>time</code>
element can be used instead.</p>
<p>The element can be used for several purposes.</p>
<p>When combined with microformats or the <a href="#microdata">microdata attributes</a> defined in
this specification, the element serves to provide both a machine-readable value for the purposes
of data processors, and a human-readable value for the purposes of rendering in a web browser. In
this case, the format to be used in the <code data-x="attr-data-value">value</code> attribute is
determined by the microformats or microdata vocabulary in use.</p>
<p>The element can also, however, be used in conjunction with scripts in the page, for when a
script has a literal value to store alongside a human-readable value. In such cases, the format to
be used depends only on the needs of the script. (The <code data-x="attr-data-*">data-*</code>
attributes can also be useful in such situations.)</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLDataElement"><code data-x="dom-data-value">value</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>
</div>
<div class="example">
<p>Here, a short table has its numeric values encoded using the <code>data</code> element so
that the table sorting JavaScript library can provide a sorting mechanism on each column
despite the numbers being presented in textual form in one column and in a decomposed form in
another.</p>
<pre><code class="html"><script src="sortable.js"></script>
<table class="sortable">
<thead> <tr> <th> Game <th> Corporations <th> Map Size
<tbody>
<tr> <td> 1830 <td> <data value="8">Eight</data> <td> <data value="93">19+74 hexes (93 total)</data>
<tr> <td> 1856 <td> <data value="11">Eleven</data> <td> <data value="99">12+87 hexes (99 total)</data>
<tr> <td> 1870 <td> <data value="10">Ten</data> <td> <data value="149">4+145 hexes (149 total)</data>
</table></code></pre>
</div>
<h4>The <dfn element><code>time</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the element has a <code data-x="attr-time-datetime">datetime</code> attribute: <span>Phrasing content</span>.</dd>
<dd>Otherwise: <span data-x="text content">Text</span>, but must match requirements described in prose below.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-time-datetime">datetime</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-time">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-time">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTimeElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-time-dateTime">dateTime</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTimeElement</code>.</dd>
</dl>
<p>The <code>time</code> element <span>represents</span> its contents, along with a
machine-readable form of those contents in the <code data-x="attr-time-datetime">datetime</code>
attribute. The kind of content is limited to various kinds of dates, times, time-zone offsets, and
durations, as described below.</p>
<p>The <dfn element-attr for="time"><code data-x="attr-time-datetime">datetime</code></dfn>
attribute may be present. If present, its value must be a representation of the element's contents
in a machine-readable format.</p>
<p>A <code>time</code> element that does not have a <code
data-x="attr-time-datetime">datetime</code> content attribute must not have any element
descendants.</p>
<p>The <dfn>datetime value</dfn> of a <code>time</code> element is the value of the element's
<code data-x="attr-time-datetime">datetime</code> content attribute, if it has one, otherwise the
<span>child text content</span> of the <code>time</code> element.</p>
<p>The <span>datetime value</span> of a <code>time</code> element must match one of the following
syntaxes.</p>
<dl>
<dt>A <span>valid month string</span></dt>
<dd>
<pre class="example"><code class="html"><time>2011-11</time></code></pre>
</dd>
<dt>A <span>valid date string</span></dt>
<dd>
<pre class="example"><code class="html"><time>2011-11-18</time></code></pre>
</dd>
<dt>A <span>valid yearless date string</span></dt>
<dd>
<pre class="example"><code class="html"><time>11-18</time></code></pre>
</dd>
<dt>A <span>valid time string</span></dt>
<dd>
<pre class="example"><code class="html"><time>14:54</time></code></pre>
<pre class="example"><code class="html"><time>14:54:39</time></code></pre>
<pre class="example"><code class="html"><time>14:54:39.929</time></code></pre>
</dd>
<dt>A <span>valid local date and time string</span></dt>
<dd>
<pre class="example"><code class="html"><time>2011-11-18T14:54</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39.929</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39.929</time></code></pre>
<p class="note">Times with dates but without a time zone offset are useful for specifying events
that are observed at the same specific time in each time zone, throughout a day. For example,
the 2020 new year is celebrated at 2020-01-01 00:00 in each time zone, not at the same precise
moment across all time zones. For events that occur at the same time across all time zones, for
example a videoconference meeting, a <span>valid global date and time string</span> is likely
more useful.</p>
</dd>
<dt>A <span>valid time-zone offset string</span></dt>
<dd>
<pre class="example"><code class="html"><time>Z</time></code></pre>
<pre class="example"><code class="html"><time>+0000</time></code></pre>
<pre class="example"><code class="html"><time>+00:00</time></code></pre>
<pre class="example"><code class="html"><time>-0800</time></code></pre>
<pre class="example"><code class="html"><time>-08:00</time></code></pre>
<p class="note">For times without dates (or times referring to events that recur on multiple
dates), specifying the geographic location that controls the time is usually more useful than
specifying a time zone offset, because geographic locations change time zone offsets with
daylight saving time. In some cases, geographic locations even change time zone, e.g. when the
boundaries of those time zones are redrawn, as happened with Samoa at the end of 2011. There
exists a time zone database that describes the boundaries of time zones and what rules apply
within each such zone, known as the <i>time zone database</i>. <ref>TZDATABASE</ref></p>
</dd>
<dt>A <span>valid global date and time string</span></dt>
<dd>
<pre class="example"><code class="html"><time>2011-11-18T14:54Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39.929Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39.929+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T14:54:39.929+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54:39-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54:39.929-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54-08:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54:39-08:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18T06:54:39.929-08:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39.929Z</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39.929+0000</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 14:54:39.929+00:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54:39-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54:39.929-0800</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54-08:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54:39-08:00</time></code></pre>
<pre class="example"><code class="html"><time>2011-11-18 06:54:39.929-08:00</time></code></pre>
<p class="note">Times with dates and a time zone offset are useful for specifying specific
events, or recurring virtual events where the time is not anchored to a specific geographic
location. For example, the precise time of an asteroid impact, or a particular meeting in a
series of meetings held at 1400 UTC every day, regardless of whether any particular part of the
world is observing daylight saving time or not. For events where the precise time varies by the
local time zone offset of a specific geographic location, a <span>valid local date and time
string</span> combined with that geographic location is likely more useful.</p>
</dd>
<dt>A <span>valid week string</span></dt>
<dd>
<pre class="example"><code class="html"><time>2011-W47</time></code></pre>
</dd>
<dt>Four or more <span>ASCII digits</span>, at least one of which is not U+0030 DIGIT ZERO (0)</dt>
<dd>
<pre class="example"><code class="html"><time>2011</time></code></pre>
<pre class="example"><code class="html"><time>0001</time></code></pre>
</dd>
<dt>A <span>valid duration string</span></dt>
<dd>
<pre class="example"><code class="html"><time>PT4H18M3S</time></code></pre>
<pre class="example"><code class="html"><time>4h 18m 3s</time></code></pre>
</dd>
</dl>
<div w-nodev>
<p>The <dfn>machine-readable equivalent of the element's contents</dfn> must be obtained from the
element's <span>datetime value</span> by using the following algorithm:</p>
<ol>
<li><p>If <span data-x="parse a month string">parsing a month string</span> from the element's
<span>datetime value</span> returns a <span data-x="concept-month">month</span>, that is the
machine-readable equivalent; return.</p></li>
<li><p>If <span data-x="parse a date string">parsing a date string</span> from the element's
<span>datetime value</span> returns a <span data-x="concept-date">date</span>, that is the
machine-readable equivalent; return.</p></li>
<li><p>If <span data-x="parse a yearless date string">parsing a yearless date string</span> from
the element's <span>datetime value</span> returns a <span data-x="concept-yearless-date">yearless
date</span>, that is the machine-readable equivalent; return.</p></li>
<li><p>If <span data-x="parse a time string">parsing a time string</span> from the element's
<span>datetime value</span> returns a <span data-x="concept-time">time</span>, that is the
machine-readable equivalent; return.</p></li>
<li><p>If <span data-x="parse a local date and time string">parsing a local date and time
string</span> from the element's <span>datetime value</span> returns a <span
data-x="concept-datetime-local">local date and time</span>, that is the machine-readable
equivalent; return.</p></li>
<li><p>If <span data-x="parse a time-zone offset string">parsing a time-zone offset string</span>
from the element's <span>datetime value</span> returns a <span data-x="concept-timezone">time-zone
offset</span>, that is the machine-readable equivalent; return.</p></li>
<li><p>If <span data-x="parse a global date and time string">parsing a global date and time
string</span> from the element's <span>datetime value</span> returns a <span
data-x="concept-datetime">global date and time</span>, that is the machine-readable equivalent;
return.</p></li>
<li><p>If <span data-x="parse a week string">parsing a week string</span> from the element's
<span>datetime value</span> returns a <span data-x="concept-week">week</span>, that is the
machine-readable equivalent; return.</p></li>
<li><p>If the element's <span>datetime value</span> consists of only <span>ASCII digits</span>,
at least one of which is not U+0030 DIGIT ZERO (0), then the machine-readable equivalent is the
base-ten interpretation of those digits, representing a year; return.</p></li>
<li><p>If <span data-x="parse a duration string">parsing a duration string</span> from the
element's <span>datetime value</span> returns a <span data-x="concept-duration">duration</span>,
that is the machine-readable equivalent; return.</p></li>
<li><p>There is no machine-readable equivalent.</p></li>
</ol>
<p class="note">The algorithms referenced above are intended to be designed such that for any
arbitrary string <var>s</var>, only one of the algorithms returns a value. A more
efficient approach might be to create a single algorithm that parses all these data types in one
pass; developing such an algorithm is left as an exercise to the reader.</p>
<p>The <dfn attribute for="HTMLTimeElement"><code data-x="dom-time-dateTime">dateTime</code></dfn>
IDL attribute must <span>reflect</span> the element's <code
data-x="attr-time-datetime">datetime</code> content attribute.</p>
</div>
<div class="example">
<p>The <code>time</code> element can be used to encode dates, for example in microformats. The
following shows a hypothetical way of encoding an event using a variant on hCalendar that uses
the <code>time</code> element:</p>
<pre><code class="html"><div class="vevent">
<a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
<span class="summary">Web 2.0 Conference</span>:
<time class="dtstart" datetime="2005-10-05">October 5</time> -
<time class="dtend" datetime="2005-10-07">7</time>,
at the <span class="location">Argent Hotel, San Francisco, CA</span>
</div></code></pre>
</div>
<div class="example">
<p>Here, a fictional microdata vocabulary based on the Atom vocabulary is used with the
<code>time</code> element to mark up a blog post's publication date.</p>
<pre><code class="html"><article itemscope itemtype="https://n.example.org/rfc4287">
<h1 itemprop="title">Big tasks</h1>
<footer>Published <time itemprop="published" datetime="2009-08-29">two days ago</time>.</footer>
<p itemprop="content">Today, I went out and bought a bike for my kid.</p>
</article></code></pre>
</div>
<div class="example">
<p>In this example, another article's publication date is marked up using <code>time</code>, this
time using the schema.org microdata vocabulary:</p>
<pre><code class="html"><article itemscope itemtype="http://schema.org/BlogPosting">
<h1 itemprop="headline">Small tasks</h1>
<footer>Published <time itemprop="datePublished" datetime="2009-08-30">yesterday</time>.</footer>
<p itemprop="articleBody">I put a bike bell on her bike.</p>
</article></code></pre>
</div>
<div class="example">
<p>In the following snippet, the <code>time</code> element is used to encode a date in the
ISO8601 format, for later processing by a script:</p>
<pre><code class="html"><p>Our first date was <time datetime="2006-09-23">a Saturday</time>.</p></code></pre>
<p>In this second snippet, the value includes a time:</p>
<pre><code class="html"><p>We stopped talking at <time datetime="2006-09-24T05:00-07:00">5am the next morning</time>.</p></code></pre>
<p>A script loaded by the page (and thus privy to the page's internal convention of marking up
dates and times using the <code>time</code> element) could scan through the page and look at all
the <code>time</code> elements therein to create an index of dates and times.</p>
</div>
<div class="example">
<p>For example, this element conveys the string "Friday" with the additional semantic that the
18th of November 2011 is the meaning that corresponds to "Friday":</p>
<pre><code class="html">Today is <time datetime="2011-11-18">Friday</time>.</code></pre>
</div>
<div class="example">
<p>In this example, a specific time in the Pacific Standard Time timezone is specified:</p>
<pre><code class="html">Your next meeting is at <time datetime="2011-11-18T15:00-08:00">3pm</time>.</code></pre>
</div>
<h4>The <dfn element><code>code</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-code">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-code">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>code</code> element <span>represents</span> a fragment of computer code. This could
be an XML element name, a filename, a computer program, or any other string that a computer would
recognize.</p>
<p>There is no formal way to indicate the language of computer code being marked up. Authors who
wish to mark <code>code</code> elements with the language used, e.g. so that syntax highlighting
scripts can use the right rules, can use the <code data-x="attr-class">class</code> attribute, e.g.
by adding a class prefixed with "<code data-x="">language-</code>" to the element.</p>
<div class="example">
<p>The following example shows how the element can be used in a paragraph to mark up element
names and computer code, including punctuation.</p>
<pre><code class="html"><p>The <code>code</code> element represents a fragment of computer
code.</p>
<p>When you call the <code>activate()</code> method on the
<code>robotSnowman</code> object, the eyes glow.</p>
<p>The example below uses the <code>begin</code> keyword to indicate
the start of a statement block. It is paired with an <code>end</code>
keyword, which is followed by the <code>.</code> punctuation character
(full stop) to indicate the end of the program.</p></code></pre>
</div>
<div class="example">
<p>The following example shows how a block of code could be marked up using the <code>pre</code>
and <code>code</code> elements.</p>
<pre><code class="html"><pre><code class="language-pascal">var i: Integer;
begin
i := 1;
end.</code></pre></code></pre>
<p>A class is used in that example to indicate the language used.</p>
</div>
<p class="note">See the <code>pre</code> element for more details.</p>
<h4>The <dfn element><code>var</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-var">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-var">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>var</code> element <span>represents</span> a variable. This could be an actual
variable in a mathematical expression or programming context, an identifier representing a
constant, a symbol identifying a physical quantity, a function parameter, or just be a term used
as a placeholder in prose.</p>
<div class="example">
<p>In the paragraph below, the letter "n" is being used as a
variable in prose:</p>
<pre><code class="html"><p>If there are <var>n</var> pipes leading to the ice
cream factory then I expect at <em>least</em> <var>n</var>
flavors of ice cream to be available for purchase!</p></code></pre>
</div>
<p>For mathematics, in particular for anything beyond the simplest of expressions, MathML is more
appropriate. However, the <code>var</code> element can still be used to refer to specific
variables that are then mentioned in MathML expressions.</p>
<div class="example">
<p>In this example, an equation is shown, with a legend that references the variables in the
equation. The expression itself is marked up with MathML, but the variables are mentioned in the
figure's legend using <code>var</code>.</p>
<pre><code class="html"><figure>
<math>
<mi>a</mi>
<mo>=</mo>
<msqrt>
<msup><mi>b</mi><mn>2</mn></msup>
<mi>+</mi>
<msup><mi>c</mi><mn>2</mn></msup>
</msqrt>
</math>
<figcaption>
Using Pythagoras' theorem to solve for the hypotenuse <var>a</var> of
a triangle with sides <var>b</var> and <var>c</var>
</figcaption>
</figure></code></pre>
</div>
<div class="example">
<p>Here, the equation describing mass-energy equivalence is used in a sentence, and the
<code>var</code> element is used to mark the variables and constants in that equation:</p>
<pre><code class="html"><p>Then she turned to the blackboard and picked up the chalk. After a few moment's
thought, she wrote <var>E</var> = <var>m</var> <var>c</var><sup>2</sup>. The teacher
looked pleased.</p></code></pre>
</div>
<h4>The <dfn element><code>samp</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-samp">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-samp">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>samp</code> element <span>represents</span> sample or quoted output from another
program or computing system.</p>
<p class="note">See the <code>pre</code> and <code>kbd</code> elements for more details.</p>
<p class="note">This element can be contrasted with the <code>output</code> element, which can be
used to provide immediate output in a web application.</p>
<div class="example">
<p>This example shows the <code>samp</code> element being used
inline:</p>
<pre><code class="html"><p>The computer said <samp>Too much cheese in tray
two</samp> but I didn't know what that meant.</p></code></pre>
</div>
<div class="example">
<p>This second example shows a block of sample output from a console program. Nested
<code>samp</code> and <code>kbd</code> elements allow for the styling of specific elements
of the sample output using a style sheet. There's also a few parts of the <code>samp</code> that
are annotated with even more detailed markup, to enable very precise styling. To achieve this,
<code>span</code> elements are used.</p>
<pre><code class="html"><pre><samp><span class="prompt">jdoe@mowmow:~$</span> <kbd>ssh demo.example.com</kbd>
Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown
<span class="prompt">jdoe@demo:~$</span> <span class="cursor">_</span></samp></pre></code></pre>
</div>
<div class="example">
<p>This third example shows a block of input and its respective output. The example uses
both <code>code</code> and <code>samp</code> elements.</p>
<pre><code class="html"><pre>
<code class="language-javascript">console.log(2.3 + 2.4)</code>
<samp>4.699999999999999</samp>
</pre></code></pre>
</div>
<h4>The <dfn element><code>kbd</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-kbd">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-kbd">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>kbd</code> element <span>represents</span> user input (typically keyboard input,
although it may also be used to represent other input, such as voice commands).</p>
<p>When the <code>kbd</code> element is nested inside a <code>samp</code> element, it represents
the input as it was echoed by the system.</p>
<p>When the <code>kbd</code> element <em>contains</em> a <code>samp</code> element, it represents
input based on system output, for example invoking a menu item.</p>
<p>When the <code>kbd</code> element is nested inside another <code>kbd</code> element, it
represents an actual key or other single unit of input as appropriate for the input mechanism.</p>
<div class="example">
<p>Here the <code>kbd</code> element is used to indicate keys to press:</p>
<pre><code class="html"><p>To make George eat an apple, press <kbd><kbd>Shift</kbd> + <kbd>F3</kbd></kbd></p></code></pre>
<p>In this second example, the user is told to pick a particular menu item. The outer
<code>kbd</code> element marks up a block of input, with the inner <code>kbd</code> elements
representing each individual step of the input, and the <code>samp</code> elements inside them
indicating that the steps are input based on something being displayed by the system, in this
case menu labels:</p>
<pre><code class="html"><p>To make George eat an apple, select
<kbd><kbd><samp>File</samp></kbd>|<kbd><samp>Eat Apple...</samp></kbd></kbd>
</p></code></pre>
<p>Such precision isn't necessary; the following is equally fine:</p>
<pre><code class="html"><p>To make George eat an apple, select <kbd>File | Eat Apple...</kbd></p></code></pre>
</div>
<h4>The <dfn element id="the-sub-element"><code>sub</code></dfn> and <dfn element
id="the-sup-element"><code>sup</code></dfn> elements</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>The <code>sub</code> element: <a
href="https://w3c.github.io/html-aria/#el-sub">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-sub">for implementers</a>.</dd>
<dd>The <code>sup</code> element: <a
href="https://w3c.github.io/html-aria/#el-sup">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-sup">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Use <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>sup</code> element <span>represents</span> a superscript and the <code>sub</code>
element <span>represents</span> a subscript.</p>
<p>These elements must be used only to mark up typographical conventions with specific meanings,
not for typographical presentation for presentation's sake. For example, it would be inappropriate
for the <code>sub</code> and <code>sup</code> elements to be used in the name of the LaTeX
document preparation system. In general, authors should use these elements only if the
<em>absence</em> of those elements would change the meaning of the content.</p>
<p>In certain languages, superscripts are part of the typographical conventions for some
abbreviations.</p>
<div class="example">
<pre><code class="html"><p>Their names are
<span lang="fr"><abbr>M<sup>lle</sup></abbr> Gwendoline</span> and
<span lang="fr"><abbr>M<sup>me</sup></abbr> Denise</span>.</p></code></pre>
</div>
<p>The <code>sub</code> element can be used inside a <code>var</code> element, for variables that
have subscripts.</p>
<div class="example">
<p>Here, the <code>sub</code> element is used to represent the subscript that identifies the
variable in a family of variables:</p>
<pre><code class="html"><p>The coordinate of the <var>i</var>th point is
(<var>x<sub><var>i</var></sub></var>, <var>y<sub><var>i</var></sub></var>).
For example, the 10th point has coordinate
(<var>x<sub>10</sub></var>, <var>y<sub>10</sub></var>).</p></code></pre>
</div>
<p>Mathematical expressions often use subscripts and superscripts. Authors are encouraged to use
MathML for marking up mathematics, but authors may opt to use <code>sub</code> and
<code>sup</code> if detailed mathematical markup is not desired. <ref>MATHML</ref></p>
<div class="example">
<pre><code class="html"><var>E</var>=<var>m</var><var>c</var><sup>2</sup></code></pre>
<pre><code class="html">f(<var>x</var>, <var>n</var>) = log<sub>4</sub><var>x</var><sup><var>n</var></sup></code></pre>
</div>
<h4>The <dfn element><code>i</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-i">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-i">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>i</code> element <span>represents</span> a span of text in an alternate voice or
mood, or otherwise offset from the normal prose in a manner indicating a different quality of
text, such as a taxonomic designation, a technical term, an idiomatic phrase from another
language, transliteration, a thought, or a ship name in Western texts.</p>
<p>Terms in languages different from the main text should be annotated with <code
data-x="attr-lang">lang</code> attributes (or, in XML, <span data-x="attr-xml-lang"><code
data-x="">lang</code> attributes in the <span>XML namespace</span></span>).</p>
<div class="example">
<p>The examples below show uses of the <code>i</code> element:</p>
<pre><code class="html"><p>The <i class="taxonomy">Felis silvestris catus</i> is cute.</p>
<p>The term <i>prose content</i> is defined above.</p>
<p>There is a certain <i lang="fr">je ne sais quoi</i> in the air.</p></code></pre>
<p>In the following example, a dream sequence is marked up using
<code>i</code> elements.</p>
<pre><code class="html"><p>Raymond tried to sleep.</p>
<p><i>The ship sailed away on Thursday</i>, he
dreamt. <i>The ship had many people aboard, including a beautiful
princess called Carey. He watched her, day-in, day-out, hoping she
would notice him, but she never did.</i></p>
<p><i>Finally one night he picked up the courage to speak with
her—</i></p>
<p>Raymond woke with a start as the fire alarm rang out.</p></code></pre>
</div>
<p>Authors can use the <code data-x="attr-class">class</code> attribute on the <code>i</code>
element to identify why the element is being used, so that if the style of a particular use (e.g.
dream sequences as opposed to taxonomic terms) is to be changed at a later date, the author
doesn't have to go through the entire document (or series of related documents) annotating each
use.</p>
<p>Authors are encouraged to consider whether other elements might be more applicable than the
<code>i</code> element, for instance the <code>em</code> element for marking up stress emphasis,
or the <code>dfn</code> element to mark up the defining instance of a term.</p>
<p class="note">Style sheets can be used to format <code>i</code> elements, just like any other
element can be restyled. Thus, it is not the case that content in <code>i</code> elements will
necessarily be italicized.</p>
<h4>The <dfn element><code>b</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-b">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-b">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>b</code> element <span>represents</span> a span of text to which attention is being
drawn for utilitarian purposes without conveying any extra importance and with no implication of
an alternate voice or mood, such as key words in a document abstract, product names in a review,
actionable words in interactive text-driven software, or an article lede.</p>
<div class="example">
<p>The following example shows a use of the <code>b</code> element to highlight key words without
marking them up as important:</p>
<pre><code class="html"><p>The <b>frobonitor</b> and <b>barbinator</b> components are fried.</p></code></pre>
</div>
<div class="example">
<p>In the following example, objects in a text adventure are highlighted as being special by use
of the <code>b</code> element.</p>
<pre><code class="html"><p>You enter a small room. Your <b>sword</b> glows
brighter. A <b>rat</b> scurries past the corner wall.</p></code></pre>
</div>
<div class="example">
<p>Another case where the <code>b</code> element is appropriate is in marking up the lede (or
lead) sentence or paragraph. The following example shows how a <a
href="http://news.bbc.co.uk/2/hi/uk_news/scotland/north_east/7101506.stm">BBC article about
kittens adopting a rabbit as their own</a> could be marked up:</p>
<pre><code class="html"><article>
<h2>Kittens 'adopted' by pet rabbit</h2>
<p><b class="lede">Six abandoned kittens have found an
unexpected new mother figure — a pet rabbit.</b></p>
<p>Veterinary nurse Melanie Humble took the three-week-old
kittens to her Aberdeen home.</p>
<i>[...]</i></code></pre>
</div>
<p>As with the <code>i</code> element, authors can use the <code data-x="attr-class">class</code>
attribute on the <code>b</code> element to identify why the element is being used, so that if the
style of a particular use is to be changed at a later date, the author doesn't have to go through
annotating each use.</p>
<p>The <code>b</code> element should be used as a last resort when no other element is more
appropriate. In particular, headings should use the <code>h1</code> to <code>h6</code> elements,
stress emphasis should use the <code>em</code> element, importance should be denoted with the
<code>strong</code> element, and text marked or highlighted should use the <code>mark</code>
element.</p>
<div class="example">
<p>The following would be <em>incorrect</em> usage:</p>
<pre class="bad"><code class="html"><p><b>WARNING!</b> Do not frob the barbinator!</p></code></pre>
<p>In the previous example, the correct element to use would have been <code>strong</code>, not
<code>b</code>.</p>
</div>
<p class="note">Style sheets can be used to format <code>b</code> elements, just like any other
element can be restyled. Thus, it is not the case that content in <code>b</code> elements will
necessarily be boldened.</p>
<h4>The <dfn element><code>u</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-u">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-u">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>u</code> element <span>represents</span> a span of text with an unarticulated, though
explicitly rendered, non-textual annotation, such as labeling the text as being a proper name in
Chinese text (a Chinese proper name mark), or labeling the text as being misspelt.</p>
<p>In most cases, another element is likely to be more appropriate: for marking stress emphasis,
the <code>em</code> element should be used; for marking key words or phrases either the
<code>b</code> element or the <code>mark</code> element should be used, depending on the context;
for marking book titles, the <code>cite</code> element should be used<!-- even for the Chinese
wavy underline 'book title mark' -->; for labeling text with explicit textual annotations, the
<code>ruby</code> element should be used; for technical terms, taxonomic designation,
transliteration, a thought, or for labeling ship names in Western texts, the <code>i</code>
element should be used.</p>
<p class="note">The default rendering of the <code>u</code> element in visual presentations
clashes with the conventional rendering of hyperlinks (underlining). Authors are encouraged to
avoid using the <code>u</code> element where it could be confused for a hyperlink.</p>
<div class="example">
<p>In this example, a <code>u</code> element is used to mark a word as misspelt:</p>
<pre><code class="html"><p>The <u>see</u> is full of fish.</p></code></pre>
</div>
<h4>The <dfn element><code>mark</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-mark">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-mark">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<!-- v2: attribute that means "highlight this on the scrollbar" -->
<p>The <code>mark</code> element <span>represents</span> a run of text in one document marked or
highlighted for <span data-x="referenced">reference</span> purposes, due to its relevance in
another context. When used in a quotation or other block of text referred to from the prose, it
indicates a highlight that was not originally present but which has been added to bring the
reader's attention to a part of the text that might not have been considered important by the
original author when the block was originally written, but which is now under previously
unexpected scrutiny. When used in the main prose of a document, it indicates a part of the
document that has been highlighted due to its likely relevance to the user's current activity.</p>
<div class="example">
<p>This example shows how the <code>mark</code> element can be used to bring attention to a
particular part of a quotation:</p>
<pre><code class="html"><p lang="en-US">Consider the following quote:</p>
<span lang="en-GB"><blockquote lang="en-GB">
<p>Look around and you will find, no-one's really
<!--en-GB--><mark>colour</mark> blind.</p>
</blockquote></span>
<p lang="en-US">As we can tell from the <em>spelling</em> of the word,
the person writing this quote is clearly not American.</p></code></pre>
<p>(If the goal was to mark the element as misspelt, however, the <code>u</code> element,
possibly with a class, would be more appropriate.)</p>
</div>
<div class="example">
<p>Another example of the <code>mark</code> element is highlighting parts of a document that are
matching some search string. If someone looked at a document, and the server knew that the user
was searching for the word "kitten", then the server might return the document with one paragraph
modified as follows:</p>
<pre><code class="html"><p>I also have some <mark>kitten</mark>s who are visiting me
these days. They're really cute. I think they like my garden! Maybe I
should adopt a <mark>kitten</mark>.</p></code></pre>
</div>
<div class="example">
<p>In the following snippet, a paragraph of text refers to a specific part of a code
fragment.</p>
<pre><code class="html"><p>The highlighted part below is where the error lies:</p>
<pre><code>var i: Integer;
begin
i := <mark>1.1</mark>;
end.</code></pre></code></pre>
<p>This is separate from <em>syntax highlighting</em>, for which <code>span</code> is more
appropriate. Combining both, one would get:</p>
<pre><code class="html"><p>The highlighted part below is where the error lies:</p>
<pre><code><span class=keyword>var</span> <span class=ident>i</span>: <span class=type>Integer</span>;
<span class=keyword>begin</span>
<span class=ident>i</span> := <span class=literal><mark>1.1</mark></span>;
<span class=keyword>end</span>.</code></pre></code></pre>
</div>
<div class="example">
<p>This is another example showing the use of <code>mark</code> to highlight a part of quoted
text that was originally not emphasized. In this example, common typographic conventions have led
the author to explicitly style <code>mark</code> elements in quotes to render in italics.</p>
<pre><code class="html"><style>
blockquote mark, q mark {
font: inherit; font-style: italic;
text-decoration: none;
background: transparent; color: inherit;
}
.bubble em {
font: inherit; font-size: larger;
text-decoration: underline;
}
</style>
<article>
<h1>She knew</h1>
<p>Did you notice the subtle joke in the joke on panel 4?</p>
<blockquote>
<p class="bubble">I didn't <em>want</em> to believe. <mark>Of course
on some level I realized it was a known-plaintext attack.</mark> But I
couldn't admit it until I saw for myself.</p>
</blockquote>
<p>(Emphasis mine.) I thought that was great. It's so pedantic, yet it
explains everything neatly.</p>
</article></code></pre>
<p>Note, incidentally, the distinction between the <code>em</code> element in this example, which
is part of the original text being quoted, and the <code>mark</code> element, which is
highlighting a part for comment.</p>
</div>
<div class="example">
<p>The following example shows the difference between denoting the <em>importance</em> of a span
of text (<code>strong</code>) as opposed to denoting the <em>relevance</em> of a span of text
(<code>mark</code>). It is an extract from a textbook, where the extract has had the parts
relevant to the exam highlighted. The safety warnings, important though they may be, are
apparently not relevant to the exam.</p>
<pre><code class="html"><h3>Wormhole Physics Introduction</h3>
<p><mark>A wormhole in normal conditions can be held open for a
maximum of just under 39 minutes.</mark> Conditions that can increase
the time include a powerful energy source coupled to one or both of
the gates connecting the wormhole, and a large gravity well (such as a
black hole).</p>
<p><mark>Momentum is preserved across the wormhole. Electromagnetic
radiation can travel in both directions through a wormhole,
but matter cannot.</mark></p>
<p>When a wormhole is created, a vortex normally forms.
<strong>Warning: The vortex caused by the wormhole opening will
annihilate anything in its path.</strong> Vortexes can be avoided when
using sufficiently advanced dialing technology.</p>
<p><mark>An obstruction in a gate will prevent it from accepting a
wormhole connection.</mark></p></code></pre>
</div>
<h4>The <dfn element><code>bdi</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd>Also, the <code data-x="attr-dir">dir</code><!-- no-annotate --> global attribute has special semantics on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-bdi">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-bdi">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>bdi</code> element <span>represents</span> a span of text that is to be isolated from
its surroundings for the purposes of bidirectional text formatting. <ref>BIDI</ref></p>
<p class="note">The <code data-x="attr-dir">dir</code> global attribute defaults to <code
data-x="attr-dir-auto">auto</code> on this element (it never inherits from the parent element like
with other elements).</p>
<div w-nodev>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<div class="example">
<p>This element is especially useful when embedding user-generated content with an unknown
directionality.</p>
<p>In this example, usernames are shown along with the number of posts that the user has
submitted. If the <code>bdi</code> element were not used, the username of the Arabic user would
end up confusing the text (the bidirectional algorithm would put the colon and the number "3"
next to the word "User" rather than next to the word "posts").</p>
<pre><code class="html"><ul>
<li>User <bdi>jcranmer</bdi>: 12 posts.
<li>User <bdi>hober</bdi>: 5 posts.
<li>User <bdi><bdo dir=rtl>إيان</bdo></bdi>: 3 posts.
</ul></code></pre>
<figure>
<img src="/images/sample-bdi.png" alt="">
<figcaption>When using the <code>bdi</code> element, the username acts as expected.</figcaption>
</figure>
<figure>
<img src="/images/sample-not-bdi.png" alt="">
<figcaption>If the <code>bdi</code> element were to be replaced by a <code>b</code> element, the username would confuse the bidirectional algorithm and the third bullet would end up saying "User 3 :", followed by the Arabic name (right-to-left), followed by "posts" and a period.</figcaption>
</figure>
</div>
<h4>The <dfn element><code>bdo</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd>Also, the <code data-x="attr-dir">dir</code><!-- no-annotate --> global attribute has special semantics on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-bdo">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-bdo">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>bdo</code> element <span>represents</span> explicit text directionality formatting
control for its children. It allows authors to override the Unicode bidirectional algorithm by
explicitly specifying a direction override. <ref>BIDI</ref></p>
<p>Authors must specify the <code data-x="attr-dir">dir</code> attribute on this element, with the
value <code data-x="attr-dir-ltr">ltr</code> to specify a left-to-right override and with the value <code data-x="attr-dir-rtl">rtl</code> to
specify a right-to-left override. The <code data-x="attr-dir-auto">auto</code> value must not be specified.</p>
<div w-nodev>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<h4>The <dfn element><code>span</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-span">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-span">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLSpanElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLSpanElement</code>.</dd>
</dl>
<p>The <code>span</code> element doesn't mean anything on its own, but can be useful when used
together with the <span>global attributes</span>, e.g. <code data-x="attr-class">class</code>,
<code data-x="attr-lang">lang</code>, or <code data-x="attr-dir">dir</code>. It
<span>represents</span> its children.</p>
<div class="example">
<p>In this example, a code fragment is marked up using <code>span</code> elements and <code
data-x="attr-class">class</code> attributes so that its keywords and identifiers can be
color-coded from CSS:</p>
<!-- extract from https://www.cs.cmu.edu/~dst/DeCSS/Gallery/vlc-dvd_css-c.txt -->
<pre><code class="html"><pre><code class="lang-c"><span class="keyword">for</span> (<span class="ident">j</span> = 0; <span class="ident">j</span> &lt; 256; <span class="ident">j</span>++) {
<span class="ident">i_t3</span> = (<span class="ident">i_t3</span> & 0x1ffff) | (<span class="ident">j</span> &lt;&lt; 17);
<span class="ident">i_t6</span> = (((((((<span class="ident">i_t3</span> >> 3) ^ <span class="ident">i_t3</span>) >> 1) ^ <span class="ident">i_t3</span>) >> 8) ^ <span class="ident">i_t3</span>) >> 5) & 0xff;
<span class="keyword">if</span> (<span class="ident">i_t6</span> == <span class="ident">i_t1</span>)
<span class="keyword">break</span>;
}</code></pre></code></pre>
</div>
<h4>The <dfn element><code>br</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-br">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-br">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLBRElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLBRElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLBRElement</code>.</dd>
</dl>
<p>The <code>br</code> element <span>represents</span> a line break.</p>
<p class="note">While line breaks are usually represented in visual media by physically moving
subsequent text to a new line, a style sheet or user agent would be equally justified in causing
line breaks to be rendered in a different manner, for instance as green dots, or as extra
spacing.</p>
<p><code>br</code> elements must be used only for line breaks that are actually part of the
content, as in poems or addresses.</p>
<div class="example">
<p>The following example is correct usage of the <code>br</code> element:</p>
<pre><code class="html"><p>P. Sherman<br>
42 Wallaby Way<br>
Sydney</p></code></pre>
</div>
<p><code>br</code> elements must not be used for separating thematic groups in a paragraph.</p>
<div class="example">
<p>The following examples are non-conforming, as they abuse the <code>br</code> element:</p>
<pre><code class="html"><p><a ...>34 comments.</a><br>
<a ...>Add a comment.</a></p></code></pre>
<pre><code class="html"><p><label>Name: <input name="name"></label><br>
<label>Address: <input name="address"></label></p></code></pre>
<p>Here are alternatives to the above, which are correct:</p>
<pre><code class="html"><p><a ...>34 comments.</a></p>
<p><a ...>Add a comment.</a></p></code></pre>
<pre><code class="html"><p><label>Name: <input name="name"></label></p>
<p><label>Address: <input name="address"></label></p></code></pre>
</div>
<p>If a <span>paragraph</span> consists of nothing but a single <code>br</code> element, it
represents a placeholder blank line (e.g. as in a template). Such blank lines must not be used for
presentation purposes.</p>
<div w-nodev>
<p>Any content inside <code>br</code> elements must not be considered part of the surrounding
text.</p>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<h4>The <dfn element><code>wbr</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-wbr">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-wbr">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>wbr</code> element <span>represents</span> a line break opportunity.</p>
<div class="example">
<p>In the following example, someone is quoted as saying something which, for effect, is written
as one long word. However, to ensure that the text can be wrapped in a readable fashion, the
individual words in the quote are separated using a <code>wbr</code> element.</p>
<pre><code class="html"><p>So then she pointed at the tiger and screamed
"there<wbr>is<wbr>no<wbr>way<wbr>you<wbr>are<wbr>ever<wbr>going<wbr>to<wbr>catch<wbr>me"!</p></code></pre>
</div>
<div w-nodev>
<p>Any content inside <code>wbr</code> elements must not be considered part of the surrounding
text.</p>
<pre class="example"><code class="js">var wbr = document.createElement("wbr");
wbr.textContent = "This is wrong";
document.body.appendChild(wbr);</code></pre>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<h4 id="usage-summary">Usage summary</h4>
<!-- NON-NORMATIVE SECTION -->
<table>
<thead>
<tr>
<th>Element
<th>Purpose
<th>Example
<tbody>
<tr>
<td><code>a</code>
<td>Hyperlinks
<td><pre class="example"><code class="html">Visit my <strong><a href="drinks.html">drinks</a></strong> page.</code></pre>
<tr>
<td><code>em</code>
<td>Stress emphasis
<td><pre class="example"><code class="html">I <!--non-normative-->must say I <strong><em>adore</em></strong> lemonade.</code></pre>
<tr>
<td><code>strong</code>
<td>Importance
<td><pre class="example"><code class="html">This tea is <strong><strong>very hot</strong></strong>.</code></pre>
<tr>
<td><code>small</code>
<td>Side comments
<td><pre class="example"><code class="html">These grapes are made into wine. <strong><small>Alcohol is addictive.</small></strong></code></pre>
<tr>
<td><code>s</code>
<td>Inaccurate text
<td><pre class="example"><code class="html">Price: <strong><s>£4.50</s></strong> £2.00!</code></pre>
<tr>
<td><code>cite</code>
<td>Titles of works
<td><pre class="example"><code class="html">The case <strong><cite>Hugo v. Danielle</cite></strong> is relevant here.</code></pre>
<tr>
<td><code>q</code>
<td>Quotations
<td><pre class="example"><code class="html">The judge said <strong><q>You can drink water from the fish tank</q></strong> but advised against it.</code></pre>
<tr>
<td><code>dfn</code>
<td>Defining instance
<td><pre class="example"><code class="html">The term <strong><dfn>organic food</dfn></strong> refers to food produced without synthetic chemicals.</code></pre>
<tr>
<td><code>abbr</code>
<td>Abbreviations
<td><pre class="example"><code class="html">Organic food in Ireland is certified by the <strong><abbr title="Irish Organic Farmers and Growers Association">IOFGA</abbr></strong>.</code></pre>
<tr>
<td><code>ruby</code>, <code>rt</code>, <code>rp</code>
<td>Ruby annotations
<td><pre class="example"><code class="html"><strong><ruby> OJ <rp>(<rt>Orange Juice<rp>)</ruby></strong></code></pre>
<tr>
<td><code>data</code>
<td>Machine-readable equivalent
<td><pre class="example"><code class="html">Available starting today! <strong><data value="UPC:022014640201">North Coast Organic Apple Cider</data></strong></code></pre>
<tr>
<td><code>time</code>
<td>Machine-readable equivalent of date- or time-related data
<td><pre class="example"><code class="html">Available starting on <strong><time datetime="2011-11-18">November 18th</time></strong>!</code></pre>
<tr>
<td><code>code</code>
<td>Computer code
<td><pre class="example"><code class="html">The <strong><code>fruitdb</code></strong> program can be used for tracking fruit production.</code></pre>
<tr>
<td><code>var</code>
<td>Variables
<td><pre class="example"><code class="html">If there are <strong><var>n</var></strong> fruit in the bowl, at least <strong><var>n</var></strong>÷2 will be ripe.</code></pre>
<tr>
<td><code>samp</code>
<td>Computer output
<td><pre class="example"><code class="html">The computer said <strong><samp>Unknown error -3</samp></strong>.</code></pre>
<tr>
<td><code>kbd</code>
<td>User input
<td><pre class="example"><code class="html">Hit <strong><kbd>F1</kbd></strong> to continue.</code></pre>
<tr>
<td><code>sub</code>
<td>Subscripts
<td><pre class="example"><code class="html">Water is H<strong><sub>2</sub></strong>O.</code></pre>
<tr>
<td><code>sup</code>
<td>Superscripts
<td><pre class="example"><code class="html">The Hydrogen in heavy water is usually <strong><sup>2</sup></strong>H.</code></pre>
<tr>
<td><code>i</code>
<td>Alternative voice
<td><pre class="example"><code class="html">Lemonade consists primarily of <strong><i>Citrus limon</i></strong>.</code></pre>
<tr>
<td><code>b</code>
<td>Keywords
<td><pre class="example"><code class="html">Take a <strong><b>lemon</b></strong> and squeeze it with a <strong><b>juicer</b></strong>.</code></pre>
<tr>
<td><code>u</code>
<td>Annotations
<td><pre class="example"><code class="html">The mixture of apple juice and <strong><u class="spelling">eldeflower</u></strong> juice is very pleasant.</code></pre>
<tr>
<td><code>mark</code>
<td>Highlight
<td><pre class="example"><code class="html">Elderflower cordial, with one <strong><mark>part</mark></strong> cordial to ten <strong><mark>part</mark></strong>s water, stands a<strong><mark>part</mark></strong> from the rest.</code></pre>
<tr>
<td><code>bdi</code>
<td>Text directionality isolation
<td><pre class="example"><code class="html">The <!--non-normative-->recommended restaurant is <strong><bdi lang="">My Juice Café (At The Beach)</bdi></strong>.</code></pre>
<tr>
<td><code>bdo</code>
<td>Text directionality formatting
<td><pre class="example"><code class="html">The proposal is to write English, but in reverse order. "Juice" would become "<strong><bdo dir=rtl>Juice</bdo></strong>"></code></pre>
<tr>
<td><code>span</code>
<td>Other
<td><pre class="example"><code class="html">In French we call it <strong><span lang="fr">sirop de sureau</span></strong>.</code></pre>
<tr>
<td><code>br</code>
<td>Line break
<td><pre class="example"><code class="html">Simply Orange Juice Company<strong><br></strong>Apopka, FL 32703<strong><br></strong>U.S.A.</code></pre>
<tr>
<td><code>wbr</code>
<td>Line breaking opportunity
<td><pre class="example"><code class="html">www.simply<strong><wbr></strong>orange<strong><wbr></strong>juice.com</code></pre>
</table>
<h3 split-filename="links" id="links">Links</h3>
<h4>Introduction</h4>
<p>Links are a conceptual construct, created by <code>a</code>, <code>area</code>,
<code>form</code>, and <code>link</code> elements, that <span data-x="represents">represent</span>
a connection between two resources, one of which is the current <code>Document</code>. There are
three kinds of links in HTML:</p>
<dl>
<dt><dfn data-x="external resource link" data-lt="external resource link" export>Links to
external resources</dfn></dt>
<dd><p>These are links to resources that are to be used to augment the current document,
generally automatically processed by the user agent. All <span data-x="external resource
link">external resource links</span> have a <span>fetch and process the linked resource</span>
algorithm which describes how the resource is obtained.</p></dd>
<dt><dfn data-x="hyperlink" data-lt="hyperlink" export>Hyperlinks</dfn></dt>
<dd><p>These are links to other resources that are generally exposed to the user by the user
agent so that the user can cause the user agent to <span>navigate</span> to those resources, e.g.
to visit them in a browser or download them.</p></dd>
<dt><dfn data-x="Internal resource link" export>Internal resource links</dfn></dt>
<dd><p>These are links to resources within the current document, used to give those resources
special meaning or behavior.</p></dd>
</dl>
<p>For <code>link</code> elements with an <code data-x="attr-link-href">href</code> attribute and a
<code data-x="attr-link-rel">rel</code> attribute, links must be created for the keywords of the
<code data-x="attr-link-rel">rel</code> attribute, as defined for those keywords in the <a
href="#linkTypes">link types</a> section.</p>
<p>Similarly, for <code>a</code> and <code>area</code> elements with an <code
data-x="attr-hyperlink-href">href</code> attribute and a <code
data-x="attr-hyperlink-rel">rel</code> attribute, links must be created for the keywords of the
<code data-x="attr-hyperlink-rel">rel</code> attribute as defined for those keywords in the <a
href="#linkTypes">link types</a> section. Unlike <code>link</code> elements, however,
<code>a</code> and <code>area</code> elements with an <code data-x="attr-hyperlink-href">href</code>
attribute that either do not have a <code data-x="attr-hyperlink-rel">rel</code> attribute, or
whose <code data-x="attr-hyperlink-rel">rel</code> attribute has no keywords that are defined as
specifying <span data-x="hyperlink">hyperlinks</span>, must also create a <span>hyperlink</span>.
This implied hyperlink has no special meaning (it has no <a href="#linkTypes">link type</a>)
beyond linking the element's <span>node document</span> to the resource given by the element's <code
data-x="attr-hyperlink-href">href</code> attribute.</p>
<p>Similarly, for <code>form</code> elements with a <code data-x="attr-form-rel">rel</code>
attribute, links must be created for the keywords of the <code data-x="attr-form-rel">rel</code>
attribute as defined for those keywords in the <a href="#linkTypes">link types</a> section.
<code>form</code> elements that do not have a <code data-x="attr-form-rel">rel</code> attribute,
or whose <code data-x="attr-form-rel">rel</code> attribute has no keywords that are defined as
specifying <span data-x="hyperlink">hyperlinks</span>, must also create a <span>hyperlink</span>.
<p>A <span>hyperlink</span> can have one or more <dfn data-x="hyperlink annotation">hyperlink
annotations</dfn> that modify the processing semantics of that hyperlink.</p>
<h4>Links created by <code>a</code> and <code>area</code> elements</h4>
<p>The <dfn element-attr for="a,area"><code data-x="attr-hyperlink-href">href</code></dfn>
attribute on <code>a</code> and <code>area</code> elements must have a value that is a <span>valid
URL potentially surrounded by spaces</span>.</p>
<p class="note">The <code data-x="attr-hyperlink-href">href</code> attribute on <code>a</code> and
<code>area</code> elements is not required; when those elements do not have <code
data-x="attr-hyperlink-href">href</code> attributes they do not create hyperlinks.</p>
<p>The <dfn element-attr for="a,area"><code data-x="attr-hyperlink-target">target</code></dfn>
attribute, if present, must be a <span>valid navigable target name or keyword</span>. It gives the
name of the <span>navigable</span> that will be used. <span w-nodev>User agents use this
name when <span>following hyperlinks</span>.</span></p>
<p>The <dfn element-attr for="a,area"><code data-x="attr-hyperlink-download">download</code></dfn>
attribute, if present, indicates that the author intends the hyperlink to be used for <span
data-x="downloading hyperlinks">downloading a resource</span>. The attribute may have a value; the
value, if any, specifies the default filename that the author recommends for use in labeling the
resource in a local file system. There are no restrictions on allowed values, but authors are
cautioned that most file systems have limitations with regard to what punctuation is supported in
filenames, and user agents are likely to adjust filenames accordingly.</p>
<p>The <dfn id="ping" element-attr for="a,area"
data-x="attr-hyperlink-ping"><code>ping</code></dfn> attribute, if present, gives the URLs of the
resources that are interested in being notified if the user follows the hyperlink. The value must
be a <span>set of space-separated tokens</span>, each of which must be a <span>valid non-empty
URL</span> whose <span data-x="concept-url-scheme">scheme</span> is an <span>HTTP(S)
scheme</span>. <span w-nodev>The value is used by the user agent for <span>hyperlink
auditing</span>.</span></p>
<p><span w-dev subdfn data-x="dom-a-rellist"></span>The <dfn element-attr for="a,area"><code
data-x="attr-hyperlink-rel">rel</code></dfn> attribute on <code>a</code> and <code>area</code>
elements controls what kinds of links the elements create. The attribute's value must be an
<span>unordered set of unique space-separated tokens</span>. The <a href="#linkTypes">allowed
keywords and their meanings</a> are defined below.</p>
<p><code data-x="attr-hyperlink-rel">rel</code>'s <span
data-x="concept-supported-tokens">supported tokens</span> are the keywords defined in <a
href="#linkTypes">HTML link types</a> which are allowed on <code>a</code> and <code>area</code>
elements, impact the processing model, and are supported by the user agent. The possible <span
data-x="concept-supported-tokens">supported tokens</span> are <code
data-x="rel-noreferrer">noreferrer</code>, <code data-x="rel-noopener">noopener</code>, and <code
data-x="rel-opener">opener</code>. <code data-x="attr-hyperlink-rel">rel</code>'s <span
data-x="concept-supported-tokens">supported tokens</span> must only include the tokens from this
list that the user agent implements the processing model for.</p>
<p>The <code data-x="attr-hyperlink-rel">rel</code> attribute has no default value. If the
attribute is omitted or if none of the values in the attribute are recognized by the user agent,
then the document has no particular relationship with the destination resource other than there
being a hyperlink between the two.</p>
<p>The <dfn element-attr for="a,area"><code data-x="attr-hyperlink-hreflang">hreflang</code></dfn>
attribute on <code>a</code> elements that create <span data-x="hyperlink">hyperlinks</span>, if
present, gives the language of the linked resource. It is purely advisory. The value must be a
valid BCP 47 language tag. <ref>BCP47</ref> <span w-nodev>User agents must not consider this
attribute authoritative — upon fetching the resource, user agents must use only language
information associated with the resource to determine its language, not metadata included in the
link to the resource.</span></p>
<p>The <dfn element-attr for="a,area"><code data-x="attr-hyperlink-type">type</code></dfn>
attribute, if present, gives the <span>MIME type</span> of the linked resource. It is purely
advisory. The value must be a <span>valid MIME type string</span>. <span w-nodev>User agents must
not consider the <code data-x="attr-hyperlink-type">type</code> attribute authoritative —
upon fetching the resource, user agents must not use metadata included in the link to the resource
to determine its type.</span></p>
<p>The <dfn element-attr for="a,area"><code
data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code></dfn> attribute is a <span>referrer
policy attribute</span>. Its purpose is to set the <span>referrer policy</span> used when
<span>following hyperlinks</span>. <ref>REFERRERPOLICY</ref></p>
<hr>
<p>When an <code>a</code> or <code>area</code> element's <span>activation behavior</span> is
invoked, the user agent may allow the user to indicate a preference regarding whether the
hyperlink is to be used for <span data-x="navigate">navigation</span> or whether the resource it
specifies is to be downloaded.</p>
<p>In the absence of a user preference, the default should be navigation if the element has no
<code data-x="attr-hyperlink-download">download</code> attribute, and should be to download the
specified resource if it does.</p>
<p>The <span>activation behavior</span> of an <code>a</code> or <code>area</code> element
<var>element</var> given an event <var>event</var> is:</p>
<ol>
<li><p>If <var>element</var> has no <code data-x="attr-hyperlink-href">href</code> attribute,
then return.</p></li>
<li><p>Let <var>hyperlinkSuffix</var> be null.</p></li>
<li><p>If <var>element</var> is an <code>a</code> element, and <var>event</var>'s <span
data-x="concept-event-target">target</span> is an <code>img</code> with an <code
data-x="attr-img-ismap">ismap</code> attribute specified, then:</p>
<ol>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A...%3Ca%20href%3D%22%23%22%3E%3Cimg%20ismap%20usemap%3D%22%23a%22%20src%3D/resources/images/smallcats%3E%3C/a%3E%0A%3Cmap%20name%3Da%3E%3Carea%20shape%3Drect%20coords%3D0%2C0%2C50%2C50%20href%3Db%3E%3C/map%3E -->
<li><p>Let <var>x</var> and <var>y</var> be 0.</p></li>
<li><p>If <var>event</var>'s <code data-x="dom-Event-isTrusted">isTrusted</code> attribute is
initialized to true, then set <var>x</var> to the distance in <span data-x="'px'">CSS
pixels</span> from the left edge of the image to the location of the click, and set
<var>y</var> to the distance in <span data-x="'px'">CSS pixels</span> from the top edge of the
image to the location of the click.</p></li>
<li><p>If <var>x</var> is negative, set <var>x</var> to 0.</p></li>
<li><p>If <var>y</var> is negative, set <var>y</var> to 0.</p></li>
<li><p>Set <var>hyperlinkSuffix</var> to the concatenation of U+003F (?), the value of
<var>x</var> expressed as a base-ten integer using <span>ASCII digits</span>, U+002C (,), and
the value of <var>y</var> expressed as a base-ten integer using <span>ASCII
digits</span>.</p></li>
</ol>
</li>
<li><p>Let <var>userInvolvement</var> be <var>event</var>'s <span data-x="event-uni">user
navigation involvement</span>.</p></li>
<li>
<p>If the user has expressed a preference to download the hyperlink, then set
<var>userInvolvement</var> to "<code data-x="uni-browser-ui">browser UI</code>".</p>
<p class="note">That is, if the user has expressed a specific preference for downloading, this
no longer counts as merely "<code data-x="uni-activation">activation</code>".</p>
</li>
<li><p>If <var>element</var> has a <code data-x="attr-hyperlink-download">download</code>
attribute, or if the user has expressed a preference to download the hyperlink, then <span
data-x="downloading hyperlinks">download the hyperlink</span> created by <var>element</var> with
<i data-x="downloading-hyperlinkSuffix">hyperlinkSuffix</i> set to <var>hyperlinkSuffix</var> and
<i data-x="downloading-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>.</p></li>
<li><p>Otherwise, <span data-x="following hyperlinks">follow the hyperlink</span> created by
<var>element</var> with <i data-x="following-hyperlinkSuffix">hyperlinkSuffix</i> set to
<var>hyperlinkSuffix</var> and <i data-x="following-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>.</p></li>
</ol>
<h4>API for <code>a</code> and <code>area</code> elements</h4>
<pre><code class="idl">interface mixin <dfn interface>HTMLHyperlinkElementUtils</dfn> {
[<span>CEReactions</span>] stringifier attribute USVString <span data-x="dom-hyperlink-href">href</span>;
readonly attribute USVString <span data-x="dom-hyperlink-origin">origin</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-protocol">protocol</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-username">username</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-password">password</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-host">host</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-hostname">hostname</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-port">port</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-pathname">pathname</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-search">search</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-hyperlink-hash">hash</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>hyperlink</var>.<span data-x="">toString()</span></code></dt>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-href">href</span></code></dt>
<dd>
<p>Returns the hyperlink's URL.</p>
<p>Can be set, to change the URL.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-origin">origin</span></code></dt>
<dd><p>Returns the hyperlink's URL's origin.</p></dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-protocol">protocol</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's scheme.</p>
<p>Can be set, to change the URL's scheme.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-username">username</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's username.</p>
<p>Can be set, to change the URL's username.</p>
</dd>
<!-- This feature is technically non-conforming -->
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-password">password</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's password.</p>
<p>Can be set, to change the URL's password.</p>
</dd>
<!-- This feature is technically non-conforming -->
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-host">host</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's host and port (if different from the default port for the
scheme).</p>
<p>Can be set, to change the URL's host and port.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-hostname">hostname</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's host.</p>
<p>Can be set, to change the URL's host.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-port">port</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's port.</p>
<p>Can be set, to change the URL's port.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-pathname">pathname</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's path.</p>
<p>Can be set, to change the URL's path.</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-search">search</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's query (includes leading "<code data-x="">?</code>" if
non-empty).</p>
<p>Can be set, to change the URL's query (ignores leading "<code data-x="">?</code>").</p>
</dd>
<dt><code data-x=""><var>hyperlink</var>.<span subdfn data-x="dom-hyperlink-hash">hash</span></code></dt>
<dd>
<p>Returns the hyperlink's URL's fragment (includes leading "<code data-x="">#</code>" if
non-empty).</p>
<p>Can be set, to change the URL's fragment (ignores leading "<code data-x="">#</code>").</p>
</dd>
</dl>
<div w-nodev>
<p>An element implementing the <code>HTMLHyperlinkElementUtils</code> mixin has an associated <dfn
data-x="concept-hyperlink-url">url</dfn> (null or a <span>URL</span>). It is initially null.
<p>An element implementing the <code>HTMLHyperlinkElementUtils</code> mixin has an associated <dfn
data-x="concept-hyperlink-url-set">set the url</dfn> algorithm, which runs these steps:</p>
<ol>
<li><p>Set this element's <span data-x="concept-hyperlink-url">url</span> to null.</p></li>
<li><p>If this element's <code data-x="attr-hyperlink-href">href</code> content attribute is
absent, then return.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given this
element's <code data-x="attr-hyperlink-href">href</code> content attribute's value, relative to
this element's <span>node document</span>.</p></li>
<li><p>If <var>url</var> is not failure, then set this element's <span
data-x="concept-hyperlink-url">url</span> to <var>url</var>.</p></li>
</ol>
<p>When elements implementing the <code>HTMLHyperlinkElementUtils</code> mixin are created, and
whenever those elements have their <code data-x="attr-hyperlink-href">href</code> content
attribute set, changed, or removed, the user agent must <span
data-x="concept-hyperlink-url-set">set the url</span>.</p>
<p class="note">This is only observable for <code data-x="blob protocol">blob:</code> URLs as
<span data-x="url parser">parsing</span> them involves a <span>Blob URL Store</span> lookup.</p>
<p>An element implementing the <code>HTMLHyperlinkElementUtils</code> mixin has an associated
<!--en-GB--><dfn id="reinitialise-url">reinitialize url</dfn> algorithm, which runs these
steps:</p>
<ol>
<li><p>If the element's <span data-x="concept-hyperlink-url">url</span> is non-null, its <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">blob</code>", and it has an
<span>opaque path</span>, then terminate these steps.</p></li>
<li><p><span data-x="concept-hyperlink-url-set">Set the url</span>.</p></li>
</ol>
<p>To <dfn>update <code>href</code></dfn>, set the element's <code
data-x="attr-hyperlink-href">href</code> content attribute's value to the element's <span
data-x="concept-hyperlink-url">url</span>, <span
data-x="concept-url-serializer">serialized</span>.</p>
<hr>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-href">href</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null and <span>this</span> has no <code
data-x="attr-hyperlink-href">href</code> content attribute, return the empty string.
<li><p>Otherwise, if <var>url</var> is null, return <span>this</span>'s <code
data-x="attr-hyperlink-href">href</code> content attribute's value.</p></li>
<li><p>Return <var>url</var>, <span data-x="concept-url-serializer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-href">href</code> setter steps are to set <span>this</span>'s
<code data-x="attr-hyperlink-href">href</code> content attribute's value to the given value.
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-origin">origin</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-hyperlink-url">url</span> is null, return the
empty string.</p></li>
<li><p>Return the <span data-x="serialization of an origin">serialization</span> of
<span>this</span>'s <span data-x="concept-hyperlink-url">url</span>'s <span
data-x="concept-url-origin">origin</span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-protocol">protocol</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-hyperlink-url">url</span> is null, return
"<code data-x="">:</code>".</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-hyperlink-url">url</span>'s <span
data-x="concept-url-scheme">scheme</span>, followed by "<code data-x="">:</code>".</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-protocol">protocol</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-hyperlink-url">url</span> is null, then
return.</p></li>
<li>
<p><span data-x="basic url parser">Basic URL parse</span> the given value, followed by "<code
data-x="">:</code>", with <span>this</span>'s <span data-x="concept-hyperlink-url">url</span> as
<span data-x="basic url parser url"><i>url</i></span> and <span>scheme start state</span> as
<span data-x="basic url parser state override"><i>state override</i></span>.</p>
<p class="note">Because the URL parser ignores multiple consecutive colons, providing a value
of "<code data-x="">https:</code>" (or even "<code data-x="">https::::</code>") is the same as
providing a value of "<code data-x="">https</code>".</p>
</li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-username">username</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-hyperlink-url">url</span> is null, return the
empty string.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-hyperlink-url">url</span>'s <span
data-x="concept-url-username">username</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-username">username</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var>
<span>cannot have a username/password/port</span>, then return.</p></li>
<li><p><span>Set the username</span>, given <var>url</var> and the given value.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-password">password</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, then return the empty string.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-password">password</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-password">password</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var>
<span>cannot have a username/password/port</span>, then return.</p></li>
<li><p><span>Set the password</span>, given <var>url</var> and the given value.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-host">host</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> or <var>url</var>'s <span data-x="concept-url-host">host</span> is null,
return the empty string.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-port">port</span> is null, return
<var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>, followed by "<code data-x="">:</code>" and <var>url</var>'s <span
data-x="concept-url-port">port</span>, <span data-x="serialize an
integer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-host">host</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var> has an <span>opaque path</span>, then
return.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>host
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-hostname">hostname</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> or <var>url</var>'s <span data-x="concept-url-host">host</span> is null,
return the empty string.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-hostname">hostname</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var> has an <span>opaque path</span>, then
return.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>hostname
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-port">port</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> or <var>url</var>'s <span data-x="concept-url-port">port</span> is null,
return the empty string.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-port">port</span>, <span
data-x="serialize an integer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-port">port</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var>
<span>cannot have a username/password/port</span>, then return.</p></li>
<li><p>If the given value is the empty string, then set <var>url</var>'s <span
data-x="concept-url-port">port</span> to null.</p></li>
<li><p>Otherwise, <span data-x="basic url parser">basic URL parse</span> the given value, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>port
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-pathname">pathname</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, then return the empty string.</p></li>
<li><p>Return the result of <span data-x="URL path serializer">URL path serializing</span>
<var>url</var>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-pathname">pathname</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null or <var>url</var> has an <span>opaque path</span>, then
return.</p></li>
<li><p>Set <var>url</var>'s <span data-x="concept-url-path">path</span> to the empty
list.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>path start
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-search">search</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, or <var>url</var>'s <span
data-x="concept-url-query">query</span> is either null or the empty string, return the empty
string.</p></li>
<li><p>Return "<code data-x="">?</code>", followed by <var>url</var>'s <span
data-x="concept-url-query">query</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-search">search</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, terminate these steps.</p></li>
<li><p>If the given value is the empty string, set <var>url</var>'s <span
data-x="concept-url-query">query</span> to null.
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>input</var> be the given value with a single leading "<code data-x="">?</code>"
removed, if any.</p></li>
<li><p>Set <var>url</var>'s <span data-x="concept-url-query">query</span> to the empty
string.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> <var>input</var>, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>query
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
</ol>
</li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLHyperlinkElementUtils"><code
data-x="dom-hyperlink-hash">hash</code></dfn> getter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, or <var>url</var>'s <span
data-x="concept-url-fragment">fragment</span> is either null or the empty string, return the
empty string.</p></li>
<li><p>Return "<code data-x="">#</code>", followed by <var>url</var>'s <span
data-x="concept-url-fragment">fragment</span>.</p></li>
</ol>
<p>The <code data-x="dom-hyperlink-hash">hash</code> setter steps are:</p>
<ol>
<li><p><span>Reinitialize url</span>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-hyperlink-url">url</span>.</p></li>
<li><p>If <var>url</var> is null, then return.</p></li>
<li><p>If the given value is the empty string, set <var>url</var>'s <span
data-x="concept-url-fragment">fragment</span> to null.
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>input</var> be the given value with a single leading "<code data-x="">#</code>"
removed, if any.</p></li>
<li><p>Set <var>url</var>'s <span data-x="concept-url-fragment">fragment</span> to the empty
string.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> <var>input</var>, with
<var>url</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>fragment
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
</ol>
</li>
<li><p><span>Update <code>href</code></span>.</p></li>
</ol>
<h4>Following hyperlinks</h4>
<p>An element <var>element</var> <dfn>cannot navigate</dfn> if any of the following are true:</p>
<ul>
<li><p><var>element</var>'s <span>node document</span> is not <span>fully active</span>;
or</p></li>
<li><p><var>element</var> is not an <code>a</code> element and is not
<span>connected</span>.</p></li>
</ul>
<p class="note">This is also used by <span data-x="concept-form-submit">form submission</span> for
the <code>form</code> element. The exception for <code>a</code> elements is for compatibility with
web content.</p>
<p>To <dfn>get an element's noopener</dfn>, given an <code>a</code>, <code>area</code>, or
<code>form</code> element <var>element</var>, a <span>URL record</span> <var>url</var>, and a
string <var>target</var>, perform the following steps. They return a boolean.</p>
<ol>
<li><p>If <var>element</var>'s <a href="#linkTypes">link types</a> include the <code
data-x="rel-noopener">noopener</code> or <code data-x="rel-noreferrer">noreferrer</code>
keyword, then return true.</li>
<li id="opener-processing-model"><p>If <var>element</var>'s <a href="#linkTypes">link types</a>
do not include the <code data-x="rel-opener">opener</code> keyword and <var>target</var> is an
<span>ASCII case-insensitive</span> match for "<code data-x="">_blank</code>", then return
true.</p></li>
<li>
<p>If <var>url</var>'s <span data-x="concept-url-blob-entry">blob URL entry</span> is not
null:</p>
<ol>
<li><p>Let <var>blobOrigin</var> be <var>url</var>'s <span
data-x="concept-url-blob-entry">blob URL entry</span>'s <span
data-x="blob-url-entry-environment">environment</span>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Let <var>topLevelOrigin</var> be <var>element</var>'s <span>relevant settings
object</span>'s <span>top-level origin</span>.</p></li>
<li><p>If <var>blobOrigin</var> is not <span>same site</span> with <var>topLevelOrigin</var>,
then return true.</p></li>
</ol>
</li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn data-x="following hyperlinks">follow the hyperlink</dfn> created by an element
<var>subject</var>, given an optional <dfn
data-x="following-hyperlinkSuffix"><var>hyperlinkSuffix</var></dfn> (default null) and an
optional <dfn data-x="following-userInvolvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"):</p>
<ol>
<li><p>If <var>subject</var> <span>cannot navigate</span>, then return.</p></li>
<li><p>Let <var>targetAttributeValue</var> be the empty string.</p></li>
<li><p>If <var>subject</var> is an <code>a</code> or <code>area</code> element, then set
<var>targetAttributeValue</var> to the result of <span data-x="get an element's target">getting
an element's target</span> given <var>subject</var>.</p></li>
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>subject</var>'s <code data-x="attr-hyperlink-href">href</code> attribute value, relative to
<var>subject</var>'s <span>node document</span>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then return.</p></li>
<li><p>Let <var>noopener</var> be the result of <span data-x="get an element's noopener">getting
an element's noopener</span> with <var>subject</var>, <var>urlRecord</var>, and
<var>targetAttributeValue</var>.</p></li>
<li><p>Let <var>targetNavigable</var> be the first return value of applying <span>the rules for
choosing a navigable</span> given <var>targetAttributeValue</var>, <var>subject</var>'s
<span>node navigable</span>, and <var>noopener</var>.</p></li>
<li><p>If <var>targetNavigable</var> is null, then return.</p></li>
<li><p>Let <var>urlString</var> be the result of applying the <span
data-x="concept-url-serializer">URL serializer</span> to <var>urlRecord</var>.</p></li>
<li><p>If <var>hyperlinkSuffix</var> is non-null, then append it to
<var>urlString</var>.</p></li>
<li><p>Let <var>referrerPolicy</var> be the current state of <var>subject</var>'s <code
data-x="">referrerpolicy</code> content attribute.</p></li>
<li id="noreferrer-a-area-processing-model"><p>If <var>subject</var>'s <a href="#linkTypes">link
types</a> includes the <code data-x="rel-noreferrer">noreferrer</code> keyword, then set
<var>referrerPolicy</var> to "<code data-x="">no-referrer</code>".</p></li>
<li>
<p><span>Navigate</span><!--DONAV hyperlink--> <var>targetNavigable</var> to
<var>urlString</var> using <var>subject</var>'s <span>node document</span>, with <i
data-x="navigation-referrer-policy">referrerPolicy</i> set to <var>referrerPolicy</var>, <i
data-x="navigation-user-involvement">userInvolvement</i> set to <var>userInvolvement</var>,
and <i data-x="navigation-source-element">sourceElement</i> set to <var>subject</var>.</p>
<p class="note">Unlike many other types of navigations, following hyperlinks does not have
special "<code data-x="NavigationHistoryBehavior-replace">replace</code>" behavior for when
documents are not <span>completely loaded</span>. This is true for both user-initiated instances
of following hyperlinks, as well as script-triggered ones via, e.g., <code
data-x="">aElement.click()</code>.</p>
</li>
</ol>
</div>
<!--DOWNLOAD-->
<h4>Downloading resources</h4>
<p>In some cases, resources are intended for later use rather than immediate viewing. To indicate
that a resource is intended to be downloaded for use later, rather than immediately used, the
<code data-x="attr-hyperlink-download">download</code> attribute can be specified on the
<code>a</code> or <code>area</code> element that creates the <span>hyperlink</span> to that
resource.</p>
<p>The attribute can furthermore be given a value, to specify the filename that user agents are
to use when storing the resource in a file system. This value can be overridden by the `<code
data-x="http-content-disposition">Content-Disposition</code>` HTTP header's filename parameters.
<ref>RFC6266</ref></p>
<p>In cross-origin situations, the <code data-x="attr-hyperlink-download">download</code>
attribute has to be combined with the `<code
data-x="http-content-disposition">Content-Disposition</code>` HTTP header, specifically with the
<code data-x="">attachment</code> disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to download sensitive personal or
confidential information without their full understanding.)</p>
<div w-nodev>
<hr>
<p>To <dfn data-x="downloading hyperlinks" export>download the hyperlink</dfn> created by an
element <var>subject</var>, given an optional <dfn
data-x="downloading-hyperlinkSuffix"><var>hyperlinkSuffix</var></dfn> (default null) and an
optional <dfn data-x="downloading-userInvolvement"><var>userInvolvement</var></dfn> (default
"<code data-x="uni-none">none</code>"):</p>
<ol>
<li><p>If <var>subject</var> <span>cannot navigate</span>, then return.</p></li>
<li id="allowed-to-download"><p>If <var>subject</var>'s <span>node document</span>'s <span>active
sandboxing flag set</span> has the <span>sandboxed downloads browsing context flag</span> set,
then return.</p></li>
<li><p>Let <var>urlString</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given <var>subject</var>'s <code data-x="attr-hyperlink-href">href</code> attribute
value, relative to <var>subject</var>'s <span>node document</span>.</p></li>
<li><p>If <var>urlString</var> is failure, then return.</p></li>
<li><p>If <var>hyperlinkSuffix</var> is non-null, then append it to
<var>urlString</var>.</p></li>
<li>
<p>If <var>userInvolvement</var> is not "<code data-x="uni-browser-ui">browser UI</code>",
then:</p>
<ol>
<li><p><span>Assert</span>: <var>subject</var> has a <code
data-x="attr-hyperlink-download">download</code> attribute.</p></li>
<li><p>Let <var>navigation</var> be <var>subject</var>'s <span>relevant global object</span>'s
<span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>filename</var> be the value of <var>subject</var>'s <code
data-x="attr-hyperlink-download">download</code> attribute.</p></li>
<li><p>Let <var>continue</var> be the result of <span data-x="fire a download request navigate
event">firing a download request <code data-x="event-navigate">navigate</code> event</span> at
<var>navigation</var> with <i data-x="fire-navigate-download-destinationURL">destinationURL</i>
set to <var>urlString</var>, <i
data-x="fire-navigate-download-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>, <i data-x="fire-navigate-download-sourceElement">sourceElement</i>
set to <var>subject</var>, and <i data-x="fire-navigate-download-filename">filename</i> set to
<var>filename</var>.</p></li>
<li><p>If <var>continue</var> is false, then return.</p></li>
</ol>
</li>
<li>
<p>Run these steps <span>in parallel</span>:</p>
<ol>
<li><p>Optionally, the user agent may abort these steps, if it believes doing so would
safeguard the user from a potentially hostile download.</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is <var>urlString</var>, <span
data-x="concept-request-client">client</span> is <span>entry settings object</span>, <span
data-x="concept-request-initiator">initiator</span> is "<code data-x="">download</code>", <span
data-x="concept-request-destination">destination</span> is the empty string, and whose
<span>synchronous flag</span> and <span>use-URL-credentials flag</span> are set.</p></li>
<!--FETCH--><li><p><span>Handle as a download</span> the result of <span
data-x="concept-fetch">fetching</span> <var>request</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>handle as a download</dfn> a <span data-x="concept-response">response</span>
<var>response</var>:</p>
<ol>
<li><p>Let <var>suggestedFilename</var> be the result of <span>getting the suggested
filename</span> for <var>response</var>.</p></li>
<li><p>Provide the user with a way to save <var>response</var> for later use. If the user agent
needs a filename, it should use <var>suggestedFilename</var>. Report any problems downloading the
file to the user.</p></li>
<li><p>Return <var>suggestedFilename</var>.</p></li>
</ol>
<p>To <dfn data-x="getting the suggested filename">get the suggested filename</dfn> for a <span
data-x="concept-response">response</span> <var>response</var>:</p>
<p class="warning">This algorithm is intended to mitigate security dangers involved in downloading
files from untrusted sites, and user agents are strongly urged to follow it.</p> <!-- but it's
optional, since it's not really an interoperability issue -->
<ol>
<li><p>Let <var>filename</var> be the undefined value.</p></li>
<!-- Content-Disposition: attachment; filename="" is always honoured, even cross-origin -->
<li><p>If <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header, that header specifies the
<code data-x="">attachment</code> disposition type, and the header includes filename information,
then let <var>filename</var> have the value specified by the header, and jump to the step labeled
<i>sanitize</i> below. <ref>RFC6266</ref></p></li>
<li><p>Let <var>interface origin</var> be the <span
data-x="concept-document-origin">origin</span> of the <code>Document</code> in which the <span
data-x="downloading hyperlinks">download</span> or <span>navigate</span> action resulting in the
download was initiated, if any.</p></li>
<li><p>Let <var>response origin</var> be the <span>origin</span> of the URL of
<var>response</var>, unless that URL's <span data-x="concept-url-scheme">scheme</span> component
is <code data-x="">data</code>, in which case let <var>response origin</var> be the same as the
<var>interface origin</var>, if any.</p></li>
<li><p>If there is no <var>interface origin</var>, then let <var>trusted operation</var> be true.
Otherwise, let <var>trusted operation</var> be true if <var>response origin</var> is the
<span>same origin</span> as <var>interface origin</var>, and false otherwise.</p></li>
<!-- Content-Disposition: *; filename="" overrides download="" for same-origin -->
<li><p>If <var>trusted operation</var> is true and <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header and that header includes
filename information, then let <var>filename</var> have the value specified by the header, and
jump to the step labeled <i>sanitize</i> below. <ref>RFC6266</ref></p></li>
<li><p>If the download was not initiated from a <span>hyperlink</span> created by an
<code>a</code> or <code>area</code> element, or if the element of the <span>hyperlink</span> from
which it was initiated did not have a <code data-x="attr-hyperlink-download">download</code>
attribute when the download was initiated, or if there was such an attribute but its value when
the download was initiated was the empty string, then jump to the step labeled <i>no proposed
filename</i>.</p></li>
<li><p>Let <var>proposed filename</var> have the value of the <code
data-x="attr-hyperlink-download">download</code> attribute of the element of the
<span>hyperlink</span> that initiated the download at the time the download was
initiated.</p></li>
<!-- download="" works for all links when same-origin -->
<!-- it is not used cross-origin, though, even for explicit user gestures -->
<!-- (except... see next step) -->
<li><p>If <var>trusted operation</var> is true, let <var>filename</var> have
the value of <var>proposed filename</var>, and jump to the step labeled <i>sanitize</i>
below.</p></li>
<!-- Content-Disposition: attachment with no filename="" allows download="" cross-origin -->
<li><p>If <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header and that header specifies
the <code data-x="">attachment</code> disposition type, let <var>filename</var> have the value of
<var>proposed filename</var>, and jump to the step labeled <i>sanitize</i> below.
<ref>RFC6266</ref></p></li>
<!-- fallback for same-origin resources or explicit downloads: use the response's filename -->
<li><p><i>No proposed filename</i>: If <var>trusted operation</var> is true, or if the user
indicated a preference for having the response in question downloaded, let <var>filename</var>
have a value derived from the <span>URL</span> of <var>response</var> in an
<span>implementation-defined</span> manner, and jump to the step labeled <i>sanitize</i>
below.</p></li>
<!-- no C-D: a header on cross-origin raises red flags -->
<li>
<p>Let <var>filename</var> be set to the user's preferred filename or to a filename selected by
the user agent, and jump to the step labeled <i>sanitize</i> below.</p>
<div class="warning">
<p>If the algorithm reaches this step, then a download was begun from a different origin than
<var>response</var>, and the origin did not mark the file as suitable for downloading, and the
download was not initiated by the user. This could be because a <code
data-x="attr-hyperlink-download">download</code> attribute was used to trigger the download, or
because <var>response</var> is not of a type that the user agent supports.</p>
<p>This could be dangerous, because, for instance, a hostile server could be trying to get a
user to unknowingly download private information and then re-upload it to the hostile server,
by tricking the user into thinking the data is from the hostile server.</p>
<p>Thus, it is in the user's interests that the user be somehow notified that
<var>response</var> comes from quite a different source, and to prevent confusion, any
suggested filename from the potentially hostile <var>interface origin</var> should be
ignored.</p>
</div>
</li>
<li><p><i>Sanitize</i>: Optionally, allow the user to influence <var>filename</var>. For
example, a user agent could prompt the user for a filename, potentially providing the value of
<var>filename</var> as determined above as a default value.</p></li>
<li>
<p>Adjust <var>filename</var> to be suitable for the local file system.</p>
<p class="example">For example, this could involve removing characters that are not legal in
filenames, or trimming leading and trailing whitespace.</p>
</li>
<li><p>If the platform conventions do not in any way use <span
data-x="concept-extension">extensions</span> to determine the types of file on the file system,
then return <var>filename</var> as the filename.</p></li>
<li><p>Let <var>claimed type</var> be the type given by <var>response</var>'s <span
data-x="Content-Type">Content-Type metadata</span>, if any is known. Let <var>named type</var> be
the type given by <var>filename</var>'s <span data-x="concept-extension">extension</span>, if any
is known. For the purposes of this step, a <i>type</i> is a mapping of a <span>MIME type</span>
to an <span data-x="concept-extension">extension</span>.</p></li>
<li><p>If <var>named type</var> is consistent with the user's preferences (e.g., because the
value of <var>filename</var> was determined by prompting the user), then return
<var>filename</var> as the filename.</p></li>
<li><p>If <var>claimed type</var> and <var>named type</var> are the same type (i.e., the type
given by <var>response</var>'s <span data-x="Content-Type">Content-Type metadata</span> is
consistent with the type given by <var>filename</var>'s <span
data-x="concept-extension">extension</span>), then return <var>filename</var> as the
filename.</p></li>
<li>
<p>If the <var>claimed type</var> is known, then alter <var>filename</var> to
add an <span data-x="concept-extension">extension</span> corresponding to <var>claimed
type</var>.</p>
<p>Otherwise, if <var>named type</var> is known to be potentially dangerous (e.g. it
will be treated by the platform conventions as a native executable, shell script, HTML
application, or executable-macro-capable document) then optionally alter <var>filename</var> to add a known-safe <span data-x="concept-extension">extension</span>
(e.g. "<code data-x="">.txt</code>").</p>
<p class="note">This last step would make it impossible to download executables, which might not
be desirable. As always, implementers are forced to balance security and usability in this
matter.</p>
</li>
<li><p>Return <var>filename</var> as the filename.</p></li>
</ol>
<p>For the purposes of this algorithm, a file <dfn data-x="concept-extension">extension</dfn>
consists of any part of the filename that platform conventions dictate will be used for
identifying the type of the file. For example, many operating systems use the part of the filename
following the last dot ("<code data-x="">.</code>") in the filename to determine the type of the
file, and from that the manner in which the file is to be opened or executed.</p>
<p>User agents should ignore any directory or path information provided by the response itself,
its <span>URL</span>, and any <code data-x="attr-hyperlink-download">download</code> attribute, in
deciding where to store the resulting file in the user's file system.</p>
</div>
<h4><dfn>Hyperlink auditing</dfn></h4>
<div w-nodev>
<p>If a <span>hyperlink</span> created by an <code>a</code> or <code>area</code> element has a
<code data-x="attr-hyperlink-ping">ping</code> attribute, and the user follows the hyperlink, and
the value of the element's <code data-x="attr-hyperlink-href">href</code> attribute can be <span
data-x="encoding-parsing a URL">parsed</span>, relative to the element's <span>node
document</span>, without failure, then the user agent must take the <code
data-x="attr-hyperlink-ping">ping</code> attribute's value, <span data-x="split a string on ASCII
whitespace">split that string on ASCII whitespace</span>, <span data-x="encoding-parsing a
URL">parse</span> each resulting token, relative to the element's <span>node document</span>, and
then run these steps for each resulting <span>URL</span> <var>ping URL</var>, ignoring when
parsing returns failure:</p>
<ol>
<li><p>If <var>ping URL</var>'s <span data-x="concept-url-scheme">scheme</span> is not an
<span>HTTP(S) scheme</span>, then return.</p></li>
<li><p>Optionally, return. (For example, the user agent might wish to ignore any or
all ping URLs in accordance with the user's expressed preferences.)</p></li>
<li><p>Let <var>settingsObject</var> be the element's <span>node document</span>'s
<span>relevant settings object</span>.</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>ping URL</var>, <span
data-x="concept-request-method">method</span> is `<code data-x="">POST</code>`, <span
data-x="concept-request-header-list">header list</span> is « (`<code>Content-Type</code>`,
`<code>text/ping</code>`) », <span data-x="concept-request-body">body</span> is `<code
data-x="">PING</code>`, <span data-x="concept-request-client">client</span> is
<var>settingsObject</var>, <span data-x="concept-request-destination">destination</span> is the
empty string, <span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", <span data-x="concept-request-referrer">referrer</span> is "<code
data-x="">no-referrer</code>", and whose <span>use-URL-credentials flag</span> is set, and whose
<span data-x="concept-request-initiator-type">initiator type</span> is "<code
data-x="">ping</code>".</p></li>
<li>
<p>Let <var>target URL</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given the element's <code data-x="attr-hyperlink-href">href</code> attribute's value,
relative to the element's <span>node document</span>, and then:</p>
<dl class="switch">
<dt>If the <span data-x="concept-document-url">URL</span> of the <code>Document</code> object
containing the hyperlink being audited and <var>ping URL</var> have the <span>same
origin</span></dt>
<dt>If the origins are different, but the <span data-x="concept-url-scheme">scheme</span> of
the <span data-x="concept-document-url">URL</span> of the <code>Document</code> containing the
hyperlink being audited is not "<code data-x="">https</code>"</dt>
<dd><var>request</var> must include a `<code>Ping-From</code>` header with, as its value, the
<span data-x="concept-document-url">URL</span> of the document containing the hyperlink, and a
`<code>Ping-To</code>` HTTP header with, as its value, the <var>target URL</var>.</dd>
<dt>Otherwise</dt>
<dd><var>request</var> must include a `<code>Ping-To</code>` HTTP header with, as its value,
<var>target URL</var>. <span class="note"><var>request</var> does not include a
`<code>Ping-From</code>` header.</span></dd>
</dl>
</li>
<li><p><span data-x="concept-fetch">Fetch</span> <var>request</var>.</p></li>
</ol>
<p>This may be done <span>in parallel</span> with the primary fetch, and is independent of the
result of that fetch.</p>
<p>User agents should allow the user to adjust this behavior, for example in conjunction with a
setting that disables the sending of HTTP `<code data-x="http-referer">Referer</code>` (sic)
headers. Based on the user's preferences, UAs may either <span>ignore</span> the <code
data-x="attr-hyperlink-ping">ping</code> attribute altogether, or selectively ignore URLs in the
list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
above.</p>
<p>User agents must ignore any entity bodies returned in the responses. User agents may close the
connection prematurely once they start receiving a response body.</p>
<p>When the <code data-x="attr-hyperlink-ping">ping</code> attribute is present, user agents
should clearly indicate to the user that following the hyperlink will also cause secondary
requests to be sent in the background, possibly including listing the actual target URLs.</p>
<p class="example">For example, a visual user agent could include the hostnames of the target ping
URLs along with the hyperlink's actual URL in a status bar or tooltip.</p>
</div>
<div class="note">
<p>The <code data-x="attr-hyperlink-ping">ping</code> attribute is redundant with pre-existing
technologies like HTTP redirects and JavaScript in allowing web pages to track which off-site
links are most popular or allowing advertisers to track click-through rates.</p>
<p>However, the <code data-x="attr-hyperlink-ping">ping</code> attribute provides these advantages
to the user over those alternatives:</p>
<ul>
<li>It allows the user to see the final target URL unobscured.</li>
<li>It allows the UA to inform the user about the out-of-band notifications.</li>
<li>It allows the user to disable the notifications without losing the underlying link
functionality.</li>
<li>It allows the UA to optimize the use of available network bandwidth so that the target page
loads faster.</li>
</ul>
<p>Thus, while it is possible to track users without this feature, authors are encouraged to use
the <code data-x="attr-hyperlink-ping">ping</code> attribute so that the user agent can make the
user experience more transparent.</p>
</div>
<!-- resolving ping urls happens at audit time, so base URL changes affect the values of ping
attributes -->
<h5 id="the-ping-headers">The `<code>Ping-From</code>` and `<code>Ping-To</code>` headers</h5>
<p>The `<dfn http-header><code>Ping-From</code></dfn>` and `<dfn
http-header><code>Ping-To</code></dfn>` HTTP request headers are included in <span>hyperlink
auditing</span> requests. Their value is a <span>URL</span>, <span
data-x="concept-url-serializer">serialized</span>.</p>
<h4 id="linkTypes">Link types</h4>
<p>The following table summarizes the link types that are defined by this specification, by their
corresponding keywords. This table is non-normative; the actual definitions for the link types are
given in the next few sections.</p>
<p>In this section, the term <i>referenced document</i> refers to the resource identified by the
element representing the link, and the term <i>current document</i> refers to the resource within
which the element representing the link finds itself.</p>
<div w-nodev>
<p>To determine which link types apply to a <code>link</code>, <code>a</code>, <code>area</code>,
or <code>form</code> element, the element's <code data-x="">rel</code> attribute must be <span
data-x="split a string on ASCII whitespace">split on ASCII whitespace</span>. The resulting tokens
are the keywords for the link types that apply to that element.</p>
</div>
<p>Except where otherwise specified, a keyword must not be specified more than once per <code
data-x="attr-hyperlink-rel">rel</code> attribute.</p>
<p>Some of the sections that follow the table below list synonyms for certain keywords. The
indicated synonyms <span w-nodev>are to be handled as specified by user agents, but</span> must
not be used in documents (for example, the keyword "<code data-x="">copyright</code>").</p>
<p>Keywords are always <span>ASCII case-insensitive</span><span w-nodev>, and must be
compared as such</span>.</p>
<p class="example">Thus, <code data-x="">rel="next"</code> is the same as <code
data-x="">rel="NEXT"</code>.</p>
<p>Keywords that are <dfn>body-ok</dfn> affect whether <code>link</code> elements are
<span>allowed in the body</span>. The <span>body-ok</span> keywords are
<code data-x="rel-dns-prefetch">dns-prefetch</code>,
<code data-x="rel-modulepreload">modulepreload</code>,
<code data-x="rel-pingback">pingback</code>,
<code data-x="rel-preconnect">preconnect</code>,
<code data-x="rel-prefetch">prefetch</code>,
<code data-x="rel-preload">preload</code>, and
<code data-x="rel-stylesheet">stylesheet</code>.</p>
<p>New link types that are to be implemented by web browsers are to be added to this standard. The
remainder can be <span data-x="concept-rel-extensions">registered as extensions</span>.</p>
<table class="yesno" id="table-link-relations">
<thead>
<tr>
<th rowspan="2">Link type</th>
<th colspan="3">Effect on...</th>
<th rowspan="2"><span>body-ok</span></th>
<th rowspan="2">Has `<code data-x="http-link">Link</code>` processing</th>
<th rowspan="2">Brief description</th>
</tr>
<tr>
<th><code>link</code></th>
<th><code>a</code> and <code>area</code></th>
<th><code>form</code></th>
</tr>
</thead>
<tbody>
<tr>
<td><code data-x="rel-alternate">alternate</code></td>
<td colspan="2"><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives alternate representations of the current document.</td>
</tr>
<tr>
<td><code data-x="rel-canonical">canonical</code></td>
<td><span>Hyperlink</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives the preferred URL for the current document.</td>
</tr>
<tr>
<td><code data-x="rel-author">author</code></td>
<td colspan="2"><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives a link to the author of the current document or article.</td>
</tr>
<tr>
<td><code data-x="rel-bookmark">bookmark</code></td>
<td><em>not allowed</em></td>
<td><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives the permalink for the nearest ancestor section.</td>
</tr>
<tr>
<td><code data-x="rel-dns-prefetch">dns-prefetch</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="no"> · </td>
<td>Specifies that the user agent should preemptively perform DNS resolution for the target resource's <span>origin</span>.</td>
</tr>
<tr>
<td><code data-x="rel-expect">expect</code></td>
<td><span data-x="internal resource link">Internal Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Expect an element with the target ID to appear in the current document.</td>
</tr>
<tr>
<td><code data-x="rel-external">external</code></td>
<td><em>not allowed</em></td>
<td colspan="2"><span data-x="hyperlink annotation">Annotation</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Indicates that the referenced document is not part of the same site as the current document.</td>
</tr>
<tr>
<td><code data-x="rel-help">help</code></td>
<td colspan="3"><span>Hyperlink</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Provides a link to context-sensitive help.</td>
</tr>
<tr>
<td><code data-x="rel-icon">icon</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Imports an icon to represent the current document.</td>
</tr>
<tr>
<td><code data-x="rel-manifest">manifest</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Imports or links to an <span>application manifest</span>. <ref>MANIFEST</ref></td>
</tr>
<tr>
<td><code data-x="rel-modulepreload">modulepreload</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="no"> · </td>
<td>Specifies that the user agent must preemptively <span data-x="fetch a single module script">fetch the module
script</span> and store it in the document's <span data-x="concept-document-module-map">module map</span> for later
evaluation. Optionally, the module's dependencies can be fetched as well.</td>
</tr>
<tr>
<td><code data-x="rel-license">license</code></td>
<td colspan="3"><span>Hyperlink</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Indicates that the main content of the current document is covered by the copyright license described by the referenced document.</td>
</tr>
<tr>
<td><code data-x="rel-next">next</code></td>
<td colspan="3"><span>Hyperlink</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Indicates that the current document is a part of a series, and that the next document in the series is the referenced document.</td>
</tr>
<tr>
<td><code data-x="rel-nofollow">nofollow</code></td>
<td><em>not allowed</em></td>
<td colspan="2"><span data-x="hyperlink annotation">Annotation</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Indicates that the current document's original author or publisher does not endorse the referenced document.</td>
</tr>
<tr>
<td><code data-x="rel-noopener">noopener</code></td>
<td><em>not allowed</em></td>
<td colspan="2"><span data-x="hyperlink annotation">Annotation</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Creates a <span>top-level traversable</span> with a non-<span>auxiliary browsing
context</span> if the hyperlink would otherwise create one that was auxiliary (i.e., has an
appropriate <code data-x="attr-hyperlink-target">target</code> attribute value).</td>
</tr>
<tr>
<td><code data-x="rel-noreferrer">noreferrer</code></td>
<td><em>not allowed</em></td>
<td colspan="2"><span data-x="hyperlink annotation">Annotation</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>No `<code data-x="http-referer">Referer</code>` (sic) header will be included.
Additionally, has the same effect as <code data-x="rel-noopener">noopener</code>.</td>
</tr>
<tr>
<td><code data-x="rel-opener">opener</code></td>
<td><em>not allowed</em></td>
<td colspan="2"><span data-x="hyperlink annotation">Annotation</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Creates an <span>auxiliary browsing context</span> if the hyperlink would otherwise create
a <span>top-level traversable</span> with a non-<span>auxiliary browsing context</span> (i.e.,
has "<code data-x="">_blank</code>" as <code data-x="attr-hyperlink-target">target</code>
attribute value).</td>
</tr>
<tr>
<td><code data-x="rel-pingback">pingback</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="no"> · </td>
<td>Gives the address of the pingback server that handles pingbacks to the current document.</td>
</tr>
<tr>
<td><code data-x="rel-preconnect">preconnect</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="yes"> Yes </td>
<td>Specifies that the user agent should preemptively connect to the target resource's <span>origin</span>.</td>
</tr>
<tr>
<td><code data-x="rel-prefetch">prefetch</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="no"> · </td>
<td>Specifies that the user agent should preemptively <span data-x="concept-fetch">fetch</span> and cache the target resource as it is likely to be required for a followup <span data-x="navigate">navigation</span>.</td>
</tr>
<tr>
<td><code data-x="rel-preload">preload</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="yes"> Yes </td>
<td>Specifies that the user agent must preemptively <span data-x="concept-fetch">fetch</span> and cache the target resource for current <span data-x="navigate">navigation</span> according to the <span data-x="concept-potential-destination">potential destination</span> given by the <code data-x="attr-link-as">as</code> attribute (and the <span data-x="concept-request-priority">priority</span> associated with the <span data-x="concept-potential-destination-translate">corresponding</span> <span data-x="concept-request-destination">destination</span>).</td>
</tr>
<tr>
<td><code data-x="rel-prev">prev</code></td>
<td colspan="3"><span>Hyperlink</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document.</td>
</tr>
<tr>
<td><code data-x="rel-privacy-policy">privacy-policy</code></td>
<td colspan="2"><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives a link to information about the data collection and usage practices that apply to the current document.</td>
</tr>
<tr>
<td><code data-x="rel-search">search</code></td>
<td colspan="3"><span>Hyperlink</span></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives a link to a resource that can be used to search through the current document and its related pages.</td>
</tr>
<tr>
<td><code data-x="rel-stylesheet">stylesheet</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="no"> · </td>
<td>Imports a style sheet.</td>
</tr>
<tr>
<td><code data-x="rel-tag">tag</code></td>
<td><em>not allowed</em></td>
<td><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives a tag (identified by the given address) that applies to the current document.</td>
</tr>
<tr>
<td><code data-x="rel-terms-of-service">terms-of-service</code></td>
<td colspan="2"><span>Hyperlink</span></td>
<td><em>not allowed</em></td>
<td class="no"> · </td>
<td class="no"> · </td>
<td>Gives a link to information about the agreements between the current document's provider and users who wish to use the current document.</td>
</tr>
</tbody>
</table>
<h5 id="rel-alternate"><span id="link-type-alternate"></span>Link type "<dfn
for="link/rel,a/rel,area/rel" attr-value><code data-x="rel-alternate">alternate</code></dfn>"</h5>
<p>The <code data-x="rel-alternate">alternate</code> keyword may be used with <code>link</code>,
<code>a</code>, and <code>area</code> elements.</p>
<p>The meaning of this keyword depends on the values of the other attributes.</p>
<dl class="switch">
<dt>If the element is a <code>link</code> element and the <code data-x="attr-link-rel">rel</code>
attribute also contains the keyword <code data-x="rel-stylesheet">stylesheet</code></dt>
<dd>
<p>The <code data-x="rel-alternate">alternate</code> keyword modifies the meaning of the <code
data-x="rel-stylesheet">stylesheet</code> keyword in the way described for that keyword. The
<code data-x="rel-alternate">alternate</code> keyword does not create a link of its own.</p>
<div class="example">
<p>Here, a set of <code>link</code> elements provide some style sheets:</p>
<pre><code class="html"><!-- a persistent style sheet -->
<link rel="stylesheet" href="default.css">
<!-- the preferred alternate style sheet -->
<link rel="stylesheet" href="green.css" title="Green styles">
<!-- some alternate style sheets -->
<link rel="alternate stylesheet" href="contrast.css" title="High contrast">
<link rel="alternate stylesheet" href="big.css" title="Big fonts">
<link rel="alternate stylesheet" href="wide.css" title="Wide screen"></code></pre>
</div>
</dd>
<dt>If the <code data-x="rel-alternate">alternate</code> keyword is used with the <code
data-x="attr-hyperlink-type">type</code> attribute set to the value <code
data-x="">application/rss+xml</code> or the value <code data-x="">application/atom+xml</code></dt>
<dd>
<p>The keyword creates a <span>hyperlink</span> referencing a syndication feed (though not
necessarily syndicating exactly the same content as the current page).</p>
<div w-nodev>
<p>For the purposes of feed autodiscovery, user agents should consider all <code>link</code>
elements in the document with the <code data-x="rel-alternate">alternate</code> keyword used and
with their <code data-x="attr-hyperlink-type">type</code> attribute set to the value <code
data-x="">application/rss+xml</code> or the value <code
data-x="">application/atom+xml</code>. If the user agent has the concept of a default
syndication feed, the first such element (in <span>tree order</span>) should be used as the
default.</p>
</div>
<div class="example">
<p>The following <code>link</code> elements give syndication feeds for a blog:</p>
<pre><code class="html"><link rel="alternate" type="application/atom+xml" href="posts.xml" title="Cool Stuff Blog">
<link rel="alternate" type="application/atom+xml" href="posts.xml?category=robots" title="Cool Stuff Blog: robots category">
<link rel="alternate" type="application/atom+xml" href="comments.xml" title="Cool Stuff Blog: Comments"></code></pre>
<p>Such <code>link</code> elements would be used by user agents engaged in feed autodiscovery,
with the first being the default (where applicable).</p>
<p>The following example offers various different syndication feeds to the user, using
<code>a</code> elements:</p>
<pre><code class="html"><p>You can access the planets database using Atom feeds:</p>
<ul>
<li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li>
<li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li>
<li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li>
</ul></code></pre>
<p>These links would not be used in feed autodiscovery.</p>
</div>
</dd>
<dt>Otherwise</dt>
<dd>
<p>The keyword creates a <span>hyperlink</span> referencing an alternate representation of the
current document.</p>
<p>The nature of the referenced document is given by the <code
data-x="attr-hyperlink-hreflang">hreflang</code>, and <code
data-x="attr-hyperlink-type">type</code> attributes.</p>
<p>If the <code data-x="rel-alternate">alternate</code> keyword is used with the <code
data-x="attr-hyperlink-hreflang">hreflang</code> attribute, and that attribute's value differs
from the <span>document element</span>'s <span>language</span>, it indicates that the referenced
document is a translation.</p>
<p>If the <code data-x="rel-alternate">alternate</code> keyword is used with the <code
data-x="attr-hyperlink-type">type</code> attribute, it indicates that the referenced document is
a reformulation of the current document in the specified format.</p>
<p>The <code data-x="attr-hyperlink-hreflang">hreflang</code> and <code
data-x="attr-hyperlink-type">type</code> attributes can be combined when specified with the <code
data-x="rel-alternate">alternate</code> keyword.</p>
<div class="example">
<p>The following example shows how you can specify versions of the page that use alternative
formats, are aimed at other languages, and that are intended for other media:</p>
<pre><code class="html"><link rel=alternate href="/en/html" hreflang=en type=text/html title="English HTML">
<link rel=alternate href="/fr/html" hreflang=fr type=text/html title="French HTML">
<link rel=alternate href="/en/html/print" hreflang=en type=text/html media=print title="English HTML (for printing)">
<link rel=alternate href="/fr/html/print" hreflang=fr type=text/html media=print title="French HTML (for printing)">
<link rel=alternate href="/en/pdf" hreflang=en type=application/pdf title="English PDF">
<link rel=alternate href="/fr/pdf" hreflang=fr type=application/pdf title="French PDF"></code></pre>
</div>
<p>This relationship is transitive — that is, if a document links to two other documents
with the link type "<code data-x="rel-alternate">alternate</code>", then, in addition to implying
that those documents are alternative representations of the first document, it is also implying
that those two documents are alternative representations of each other.</p>
</dd>
</dl>
<h5>Link type "<dfn attr-value for="link/rel,a/rel,area/rel"><code
data-x="rel-author">author</code></dfn>"</h5>
<p>The <code data-x="rel-author">author</code> keyword may be used with <code>link</code>,
<code>a</code>, and <code>area</code> elements. This keyword creates a <span>hyperlink</span>.</p>
<p>For <code>a</code> and <code>area</code> elements, the <code data-x="rel-author">author</code>
keyword indicates that the referenced document provides further information about the author of
the nearest <code>article</code> element ancestor of the element defining the hyperlink, if there
is one, or of the page as a whole, otherwise.</p>
<p>For <code>link</code> elements, the <code data-x="rel-author">author</code> keyword indicates
that the referenced document provides further information about the author for the page as a
whole.</p>
<p class="note">The "referenced document" can be, and often is, a <code data-x="mailto
protocol">mailto:</code> URL giving the email address of the author. <ref>MAILTO</ref></p>
<div w-nodev>
<p><strong>Synonyms</strong>: For historical reasons, user agents must also treat
<code>link</code>, <code>a</code>, and <code>area</code> elements that have a <code
data-x="">rev</code> attribute with the value "<code data-x="">made</code>" as having the <code
data-x="rel-author">author</code> keyword specified as a link relationship.</p>
</div>
<h5>Link type "<dfn attr-value for="a/rel,area/rel"><code
data-x="rel-bookmark">bookmark</code></dfn>"</h5>
<p>The <code data-x="rel-bookmark">bookmark</code> keyword may be used with <code>a</code> and
<code>area</code> elements. This keyword creates a <span>hyperlink</span>.</p>
<p>The <code data-x="rel-bookmark">bookmark</code> keyword gives a permalink for the nearest
ancestor <code>article</code> element of the linking element in question, or of
the section the linking element is most closely associated with, if
there are no ancestor <code>article</code> elements.</p>
<div class="example">
<p>The following snippet has three permalinks. A user agent could determine which permalink
applies to which part of the spec by looking at where the permalinks are given.</p>
<pre><code class="html"> ...
<body>
<h1>Example of permalinks</h1>
<div id="a">
<h2>First example</h2>
<p><a href="a.html" rel="bookmark">This permalink applies to
only the content from the first H2 to the second H2</a>. The DIV isn't
exactly that section, but it roughly corresponds to it.</p>
</div>
<h2>Second example</h2>
<article id="b">
<p><a href="b.html" rel="bookmark">This permalink applies to
the outer ARTICLE element</a> (which could be, e.g., a blog post).</p>
<article id="c">
<p><a href="c.html" rel="bookmark">This permalink applies to
the inner ARTICLE element</a> (which could be, e.g., a blog comment).</p>
</article>
</article>
</body>
...</code></pre>
</div>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-canonical">canonical</code></dfn>"</h5>
<p>The <code data-x="rel-canonical">canonical</code> keyword may be used with <code>link</code>
element. This keyword creates a <span>hyperlink</span>.</p>
<p>The <code data-x="rel-canonical">canonical</code> keyword indicates that URL given by the <code
data-x="attr-link-href">href</code> attribute is the preferred URL for the current document. That
helps search engines reduce duplicate content, as described in more detail in <cite>The Canonical
Link Relation</cite>. <ref>RFC6596</ref></p>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-dns-prefetch">dns-prefetch</code></dfn>"</h5>
<p>The <code data-x="rel-dns-prefetch">dns-prefetch</code> keyword may be used with
<code>link</code> elements. This keyword creates an <span data-x="external resource link">external
resource link</span>. This keyword is <span>body-ok</span>.</p>
<p>The <code data-x="rel-dns-prefetch">dns-prefetch</code> keyword indicates that preemptively
performing DNS resolution for the <span>origin</span> of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
<span>origin</span>, and the user experience would be improved by preempting the latency costs
associated with DNS resolution.</p>
<p>There is no default type for resources given by the <code
data-x="rel-dns-prefetch">dns-prefetch</code> keyword.</p>
<p>The appropriate times to <span data-x="fetch and process the linked resource">fetch and
process</span> this type of link are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<!-- e.g. rel="" changed, href="" set... -->
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
</ul>
<p>The <span>fetch and process the linked resource</span> steps for this type of linked resource,
given a <code>link</code> element <var>el</var>, are:
<ol>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>el</var>'s <code data-x="attr-link-href">href</code> attribute's value, relative to
<var>el</var>'s <span>node document</span>.</p></li>
<li><p>If <var>url</var> is failure, then return.</p></li>
<li><p>Let <var>partitionKey</var> be the result of <span data-x="determine the network
partition key">determining the network partition key</span> given <var>el</var>'s
<span>node document</span>'s <span>relevant settings object</span>.</p></li>
<li>
<p>The user agent should <span>resolve an origin</span> given <var>partitionKey</var> and
<var>url</var>'s <span data-x="concept-url-origin">origin</span>.</p>
<p class="note">As the results of this algorithm can be cached, future fetches could be
faster.</p>
</li>
</ol>
<h5>Link type "<dfn attr-value for="link/rel"><code data-x="rel-expect">expect</code></dfn>"</h5>
<p>The <code data-x="rel-expect">expect</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="internal resource link">internal resource
link</span>.</p>
<p>An <span>internal resource link</span> created by the <code data-x="rel-expect">expect</code>
keyword can be used to <span data-x="render-blocked">block rendering</span> until the element that
it <span data-x="indicated part">indicates</span> is connected to the document and fully
parsed.</p>
<p>There is no default type for resources given by the <code data-x="rel-expect">expect</code>
keyword.</p>
<p>Whenever any of the following conditions occur for a <code>link</code> element
<var>el</var>:</p>
<ul>
<li><p>the <code data-x="rel-expect">expect</code> <span>internal resource link</span> is created
on <var>el</var> that is already <span>browsing-context connected</span>;</p></li>
<li><p>an <code data-x="rel-expect">expect</code> <span>internal resource link</span> has been
created on <var>el</var> and <var>el</var> becomes
<span>browsing-context connected</span>;</p></li>
<li><p>an <code data-x="rel-expect">expect</code><span>internal resource link</span> has been
created on <var>el</var>, <var>el</var> is already <span>browsing-context connected</span>, and
<var>el</var>'s <code data-x="attr-link-href">href</code> attribute is set, changed, or removed;
or</p></li>
<li><p>an <code data-x="rel-expect">expect</code> <span>internal resource link</span> has been
created on <var>el</var>, <var>el</var> is already <span>browsing-context connected</span>, and
<var>el</var>'s <code data-x="attr-link-media">media</code> attribute is set, changed, or
removed,</p></li>
</ul>
<p>then <span data-x="process internal resource link">process</span> <var>el</var>.</p>
<p>To <dfn>process internal resource link</dfn> given a <code>link</code> element <var>el</var>,
run these steps:</p>
<ol>
<li><p>Let <var>doc</var> be <var>el</var>'s <span>node document</span>.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>el</var>'s <code data-x="attr-link-href">href</code> attribute's value, relative to
<var>doc</var>.</p></li>
<li><p>If this fails, or if <var>url</var> does not <span
data-x="concept-url-equals">equal</span> <var>doc</var>'s
<span data-x="concept-document-url">URL</span> with <i data-x="url equals exclude
fragments">exclude fragments</i> set to false, then <span>unblock rendering</span> on
<var>el</var> and return.</p></li>
<li><p>Let <var>indicatedElement</var> be the result of <span
data-x="select the indicated part">selecting the indicated part</span> given <var>doc</var>
and <var>url</var>.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>doc</var>'s <span>current document readiness</span> is "<code
data-x="">loading</code>";</p></li>
<li><p><var>el</var> creates an <span>internal resource link</span>;</p></li>
<li><p><var>el</var> is <span>browsing-context connected</span>;</p></li>
<li><p><var>el</var>'s <code data-x="attr-link-rel">rel</code> attribute
contains <code data-x="rel-expect">expect</code>;</p></li>
<li><p><var>el</var> is <span>potentially render-blocking</span>;</p></li>
<li><p><var>el</var>'s <code data-x="attr-link-media">media</code> attribute
<span>matches the environment</span>; and</p></li>
<li><p><var>indicatedElement</var> is not an element, or is on a
<span>stack of open elements</span> of an <span>HTML parser</span> whose associated
<code>Document</code> is <var>doc</var>,</p></li>
</ul>
<p>then <span>block rendering</span> on <var>el</var>.</p>
</li>
<li><p>Otherwise, <span>unblock rendering</span> on <var>el</var>.</p></li>
</ol>
<p>To <dfn>process internal resource links</dfn> given a <code>Document</code> <var>doc</var>:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <code
data-x="rel-expect">expect</code> <code>link</code> element <var>link</var> in
<var>doc</var>'s <span>render-blocking element set</span>, <span
data-x="process internal resource link">process</span> <var>link</var>.</p></li>
</ol>
<p>The following <span
data-x="concept-element-attributes-change-ext">attribute change steps</span>, given
<var>element</var>, <var>localName</var>, <var>value</var>, and <var>namespace</var>, are used to
ensure <code data-x="rel-expect">expect</code> <code>link</code> elements respond to dynamic <code
data-x="attr-id">id</code> and <code data-x="attr-a-name">name</code> changes:</p>
<ol>
<li><p>If <var>namespace</var> is not null, then return.</p></li>
<li><p>If <var>element</var> is in a <span>stack of open elements</span> of an
<span>HTML parser</span>, then return.</p></li>
<li>
<p>If any of the following is true:</p>
<ul>
<li><p><var>localName</var> is <code data-x="attr-id">id</code>; or</p></li>
<li><p><var>localName</var> is <code
data-x="attr-a-name">name</code> and <var>element</var> is an <code>a</code> element,</p></li>
</ul>
<p>then <span>process internal resource links</span> given <var>element</var>'s
<span>node document</span>.</p>
</li>
</ol>
<h5>Link type "<dfn attr-value for="a/rel,area/rel,form/rel"><code
data-x="rel-external">external</code></dfn>"</h5>
<!-- fifth and sixth most used <a rel> value (sixth is "external nofollow") -->
<p>The <code data-x="rel-external">external</code> keyword may be used with <code>a</code>,
<code>area</code>, and <code>form</code> elements. This keyword does not create a
<span>hyperlink</span>, but <span data-x="hyperlink annotation">annotates</span> any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).</p>
<p>The <code data-x="rel-external">external</code> keyword indicates that the link is leading to a
document that is not part of the site that the current document forms a part of.</p>
<h5>Link type "<dfn attr-value for="link/rel,a/rel,area/rel,form/rel"><code
data-x="rel-help">help</code></dfn>"</h5>
<p>The <code data-x="rel-help">help</code> keyword may be used with <code>link</code>,
<code>a</code>, <code>area</code>, and <code>form</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>For <code>a</code>, <code>area</code>, and <code>form</code> elements, the <code
data-x="rel-help">help</code> keyword indicates that the referenced document provides further help
information for the parent of the element defining the hyperlink, and its children.</p>
<div class="example">
<p>In the following example, the form control has associated context-sensitive help. The user
agent could use this information, for example, displaying the referenced document if the user
presses the "Help" or "F1" key.</p>
<pre><code class="html"> <p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p></code></pre>
</div>
<p>For <code>link</code> elements, the <code data-x="rel-help">help</code> keyword indicates that
the referenced document provides help for the page as a whole.</p>
<p>For <code>a</code> and <code>area</code> elements, on some browsers, the <code
data-x="rel-help">help</code> keyword causes the link to use a different cursor.</p>
<h5 id=rel-icon>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-icon">icon</code></dfn>"</h5>
<p>The <code data-x="rel-icon">icon</code> keyword may be used with <code>link</code> elements.
This keyword creates an <span>external resource link</span>.</p>
<div w-nodev>
<p>The specified resource is an icon representing the page or site, and should be used by the user
agent when representing the page in the user interface.</p>
</div>
<p>Icons could be auditory icons, visual icons, or other kinds of icons. <span w-nodev>If
multiple icons are provided, the user agent must select the most appropriate icon according to the
<code data-x="attr-link-type">type</code>, <code data-x="attr-link-media">media</code>, and <code
data-x="attr-link-sizes">sizes</code> attributes. If there are multiple equally appropriate icons,
user agents must use the last one declared in <span>tree order</span> at the time that the user
agent collected the list of icons. If the user agent tries to use an icon but that icon is
determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
unsupported format), then the user agent must try the next-most-appropriate icon as determined by
the attributes.</span></p>
<div w-nodev>
<p class="note">User agents are not required to update icons when the list of icons changes, but
are encouraged to do so.</p>
<p>There is no default type for resources given by the <code data-x="rel-icon">icon</code> keyword.
However, for the purposes of <a href="#concept-link-type-sniffing">determining the type of the
resource</a>, user agents must expect the resource to be an image.</p>
</div>
<p>The <code data-x="attr-link-sizes">sizes</code> keywords represent icon sizes in raw pixels (as
opposed to <span data-x="'px'">CSS pixels</span>).</p>
<p class="note">An icon that is 50 <span data-x="'px'">CSS pixels</span> wide intended for
displays with a device pixel density of two device pixels per <span data-x="'px'">CSS pixel</span>
(2x, 192dpi) would have a width of 100 raw pixels. This feature does not support indicating that a
different resource is to be used for small high-resolution icons vs large low-resolution icons
(e.g. 50×50 2x vs 100×100 1x).</p>
<div w-nodev>
<p>To parse and process the attribute's value, the user agent must first <span data-x="split a
string on ASCII whitespace">split the attribute's value on ASCII whitespace</span>, and must then
parse each resulting keyword to determine what it represents.</p>
</div>
<p>The <dfn><code data-x="attr-link-sizes-any">any</code></dfn> keyword represents that the
resource contains a scalable icon, e.g. as provided by an SVG image.</p>
<div w-nodev>
<p>Other keywords must be further parsed as follows to determine what they represent:</p>
<ol>
<li><p>If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN
CAPITAL LETTER X character, then this keyword doesn't represent anything. Return for
that keyword.</p></li>
<li><p>Let <var>width string</var> be the string before the "<code data-x="">x</code>" or
"<code data-x="">X</code>".</p></li>
<li><p>Let <var>height string</var> be the string after the "<code data-x="">x</code>" or
"<code data-x="">X</code>".</p></li>
<li><p>If either <var>width string</var> or <var>height string</var> start with
a U+0030 DIGIT ZERO (0) character or contain any characters other than <span>ASCII digits</span>,
then this keyword doesn't represent anything. Return for that keyword.</p></li>
<li><p>Apply the <span>rules for parsing non-negative integers</span> to <var>width
string</var> to obtain <var>width</var>.</p></li>
<li><p>Apply the <span>rules for parsing non-negative integers</span> to <var>height
string</var> to obtain <var>height</var>.</p></li>
<li><p>The keyword represents that the resource contains a bitmap icon with a width of <var>width</var> device pixels and a height of <var>height</var> device
pixels.</p></li>
</ol>
</div>
<p>The keywords specified on the <code data-x="attr-link-sizes">sizes</code> attribute must not
represent icon sizes that are not actually available in the linked resource.</p>
<div w-nodev>
<p>The <span>linked resource fetch setup steps</span> for this type of linked resource, given a
<code>link</code> element <var>el</var> and <span data-x="concept-request">request</span>
<var>request</var>, are:</p>
<ol>
<li><p>Set <var>request</var>'s <span data-x="concept-request-destination">destination</span> to
"<code data-x="">image</code>".</p></li>
<li><p>Return true.</p></li>
</ol>
<p>The <span>process a link header</span> steps for this type of linked resource are to do
nothing.</p>
<p>In the absence of a <code>link</code> with the <code data-x="rel-icon">icon</code> keyword, for
<code>Document</code> objects whose <span data-x="concept-document-url">URL</span>'s
<span data-x="concept-url-scheme">scheme</span> is an <span>HTTP(S) scheme</span>, user agents may
instead run these steps <span>in parallel</span>:</p>
<ol>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is the <span>URL record</span> obtained by
resolving the <span>URL</span> "<code data-x="">/favicon.ico</code>" against the
<code>Document</code> object's <span data-x="concept-document-url">URL</span>, <span
data-x="concept-request-client">client</span> is the <code>Document</code> object's
<span>relevant settings object</span>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">image</code>",
<span>synchronous flag</span> is set, <span data-x="concept-request-credentials-mode">credentials
mode</span> is "<code data-x="">include</code>", and whose <span>use-URL-credentials flag</span>
is set.</p></li>
<!--FETCH--><li><p>Let <var>response</var> be the result of <span
data-x="concept-fetch">fetching</span> <var>request</var>.</p></li>
<li><p>Use <var>response</var>'s <span>unsafe response</span> as an icon as if it had been
declared using the <code data-x="rel-icon">icon</code> keyword.</p></li>
</ol>
</div>
<div class="example">
<p>The following snippet shows the top part of an application with several icons.</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>lsForums — Inbox</title>
<link rel=icon href=favicon.png sizes="16x16" type="image/png">
<link rel=icon href=windows.ico sizes="32x32 48x48" type="image/vnd.microsoft.icon">
<link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768">
<link rel=icon href=iphone.png sizes="57x57" type="image/png">
<link rel=icon href=gnome.svg sizes="any" type="image/svg+xml">
<link rel=stylesheet href=lsforums.css>
<script src=lsforums.js></script>
<meta name=application-name content="lsForums">
</head>
<body>
...</code></pre>
</div>
<p>For historical reasons, the <code data-x="rel-icon">icon</code> keyword may be preceded by the
keyword "<code data-x="">shortcut</code>". If the "<code data-x="">shortcut</code>" keyword is
present, the <code data-x="attr-hyperlink-rel">rel</code> attribute's entire value must be an
<span>ASCII case-insensitive</span> match for the string "<code
data-x="">shortcut icon</code>" (with a single U+0020 SPACE character between the tokens and
no other <span>ASCII whitespace</span>).</p>
<h5>Link type "<dfn attr-value for="link/rel,a/rel,area/rel,form/rel"><code
data-x="rel-license">license</code></dfn>"</h5>
<p>The <code data-x="rel-license">license</code> keyword may be used with <code>link</code>,
<code>a</code>, <code>area</code>, and <code>form</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-license">license</code> keyword indicates that the referenced document
provides the copyright license terms under which the main content of the current document is
provided.</p>
<p>This specification does not specify how to distinguish between the main content of a document
and content that is not deemed to be part of that main content. The distinction should be made
clear to the user.</p>
<div class="example">
<p>Consider a photo sharing site. A page on that site might describe and show a photograph, and
the page might be marked up as follows:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Exampl Pictures: Kissat</title>
<link rel="stylesheet" href="/style/default">
</head>
<body>
<h1>Kissat</h1>
<nav>
<a href="../">Return to photo index</a>
</nav>
<figure>
<img src="/pix/39627052_fd8dcd98b5.jpg">
<figcaption>Kissat</figcaption>
</figure>
<p>One of them has six toes!</p>
<p><small><a rel="license" href="http://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p>
<footer>
<a href="/">Home</a> | <a href="../">Photo index</a>
<p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p>
</footer>
</body>
</html></code></pre>
<p>In this case the <code data-x="rel-license">license</code> applies to just the photo (the main
content of the document), not the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of the document. This could be made
clearer in the styling (e.g. making the license link prominently positioned near the photograph,
while having the page copyright in light small text at the foot of the page).</p>
</div>
<div w-nodev>
<p><strong>Synonyms</strong>: For historical reasons, user agents must also treat the keyword
"<code data-x="">copyright</code>" like the <code data-x="rel-license">license</code> keyword.</p>
</div>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-manifest">manifest</code></dfn>"</h5>
<p>The <code data-x="rel-manifest">manifest</code> keyword may be used with <code>link</code> elements.
This keyword creates an <span data-x="external resource link">external resource link</span>.</p>
<p>The <code data-x="rel-manifest">manifest</code> keyword indicates the manifest file that provides
metadata associated with the current document.</p>
<div w-nodev>
<p>There is no default type for resources given by the <code data-x="rel-manifest">manifest</code>
keyword.</p>
<p>When a web application is not <span data-x="installed web application">installed</span>, the
appropriate time to <span>fetch and process the linked resource</span> for this link type is when
the user agent deems it necessary. For example, when the user chooses to <span data-x="installed
web application">install the web application</span>.</p>
<p>For an <span data-x="installed web application">installed web application</span>, the
appropriate times to <span>fetch and process the linked resource</span> for this link type
are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
</ul>
<p>In any case, only the first <code>link</code> element in <span>tree order</span> whose <code
data-x="attr-link-rel">rel</code> attribute contains the token <code
data-x="rel-manifest">manifest</code> may be used.</p>
<p>A user agent must not <span>delay the load event</span> for this link type.</p>
<p>The <span>linked resource fetch setup steps</span> for this type of linked resource, given a
<code>link</code> element <var>el</var> and <span data-x="concept-request">request</span>
<var>request</var>, are:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>el</var>'s <span>node document</span>'s <span>node
navigable</span>.</p></li>
<li><p>If <var>navigable</var> is null, then return false.</p></li>
<li><p>If <var>navigable</var> is not a <span>top-level traversable</span>, then return
false.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator">initiator</span> to
"<code data-x="">manifest</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-destination">destination</span> to
"<code data-x="">manifest</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-mode">mode</span> to "<code
data-x="">cors</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-credentials-mode">credentials
mode</span> to the <span>CORS settings attribute credentials mode</span> for <var>el</var>'s
<code data-x="attr-link-crossorigin">crossorigin</code> content attribute.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>To <span data-x="process the linked resource">process this type of linked resource</span> given
a <code>link</code> element <var>el</var>, boolean <var>success</var>, <span
data-x="concept-response">response</span> <var>response</var>, and <span>byte sequence</span>
<var>bodyBytes</var>:</p>
<ol>
<li><p>If <var>response</var>'s <span data-x="Content-Type">Content-Type metadata</span> is not a
<span>JSON MIME type</span>, then set <var>success</var> to false.</p></li>
<li>
<p>If <var>success</var> is true:</p>
<ol>
<li><p>Let <var>document URL</var> be <var>el</var>'s <span>node document</span>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>Let <var>manifest URL</var> be <var>response</var>'s <span
data-x="concept-response-url">URL</span>.</p></li>
<li><p><span>Process the manifest</span> given <var>document URL</var>, <var>manifest
URL</var>, and <var>bodyBytes</var>. <ref>MANIFEST</ref></p></li>
</ol>
</li>
</ol>
<p>The <span>process a link header</span> steps for this type of linked resource are to do
nothing.</p>
</div>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-modulepreload">modulepreload</code></dfn>"</h5>
<p>The <code data-x="rel-modulepreload">modulepreload</code> keyword may be used with
<code>link</code> elements. This keyword creates an <span>external resource link</span>. This
keyword is <span>body-ok</span>.</p>
<p>The <code data-x="rel-modulepreload">modulepreload</code> keyword is a specialized alternative
to the <code data-x="rel-preload">preload</code> keyword, with a processing model geared toward
preloading <span data-x="module script">module scripts</span>. In particular, it uses the specific
fetch behavior for module scripts (including, e.g., a different interpretation of the <code
data-x="attr-link-crossorigin">crossorigin</code> attribute), and places the result into the
appropriate <span data-x="concept-document-module-map">module map</span> for later evaluation. In
contrast, a similar <span>external resource link</span> using the <code
data-x="rel-preload">preload</code> keyword would place the result in the preload cache, without
affecting the document's <span data-x="concept-document-module-map">module map</span>.</p>
<p>Additionally, implementations can take advantage of the fact that <span data-x="module
script">module scripts</span> declare their dependencies in order to fetch the specified module's
dependency as well. This is intended as an optimization opportunity, since the user agent knows
that, in all likelihood, those dependencies will also be needed later. It will not generally be
observable without using technology such as service workers, or monitoring on the server side.
Notably, the appropriate <code data-x="event-load">load</code> or <code
data-x="event-error">error</code> events will occur after the specified module is fetched, and
will not wait for any dependencies.</p>
<div w-nodev>
<p>A user agent must not <span>delay the load event</span> for this link type.</p>
<p>The appropriate times to <span>fetch and process the linked resource</span> for such a link
are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
</ul>
</div>
<p class="note">Unlike some other link relations, changing the relevant attributes (such as <code
data-x="attr-link-as">as</code>, <code data-x="attr-link-crossorigin">crossorigin</code>, and
<code data-x="attr-link-referrerpolicy">referrerpolicy</code>) of such a <code>link</code>
does not trigger a new fetch. This is because the document's <span
data-x="concept-document-module-map">module map</span> has already been populated by a previous
fetch, and so re-fetching would be pointless.</p>
<div w-nodev>
<p>The <span>fetch and process the linked resource</span> algorithm for <code
data-x="rel-modulepreload">modulepreload</code> links, given a <code>link</code> element
<var>el</var>, is as follows:</p>
<ol>
<li><p>If <var>el</var>'s <code data-x="attr-link-href">href</code> attribute's value is the
empty string, then return.</p></li>
<li><p>Let <var>destination</var> be the current state of <var>el</var>'s <code
data-x="attr-link-as">as</code> attribute (a <span
data-x="concept-request-destination">destination</span>), or "<code data-x="">script</code>" if
it is in no state.</p></li>
<li><p>If <var>destination</var> is not <span
data-x="concept-script-like-destination">script-like</span>, then <span>queue an element
task</span> on the <span>networking task source</span> given <var>el</var> to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
at <var>el</var>, and return.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>el</var>'s <code data-x="attr-link-href">href</code> attribute's value, relative to
<var>el</var>'s <span>node document</span>.</p></li>
<li><p>If <var>url</var> is failure, then return.</p></li>
<li><p>Let <var>settings object</var> be <var>el</var>'s <span>node document</span>'s
<span>relevant settings object</span>.</p></li>
<li><p>Let <var>credentials mode</var> be the <span>CORS settings attribute credentials
mode</span> for <var>el</var>'s <code data-x="attr-link-crossorigin">crossorigin</code>
attribute.</p></li>
<li><p>Let <var>cryptographic nonce</var> be
<var>el</var>.<span>[[CryptographicNonce]]</span>.</p></li>
<li><p>Let <var>integrity metadata</var> be the value of <var>el</var>'s <code
data-x="attr-link-integrity">integrity</code> attribute, if it is specified, or the empty string
otherwise.</p></li>
<li><p>If <var>el</var> does not have an <code data-x="attr-link-integrity">integrity</code>
attribute, then set <var>integrity metadata</var> to the result of <span>resolving a module
integrity metadata</span> with <var>url</var> and <var>settings object</var>.</p></li>
<li><p>Let <var>referrer policy</var> be the current state of <var>el</var>'s <code
data-x="attr-link-referrerpolicy">referrerpolicy</code> attribute.</p></li>
<li><p>Let <var>fetch priority</var> be the current state of <var>el</var>'s <code
data-x="attr-link-fetchpriority">fetchpriority</code> attribute.</p></li>
<li><p>Let <var>options</var> be a <span>script fetch options</span> whose <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is <var>cryptographic
nonce</var>, <span data-x="concept-script-fetch-options-integrity">integrity metadata</span> is
<var>integrity metadata</var>, <span data-x="concept-script-fetch-options-parser">parser
metadata</span> is "<code data-x="">not-parser-inserted</code>", <span
data-x="concept-script-fetch-options-credentials">credentials mode</span> is <var>credentials
mode</var>, <span data-x="concept-script-fetch-options-referrer-policy">referrer
policy</span> is <var>referrer policy</var>, and <span
data-x="concept-script-fetch-options-fetch-priority">fetch priority</span> is
<var>fetch priority</var>.</p></li>
<li>
<p><span>Fetch a modulepreload module script graph</span> given <var>url</var>,
<var>destination</var>, <var>settings object</var>, <var>options</var>, and with the following
steps given <var>result</var>:</p>
<ol>
<li><p>If <var>result</var> is null, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-error">error</code> at <var>el</var>,
and return.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at <var>el</var>.</p></li>
</ol>
</li>
</ol>
<p>The <span>process a link header</span> steps for this type of linked resource are to do
nothing.</p>
</div>
<div class="example" id="example-modulepreload-manifest">
<p>The following snippet shows the top part of an application with several modules preloaded:</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<title>IRCFog</title>
<link rel="modulepreload" href="app.mjs">
<link rel="modulepreload" href="helpers.mjs">
<link rel="modulepreload" href="irc.mjs">
<link rel="modulepreload" href="fog-machine.mjs">
<script type="module" src="app.mjs">
...</code></pre>
<p>Assume that the module graph for the application is as follows:</p>
<img src="/images/ircfog-modules.svg" width="301" height="151" alt="The module graph is rooted at app.mjs, which depends on irc.mjs and fog-machine.mjs. In turn, irc.mjs depends on helpers.mjs." class="darkmode-aware">
<p>Here we see the application developer has used <code
data-x="rel-modulepreload">modulepreload</code> to declare all of the modules in their module graph,
ensuring that the user agent initiates fetches for them all. Without such preloading, the user
agent might need to go through multiple network roundtrips before discovering <code
data-x="">helpers.mjs</code>, if technologies such as HTTP/2 Server Push are not in play. In
this way, <code data-x="rel-modulepreload">modulepreload</code> <code>link</code> elements can be
used as a sort of "manifest" of the application's modules.</p>
</div>
<div class="example" id="example-modulepreload-dynamic-import">
<p>The following code shows how <code data-x="rel-modulepreload">modulepreload</code> links can
be used in conjunction with <code>import()</code> to ensure network fetching is done ahead of
time, so that when <code>import()</code> is called, the module is already ready (but not
evaluated) in the <span>module map</span>:</p>
<pre><code class="html"><link rel="modulepreload" href="awesome-viewer.mjs">
<button onclick="import('./awesome-viewer.mjs').then(m => m.view())">
View awesome thing
</button></code></pre>
</div>
<h5>Link type "<dfn attr-value for="a/rel,area/rel,form/rel"><code
data-x="rel-nofollow">nofollow</code></dfn>"</h5>
<p>The <code data-x="rel-nofollow">nofollow</code> keyword may be used with <code>a</code>,
<code>area</code>, and <code>form</code> elements. This keyword does not create a
<span>hyperlink</span>, but <span data-x="hyperlink annotation">annotates</span> any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).</p>
<p>The <code data-x="rel-nofollow">nofollow</code> keyword indicates that the link is not endorsed
by the original author or publisher of the page, or that the link to the referenced document was
included primarily because of a commercial relationship between people affiliated with the two
pages.</p>
<h5>Link type "<dfn attr-value for="a/rel,area/rel,form/rel"><code
data-x="rel-noopener">noopener</code></dfn>"</h5>
<p>The <code data-x="rel-noopener">noopener</code> keyword may be used with <code>a</code>,
<code>area</code>, and <code>form</code> elements. This keyword does not create a
<span>hyperlink</span>, but <span data-x="hyperlink annotation">annotates</span> any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).</p>
<p>The keyword indicates that any newly created <span>top-level traversable</span> which results
from following the <span>hyperlink</span> will not contain an <span>auxiliary browsing
context</span>. E.g., the resulting <code>Window</code>'s <code data-x="dom-opener">opener</code>
getter will return null.</p>
<p w-nodev class="note">See also the <a href="#noopener">processing model</a>.</p>
<div class="example">
<p>This typically creates a <span>top-level traversable</span> with an <span>auxiliary browsing
context</span> (assuming there is no existing <span>navigable</span> whose <span
data-x="nav-target">target name</span> is "<code data-x="">example</code>"):</p>
<pre><code class="html"><a href=help.html target=example>Help!</a></code></pre>
<p>This creates a <span>top-level traversable</span> with a non-<span>auxiliary browsing
context</span> (assuming the same thing):</p>
<pre><code class="html"><a href=help.html target=example rel=noopener>Help!</a></code></pre>
<p>These are equivalent and only navigate the <span data-x="nav-parent">parent
navigable</span>:</p>
<pre><code class="html"><a href=index.html target=_parent>Home</a></code></pre>
<pre><code class="html"><a href=index.html target=_parent rel=noopener>Home</a></code></pre>
</div>
<h5>Link type "<dfn attr-value for="a/rel,area/rel,form/rel"><code
data-x="rel-noreferrer">noreferrer</code></dfn>"</h5>
<p>The <code data-x="rel-noreferrer">noreferrer</code> keyword may be used with <code>a</code>,
<code>area</code>, and <code>form</code> elements. This keyword does not create a
<span>hyperlink</span>, but <span data-x="hyperlink annotation">annotates</span> any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).</p>
<p>It indicates that no referrer information is to be leaked when following the link and also
implies the <code data-x="rel-noopener">noopener</code> keyword behavior under the same
conditions.</p>
<p w-nodev class="note">See also the <a href="#noreferrer-a-area-processing-model">processing
model</a> where referrer is directly manipulated.</p>
<p class="example"><code data-x=""><a href="..." rel="noreferrer" target="_blank"></code>
has the same behavior as <code
data-x=""><a href="..." rel="noreferrer noopener" target="_blank"></code>.</p>
<h5>Link type "<dfn attr-value for="a/rel,area/rel,form/rel"><code
data-x="rel-opener">opener</code></dfn>"</h5>
<p>The <code data-x="rel-opener">opener</code> keyword may be used with <code>a</code>,
<code>area</code>, and <code>form</code> elements. This keyword does not create a
<span>hyperlink</span>, but <span data-x="hyperlink annotation">annotates</span> any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).</p>
<p>The keyword indicates that any newly created <span>top-level traversable</span> which results
from following the <span>hyperlink</span> will contain an <span>auxiliary browsing
context</span>.</p>
<p w-nodev class="note">See also the <a href="#opener-processing-model">processing model</a>.</p>
<div class="example">
<p>In the following example the <code data-x="rel-opener">opener</code> is used to allow the help
page popup to navigate its opener, e.g., in case what the user is looking for can be found
elsewhere. An alternative might be to use a named target, rather than <code
data-x="">_blank</code>, but this has the potential to clash with existing names.</p>
<pre><code class="html"><a href="..." <mark>rel=opener</mark> target=_blank>Help!</a></code></pre>
</div>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-pingback">pingback</code></dfn>"</h5>
<p>The <code data-x="rel-pingback">pingback</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="external resource link">external resource
link</span>. This keyword is <span>body-ok</span>.</p>
<p>For the semantics of the <code data-x="rel-pingback">pingback</code> keyword, see
<cite>Pingback 1.0</cite>. <ref>PINGBACK</ref></p>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-preconnect">preconnect</code></dfn>"</h5>
<p>The <code data-x="rel-preconnect">preconnect</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="external resource link">external resource
link</span>. This keyword is <span>body-ok</span>.</p>
<p>The <code data-x="rel-preconnect">preconnect</code> keyword indicates that preemptively
initiating a connection to the <span>origin</span> of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
<span>origin</span>, and the user experience would be improved by preempting the latency costs
associated with establishing the connection.</p>
<p>There is no default type for resources given by the <code
data-x="rel-preconnect">preconnect</code> keyword.</p>
<p>A user agent must not <span>delay the load event</span> for this link type.</p>
<p>The appropriate times to <span data-x="fetch and process the linked resource">fetch and
process</span> this type of link are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<!-- e.g. rel="" changed, href="" set... -->
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
<li><p>When the <code data-x="attr-link-crossorigin">crossorigin</code> attribute of the
<code>link</code> element of an <span data-x="external resource link">external resource
link</span> that is already <span>browsing-context connected</span> is set, changed, or
removed.</p></li>
</ul>
<p>The <span>fetch and process the linked resource</span> steps for this type of linked resource,
given a <code>link</code> element <var>el</var>, are to <span
data-x="create link options from element">create link options</span> from <var>el</var> and
to <span>preconnect</span> given the result.</p>
<p>The <span>process a link header</span> step for this type of linked resource given a <span
data-x="link processing options">link processing options</span> <var>options</var> are to
<span>preconnect</span> given <var>options</var>.</p>
<p>To <dfn>preconnect</dfn> given a <span>link processing options</span> <var>options</var>:</p>
<ol>
<li><p>If <var>options</var>'s
<span data-x="link options href">href</span> is an empty string, return.</p></li>
<li>
<p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>options</var>'s <span data-x="link options href">href</span>, relative to
<var>options</var>'s <span data-x="link options base URL">base URL</span>.</p>
<p class="XXX">Passing the base URL instead of a document or environment is tracked by <a
href="https://github.com/whatwg/html/issues/9715">issue #9715</a>.</p>
</li>
<li><p>If <var>url</var> is failure, then return.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-scheme">scheme</span> is not an
<span>HTTP(S) scheme</span>, then return.</p></li>
<li><p>Let <var>partitionKey</var> be the result of <span data-x="determine the network
partition key">determining the network partition key</span> given <var>options</var>'s
<span data-x="link options environment">environment</span>.</p></li>
<li><p>Let <var>useCredentials</var> be true.</p></li>
<li><p>If <var>options</var>'s <span data-x="link options crossorigin">crossorigin</span> is
<span data-x="attr-crossorigin-anonymous">Anonymous</span> and <var>options</var>'s <span
data-x="link options origin">origin</span> does not
have the <span>same origin</span> as <var>url</var>'s
<span data-x="concept-url-origin">origin</span>, then set <var>useCredentials</var> to
false.</p></li>
<li>
<p>The user agent should <span>obtain a connection</span> given <var>partitionKey</var>,
<var>url</var>'s <span data-x="concept-url-origin">origin</span>, and
<var>useCredentials</var>.</p>
<p class="note">This connection is obtained but not used directly. It will remain in the
<span>connection pool</span> for subsequent use.</p>
<p>The user agent should attempt to initiate a preconnect and perform the full connection
handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins) whenever possible, but is
allowed to elect to perform a partial handshake (DNS only for HTTP, and DNS or DNS+TCP for
HTTPS origins), or skip it entirely, due to resource constraints or other reasons.</p>
<p>The optimal number of connections per origin is dependent on the negotiated protocol, users
current connectivity profile, available device resources, global connection limits, and other
context specific variables. As a result, the decision for how many connections should be opened
is deferred to the user agent.</p>
</li>
</ol>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-prefetch">prefetch</code></dfn>"</h5>
<p>The <code data-x="rel-prefetch">prefetch</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="external resource link">external resource
link</span>. This keyword is <span>body-ok</span>.</p>
<p>The <code data-x="rel-prefetch">prefetch</code> keyword indicates that preemptively <span
data-x="concept-fetch">fetching</span> and caching the specified resource or same-site document is
likely to be beneficial, as it is highly likely that the user will require this resource for
future navigations.</p>
<p>There is no default type for resources given by the <code data-x="rel-prefetch">prefetch</code>
keyword.</p>
<p>The appropriate times to <span data-x="fetch and process the linked resource">fetch and
process</span> this type of link are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
<li><p>When the <code data-x="attr-link-crossorigin">crossorigin</code> attribute of the
<code>link</code> element of an <span data-x="external resource link">external resource
link</span> that is already <span>browsing-context connected</span> is set, changed, or
removed.</p></li>
</ul>
<p>The <span>fetch and process the linked resource</span> algorithm for <code
data-x="rel-prefetch">prefetch</code> links, given a <code>link</code> element
<var>el</var>, is as follows:</p>
<ol>
<li><p>If <var>el</var>'s <code data-x="attr-link-href">href</code> attribute's value is the
empty string, then return.</p></li>
<li><p>Let <var>options</var> be the result of <span data-x="create link options from
element">creating link options</span> from <var>el</var>.</p></li>
<li><p>Set <var>options</var>'s <span data-x="link options destination">destination</span> to
the empty string.</p></li>
<li><p>Let <var>request</var> be the result of <span data-x="create a link request">creating a
link request</span> given <var>options</var>.</p></li>
<li><p>If <var>request</var> is null, then return.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator">initiator</span> to
"<code data-x="">prefetch</code>".</p></li>
<li>
<p>Let <var>processPrefetchResponse</var> be the following steps given a <span
data-x="concept-response">response</span> <var>response</var> and null, failure, or a
<span>byte sequence</span> <var>bytesOrNull</var>:</p>
<ol>
<li><p>If <var>response</var> is a <span>network error</span>, <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at <var>el</var>.</p></li>
<li><p>Otherwise, <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-load">load</code> at <var>el</var>.</p></li>
</ol>
</li>
<li><p>The user agent should <span data-x="concept-fetch">fetch</span> <var>request</var>, with
<i data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to
<var>processPrefetchResponse</var>. User agents may delay the fetching of <var>request</var> to
prioritize other requests that are necessary for the current document.</p></li>
</ol>
<p>The <span>process a link header</span> steps for this type of linked resource are to do
nothing.</p>
<h5>Link type "<dfn for="link/rel" attr-value><code
data-x="rel-preload">preload</code></dfn>"</h5>
<p>The <code data-x="rel-preload">preload</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="external resource link">external resource
link</span>. This keyword is <span>body-ok</span>.</p>
<p>The <code data-x="rel-preload">preload</code> keyword indicates that the user agent will
preemptively <span data-x="concept-fetch">fetch</span> and cache the specified resource according
to the <span data-x="concept-potential-destination">potential destination</span> given by the
<code data-x="attr-link-as">as</code> attribute, and the <span
data-x="concept-request-priority">priority</span> given by the <code
data-x="attr-link-fetchpriority">fetchpriority</code> attribute, as it is highly likely that the
user will require this resource for the current navigation.
<p class="note">User-agents might perform additional operations when a resource is loaded, such as
preemptively <span data-x="dom-img-decode">decoding images</span> or <span
data-x="Create a CSS style sheet">creating stylesheets</span>. However, these additional
operations cannot have observable effects.</p>
<p>There is no default type for resources given by the <code data-x="rel-preload">preload</code>
keyword.</p>
<p>A user agent must not <span>delay the load event</span> for this link type.</p>
<p>The appropriate times to <span>fetch and process the linked resource</span> for such a link
are:</p>
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
<li><p>When the <code data-x="attr-link-as">as</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
<li><p>When the <code data-x="attr-link-type">type</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span>, but was previously not obtained due to the <code
data-x="attr-link-type">type</code> attribute specifying an unsupported type for the request
<span data-x="concept-request-destination">destination</span>, is set, removed, or
changed.</p></li>
<li><p>When the <code data-x="attr-link-media">media</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span>, but was previously not obtained due to the <code
data-x="attr-link-media">media</code> attribute not
<span data-x="matches the environment">matching the environment</span>, is changed or
removed.</p></li>
</ul>
<p>A <code>Document</code> has a <dfn>map of preloaded resources</dfn>, which is an
<span>ordered map</span>, initially empty.</p>
<p>A <dfn>preload key</dfn> is a <span>struct</span>. It has the following <span data-x="struct
item">items</span>:</p>
<dl>
<dt><dfn data-x="preload URL">URL</dfn>
<dd>A <span>URL</span>
<dt><dfn data-x="preload destination">destination</dfn>
<dd>A string
<dt><dfn data-x="preload mode">mode</dfn>
<dd>A <span data-x="concept-request-mode">request mode</span>, either
"<code data-x="">same-origin</code>", "<code data-x="">cors</code>", or
"<code data-x="">no-cors</code>"
<dt><dfn data-x="preload credentials mode">credentials mode</dfn>
<dd>A <span data-x="concept-request-credentials-mode">credentials mode</span>
</dl>
<p>A <dfn>preload entry</dfn> is a <span>struct</span>. It has the following <span data-x="struct
item">items</span>:</p>
<dl>
<dt><dfn data-x="preload integrity metadata">integrity metadata</dfn>
<dd>A string
<dt><dfn data-x="preload response">response</dfn>
<dd>Null or a <span data-x="concept-response">response</span>
<dt><dfn data-x="preload on response available">on response available</dfn>
<dd>Null, or an algorithm accepting a <span data-x="concept-response">response</span> or null
</dl>
<p>To <dfn export>consume a preloaded resource</dfn> for <code>Window</code> <var>window</var>,
given a <span>URL</span> <var>url</var>, a string <var>destination</var>, a string
<var>mode</var>, a string <var>credentialsMode</var>, a string <var>integrityMetadata</var>, and
<var>onResponseAvailable</var>, which is an algorithm accepting a <span
data-x="concept-response">response</span>:</p>
<ol>
<li><p>Let <var>key</var> be a <span>preload key</span> whose <span data-x="preload
URL">URL</span> is <var>url</var>, <span data-x="preload destination">destination</span> is
<var>destination</var>, <span data-x="preload mode">mode</span> is <var>mode</var>, and
<span data-x="preload credentials mode">credentials mode</span> is
<var>credentialsMode</var>.</p></li>
<li><p>Let <var>preloads</var> be <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span>'s <span>map of
preloaded resources</span>.</p></li>
<li><p>If <var>key</var> does not <span data-x="map exists">exist</span> in <var>preloads</var>,
then return false.</p></li>
<li><p>Let <var>entry</var> be <var>preloads</var>[<var>key</var>].</p></li>
<li><p>Let <var>consumerIntegrityMetadata</var> be the result of
<span data-x="parse integrity metadata">parsing</span> <var>integrityMetadata</var>.</p></li>
<li><p>Let <var>preloadIntegrityMetadata</var> be the result of
<span data-x="parse integrity metadata">parsing</span> <var>entry</var>'s
<span data-x="preload integrity metadata">integrity metadata</span>.</p></li>
<li>
<p>If none of the following conditions apply:</p>
<ul>
<li><p><var>consumerIntegrityMetadata</var> is <code data-x="">no metadata</code>;</p></li>
<li>
<p><var>consumerIntegrityMetadata</var> is equal to <var>preloadIntegrityMetadata</var>;
or</p>
<p class="XXX">This comparison would ignore unknown integrity options. See <a
href="https://github.com/w3c/webappsec-subresource-integrity/issues/116">issue #116.</a></p>
</li>
</ul>
<p>then return false.</p>
<p class="note">A mismatch in integrity metadata between the preload and the consumer, even if
both match the data, would lead to an additional fetch from the network.</p>
<p class="note">It is important that <span data-x="network error">network errors</span> are
added to the preload cache so that if a preload request results in an error, the erroneous
response isn't re-requested from the network later. This also has security implications;
consider the case where a developer specifies subresource integrity metadata on a preload
request, but not the following resource request. If the preload request fails subresource
integrity verification and is discarded, the resource request will fetch and consume a
potentially-malicious response from the network without verifying its integrity.
<ref>SRI</ref></p>
</li>
<li><p><span data-x="map remove">Remove</span> <var>preloads</var>[<var>key</var>].</p></li>
<li><p>If <var>entry</var>'s <span data-x="preload response">response</span> is null, then set
<var>entry</var>'s <span data-x="preload on response available">on response available</span> to
<var>onResponseAvailable</var>.</p></li>
<li><p>Otherwise, call <var>onResponseAvailable</var> with <var>entry</var>'s <span
data-x="preload response">response</span>.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>For the purposes of this section, a string <var>type</var>
<dfn data-x="match preload type">matches</dfn> a string <var>destination</var> if the following
algorithm returns true:</p>
<ol>
<li><p>If <var>type</var> is an empty string, then return true.</p></li>
<li><p>If <var>destination</var> is "<code data-x="">fetch</code>", then return true.</p></li>
<li><p>Let <var>mimeTypeRecord</var> be the result of
<span data-x="Parse a mime type">parsing</span> <var>type</var>.</p></li>
<li><p>If <var>mimeTypeRecord</var> is failure, then return false.</p></li>
<li><p>If <var>mimeTypeRecord</var> is not <span
data-x="Is MIME type supported by the user agent?">supported by the user agent</span>, then
return false.</p>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>destination</var> is "<code data-x="">audio</code>" or "<code
data-x="">video</code>", and <var>mimeTypeRecord</var> is an
<span>audio or video MIME type</span>;</p></li>
<li><p><var>destination</var> is a
<span data-x="concept-script-like-destination">script-like destination</span> and
<var>mimeTypeRecord</var> is a <span>JavaScript MIME type</span>;</p></li>
<li><p><var>destination</var> is "<code data-x="">image</code>" and
<var>mimeTypeRecord</var> is an <span>image MIME type</span>;</p></li>
<li><p><var>destination</var> is "<code data-x="">font</code>" and
<var>mimeTypeRecord</var> is a <span>font MIME type</span>;</p></li>
<li><p><var>destination</var> is "<code data-x="">json</code>" and
<var>mimeTypeRecord</var> is a <span>JSON MIME type</span>;</p></li>
<li><p><var>destination</var> is "<code data-x="">style</code>" and
<var>mimeTypeRecord</var>'s <span data-x="MIME type essence">essence</span> is
<code>text/css</code>; or</p></li>
<li><p><var>destination</var> is "<code data-x="">track</code>" and
<var>mimeTypeRecord</var>'s <span data-x="MIME type essence">essence</span> is
<code>text/vtt</code>,</p></li>
</ul>
<p>then return true.</p>
</li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn>create a preload key</dfn> for a <span data-x="concept-request">request</span>
<var>request</var>, return a new <span>preload key</span> whose <span data-x="preload
URL">URL</span> is <var>request</var>'s <span data-x="concept-request-url">URL</span>, <span
data-x="preload destination">destination</span> is <var>request</var>'s <span
data-x="concept-request-destination">destination</span>, <span data-x="preload
mode">mode</span> is <var>request</var>'s <span data-x="concept-request-mode">mode</span>, and
<span data-x="preload credentials mode">credentials mode</span> is <var>request</var>'s <span
data-x="concept-request-credentials-mode">credentials mode</span>.</p>
<p>To <dfn>translate a preload destination</dfn> given a string <var>destination</var>:</p>
<ol>
<li><p>If <var>destination</var> is not "<code data-x="">fetch</code>", "<code data-x="">font</code>",
"<code data-x="">image</code>", "<code data-x="">script</code>", "<code data-x="">style</code>",
or "<code data-x="">track</code>", then return null.</p></li>
<li><p>Return the result of <span
data-x="concept-potential-destination-translate">translating</span>
<var>destination</var>.</p></li>
</ol>
<p>To <dfn>preload</dfn> given a <span
data-x="link processing options">link processing options</span> <var>options</var> and
an optional <var>processResponse</var>, which is an algorithm accepting a <span
data-x="concept-response">response</span>:</p>
<ol>
<li><p>If <var>options</var>'s <span data-x="link options type">type</span> doesn't <span
data-x="match preload type">match</span> <var>options</var>'s <span
data-x="link options destination">destination</span>, then return.</p></li>
<li><p>If <var>options</var>'s <span data-x="link options destination">destination</span> is
"<code data-x="">image</code>" and <var>options</var>'s <span data-x="link options source
set">source set</span> is not null, then set <var>options</var>'s <span data-x="link options
href">href</span> to the result of <span data-x="select an image source from a source
set">selecting an image source</span> from <var>options</var>'s <span data-x="link options
source set">source set</span>.</p></li>
<li><p>Let <var>request</var> be the result of <span data-x="create a link request">creating a
link request</span> given <var>options</var>.</p></li>
<li><p>If <var>request</var> is null, then return.</p></li>
<li><p>Let <var>unsafeEndTime</var> be 0.</p></li>
<li><p>Let <var>entry</var> be a new <span>preload entry</span> whose
<span data-x="preload integrity metadata">integrity metadata</span> is <var>options</var>'s
<span data-x="link options integrity">integrity</span>.</p></li>
<li><p>Let <var>key</var> be the result of <span data-x="create a preload key">creating a
preload key</span> given <var>request</var>.</p></li>
<li><p>If <var>options</var>'s <span data-x="link options document">document</span> is "<code
data-x="">pending</code>", then set <var>request</var>'s <span
data-x="concept-request-initiator-type">initiator type</span> to "<code data-x="">early
hint</code>".</p></li>
<li><p>Let <var>controller</var> be null.</p></li>
<li><p>Let <var>reportTiming</var> given a <code>Document</code> <var>document</var> be to
<span>report timing</span> for <var>controller</var> given <var>document</var>'s <span>relevant
global object</span>.</p></li>
<li>
<p><!--FETCH-->Set <var>controller</var> to the result of <span
data-x="concept-fetch">fetching</span> <var>request</var>, with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to the following steps
given a <span data-x="concept-response">response</span> <var>response</var> and null, failure,
or a <span>byte sequence</span> <var>bodyBytes</var>:</p>
<ol>
<li>
<p>If <var>bodyBytes</var> is a <span>byte sequence</span>, then set <var>response</var>'s
<span data-x="concept-response-body">body</span> to <var>bodyBytes</var> <span>as a
body</span>.</p>
<p class=note>By using <i data-x="processResponseConsumeBody">processResponseConsumeBody</i>,
we have <span data-x="body safely extract">extracted</span> the entire <span
data-x="concept-response-body">body</span>. This is necessary to ensure the preloader loads the
entire body from the network, regardless of whether the preload will be consumed (which is
uncertain at this point). This step then resets the request's body to a new body containing the
same bytes, so that other specifications can read from it at the time of actual consumption,
despite us having already done so once.</p>
</li>
<li><p>Otherwise, set <var>response</var> to a <span>network error</span>.</p></li>
<li><p>Set <var>unsafeEndTime</var> to the <span>unsafe shared current time</span>.</p></li>
<li><p>If <var>options</var>'s <span data-x="link options document">document</span> is not
null, then call <var>reportTiming</var> given <var>options</var>'s <span
data-x="link options document">document</span>.</p></li>
<li><p>If <var>entry</var>'s <span data-x="preload on response available">on response
available</span> is null, then set <var>entry</var>'s <span data-x="preload
response">response</span> to <var>response</var>; otherwise call <var>entry</var>'s <span
data-x="preload on response available">on response available</span> given
<var>response</var>.</p></li>
<li><p>If <var>processResponse</var> is given, then call <var>processResponse</var> with
<var>response</var>.</p></li>
</ol>
</li>
<li>
<p>Let <var>commit</var> be the following steps given a <code>Document</code>
<var>document</var>:</p>
<ol>
<li><p>If <var>entry</var>'s <span data-x="preload response">response</span> is not null, then
call <var>reportTiming</var> given <var>document</var>.</p></li>
<li><p>Set <var>document</var>'s <span>map of preloaded resources</span>[<var>key</var>] to
<var>entry</var>.</p></li>
</ol>
</li>
<li><p>If <var>options</var>'s <span
data-x="link options document">document</span> is null, then set <var>options</var>'s <span
data-x="link options on document ready">on document ready</span> to <var>commit</var>.
Otherwise, call <var>commit</var> with <var>options</var>'s <span
data-x="link options document">document</span>.</p></li>
</ol>
<p>The <span>fetch and process the linked resource</span> steps for this type of linked resource,
given a <code>link</code> element <var>el</var>, are:</p>
<ol>
<li><p><span>Update the source set</span> for <var>el</var>.</p></li>
<li><p>Let <var>options</var> be the result of <span
data-x="create link options from element">creating link options</span> from
<var>el</var>.</p></li>
<li>
<p><span>Preload</span> <var>options</var>, with the following steps given a <span
data-x="concept-response">response</span> <var>response</var>:
<ol>
<li>
<p>If <var>response</var> is a <span>network error</span>, <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at <var>el</var>. Otherwise, <span
data-x="concept-event-fire">fire an event</span> named
<code data-x="event-load">load</code> at <var>el</var>.</p>
<p class="XXX">The actual browsers' behavior is different from the spec here, and the
feasibility of changing the behavior has not yet been investigated. See <a
href="https://github.com/whatwg/html/issues/1142">issue #1142</a>.</p>
</li>
</ol>
</li>
</ol>
<p>The <span>process a link header</span> step for this type of link
given a <span data-x="link processing options">link processing options</span> <var>options</var>
is to <span>preload</span> <var>options</var>.</p>
<h5>Link type "<dfn attr-value for="link/rel,a/rel,area/rel"><code
data-x="rel-privacy-policy">privacy-policy</code></dfn>"</h5>
<p>The <code data-x="rel-privacy-policy">privacy-policy</code> keyword may be used with
<code>link</code>, <code>a</code>, and <code>area</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-privacy-policy">privacy-policy</code> keyword indicates that the
referenced document contains information about the data collection and usage practices that apply
to the current document, as described in more detail in <cite>Additional Link Relation
Types</cite>. The referenced document may be a standalone privacy policy, or a specific section of
some more general document. <ref>RFC6903</ref></p>
<h5>Link type "<dfn attr-value for="link/rel,a/rel,area/rel,form/rel"><code
data-x="rel-search">search</code></dfn>"</h5>
<p>The <code data-x="rel-search">search</code> keyword may be used with <code>link</code>,
<code>a</code>, <code>area</code>, and <code>form</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-search">search</code> keyword indicates that the referenced document
provides an interface specifically for searching the document and its related resources.</p>
<p class="note">OpenSearch description documents can be used with <code>link</code> elements and
the <code data-x="rel-search">search</code> link type to enable user agents to autodiscover search
interfaces. <ref>OPENSEARCH</ref></p>
<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-stylesheet">stylesheet</code></dfn>"</h5>
<p>The <code data-x="rel-stylesheet">stylesheet</code> keyword may be used with <code>link</code>
elements. This keyword creates an <span data-x="external resource link">external resource
link</span> that contributes to the styling processing model. This keyword is
<span>body-ok</span>.</p>
<p>The specified resource is a <span>CSS style sheet</span> that describes how to present the
document.</p>
<p>If the <code data-x="rel-alternate">alternate</code> keyword is also specified on the
<code>link</code> element, then <dfn id="the-link-is-an-alternative-stylesheet">the link is an
alternative style sheet</dfn>; in this case, the <code data-x="attr-title">title</code> attribute
must be specified on the <code>link</code> element, with a non-empty value.</p>
<p>The default type for resources given by the <code data-x="rel-stylesheet">stylesheet</code>
keyword is <code>text/css</code>.</p>
<p>A <code>link</code> element of this type is <span>implicitly potentially render-blocking</span>
if the element was created by its <span>node document</span>'s parser.</p>
<div w-nodev>
<p>When the <code data-x="attr-link-disabled">disabled</code> attribute of a <code>link</code>
element with a <code data-x="rel-stylesheet">stylesheet</code> keyword is set, <span
data-x="disable a CSS style sheet">disable</span> the <span>associated CSS style sheet</span>.</p>
<p>The appropriate times to <span data-x="fetch and process the linked resource">fetch and
process</span> this type of link are:
<!-- has a browsing context: https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=4299 -->
<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>
<!-- e.g. rel="" changed, href="" set... -->
<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>
<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2588 -->
<li><p>When the <code data-x="attr-link-disabled">disabled</code> attribute of the
<code>link</code> element of an <span>external resource link</span> that is already
<span>browsing-context connected</span> is set, changed, or removed.</p></li>
<li><p>When the <code data-x="attr-link-crossorigin">crossorigin</code> attribute of the
<code>link</code> element of an <span data-x="external resource link">external resource
link</span> that is already <span>browsing-context connected</span> is set, changed, or
removed.</p></li>
<li><p>When the <code data-x="attr-link-type">type</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is set or changed to a value that does not or no longer matches the <span
data-x="Content-Type">Content-Type metadata</span> of the previous obtained external resource, if
any.</p></li>
<li><p>When the <code data-x="attr-link-type">type</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span>, but was previously not obtained due to the <code
data-x="attr-link-type">type</code> attribute specifying an unsupported type, is removed or
changed.</p></li>
<li><p>When the <span>external resource link</span> that is already <span>browsing-context
connected</span> changes from being <span data-x="the link is an alternative style sheet">an
alternative style sheet</span> to not being one, or vice versa.</p></li>
</ul>
<p><strong>Quirk</strong>: If the document has been set to <span>quirks mode</span>, has the
<span>same origin</span> as the <span>URL</span> of the external resource<!-- CVE-2010-0654 -->,
and the <span data-x="Content-Type">Content-Type metadata</span> of the external resource is not a
supported style sheet type, the user agent must instead assume it to be <code>text/css</code>.</p>
<p>The <span>linked resource fetch setup steps</span> for this type of linked resource, given a
<code>link</code> element <var>el</var> and <span data-x="concept-request">request</span>
<var>request</var>, are:</p>
<ol>
<li><p>If <var>el</var>'s <code data-x="attr-link-disabled">disabled</code> attribute is set,
then return false.</p></li>
<li><p>If <var>el</var> <span>contributes a script-blocking style sheet</span>, <span data-x="set
append">append</span> <var>el</var> to its <span>node document</span>'s <span>script-blocking
style sheet set</span>.</p></li>
<li><p>If <var>el</var>'s <code data-x="attr-link-media">media</code> attribute's value
<span>matches the environment</span> and <var>el</var> is
<span>potentially render-blocking</span>, then <span>block rendering</span> on
<var>el</var>.</p></li>
<li><p>If <var>el</var> is currently <span>render-blocking</span>, then set <var>request</var>'s
<span data-x="concept-request-render-blocking">render-blocking</span> to true.</p></li>
<li><p>Return true.</p></li>
</ol>
<p class="XXX">See <a href="https://github.com/whatwg/html/issues/968">issue #968</a> for plans
to use the CSSOM <a href="https://drafts.csswg.org/cssom/#fetching-css-style-sheets">fetch a CSS
style sheet</a> algorithm instead of the <span>default fetch and process the linked
resource</span> algorithm. In the meantime, any <span data-x="critical subresources">critical
subresource</span> <span data-x="concept-request">request</span> should have its <span
data-x="concept-request-render-blocking">render-blocking</span> set to whether or not the
<code>link</code> element is currently <span>render-blocking</span>.</p>
<p>To <span data-x="process the linked resource">process this type of linked resource</span>
given a <code>link</code> element <var>el</var>, boolean <var>success</var>, <span
data-x="concept-response">response</span> <var>response</var>, and <span>byte sequence</span>
<var>bodyBytes</var>:</p>
<!-- note that we can only get this far if we have a browsing context, since if you don't have a
browsing context (and are active) you can't ever get a result back from "fetch", and thus you
never obtain the sheet -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2741 -->
<ol>
<li><p>If the resource's <span data-x="Content-Type">Content-Type metadata</span> is not
<code>text/css</code>, then set <var>success</var> to false.</p></li>
<li>
<p>If <var>el</var> no longer creates an <span>external resource link</span> that contributes to
the styling processing model, or if, since the resource in question was <span data-x="fetch and
process the linked resource">fetched</span>, it has become appropriate to <span data-x="fetch
and process the linked resource">fetch</span> it again, then:</p>
<ol>
<li><p><span data-x="list remove">Remove</span> <var>el</var> from <var>el</var>'s <span>node
document</span>'s <span>script-blocking style sheet set</span>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>If <var>el</var> has an <span>associated CSS style sheet</span>, <span data-x="remove a
CSS style sheet">remove the CSS style sheet</span>.</p></li>
<li>
<p>If <var>success</var> is true, then:</p>
<ol>
<li>
<p><span>Create a CSS style sheet</span> with the following properties:</p>
<dl>
<dt><span data-x="concept-css-style-sheet-type">type</span></dt>
<dd><p><code>text/css</code></p></dd>
<dt><span data-x="concept-css-style-sheet-location">location</span></dt>
<dd>
<p><var>response</var>'s <span data-x="concept-response-url-list">URL list</span>[0]</p>
<p class="XXX">We provide a URL here on the assumption that <a
href="https://github.com/w3c/csswg-drafts/issues/9316">w3c/csswg-drafts issue #9316</a> will
be fixed.</p>
</dd>
<dt><span data-x="concept-css-style-sheet-owner-node">owner node</span></dt>
<dd><p><var>el</var></p></dd>
<dt><span data-x="concept-css-style-sheet-media">media</span></dt>
<dd>
<p>The <code data-x="attr-link-media">media</code> attribute of <var>el</var>.</p>
<p class="note">This is a reference to the (possibly absent at this time) attribute, rather
than a copy of the attribute's current value. <cite>CSSOM</cite> defines what happens
when the attribute is dynamically set, changed, or removed.</p>
</dd>
<dt><span data-x="concept-css-style-sheet-title">title</span></dt>
<dd>
<p>The <code data-x="attr-link-title">title</code> attribute of <var>el</var>, if
<var>el</var> is <span>in a document tree</span>, or the empty string otherwise.</p>
<p class="note">This is similarly a reference to the attribute, rather than a copy of the
attribute's current value.</p>
</dd>
<dt><span data-x="concept-css-style-sheet-alternate-flag">alternate flag</span></dt>
<dd><p>Set if <span>the link is an alternative style sheet</span> and <var>el</var>'s
<span>explicitly enabled</span> is false; unset otherwise.</p></dd>
<dt><span data-x="concept-css-style-sheet-origin-clean-flag">origin-clean flag</span></dt>
<dd><p>Set if the resource is <span>CORS-same-origin</span>; unset otherwise.</p></dd>
<dt>
<span data-x="concept-css-style-sheet-parent-CSS-style-sheet">parent CSS style
sheet</span>
</dt>
<dt><span data-x="concept-css-style-sheet-owner-CSS-rule">owner CSS rule</span></dt>
<dd><p>null</p></dd>
<dt><span data-x="concept-css-style-sheet-disabled-flag">disabled flag</span></dt>
<dd><p>Left at its default value.</p></dd>
<dt><span data-x="concept-css-style-sheet-CSS-rules">CSS rules</span></dt>
<dd>
<p>Left uninitialized.</p>
<p class="XXX">This doesn't seem right. Presumably we should be using <var>bodyBytes</var>?
Tracked as <a href="https://github.com/whatwg/html/issues/2997">issue #2997</a>.</p>
</dd>
</dl>
<p>The CSS <span>environment encoding</span> is the result of running the following steps:
<ref>CSSSYNTAX</ref></p>
<ol>
<li><p>If <var>el</var> has a <code data-x="attr-link-charset">charset</code> attribute,
<span data-x="getting an encoding">get an encoding</span> from that attribute's value. If
that succeeds, return the resulting encoding. <ref>ENCODING</ref></p></li>
<li><p>Otherwise, return the <span>document's character encoding</span>.
<ref>DOM</ref></p></li>
</ol>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at <var>el</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at <var>el</var>.</p></li>
<li>
<p>If <var>el</var> <span>contributes a script-blocking style sheet</span>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>el</var>'s <span>node document</span>'s <span>script-blocking
style sheet set</span> <span data-x="list contains">contains</span> <var>el</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>el</var> from its <span>node
document</span>'s <span>script-blocking style sheet set</span>.</p></li>
</ol>
</li>
<li><p><span>Unblock rendering</span> on <var>el</var>.</p></li>
</ol>
<p>The <span>process a link header</span> steps for this type of linked resource are to do
nothing.</p>
</div>
<h5>Link type "<dfn attr-value for="a/rel,area/rel"><code
data-x="rel-tag">tag</code></dfn>"</h5>
<p>The <code data-x="rel-tag">tag</code> keyword may be used with <code>a</code> and
<code>area</code> elements. This keyword creates a <span>hyperlink</span>.</p>
<p>The <code data-x="rel-tag">tag</code> keyword indicates that the <em>tag</em> that the
referenced document represents applies to the current document.</p>
<p class="note">Since it indicates that the tag <em>applies to the current document</em>, it would
be inappropriate to use this keyword in the markup of a <a href="#tag-cloud">tag cloud</a>, which
lists the popular tags across a set of pages.</p>
<div class="example">
<p>This document is about some gems, and so it is <i>tagged</i> with "<code
data-x="">https://en.wikipedia.org/wiki/Gemstone</code>" to unambiguously categorize it as applying
to the "jewel" kind of gems, and not to, say, the towns in the US, the Ruby package format, or
the Swiss locomotive class:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>My Precious</title>
</head>
<body>
<header><h1>My precious</h1> <p>Summer 2012</p></header>
<p>Recently I managed to dispose of a red gem that had been
bothering me. I now have a much nicer blue sapphire.</p>
<p>The red gem had been found in a bauxite stone while I was digging
out the office level, but nobody was willing to haul it away. The
same red gem stayed there for literally years.</p>
<footer>
Tags: <a rel=tag href="https://en.wikipedia.org/wiki/Gemstone">Gemstone</a>
</footer>
</body>
</html></code></pre>
</div>
<div class="example">
<p>In <em>this</em> document, there are two articles. The "<code data-x="rel-tag">tag</code>"
link, however, applies to the whole page (and would do so wherever it was placed, including if it
was within the <code>article</code> elements).</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Gem 4/4</title>
</head>
<body>
<article>
<h1>801: Steinbock</h1>
<p>The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</p>
</article>
<article>
<h1>802: Murmeltier</h1>
<figure>
<img src="https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
alt="The 802 was red with pantographs and tall vents on the side.">
<figcaption>The 802 in the 1980s, above Lago Bianco.</figcaption>
</figure>
<p>The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</p>
</article>
<p class="topic"><a rel=tag href="https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4">Gem 4/4</a></p>
</body>
</html></code></pre>
</div>
<h5>Link Type "<dfn attr-value for="link/rel,a/rel,area/rel"><code
data-x="rel-terms-of-service">terms-of-service</code></dfn>"</h5>
<p>The <code data-x="rel-terms-of-service">terms-of-service</code> keyword may be used with
<code>link</code>, <code>a</code>, and <code>area</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-terms-of-service">terms-of-service</code> keyword indicates that the
referenced document contains information about the agreements between the current document's
provider and users who wish to use the current document, as described in more detail in
<cite>Additional Link Relation Types</cite>. <ref>RFC6903</ref></p>
<h5>Sequential link types</h5>
<p>Some documents form part of a sequence of documents.</p>
<p>A sequence of documents is one where each document can have a <em>previous sibling</em> and a
<em>next sibling</em>. A document with no previous sibling is the start of its sequence, a
document with no next sibling is the end of its sequence.</p>
<p>A document may be part of multiple sequences.</p>
<h6>Link type "<dfn attr-value for="link/rel,a/rel,area/rel,form/rel"><code
data-x="rel-next">next</code></dfn>"</h6>
<p>The <code data-x="rel-next">next</code> keyword may be used with <code>link</code>,
<code>a</code>, <code>area</code>, and <code>form</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-next">next</code> keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the next logical document in the
sequence.</p>
<p w-nodev>When the <code data-x="rel-next">next</code> keyword is used with a <code>link</code>
element, user agents should process such links as if they were using one of the <code
data-x="rel-dns-prefetch">dns-prefetch</code>, <code data-x="rel-preconnect">preconnect</code>, or
<code data-x="rel-prefetch">prefetch</code> keywords. Which keyword the user agent wishes to use
is implementation-dependent; for example, a user agent may wish to use the less-costly <code
data-x="rel-preconnect">preconnect</code> processing model when trying to conserve data, battery
power, or processing power, or may wish to pick a keyword depending on heuristic analysis of past
user behavior in similar scenarios.</p>
<h6>Link type "<dfn attr-value for="link/rel,a/rel,area/rel,form/rel"><code
data-x="rel-prev">prev</code></dfn>"</h6>
<p>The <code data-x="rel-prev">prev</code> keyword may be used with <code>link</code>,
<code>a</code>, <code>area</code>, and <code>form</code> elements. This keyword creates a
<span>hyperlink</span>.</p>
<p>The <code data-x="rel-prev">prev</code> keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the previous logical document in
the sequence.</p>
<div w-nodev>
<p><strong>Synonyms</strong>: For historical reasons, user agents must also treat the keyword
"<code data-x="">previous</code>" like the <code data-x="rel-prev">prev</code> keyword.</p>
</div>
<h5>Other link types</h5>
<p><dfn data-x="concept-rel-extensions">Extensions to the predefined set of link types</dfn> may
be registered on the <a
href="https://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions">microformats
page for existing rel values</a>. <ref>MFREL</ref></p>
<p>Anyone is free to edit the <span data-x="">microformats page for existing rel values</span> at
any time to add a type. Extension types must be specified with the following information:</p>
<dl>
<dt>Keyword</dt>
<dd>
<p>The actual value being defined. The value should not be confusingly similar to any other
defined value (e.g. differing only in case).</p>
<p>If the value contains a U+003A COLON character (:), it must also be an <span>absolute
URL</span>.</p>
</dd>
<dt>Effect on... <code>link</code></dt>
<dd>
<p>One of the following:</p>
<dl>
<dt>Not allowed</dt>
<dd>The keyword must not be specified on <code>link</code> elements.</dd>
<dt>Hyperlink</dt>
<dd>The keyword may be specified on a <code>link</code> element; it creates a
<span>hyperlink</span>.</dd>
<dt>External Resource</dt>
<dd>The keyword may be specified on a <code>link</code> element; it creates an <span>external
resource link</span>.</dd>
</dl>
</dd>
<dt>Effect on... <code>a</code> and <code>area</code></dt>
<dd>
<p>One of the following:</p>
<dl>
<dt>Not allowed</dt>
<dd>The keyword must not be specified on <code>a</code> and <code>area</code> elements.</dd>
<dt>Hyperlink</dt>
<dd>The keyword may be specified on <code>a</code> and <code>area</code> elements; it creates a
<span>hyperlink</span>.</dd>
<dt>External Resource</dt>
<dd>The keyword may be specified on <code>a</code> and <code>area</code> elements; it creates
an <span>external resource link</span>.</dd>
<dt>Hyperlink Annotation</dt>
<dd>The keyword may be specified on <code>a</code> and <code>area</code> elements; it <span
data-x="hyperlink annotation">annotates</span> other <span data-x="hyperlink">hyperlinks</span>
created by the element.</dd>
</dl>
</dd>
<dt>Effect on... <code>form</code></dt>
<dd>
<p>One of the following:</p>
<dl>
<dt>Not allowed</dt>
<dd>The keyword must not be specified on <code>form</code> elements.</dd>
<dt>Hyperlink</dt>
<dd>The keyword may be specified on <code>form</code> elements; it creates a
<span>hyperlink</span>.</dd>
<dt>External Resource</dt>
<dd>The keyword may be specified on <code>form</code> elements; it creates an <span>external
resource link</span>.</dd>
<dt>Hyperlink Annotation</dt>
<dd>The keyword may be specified on <code>form</code> elements; it <span data-x="hyperlink
annotation">annotates</span> other <span data-x="hyperlink">hyperlinks</span> created by the
element.</dd>
</dl>
</dd>
<dt>Brief description</dt>
<dd><p>A short non-normative description of what the keyword's meaning is.</p></dd>
<dt>Specification</dt>
<dd><p>A link to a more detailed description of the keyword's semantics and requirements. It
could be another page on the wiki, or a link to an external page.</p></dd>
<dt>Synonyms</dt>
<dd><p>A list of other keyword values that have exactly the same processing requirements. Authors
should not use the values defined to be synonyms, they are only intended to allow user agents to
support legacy content. Anyone may remove synonyms that are not used in practice; only names that
need to be processed as synonyms for compatibility with legacy content are to be registered in
this way.</p></dd>
<dt>Status</dt>
<dd>
<p>One of the following:</p>
<dl>
<dt>Proposed</dt>
<dd>The keyword has not received wide peer review and approval. Someone has proposed it and is,
or soon will be, using it.</dd>
<dt>Ratified</dt>
<dd>The keyword has received wide peer review and approval. It has a specification that
unambiguously defines how to handle pages that use the keyword, including when they use it in
incorrect ways.</dd>
<dt>Discontinued</dt>
<dd>The keyword has received wide peer review and it has been found wanting. Existing pages are
using this keyword, but new pages should avoid it. The "brief description" and "specification"
entries will give details of what authors should use instead, if anything.</dd>
</dl>
<p>If a keyword is found to be redundant with existing values, it should be removed and listed
as a synonym for the existing value.</p>
<p>If a keyword is registered in the "proposed" state for a period of a month or more without
being used or specified, then it may be removed from the registry.</p>
<p>If a keyword is added with the "proposed" status and found to be redundant with existing
values, it should be removed and listed as a synonym for the existing value. If a keyword is
added with the "proposed" status and found to be harmful, then it should be changed to
"discontinued" status.</p>
<p>Anyone can change the status at any time, but should only do so in accordance with the
definitions above.</p>
</dd>
</dl>
<div w-nodev>
<p>Conformance checkers must use the information given on the <span data-x="">microformats page
for existing rel values</span> to establish if a value is allowed or not: values defined in this
specification or marked as "proposed" or "ratified" must be accepted when used on the elements for
which they apply as described in the "Effect on..." field, whereas values marked as "discontinued"
or not listed in either this specification or on the aforementioned page must be rejected as
invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid
the use of unreliable network connectivity).</p>
<p>When an author uses a new type not defined by either this specification or the wiki page,
conformance checkers should offer to add the value to the wiki, with the details described above,
with the "proposed" status.</p>
</div>
<p>Types defined as extensions in the <a
href="https://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions">microformats
page for existing rel values</a> with the status "proposed" or "ratified" may be used with the
<code data-x="">rel</code> attribute on <code>link</code>, <code>a</code>, and <code>area</code>
elements in accordance to the "Effect on..." field. <ref>MFREL</ref></p>
<h3 split-filename="edits">Edits</h3>
<p>The <code>ins</code> and <code>del</code> elements represent edits to the document.</p>
<h4>The <dfn element><code>ins</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-mod-cite">cite</code></dd>
<dd><code data-x="attr-mod-datetime">datetime</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-ins">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-ins">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLModElement</code>.</dd>
</dl>
<p>The <code>ins</code> element <span>represents</span> an addition to the document.</p>
<div class="example">
<p>The following represents the addition of a single paragraph:</p>
<pre><code class="html"><aside>
<ins>
<p> I like fruit. </p>
</ins>
</aside></code></pre>
<p>As does the following, because everything in the <code>aside</code> element here counts as
<span>phrasing content</span> and therefore there is just one <span>paragraph</span>:</p>
<pre><code class="html"><aside>
<ins>
Apples are <em>tasty</em>.
</ins>
<ins>
So are pears.
</ins>
</aside></code></pre>
</div>
<p><code>ins</code> elements should not cross <span data-x="paragraph">implied paragraph</span>
boundaries.</p>
<div class="example">
<p>The following example represents the addition of two paragraphs, the second of which was
inserted in two parts. The first <code>ins</code> element in this example thus crosses a
paragraph boundary, which is considered poor form.</p>
<pre class="bad"><code class="html"><aside>
<!-- don't do this -->
<ins datetime="2005-03-16 00:00Z">
<p> I like fruit. </p>
Apples are <em>tasty</em>.
</ins>
<ins datetime="2007-12-19 00:00Z">
So are pears.
</ins>
</aside></code></pre>
<p>Here is a better way of marking this up. It uses more elements, but none of the elements cross
implied paragraph boundaries.</p>
<pre><code class="html"><aside>
<ins datetime="2005-03-16 00:00Z">
<p> I like fruit. </p>
</ins>
<ins datetime="2005-03-16 00:00Z">
Apples are <em>tasty</em>.
</ins>
<ins datetime="2007-12-19 00:00Z">
So are pears.
</ins>
</aside></code></pre>
<!-- Those dates aren't random. They're the start and end of something. Can you guess what? -->
</div>
<h4>The <dfn element><code>del</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-mod-cite">cite</code></dd>
<dd><code data-x="attr-mod-datetime">datetime</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-del">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-del">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLModElement</code>.</dd>
</dl>
<p>The <code>del</code> element <span>represents</span> a removal from the document.</p>
<p><code>del</code> elements should not cross <span data-x="paragraph">implied paragraph</span>
boundaries.</p>
<div class="example">
<p>The following shows a "to do" list where items that have been done are crossed-off with the
date and time of their completion.</p>
<pre><code class="html"><h1>To Do</h1>
<ul>
<li>Empty the dishwasher</li>
<li><del datetime="2009-10-11T01:25-07:00">Watch Walter Lewin's lectures</del></li>
<li><del datetime="2009-10-10T23:38-07:00">Download more tracks</del></li>
<li>Buy a printer</li>
</ul></code></pre>
</div>
<h4>Attributes common to <code>ins</code> and <code>del</code> elements</h4>
<p>The <dfn element-attr for="ins,del"><code data-x="attr-mod-cite">cite</code></dfn> attribute
may be used to specify the <span data-x="concept-document-url">URL</span> of a document that
explains the change. When that document is long, for instance the minutes of a meeting, authors
are encouraged to include a <span data-x="concept-url-fragment">fragment</span> pointing to the
specific part of that document that discusses the change.</p>
<p>If the <code data-x="attr-mod-cite">cite</code> attribute is present, it must be a <span>valid
URL potentially surrounded by spaces</span> that explains the change. <span w-nodev>To obtain
the corresponding citation link, the value of the attribute must be <span data-x="encoding-parsing
a URL">parsed</span> relative to the element's <span>node document</span>.</span> User agents may
allow users to follow such citation links, but they are primarily intended for private use (e.g.,
by server-side scripts collecting statistics about a site's edits), not for readers.</p>
<p>The <dfn element-attr for="ins,del"><code data-x="attr-mod-datetime">datetime</code></dfn>
attribute may be used to specify the time and date of the change.</p>
<p>If present, the <code data-x="attr-mod-datetime">datetime</code> attribute's value must be a
<span>valid date string with optional time</span>.</p>
<div w-nodev>
<p>User agents must parse the <code data-x="attr-mod-datetime">datetime</code> attribute according
to the <span>parse a date or time string</span> algorithm. If that doesn't return a <span
data-x="concept-date">date</span> or a <span data-x="concept-datetime">global date and time</span>,
then the modification has no associated timestamp (the value is non-conforming; it is not a
<span>valid date string with optional time</span>). Otherwise, the modification is marked as
having been made at the given <span data-x="concept-date">date</span> or <span
data-x="concept-datetime">global date and time</span>. If the given value is a <span
data-x="concept-datetime">global date and time</span> then user agents should use the associated
time-zone offset information to determine which time zone to present the given datetime in.</p>
</div>
<p>This value <span w-nodev>may be shown to the user, but it</span> is primarily intended for
private use.</p>
<div w-nodev>
<p>The <code>ins</code> and <code>del</code> elements must implement the
<code>HTMLModElement</code> interface:</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLModElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-mod-cite">cite</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-mod-dateTime">dateTime</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLModElement"><code data-x="dom-mod-cite">cite</code></dfn> IDL
attribute must <span>reflect</span> the element's <code data-x="attr-mod-cite">cite</code> content
attribute. The <dfn attribute for="HTMLModElement"><code
data-x="dom-mod-dateTime">dateTime</code></dfn> IDL attribute must <span>reflect</span> the
element's <code data-x="attr-mod-datetime">datetime</code> content attribute.</p>
</div>
<h4>Edits and paragraphs</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Since the <code>ins</code> and <code>del</code> elements do not affect <span
data-x="paragraph">paragraphing</span>, it is possible, in some cases where paragraphs are <span
data-x="paragraph">implied</span> (without explicit <code>p</code> elements), for an
<code>ins</code> or <code>del</code> element to span both an entire paragraph or other
non-<span>phrasing content</span> elements and part of another paragraph. For example:</p>
<pre><code class="html"><section>
<ins>
<p>
This is a paragraph that was inserted.
</p>
This is another paragraph whose first sentence was inserted
at the same time as the paragraph above.
</ins>
This is a second sentence, which was there all along.
</section></code></pre>
<p>By only wrapping some paragraphs in <code>p</code> elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third paragraph to be covered by the same
<code>ins</code> or <code>del</code> element (though this is very confusing, and not considered
good practice):</p>
<pre class="bad"><code class="html"><section>
This is the first paragraph. <ins>This sentence was
inserted.
<p>This second paragraph was inserted.</p>
This sentence was inserted too.</ins> This is the
third paragraph in this example.
<!-- (don't do this) -->
</section></code></pre>
<p>However, due to the way <span data-x="paragraph">implied paragraphs</span> are defined, it is
not possible to mark up the end of one paragraph and the start of the very next one using the same
<code>ins</code> or <code>del</code> element. You instead have to use one (or two) <code>p</code>
element(s) and two <code>ins</code> or <code>del</code> elements, as for example:</p>
<pre><code class="html"><section>
<p>This is the first paragraph. <del>This sentence was
deleted.</del></p>
<p><del>This sentence was deleted too.</del> That
sentence needed a separate &lt;del&gt; element.</p>
</section></code></pre>
<p>Partly because of the confusion described above, authors are strongly encouraged to always mark
up all paragraphs with the <code>p</code> element, instead of having <code>ins</code> or
<code>del</code> elements that cross <span data-x="paragraph">implied paragraphs</span>
boundaries.</p>
<h4>Edits and lists</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The content models of the <code>ol</code> and <code>ul</code> elements do not allow
<code>ins</code> and <code>del</code> elements as children. Lists always represent all their
items, including items that would otherwise have been marked as deleted.</p>
<p>To indicate that an item is inserted or deleted, an <code>ins</code> or <code>del</code>
element can be wrapped around the contents of the <code>li</code> element. To indicate that an
item has been replaced by another, a single <code>li</code> element can have one or more
<code>del</code> elements followed by one or more <code>ins</code> elements.</p>
<div class="example">
<p>In the following example, a list that started empty had items added and removed from it over
time. The bits in the example that have been emphasized show the parts that are the "current"
state of the list. The list item numbers don't take into account the edits, though.</p>
<pre><code class="html"><h1>Stop-ship bugs</h1>
<ol>
<li><ins datetime="2008-02-12T15:20Z"><em>Bug 225:
Rain detector doesn't work in snow</em></ins></li>
<li><del datetime="2008-03-01T20:22Z"><ins datetime="2008-02-14T12:02Z">Bug 228:
Water buffer overflows in April</ins></del></li>
<li><ins datetime="2008-02-16T13:50Z"><em>Bug 230:
Water heater doesn't use renewable fuels</em></ins></li>
<li><del datetime="2008-02-20T21:15Z"><ins datetime="2008-02-16T14:25Z">Bug 232:
Carbon dioxide emissions detected after startup</ins></del></li>
</ol></code></pre>
</div>
<div class="example">
<p>In the following example, a list that started with just fruit was replaced by a list with just
colors.</p>
<pre><code class="html"><h1>List of <del>fruits</del><ins>colors</ins></h1>
<ul>
<li><del>Lime</del><ins>Green</ins></li>
<li><del>Apple</del></li>
<li>Orange</li>
<li><del>Pear</del></li>
<li><ins>Teal</ins></li>
<li><del>Lemon</del><ins>Yellow</ins></li>
<li>Olive</li>
<li><ins>Purple</ins></li>
</ul></code></pre>
</div>
<h4>Edits and tables</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The elements that form part of the table model have complicated content model requirements that
do not allow for the <code>ins</code> and <code>del</code> elements, so indicating edits to a
table can be difficult.</p>
<p>To indicate that an entire row or an entire column has been added or removed, the entire
contents of each cell in that row or column can be wrapped in <code>ins</code> or <code>del</code>
elements (respectively).</p>
<div class="example">
<p>Here, a table's row has been added:</p>
<pre><code class="html"><table>
<thead>
<tr> <th> Game name <th> Game publisher <th> Verdict
<tbody>
<tr> <td> Diablo 2 <td> Blizzard <td> 8/10
<tr> <td> Portal <td> Valve <td> 10/10
<strong> <tr> <td> <ins>Portal 2</ins> <td> <ins>Valve</ins> <td> <ins>10/10</ins></strong>
</table></code></pre>
<p>Here, a column has been removed (the time at which it was removed is given also, as is a link
to the page explaining why):</p>
<pre><code class="html"><table>
<thead>
<tr> <th> Game name <th> Game publisher <th> <strong><del cite="/edits/r192" datetime="2011-05-02 14:23Z">Verdict</del></strong>
<tbody>
<tr> <td> Diablo 2 <td> Blizzard <td> <strong><del cite="/edits/r192" datetime="2011-05-02 14:23Z">8/10</del></strong>
<tr> <td> Portal <td> Valve <td> <strong><del cite="/edits/r192" datetime="2011-05-02 14:23Z">10/10</del></strong>
<tr> <td> Portal 2 <td> Valve <td> <strong><del cite="/edits/r192" datetime="2011-05-02 14:23Z">10/10</del></strong>
</table></code></pre>
</div>
<p>Generally speaking, there is no good way to indicate more complicated edits (e.g. that a cell
was removed, moving all subsequent cells up or to the left).</p>
<h3 split-filename="embedded-content" id="embedded-content">Embedded content</h3>
<h4>The <dfn element><code>picture</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>source</code> elements, followed by one <code>img</code> element,
optionally intermixed with <span>script-supporting elements</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-picture">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-picture">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLPictureElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLPictureElement</code>.</dd>
</dl>
<p>The <code>picture</code> element is a container
which provides multiple sources to its contained <code>img</code> element
to allow authors to declaratively control or give hints to the user agent about which image resource to use,
based on the screen pixel density, <span>viewport</span> size, image format, and other factors.
It <span>represents</span> its children.</p>
<p class="note">The <code>picture</code> element is somewhat different from the similar-looking
<code>video</code> and <code>audio</code> elements. While all of them contain <code>source</code>
elements, the <code>source</code> element's <code data-x="attr-source-src">src</code> attribute
has no meaning when the element is nested within a <code>picture</code> element, and the resource
selection algorithm is different. Also, the <code>picture</code> element itself does not display
anything; it merely provides a context for its contained <code>img</code> element that enables it
to choose from multiple <span data-x="URL">URLs</span>.</p>
<h4>The <dfn element><code>source</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>picture</code> element, before the <code>img</code> element.</dd>
<dd>As a child of a <span>media element</span>, before any <span>flow content</span> or
<code>track</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-source-type">type</code></dd>
<dd><code data-x="attr-source-media">media</code></dd>
<dd><code data-x="attr-source-src">src</code> (in <code>audio</code> or <code>video</code>)</dd>
<dd><code data-x="attr-source-srcset">srcset</code> (in <code>picture</code>)</dd>
<dd><code data-x="attr-source-sizes">sizes</code> (in <code>picture</code>)</dd>
<dd><code data-x="attr-dim-width">width</code> (in <code>picture</code>)</dd>
<dd><code data-x="attr-dim-height">height</code> (in <code>picture</code>)</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-source">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-source">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLSourceElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-source-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-source-type">type</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-source-srcset">srcset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-source-sizes">sizes</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-source-media">media</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-dim-width">width</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-dim-height">height</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLSourceElement</code>.</dd>
</dl>
<p>The <code>source</code> element allows authors to specify multiple alternative
<span data-x="source set">source sets</span> for <code>img</code> elements or multiple alternative
<span data-x="media resource">media resources</span> for <span data-x="media element">media
elements</span>. It does not <span data-x="represents">represent</span> anything on its own.</p>
<p>The <dfn element-attr for="source" data-x="attr-source-type"><code>type</code></dfn> attribute
may be present. If present, the value must be a <span>valid MIME type string</span>.</p>
<p>The <dfn element-attr for="source" data-x="attr-source-media"><code>media</code></dfn>
attribute may also be present. If present, the value must contain a <span>valid media query
list</span>. The user agent will skip to the next <code>source</code> element if the value does
not <span data-x="matches the environment">match the environment</span>.</p>
<p class="note">The <code data-x="attr-source-media">media</code> attribute is only evaluated
once during the <span data-x="concept-media-load-algorithm">resource selection algorithm</span>
for <span data-x="media element">media elements</span>. In contrast, when using the
<code>picture</code> element, the user agent will <a href="#img-environment-changes">react to
changes in the environment</a>.</p>
<p>The remainder of the requirements depend on whether the parent is a <code>picture</code>
element or a <span>media element</span>:</p>
<dl class="switch">
<dt>The <code>source</code> element's parent is a <code>picture</code> element</dt>
<dd>
<p>The <dfn element-attr for="source" data-x="attr-source-srcset"><code>srcset</code></dfn>
attribute must be present, and is a <span>srcset attribute</span>.</p>
<p>The <code data-x="attr-source-srcset">srcset</code> attribute contributes the <span
data-x="image source">image sources</span> to the <span>source set</span>, if the
<code>source</code> element is selected.</p>
<p>If the <code data-x="attr-source-srcset">srcset</code> attribute has any <span data-x="image
candidate string">image candidate strings</span> using a <span>width descriptor</span>, the
<code data-x="attr-source-sizes">sizes</code> attribute may also be present. If, additionally,
the following sibling <code>img</code> element does not <span data-x="allows auto-sizes">allow
auto-sizes</span>, the <code data-x="attr-source-sizes">sizes</code> attribute must be present.
The <dfn element-attr for="source" data-x="attr-source-sizes"><code>sizes</code></dfn>
attribute is a <span>sizes attribute</span>, which contributes the <span>source size</span> to
the <span>source set</span>, if the <code>source</code> element is selected.</p>
<p class="note">If the <code>img</code> element <span>allows auto-sizes</span>, then the <code
data-x="attr-source-sizes">sizes</code> attribute can be omitted on previous sibling
<code>source</code> elements. In such cases, it is equivalent to specifying <code
data-x="valdef-sizes-auto">auto</code>.</p>
<p>The <code>source</code> element supports <span>dimension attributes</span>. The
<code>img</code> element can use the <code data-x="attr-dim-width">width</code> and <code
data-x="attr-dim-height">height</code> attributes of a <code>source</code> element, instead of
those on the <code>img</code> element itself, to determine its rendered dimensions and
aspect-ratio, <a href="#dimRendering">as defined in the Rendering section</a>.</p>
<p>The <code data-x="attr-source-type">type</code> attribute gives the type of the images in the
<span>source set</span>, to allow the user agent to skip to the next <code>source</code> element
if it does not support the given type.</p>
<p class="note">If the <code data-x="attr-source-type">type</code> attribute is <em>not</em>
specified, the user agent will not select a different <code>source</code> element if it finds
that it does not support the image format after fetching it.</p>
<p>When a <code>source</code> element has a following sibling <code>source</code> element or
<code>img</code> element with a <code data-x="attr-img-srcset">srcset</code> attribute
specified, it must have at least one of the following:</p>
<ul>
<li><p>A <code data-x="attr-source-media">media</code> attribute specified with a value that,
after <span data-x="strip leading and trailing ASCII whitespace">stripping leading and trailing
ASCII whitespace</span>, is not the empty string and is not an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">all</code>".</p></li>
<li><p>A <code data-x="attr-source-type">type</code> attribute specified.</p></li>
</ul>
<p>The <code data-x="attr-source-src">src</code> attribute must not be present.</p>
</dd>
<dt>The <code>source</code> element's parent is a <span>media element</span></dt>
<dd>
<p>The <dfn element-attr for="source"><code data-x="attr-source-src">src</code></dfn> attribute
gives the <span>URL</span> of the <span>media resource</span>. The value must be a <span>valid
non-empty URL potentially surrounded by spaces</span>. This attribute must be present.</p>
<p>The <code data-x="attr-source-type">type</code> attribute gives the type of the <span>media
resource</span>, to help the user agent determine if it can play this <span>media
resource</span> before fetching it. The <code data-x="">codecs</code> parameter, which certain
MIME types define, might be necessary to specify exactly how the resource is encoded.
<ref>RFC6381</ref></p>
<p class="note">Dynamically modifying a <code>source</code> element's <code
data-x="attr-source-src">src</code> or <code data-x="attr-source-type">type</code> attribute
when the element is already inserted in a <code>video</code> or <code>audio</code> element will
have no effect. To change what is playing, just use the <code data-x="attr-media-src">src</code>
attribute on the <span>media element</span> directly, possibly making use of the <code
data-x="dom-navigator-canPlayType">canPlayType()</code> method to pick from amongst available
resources. Generally, manipulating <code>source</code> elements manually after the document has
been parsed is an unnecessarily complicated approach.</p>
<div class="example">
<p>The following list shows some examples of how to use the <code data-x="">codecs=</code> MIME
parameter in the <code data-x="attr-source-type">type</code> attribute.</p>
<dl>
<dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></code></pre></dd>
<dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></code></pre></dd>
<dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></code></pre></dd>
<dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></code></pre></dd>
<dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></code></pre></dd>
<dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
<dd><pre><code class="html"><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></code></pre></dd>
<dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
<dd><pre><code class="html"><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></code></pre></dd>
<dt>Theora video and Vorbis audio in Ogg container</dt>
<dd><pre><code class="html"><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></code></pre></dd>
<dt>Theora video and Speex audio in Ogg container</dt>
<dd><pre><code class="html"><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></code></pre></dd>
<dt>Vorbis audio alone in Ogg container</dt>
<dd><pre><code class="html"><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></code></pre></dd>
<dt>Speex audio alone in Ogg container</dt>
<dd><pre><code class="html"><source src='audio.spx' type='audio/ogg; codecs=speex'></code></pre></dd>
<dt>FLAC audio alone in Ogg container</dt>
<dd><pre><code class="html"><source src='audio.oga' type='audio/ogg; codecs=flac'></code></pre></dd>
<dt>Dirac video and Vorbis audio in Ogg container</dt>
<dd><pre><code class="html"><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></code></pre></dd>
<!-- awaiting definition by the Matroska guys:
<dt>Theora video and Vorbis audio in Matroska container</dt>
<dd><pre><code class="html"><source src='video.mkv' type='video/x-matroska; codecs="theora, vorbis"'></code></pre></dd>
-->
<!-- awaiting definition by the Ogg or BBC guys:
<dt>Dirac video and Vorbis audio in Matroska container</dt>
<dd><pre><code class="html"><source src='video.mkv' type='video/x-matroska; codecs='></code></pre></dd>
-->
<!-- awaiting definition by the Microsoft guys:
<dt>WMV9 video and WMA 2 audio in ASF container</dt>
<dd><pre><code class="html"><source src='video.wmv' type='video/x-ms-wmv; codecs='></code></pre></dd>
<dt>WMV8 video and WMA 2 audio in ASF container</dt>
<dd><pre><code class="html"><source src='video.wmv' type='video/x-ms-wmv; codecs='></code></pre></dd>
<dt>VC-1 video and WMA 10 Pro audio in ASF container</dt>
<dd><pre><code class="html"><source src='video.wmv' type='video/x-ms-wmv; codecs='></code></pre></dd>
<dt>XviD video and MP3 audio in AVI container</dt>
<dd><pre><code class="html"><source src='video.avi' type='video/x-msvideo; codecs='></code></pre></dd>
<dt>Motion-JPEG video and uncompressed PCM audio in AVI container</dt>
<dd><pre><code class="html"><source src='video.avi' type='video/x-msvideo; codecs='></code></pre></dd>
-->
<!-- awaiting definition by Real:
<dt>Real Video 10 video and High-Efficiency AAC audio in Real Media container</dt>
<dd><pre><code class="html"><source src='video.rm' type='application/vnd.rn-realmedia; codecs='></code></pre></dd>
-->
<!-- undefined:
<dt>MPEG-1 video and MPEG-1 Audio Layer II audio in MPEG-1 program stream</dt>
<dd><pre><code class="html"><source src='video.mpg' type='video/mpeg; codecs='></code></pre></dd>
-->
</dl>
</div>
<p>The <code data-x="attr-source-srcset">srcset</code> and <code
data-x="attr-source-sizes">sizes</code> attributes must not be present.</p>
</dd>
</dl>
<div w-nodev>
<p>The <code>source</code> <span>HTML element insertion steps</span>, given
<var>insertedNode</var>, are:</p>
<ol>
<li><p>Let <var>parent</var> be <var>insertedNode</var>'s <span>parent</span>.</p></li>
<li><p>If <var>parent</var> is a <span>media element</span> that has no <code
data-x="attr-media-src">src</code> attribute and whose <code
data-x="dom-media-networkState">networkState</code> has the value <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, then invoke that <span>media
element</span>'s <span data-x="concept-media-load-algorithm">resource selection
algorithm</span>.</p></li>
<li><p>If <var>parent</var> is a <code>picture</code> element, then <span data-x="list
iterate">for each</span> <var>child</var> of <var>parent</var>'s <span
data-x="concept-tree-child">children</span>, if <var>child</var> is an <code>img</code> element,
then count this as a <span data-x="relevant mutations">relevant mutation</span> for
<var>child</var>.</p></li>
</ol>
<p>The <code>source</code> <span>HTML element moving steps</span>, given <var>movedNode</var> and
<var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>picture</code> element, then <span data-x="list
iterate">for each</span> <var>child</var> of <var>oldParent</var>'s <span
data-x="concept-tree-child">children</span>, if <var>child</var> is an <code>img</code> element,
then count this as a <span data-x="relevant mutations">relevant mutation</span> for
<var>child</var>.</p></li>
</ol>
<p>The <code>source</code> <span>HTML element removing steps</span>, given <var>removedNode</var>
and <var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>picture</code> element, then <span data-x="list
iterate">for each</span> <var>child</var> of <var>oldParent</var>'s <span
data-x="concept-tree-child">children</span>, if <var>child</var> is an <code>img</code> element,
then count this as a <span data-x="relevant mutations">relevant mutation</span> for
<var>child</var>.</p></li>
</ol>
<p>The IDL attributes <dfn attribute for="HTMLSourceElement"><code
data-x="dom-source-src">src</code></dfn>, <dfn attribute for="HTMLSourceElement"><code
data-x="dom-source-type">type</code></dfn>, <dfn attribute for="HTMLSourceElement"
data-x="dom-source-srcset"><code>srcset</code></dfn>, <dfn attribute for="HTMLSourceElement"
data-x="dom-source-sizes"><code>sizes</code></dfn>, and <dfn attribute for="HTMLSourceElement"
data-x="dom-source-media"><code>media</code></dfn> must <span>reflect</span> the respective
content attributes of the same name.</p>
</div>
<div class="example">
<p>If the author isn't sure if user agents will all be able to render the media resources
provided, the author can listen to the <code data-x="event-error">error</code> event on the last
<code>source</code> element and trigger fallback behavior:</p>
<pre><code class="html"><script>
function fallback(video) {
// replace <video> with its contents
while (video.hasChildNodes()) {
if (video.firstChild instanceof HTMLSourceElement)
video.removeChild(video.firstChild);
else
video.parentNode.insertBefore(video.firstChild, video);
}
video.parentNode.removeChild(video);
}
</script>
<video controls autoplay>
<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
onerror="fallback(parentNode)">
...
</video></code></pre>
</div>
<h4>The <dfn element><code>img</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd><span>Form-associated element</span>.</dd>
<dd>If the element has a <code data-x="attr-hyperlink-usemap">usemap</code> attribute: <span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dd>As a child of a <code>picture</code> element, after all <code>source</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-img-alt">alt</code></dd>
<dd><code data-x="attr-img-src">src</code></dd>
<dd><code data-x="attr-img-srcset">srcset</code></dd>
<dd><code data-x="attr-img-sizes">sizes</code></dd>
<dd><code data-x="attr-img-crossorigin">crossorigin</code></dd>
<dd><code data-x="attr-hyperlink-usemap">usemap</code></dd>
<dd><code data-x="attr-img-ismap">ismap</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dd><code data-x="attr-img-referrerpolicy">referrerpolicy</code></dd>
<dd><code data-x="attr-img-decoding">decoding</code></dd>
<dd><code data-x="attr-img-loading">loading</code></dd>
<dd><code data-x="attr-img-fetchpriority">fetchpriority</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If the element has a non-empty <code data-x="attr-img-alt">alt</code> attribute: <a
href="https://w3c.github.io/html-aria/#el-img">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-img">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-img-empty-alt">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-img-empty-alt">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window,
<span>LegacyFactoryFunction</span>=<span data-x="dom-image">Image</span>(optional unsigned long width, optional unsigned long height)]
interface <dfn interface>HTMLImageElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-alt">alt</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-img-src">src</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-img-srcset">srcset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-sizes">sizes</span>;
[<span>CEReactions</span>] attribute DOMString? <span data-x="dom-img-crossOrigin">crossOrigin</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-useMap">useMap</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-img-isMap">isMap</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-img-width">width</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-img-height">height</span>;
readonly attribute unsigned long <span data-x="dom-img-naturalWidth">naturalWidth</span>;
readonly attribute unsigned long <span data-x="dom-img-naturalHeight">naturalHeight</span>;
readonly attribute boolean <span data-x="dom-img-complete">complete</span>;
readonly attribute USVString <span data-x="dom-img-currentSrc">currentSrc</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-referrerPolicy">referrerPolicy</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-decoding">decoding</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-loading">loading</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-fetchPriority">fetchPriority</span>;
<span data-x="idl-Promise">Promise</span><undefined> <span data-x="dom-img-decode">decode</span>();
// <a href="#HTMLImageElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLImageElement</code>.</dd>
</dl>
<p>An <code>img</code> element represents an image.</p>
<p>An <code>img</code> element has a <dfn data-x="concept-img-dimension-attribute-source">dimension
attribute source</dfn>, initially set to the element itself.</p>
<!-- v2 ideas for <img>:
* Maps sites would like to know which images are already cached, so that they can use images
that are vaguely suitable while they wait for the most appropriate image to download.
Almost like lowsrc="", except that many images might be appropriate.
Slight hitch: their images are at a different origin, and we don't want to allow arbitrary
cross-origin inspection (privacy leak risk). So it will require them to do CORS opt-in.
* See note at rel=noreferrer.
-->
<p>The image given by the <dfn element-attr for="img" data-x="attr-img-src"><code>src</code></dfn>
and <dfn data-x="attr-img-srcset" element-attr for="img"><code>srcset</code></dfn> attributes, and
any previous sibling <code>source</code> elements' <code data-x="attr-source-srcset">srcset</code>
attributes if the parent is a <code>picture</code> element, is the embedded content; the value of
the <dfn element-attr for="img" data-x="attr-img-alt"><code>alt</code></dfn> attribute provides
equivalent content for those who cannot process images or who have image loading disabled (i.e. it
is the <code>img</code> element's <span>fallback content</span>).</p>
<p>The requirements on the <code data-x="attr-img-alt">alt</code> attribute's value are described
<a href="#alt">in a separate section</a>.</p>
<p>The <code data-x="attr-img-src">src</code> attribute must be present, and must contain a
<span>valid non-empty URL potentially surrounded by spaces</span> referencing a non-interactive,
optionally animated, image resource that is neither paged nor scripted.</p>
<p class="note">The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs,
JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element),
animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG
<span>document element</span> that use declarative SMIL animation), and so forth. However, these
definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML
documents, plain text documents, and the like. <ref>PNG</ref> <ref>GIF</ref> <ref>JPEG</ref>
<ref>PDF</ref> <ref>XML</ref> <ref>APNG</ref> <ref>SVG</ref> <ref>MNG</ref> </p>
<p>The <code data-x="attr-img-srcset">srcset</code> attribute may also be present, and is a
<span>srcset attribute</span>.</p>
<p>The <code data-x="attr-img-srcset">srcset</code> attribute and the <code
data-x="attr-img-src">src</code> attribute (if <span data-x="width descriptor">width
descriptors</span> are not used) contribute the <span data-x="image source">image sources</span>
to the <span>source set</span> (if no <code>source</code> element was selected).</p>
<p>If the <code data-x="attr-img-srcset">srcset</code> attribute is present and has any <span
data-x="image candidate string">image candidate strings</span> using a <span>width
descriptor</span>, the <code data-x="attr-img-sizes">sizes</code> attribute must also be present.
If the <code data-x="attr-img-srcset">srcset</code> attribute is <em>not</em> specified, and the
<code data-x="attr-img-loading">loading</code> attribute is in the <span
data-x="attr-loading-lazy-state">Lazy</span> state, the <code
data-x="attr-img-sizes">sizes</code> attribute may be specified with the value "<code
data-x="">auto</code>" (<span>ASCII case-insensitive</span>). The <dfn element-attr for="img"
data-x="attr-img-sizes"><code>sizes</code></dfn> attribute is a <span>sizes attribute</span>,
which contributes the <span>source size</span> to the <span>source set</span> (if no
<code>source</code> element was selected).</p>
<p>An <code>img</code> element <dfn>allows auto-sizes</dfn> if:</p>
<ul>
<li>its <code data-x="attr-img-loading">loading</code> attribute is in the <span
data-x="attr-loading-lazy-state">Lazy</span> state, and</li>
<li>its <code data-x="attr-img-sizes">sizes</code> attribute's value is "<code
data-x="">auto</code>" (<span>ASCII case-insensitive</span>), or starts with "<code
data-x="">auto,</code>" (<span>ASCII case-insensitive</span>).</li>
</ul>
<p>The <dfn element-attr for="img" data-x="attr-img-crossorigin"><code>crossorigin</code></dfn>
attribute is a <span>CORS settings attribute</span>. Its purpose is to allow images from
third-party sites that allow cross-origin access to be used with <code>canvas</code>.</p>
<p>The <dfn element-attr for="img"
data-x="attr-img-referrerpolicy"><code>referrerpolicy</code></dfn> attribute is a <span>referrer
policy attribute</span>. Its purpose is to set the <span>referrer policy</span> used when <span
data-x="concept-fetch">fetching</span> the image. <ref>REFERRERPOLICY</ref></p>
<p>The <dfn element-attr for="img" data-x="attr-img-decoding"><code>decoding</code></dfn>
attribute indicates the preferred method to <span data-x="img-decoding-process">decode</span> this
image. The attribute, if present, must be an <span>image decoding hint</span>. This attribute's <i
data-x="missing value default">missing value default</i> and <i data-x="invalid value
default">invalid value default</i> are both the <span
data-x="attr-img-decoding-auto-state">auto</span> state.</p>
<p>The <dfn element-attr for="img"
data-x="attr-img-fetchpriority"><code>fetchpriority</code></dfn> attribute is a <span>fetch
priority attribute</span>. Its purpose is to set the <span
data-x="concept-request-priority">priority</span> used when <span
data-x="concept-fetch">fetching</span> the image.</p>
<p>The <dfn element-attr for="img" data-x="attr-img-loading"><code>loading</code></dfn> attribute is a <span>lazy
loading attribute</span>. Its purpose is to indicate the policy for loading images that are
outside the viewport.</p>
<p>When the <code data-x="attr-img-loading">loading</code> attribute's state is changed to the
<span data-x="attr-loading-eager-state">Eager</span> state, the user agent must run these
steps:</p>
<ol>
<li><p>Let <var>resumptionSteps</var> be the <code>img</code> element's <span>lazy load
resumption steps</span>.</p></li>
<li><p>If <var>resumptionSteps</var> is null, then return.</p></li>
<li><p>Set the <code>img</code>'s <span>lazy load resumption steps</span> to null.</p></li>
<li><p>Invoke <var>resumptionSteps</var>.</p></li>
</ol>
<div class="example">
<pre><code class="html"><img src="1.jpeg" alt="1">
<img src="2.jpeg" loading=eager alt="2">
<img src="3.jpeg" loading=lazy alt="3">
<div id=very-large></div> <!-- Everything after this div is below the viewport -->
<img src="4.jpeg" alt="4">
<img src="5.jpeg" loading=lazy alt="5"></code></pre>
<p>In the example above, the images load as follows:</p>
<dl class="switch">
<dt><code data-x="">1.jpeg</code>, <code data-x="">2.jpeg</code>,
<code data-x="">4.jpeg</code></dt>
<dd><p>The images load eagerly and delay the window's load event.</p></dd>
<dt><code data-x="">3.jpeg</code></dt>
<dd><p>The image loads when layout is known, due to being in the viewport, however it does not
delay the window's load event.</p></dd>
<dt><code data-x="">5.jpeg</code></dt>
<dd><p>The image loads only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>
</dl>
<p class="note">Developers are encouraged to specify a preferred aspect ratio via <code
data-x="attr-dim-width">width</code> and <code data-x="attr-dim-height">height</code> attributes
on lazy loaded images, even if CSS sets the image's width and height properties, to prevent the
page layout from shifting around after the image loads.</p>
</div>
<p>The <code>img</code> <span>HTML element insertion steps</span>, given <var>insertedNode</var>,
are:</p>
<ol>
<li><p>If <var>insertedNode</var>'s parent is a <code>picture</code> element, then, count this as
a <span data-x="relevant mutations">relevant mutation</span> for
<var>insertedNode</var>.</p></li>
</ol>
<p>The <code>img</code> <span>HTML element moving steps</span>, given <var>movedNode</var> and
<var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>picture</code> element, then, count this as a <span
data-x="relevant mutations">relevant mutation</span> for <var>movedNode</var>.</p></li>
</ol>
<p>The <code>img</code> <span>HTML element removing steps</span>, given <var>removedNode</var> and
<var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>picture</code> element, then, count this as a
<span data-x="relevant mutations">relevant mutation</span> for <var>removedNode</var>.</p></li>
</ol>
<hr>
<p>The <code>img</code> element must not be used as a layout tool. In particular, <code>img</code>
elements should not be used to display transparent images, as such images rarely convey meaning and
rarely add anything useful to the document.</p>
<div w-nodev>
<hr>
<p>What an <code>img</code> element represents depends on the <code
data-x="attr-img-src">src</code> attribute and the <code data-x="attr-img-alt">alt</code>
attribute.</p>
<dl class="switch">
<dt>If the <code data-x="attr-img-src">src</code> attribute is set and the <code
data-x="attr-img-alt">alt</code> attribute is set to the empty string</dt>
<dd>
<p>The image is either decorative or supplemental to the rest of the content, redundant with
some other information in the document.</p>
<p>If the image is <span data-x="img-available">available</span> and the user agent is configured
to display that image, then the element <span>represents</span> the element's image data.</p>
<p>Otherwise, the element <span>represents</span> nothing, and may be omitted completely from
the rendering. User agents may provide the user with a notification that an image is present but
has been omitted from the rendering.</p>
</dd>
<dt>If the <code data-x="attr-img-src">src</code> attribute is set and the <code
data-x="attr-img-alt">alt</code> attribute is set to a value that isn't empty</dt>
<dd>
<p>The image is a key part of the content; the <code data-x="attr-img-alt">alt</code> attribute
gives a textual equivalent or replacement for the image.</p>
<p>If the image is <span data-x="img-available">available</span> and the user agent is configured
to display that image, then the element <span>represents</span> the element's image data.</p>
<p>Otherwise, the element <span>represents</span> the text given by the <code
data-x="attr-img-alt">alt</code> attribute. User agents may provide the user with a notification
that an image is present but has been omitted from the rendering.</p>
</dd>
<dt>If the <code data-x="attr-img-src">src</code> attribute is set and the <code
data-x="attr-img-alt">alt</code> attribute is not</dt>
<dd>
<p>The image might be a key part of the content, and there is no textual equivalent of the image
available.</p>
<p class="note">In a conforming document, the absence of the <code
data-x="attr-img-alt">alt</code> attribute indicates that the image is a key part of the content
but that a textual replacement for the image was not available when the image was generated.</p>
<p>If the image is <span data-x="img-available">available</span> and the user agent is configured
to display that image, then the element <span>represents</span> the element's image data.</p>
<p>If the image has a <code data-x="attr-img-src">src</code> attribute whose value is
the empty string, then the element <span>represents</span> nothing.</p>
<p>Otherwise, the user agent should display some sort of indicator that there is an image that
is not being rendered, and may, if requested by the user, or if so configured, or when required
to provide contextual information in response to navigation, provide caption information for the
image, derived as follows:</p>
<ol>
<!-- when editing this list, search for the two other occurrences of 'critical-no-alt' -->
<!-- NOTE: the order of these steps is important; it's intended to make the innermost caption
override the outer ones -->
<li><p>If the image has a <code data-x="attr-title">title</code> attribute whose value is not
the empty string, then return the value of that attribute.</p></li>
<li><p>If the image is a descendant of a <code>figure</code> element that has a child
<code>figcaption</code> element, and, ignoring the <code>figcaption</code> element and its
descendants, the <code>figure</code> element has no <span>flow content</span> descendants other
than <span>inter-element whitespace</span> and the <code>img</code> element, then return the
contents of the first such <code>figcaption</code> element.</p></li>
<li><p>Return nothing. (There is no caption information.)</p></li>
</ol>
</dd>
<dt>If the <code data-x="attr-img-src">src</code> attribute is not set and either the <code
data-x="attr-img-alt">alt</code> attribute is set to the empty string or the <code
data-x="attr-img-alt">alt</code> attribute is not set at all</dt>
<dd>
<p>The element <span>represents</span> nothing.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>The element <span>represents</span> the text given by the <code
data-x="attr-img-alt">alt</code> attribute.</p>
</dd>
</dl>
<p>The <code data-x="attr-img-alt">alt</code> attribute does not represent advisory information.
User agents must not present the contents of the <code data-x="attr-img-alt">alt</code> attribute
in the same way as content of the <code data-x="attr-title">title</code> attribute.</p>
<p>User agents may always provide the user with the option to display any image, or to prevent any
image from being displayed. User agents may also apply heuristics to help the user make use of the
image when the user is unable to see it, e.g. due to a visual disability or because they are using
a text terminal with no graphics capabilities. Such heuristics could include, for instance,
optical character recognition (OCR) of text found within the image.</p>
<p class="warning">While user agents are encouraged to repair cases of missing <code
data-x="attr-img-alt">alt</code> attributes, authors must not rely on such behavior. <a
href="#alt">Requirements for providing text to act as an alternative for images</a> are described
in detail below.</p>
<p>The <em>contents</em> of <code>img</code> elements, if any, are ignored for the purposes of
rendering.</p>
</div>
<hr>
<p>The <code data-x="attr-hyperlink-usemap">usemap</code> attribute,
if present, can indicate that the image has an associated
<span>image map</span>.</p>
<p>The <dfn element-attr for="img" data-x="attr-img-ismap"><code>ismap</code></dfn> attribute,
when used on an element that is a descendant of an <code>a</code> element with an <code
data-x="attr-hyperlink-href">href</code> attribute, indicates by its presence that the element
provides access to a server-side image map. This affects how events are handled on the
corresponding <code>a</code> element.</p>
<p>The <code data-x="attr-img-ismap">ismap</code> attribute is a
<span>boolean attribute</span>. The attribute must not be specified
on an element that does not have an ancestor <code>a</code> element
with an <code data-x="attr-hyperlink-href">href</code> attribute.</p>
<p class="note">The <code data-x="attr-hyperlink-usemap">usemap</code> and <code
data-x="attr-img-ismap">ismap</code> attributes can result in confusing behavior when used
together with <code>source</code> elements with the <code data-x="attr-source-media">media</code>
attribute specified in a <code>picture</code> element.</p>
<p>The <code>img</code> element supports <span>dimension
attributes</span>.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLImageElement" data-x="dom-img-alt"><code>alt</code></dfn>, <dfn
attribute for="HTMLImageElement" data-x="dom-img-src"><code>src</code></dfn>, <dfn attribute
for="HTMLImageElement" data-x="dom-img-srcset"><code>srcset</code></dfn>, and <dfn attribute
for="HTMLImageElement" data-x="dom-img-sizes"><code>sizes</code></dfn> IDL attributes must
<span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLImageElement"
data-x="dom-img-crossOrigin"><code>crossOrigin</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-img-crossorigin">crossorigin</code> content attribute,
<span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLImageElement" data-x="dom-img-useMap"><code>useMap</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-hyperlink-usemap">usemap</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLImageElement" data-x="dom-img-isMap"><code>isMap</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-img-ismap">ismap</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLImageElement"><code
data-x="dom-img-referrerPolicy">referrerPolicy</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-img-referrerpolicy">referrerpolicy</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLImageElement"><code data-x="dom-img-decoding">decoding</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-img-decoding">decoding</code>
content attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLImageElement"><code data-x="dom-img-loading">loading</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-img-loading">loading</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLImageElement"><code
data-x="dom-img-fetchPriority">fetchPriority</code></dfn> IDL attribute
must <span>reflect</span> the <code data-x="attr-img-fetchpriority">fetchpriority</code> content
attribute, <span>limited to only known values</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-width">width</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-height">height</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>These attributes return the actual rendered dimensions of the image, or 0 if the dimensions
are not known.</p>
<p>They can be set, to change the corresponding content attributes.</p>
</dd>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-naturalWidth">naturalWidth</span></code></dt>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-naturalHeight">naturalHeight</span></code></dt>
<dd>
<p>These attributes return the natural dimensions of the image, or 0 if the dimensions are not
known.</p>
</dd>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-complete">complete</span></code></dt>
<dd>
<p>Returns true if the image has been completely downloaded or if no image is specified;
otherwise, returns false.</p>
</dd>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-currentSrc">currentSrc</span></code></dt>
<dd><p>Returns the image's <span>absolute URL</span>.</p></dd>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-img-decode">decode</span>()</code></dt>
<dd>
<p>This method causes the user agent to <span data-x="img-decoding-process">decode</span> the
image <span>in parallel</span>, returning a promise that fulfills when decoding is complete.</p>
<p>The promise will be rejected with an <span>"<code>EncodingError</code>"</span>
<code>DOMException</code> if the image cannot be decoded.</p>
</dd>
<dt><code data-x=""><var>image</var> = new <span subdfn data-x="dom-image">Image</span>([ <var>width</var> [, <var>height</var> ] ])</code></dt>
<dd>
<p>Returns a new <code>img</code> element, with the <code data-x="attr-dim-width">width</code>
and <code data-x="attr-dim-height">height</code> attributes set to the values passed in the
relevant arguments, if applicable.</p>
</dd>
</dl>
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLImageElement"
data-x="dom-img-width"><code>width</code></dfn> and <dfn attribute for="HTMLImageElement"
data-x="dom-img-height"><code>height</code></dfn> must return the rendered width and height of the
image, in <span data-x="'px'">CSS pixels</span>, if the image is <span>being rendered</span>; or
else the <span>density-corrected natural width and height</span> of the image, in <span
data-x="'px'">CSS pixels</span>, if the image has <span>density-corrected natural width and
height</span> and is <i data-x="img-available">available</i> but is not <span>being
rendered</span>; or else 0, if the image is not <i data-x="img-available">available</i> or does
not have <span>density-corrected natural width and height</span>. <ref>CSS</ref></p>
<p>On setting, they must act as if they <span data-x="reflect">reflected</span> the respective
content attributes of the same name.</p>
<p>The IDL attributes <dfn attribute for="HTMLImageElement"
data-x="dom-img-naturalWidth"><code>naturalWidth</code></dfn> and <dfn attribute
for="HTMLImageElement" data-x="dom-img-naturalHeight"><code>naturalHeight</code></dfn> must return
the <span>density-corrected natural width and height</span> of the image, in <span
data-x="'px'">CSS pixels</span>, if the image has <span>density-corrected natural width and
height</span> and is <i data-x="img-available">available</i>, or else 0. <ref>CSS</ref></p>
<p class="note">Since the <span>density-corrected natural width and height</span> of an image
take into account any orientation specified in its metadata, <code
data-x="dom-img-naturalWidth">naturalWidth</code> and <code
data-x="dom-img-naturalHeight">naturalHeight</code> reflect the dimensions after applying any
rotation needed to correctly orient the image, regardless of the value of the
<span>'image-orientation'</span> property.</p>
<p>The <dfn attribute for="HTMLImageElement"
data-x="dom-img-complete"><code>complete</code></dfn> getter steps are:</p>
<ol>
<li>
<p>If any of the following are true:</p>
<ul>
<!--TODO: check picture parent-->
<li><p>both the <code data-x="attr-img-src">src</code> attribute and the <code
data-x="attr-img-srcset">srcset</code> attribute are omitted;</p></li>
<li><p>the <code data-x="attr-img-srcset">srcset</code> attribute is omitted and the <code
data-x="attr-img-src">src</code> attribute's value is the empty string;</p></li>
<!-- we only have this hack for src="", not srcset=""; present but empty or bogus srcset=""
still means complete=false if it's not in the img-error state -->
<li><p>the <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-all">completely available</span> and
its <span>pending request</span> is null; or</p></li>
<li><p>the <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-error">broken</span> and its
<span>pending request</span> is null,</p></li>
</ul>
<p>then return true.</p>
</li>
<li><p>Return false.</p></li>
</ol>
<p>The <dfn attribute for="HTMLImageElement"
data-x="dom-img-currentSrc"><code>currentSrc</code></dfn> IDL attribute must return the
<code>img</code> element's <span>current request</span>'s <span data-x="img-req-url">current
URL</span>.</p>
<p>The <dfn method for="HTMLImageElement" data-x="dom-img-decode"><code>decode()</code></dfn>
method, when invoked, must perform the following steps:</p>
<ol>
<li><p>Let <var>promise</var> be a new promise.</p></li>
<li>
<p><span>Queue a microtask</span> to perform the following steps:</p>
<div class="note">
<p>This is done because <span data-x="update the image data">updating the image data</span>
takes place in a microtask as well. Thus, to make code such as</p>
<pre><code class="js">img.src = "stars.jpg";
img.decode();</code></pre>
<p>properly decode <code data-x="">stars.jpg</code>, we need to delay any processing by one
microtask.</p>
</div>
<ol>
<li><p>Let <var>global</var> be <span>this</span>'s <span>relevant global
object</span>.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><span>this</span>'s <span>node document</span> is not <span>fully active</span>;
or</p></li>
<li><p><span>this</span>'s <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-error">broken</span>,</p></li>
</ul>
<p>then reject <var>promise</var> with an <span>"<code>EncodingError</code>"</span>
<code>DOMException</code>.</p>
</li>
<li>
<p>Otherwise, <span>in parallel</span>, wait for one of the following cases to occur, and
perform the corresponding actions:</p>
<dl class="switch">
<dt>This <code>img</code> element's <span>node document</span> stops being <span>fully
active</span></dt>
<dt>This <code>img</code> element's <span>current request</span> changes or is mutated</dt>
<dt>This <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> becomes <span data-x="img-error">broken</span></dt>
<dd><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> with
<var>global</var> to reject <var>promise</var> with an
<span>"<code>EncodingError</code>"</span> <code>DOMException</code>.</p></dd>
<dt>This <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> becomes <span data-x="img-all">completely
available</span></dt>
<dd>
<p><span data-x="img-decoding-process">Decode</span> the image.</p>
<p>If decoding does not need to be performed for this image (for example because it is a
vector graphic) or the decoding process completes successfully, then <span>queue a global
task</span> on the <span>DOM manipulation task source</span> with <var>global</var> to
resolve <var>promise</var> with undefined.</p>
<p>If decoding fails (for example due to invalid image data), then <span>queue a global
task</span> on the <span>DOM manipulation task source</span> with <var>global</var> to
reject <var>promise</var> with an <span>"<code>EncodingError</code>"</span>
<code>DOMException</code>.</p>
<p>User agents should ensure that the decoded media data stays readily available until at
least the end of the next successful <span>update the rendering</span> step in the
<span>event loop</span>. This is an important part of the API contract, and should not be
broken if at all possible. (Typically, this would only be violated in low-memory situations
that require evicting decoded image data, or when the image is too large to keep in decoded
form for this period of time.)</p>
</dd>
</dl>
<p class="note">Animated images will become <span data-x="img-all">completely available</span>
only after all their frames are loaded. Thus, even though an implementation could decode the
first frame before that point, the above steps will not do so, instead waiting until all
frames are available.</p>
</li>
</ol>
</li>
<li><p>Return <var>promise</var>.</p></li>
</ol>
</div>
<div class="example">
<p>Without the <code data-x="dom-img-decode">decode()</code> method, the process of loading an
<code>img</code> element and then displaying it might look like the following:</p>
<pre><code class="js">const img = new Image();
img.src = "nebula.jpg";
img.onload = () => {
document.body.appendChild(img);
};
img.onerror = () => {
document.body.appendChild(new Text("Could not load the nebula :("));
};</code></pre>
<p>However, this can cause notable dropped frames, as the paint that occurs after inserting the
image into the DOM causes a synchronous decode on the main thread.</p>
<p>This can instead be rewritten using the <code data-x="dom-img-decode">decode()</code>
method:</p>
<pre><code class="js">const img = new Image();
img.src = "nebula.jpg";
img.decode().then(() => {
document.body.appendChild(img);
}).catch(() => {
document.body.appendChild(new Text("Could not load the nebula :("));
});</code></pre>
<p>This latter form avoids the dropped frames of the original, by allowing the user agent to
decode the image <span>in parallel</span>, and only inserting it into the DOM (and thus causing
it to be painted) once the decoding process is complete.</p>
</div>
<div class="example">
<p>Because the <code data-x="dom-img-decode">decode()</code> method attempts to ensure that the
decoded image data is available for at least one frame, it can be combined with the <code
data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame()</code> API.
This means it can be used with coding styles or frameworks that ensure that all DOM modifications
are batched together as <span data-x="map of animation frame callbacks">animation frame
callbacks</span>:</p>
<pre><code class="js">const container = document.querySelector("#container");
const { containerWidth, containerHeight } = computeDesiredSize();
requestAnimationFrame(() => {
container.style.width = containerWidth;
container.style.height = containerHeight;
});
// ...
const img = new Image();
img.src = "supernova.jpg";
img.decode().then(() => {
requestAnimationFrame(() => container.appendChild(img));
});</code></pre>
</div>
<div w-nodev>
<p>A legacy factory function is provided for creating <code>HTMLImageElement</code> objects (in
addition to the factory methods from DOM such as <code
data-x="dom-Document-createElement">createElement()</code>): <dfn
data-x="dom-image"><code>Image(<var>width</var>, <var>height</var>)</code></dfn>. When invoked,
the legacy factory function must perform the following steps:</p>
<ol>
<li><p>Let <var>document</var> be the <span>current global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>img</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">img</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p>If <var>width</var> is given, then <span data-x="concept-element-attributes-set-value">set
an attribute value</span> for <var>img</var> using "<code data-x="attr-dim-width">width</code>"
and <var>width</var>.</p></li>
<li><p>If <var>height</var> is given, then <span
data-x="concept-element-attributes-set-value">set an attribute value</span> for <var>img</var>
using "<code data-x="attr-dim-height">height</code>" and <var>height</var>.</p></li>
<li><p>Return <var>img</var>.</p></li>
</ol>
</div>
<div class="example">
<p>A single image can have different appropriate alternative text depending on the context.</p>
<p>In each of the following cases, the same image is used, yet the <code
data-x="attr-img-alt">alt</code> text is different each time. The image is the coat of arms of the
Carouge municipality in the canton Geneva in Switzerland.</p>
<p>Here it is used as a supplementary icon:</p>
<pre><code class="html"><p>I lived in <img src="carouge.svg" alt=""> Carouge.</p></code></pre>
<p>Here it is used as an icon representing the town:</p>
<pre><code class="html"><p>Home town: <img src="carouge.svg" alt="Carouge"></p></code></pre>
<p>Here it is used as part of a text on the town:</p>
<pre><code class="html"><p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt="The coat of arms depicts a lion, sitting in front of a tree."></p>
<p>It is used as decoration all over the town.</p></code></pre>
<p>Here it is used as a way to support a similar text where the description is given as well as,
instead of as an alternative to, the image:</p>
<pre><code class="html"><p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt=""></p>
<p>The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.</p></code></pre>
<p>Here it is used as part of a story:</p>
<pre><code class="html"><p>She picked up the folder and a piece of paper fell out.</p>
<p><img src="carouge.svg" alt="Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S."></p>
<p>She stared at the folder. S! The answer she had been looking for all
this time was simply the letter S! How had she not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the time Maria had stuck her tongue out...</p></code></pre>
<p>Here it is not known at the time of publication what the image will be, only that it will be a
coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief
caption for the image is provided, in the <code data-x="attr-title">title</code> attribute:</p>
<pre><code class="html"><p>The last user to have uploaded a coat of arms uploaded this one:</p>
<p><img src="last-uploaded-coat-of-arms.cgi" title="User-uploaded coat of arms."></p></code></pre>
<p>Ideally, the author would find a way to provide real replacement text even in this case, e.g.
by asking the previous user. Not providing replacement text makes the document more difficult to
use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth
connections or who pay by the byte, or users who are forced to use a text-only web browser.</p>
</div>
<div class="example">
<p>Here are some more examples showing the same picture used in different contexts, with
different appropriate alternate texts each time.</p>
<pre><code class="html"><article>
<h1>My cats</h1>
<h2>Fluffy</h2>
<p>Fluffy is my favorite.</p>
<img src="fluffy.jpg" alt="She likes playing with a ball of yarn.">
<p>She's just too cute.</p>
<h2>Miles</h2>
<p>My other cat, Miles just eats and sleeps.</p>
</article></code></pre>
<pre><code class="html"><article>
<h1>Photography</h1>
<h2>Shooting moving targets indoors</h2>
<p>The trick here is to know how to anticipate; to know at what speed and
what distance the subject will pass by.</p>
<img src="fluffy.jpg" alt="A cat flying by, chasing a ball of yarn, can be
photographed quite nicely using this technique.">
<h2>Nature by night</h2>
<p>To achieve this, you'll need either an extremely sensitive film, or
immense flash lights.</p>
</article></code></pre>
<pre><code class="html"><article>
<h1>About me</h1>
<h2>My pets</h2>
<p>I've got a cat named Fluffy and a dog named Miles.</p>
<img src="fluffy.jpg" alt="Fluffy, my cat, tends to keep itself busy.">
<p>My dog Miles and I like go on long walks together.</p>
<h2>music</h2>
<p>After our walks, having emptied my mind, I like listening to Bach.</p>
</article></code></pre>
<pre><code class="html"><article>
<h1>Fluffy and the Yarn</h1>
<p>Fluffy was a cat who liked to play with yarn. She also liked to jump.</p>
<aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
<p>She would play in the morning, she would play in the evening.</p>
</article></code></pre>
</div>
<h4 split-filename="images">Images</h4>
<h5>Introduction</h5>
<!-- NON-NORMATIVE SECTION -->
<p>To embed an image in HTML, when there is only a single image resource, use the <code>img</code>
element and its <code data-x="attr-img-src">src</code> attribute.</p>
<div class="example">
<pre><code class="html"><h2>From today's featured article</h2>
<strong><img src="/uploads/100-marie-lloyd.jpg" alt="" width="100" height="150"></strong>
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
was an English <a href="/wiki/Music_hall">music hall</a> singer, ...</code></pre>
</div>
<p>However, there are a number of situations for which the author might wish to use multiple image
resources that the user agent can choose from:</p>
<ul>
<li>
<p>Different users might have different environmental characteristics:</p>
<ul>
<li>
<p>The users' physical screen size might be different from one another.</p>
<div class="example">
<p>A mobile phone's screen might be 4 inches diagonally, while a laptop's screen might be 14
inches diagonally.</p>
<svg viewBox="0 0 80 32" height="200" font-size="2.5" font-family="sans-serif" role="img"
aria-label="The phone's screen is much smaller compared to the laptop's screen.">
<!-- smartphone -->
<rect width="6" fill="white" stroke="black" x="6" y="18" height="12" rx="1"/>
<text text-anchor="middle" dominant-baseline="middle" transform="translate(9 24)
rotate(-60)">4″</text>
<!-- laptop -->
<rect width="40" fill="white" stroke="black" x="30" y="2" height="26" rx="2"
stroke-width="2"/>
<line y2="30" stroke-linecap="round" stroke="black" x1="26" x2="74" y1="30"
stroke-width="2"/>
<text text-anchor="middle" dominant-baseline="middle" transform="translate(50 15)
rotate(-30)">14″</text>
</svg>
</div>
<p class="note">This is only relevant when an image's rendered size depends on the
<span>viewport</span> size.</p>
</li>
<li>
<p>The users' screen pixel density might be different from one another.</p>
<div class="example">
<p>A mobile phone's screen might have three times as many physical pixels per inch
compared to another mobile phone's screen, regardless of their physical screen size.</p>
<svg viewBox="0 0 56 27" height="170" font-size="2.5" font-family="sans-serif" role="img"
aria-label="One phone has big pixels, the other has small pixels.">
<defs>
<pattern id="img-intro-pixel" x="0" y="0" width="3" height="3" stroke-linecap="round"
patternUnits="userSpaceOnUse">
<rect x="0" y="0" width="3" height="3" fill="black"/>
<line x1="0.5" y1="0.5" x2="0.5" y2="2.5" stroke="red"/>
<line x1="1.5" y1="0.5" x2="1.5" y2="2.5" stroke="lime"/>
<line x1="2.5" y1="0.5" x2="2.5" y2="2.5" stroke="blue"/>
</pattern>
</defs>
<!-- smartphones -->
<rect width="6" fill="white" stroke="black" x="6" y="8" height="12" rx="1"/>
<rect width="6" fill="white" stroke="black" x="36" y="8" height="12" rx="1"/>
<!-- magnifiers -->
<line x1="15" y1="16" x2="22" y2="24" stroke="brown" stroke-width="3"/>
<circle r="8" fill="url(#img-intro-pixel)" stroke="black" cx="10" cy="10"/>
<line x1="45" y1="16" x2="52" y2="24" stroke="brown" stroke-width="3"/>
<circle r="24" fill="url(#img-intro-pixel)" stroke="black" stroke-width="3" cx="120" cy="30"
transform="scale(0.333333)"/>
<!-- text -->
<text dominant-baseline="middle" x="20" y="10">1x</text>
<text dominant-baseline="middle" x="50" y="10">3x</text>
</svg>
</div>
</li>
<li>
<p>The users' zoom level might be different from one another, or might change for a single
user over time.</p>
<p class="example">A user might zoom in to a particular image to be able to get a more
detailed look.</p>
<p>The zoom level and the screen pixel density (the previous point) can both affect the number
of physical screen pixels per <span data-x="'px'">CSS pixel</span>. This ratio is usually
referred to as <dfn>device-pixel-ratio</dfn>.</p>
</li>
<li>
<p>The users' screen orientation might be different from one another, or might change for a
single user over time.</p>
<div class="example">
<p>A tablet can be held upright or rotated 90 degrees, so that the screen is either
"portrait" or "landscape".</p>
<svg viewBox="0 0 60 32" height="200" font-size="2.5" font-family="sans-serif" role="img"
aria-label="The tablet has two orientations.">
<!-- tablets -->
<rect width="14" fill="white" stroke="black" x="6" y="5" height="20" rx="1"/>
<line stroke="black" stroke-width="1.1" x1="6" y1="24" x2="20" y2="24"/>
<text text-anchor="middle" dominant-baseline="middle" x="13" y="14.5">Portrait</text>
<rect width="20" fill="white" stroke="black" x="30" y="11" height="14" rx="1"/>
<line stroke="black" stroke-width="1.1" x1="31" y1="25" x2="31" y2="11"/>
<text text-anchor="middle" dominant-baseline="middle" x="40.5" y="18">Landscape</text>
</svg>
</div>
</li>
<li>
<p>The users' network speed, network latency and bandwidth cost might be different from one
another, or might change for a single user over time.</p>
<p class="example">A user might be on a fast, low-latency and constant-cost connection while
at work, on a slow, low-latency and constant-cost connection while at home, and on a
variable-speed, high-latency and variable-cost connection anywhere else.</p>
</li>
</ul>
</li>
<li>
<p>Authors might want to show the same image content but with different rendered size depending
on, usually, the width of the <span>viewport</span>. This is usually referred to as
<dfn>viewport-based selection</dfn>.</p>
<div class="example">
<p>A web page might have a banner at the top that always spans the entire <span>viewport</span>
width. In this case, the rendered size of the image depends on the physical size of the screen
(assuming a maximised browser window).</p>
<svg viewBox="0 0 52 25.6" height="160" role="img" aria-label="The upright-held phone shows a
small wolf at the top, and the tablet shows the same image but it is bigger.">
<!-- wolf.jpg from https://commons.wikimedia.org/wiki/File:WolfRunningInSnow.jpg -->
<!-- smartphone -->
<rect width="6" fill="white" stroke="black" x="6" y="8" height="12" rx="1"/>
<rect width="4" fill="#716966" x="7" y="9" height="2"/>
<image width="4" x="7" y="9" height="2" xlink:href="/images/wolf.jpg"/>
<!-- tablet -->
<rect width="20" fill="white" stroke="black" x="25" y="6" height="14" rx="1"/>
<line stroke="black" stroke-width="1.1" x1="26" y1="20" x2="26" y2="6"/>
<rect width="17" fill="#716966" x="27" y="7" height="8.5"/>
<image width="17" x="27" y="7" height="8.5" xlink:href="/images/wolf.jpg"/>
</svg>
</div>
<div class="example">
<p>Another web page might have images in columns, with a single column for screens with a small
physical size, two columns for screens with medium physical size, and three columns for screens
with big physical size, with the images varying in rendered size in each case to fill up the
<span>viewport</span>. In this case, the rendered size of an image might be <em>bigger</em> in
the one-column layout compared to the two-column layout, despite the screen being smaller.</p>
<svg viewBox="0 0 115 32" height="200" font-size="2.5" font-family="sans-serif" role="img"
aria-label="The rotated phone shows a top part of an image of a kettlebell swing; the
upright-held tablet shows a bit smaller images in two columns; the laptop shows images in three
columns.">
<!-- kettlebell.jpg from https://pixabay.com/en/functional-mobility-articular-606568/ -->
<!-- narrow -->
<rect width="12" fill="white" stroke="black" x="6" y="24" height="6" rx="1"/>
<rect x="7" y="25" width="10" height="4.5" fill="#987b5a"/>
<image x="7" y="25" width="10" height="4.5" xlink:href="/images/kettlebell.jpg"
preserveAspectRatio="xMinYMin slice"/>
<text text-anchor="middle" x="12" y="21">Narrow, 1 column</text>
<!-- medium -->
<rect width="14" fill="white" stroke="black" x="32" y="10" height="20" rx="1"/>
<line stroke="black" stroke-width="1.1" x1="32" y1="29" x2="46" y2="29"/>
<rect x="33" y="11" width="5.5" height="5.5" fill="#987b5a"/>
<image x="33" y="11" width="5.5" height="5.5" xlink:href="/images/kettlebell.jpg"/>
<rect x="39.5" y="11" width="5.5" height="5.5" fill="burlywood"/>
<rect x="33" y="17.5" width="5.5" height="5.5" fill="silver"/>
<text text-anchor="middle" x="39" y="7">Medium, 2 columns</text>
<!-- wide -->
<rect width="40" fill="white" stroke="black" x="65" y="2" height="26" rx="2"
stroke-width="2"/>
<line y2="30" stroke-linecap="round" stroke="black" x1="61" x2="109" y1="30"
stroke-width="2"/>
<rect x="67" y="4" width="10" height="10" fill="#987b5a"/>
<image x="67" y="4" width="10" height="10" xlink:href="/images/kettlebell.jpg"/>
<rect x="80" y="4" width="10" height="10" fill="burlywood"/>
<rect x="93" y="4" width="10" height="10" fill="silver"/>
<text text-anchor="middle" x="85" y="25">Wide, 3 columns</text>
</svg>
</div>
</li>
<li>
<p>Authors might want to show different image content depending on the rendered size of the
image. This is usually referred to as <dfn>art direction</dfn>.</p>
<div class="example">
<p>When a web page is viewed on a screen with a large physical size (assuming a maximised
browser window), the author might wish to include some less relevant parts surrounding the
critical part of the image. When the same web page is viewed on a screen with a small physical
size, the author might wish to show only the critical part of the image.</p>
<svg viewBox="0 0 52 25.6" height="160" role="img" aria-label="The upright-held phone shows a
cropped image of a wolf; the rotated tablet shows the uncropped image.">
<!-- wolf.jpg from https://commons.wikimedia.org/wiki/File:WolfRunningInSnow.jpg -->
<!-- smartphone -->
<rect width="6" fill="white" stroke="black" x="6" y="8" height="12" rx="1"/>
<rect width="4" fill="#716966" x="7" y="9" height="6"/>
<image width="4" x="7" y="9" height="6" xlink:href="/images/wolf.jpg"
preserveAspectRatio="xMidYMid slice"/>
<!-- tablet -->
<rect width="20" fill="white" stroke="black" x="25" y="6" height="14" rx="1"/>
<line stroke="black" stroke-width="1.1" x1="26" y1="20" x2="26" y2="6"/>
<rect width="17" fill="#716966" x="27" y="7" height="8.5"/>
<image width="17" x="27" y="7" height="8.5" xlink:href="/images/wolf.jpg"/>
</svg>
</div>
</li>
<li>
<p>Authors might want to show the same image content but using different image formats,
depending on which image formats the user agent supports. This is usually referred to as
<dfn>image format-based selection</dfn>.</p>
<p class="example">A web page might have some images in the JPEG, WebP and JPEG XR image
formats, with the latter two having better compression abilities compared to JPEG. Since
different user agents can support different image formats, with some formats offering better
compression ratios, the author would like to serve the better formats to user agents that
support them, while providing JPEG fallback for user agents that don't.<!--TODO: refs?--></p>
</li>
</ul>
<p>The above situations are not mutually exclusive. For example, it is reasonable to combine
different resources for different <span>device-pixel-ratio</span> with different resources for
<span>art direction</span>.</p>
<p>While it is possible to solve these problems using scripting, doing so introduces some other
problems:</p>
<ul>
<li><p>Some user agents aggressively download images specified in the HTML markup, before scripts
have had a chance to run, so that web pages complete loading sooner. If a script changes which
image to download, the user agent will potentially start two separate downloads, which can
instead cause worse page loading performance.</p></li>
<li><p>If the author avoids specifying any image in the HTML markup and instead instantiates a
single download from script, that avoids the double download problem above but then no image will
be downloaded at all for users with scripting disabled and the aggressive image downloading
optimization will also be disabled.</p></li>
</ul>
<p>With this in mind, this specification introduces a number of features to address the above
problems in a declarative manner.</p>
<dl>
<dt><span>Device-pixel-ratio</span>-based selection when the rendered size of the image is
fixed</dt>
<dd>
<p>The <code data-x="attr-img-src">src</code> and <code data-x="attr-img-srcset">srcset</code>
attributes on the <code>img</code> element can be used, using the <code data-x="">x</code>
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).</p>
<p class="note">The <code data-x="">x</code> descriptor is not appropriate when the rendered
size of the image depends on the <span>viewport</span> width
(<span>viewport-based selection</span>), but can be used together with
<span>art direction</span>.</p>
<div class="example">
<pre><code class="html"><h2>From today's featured article</h2>
<img <strong>src="/uploads/100-marie-lloyd.jpg"</strong>
<strong>srcset="/uploads/150-marie-lloyd.jpg 1.5x, /uploads/200-marie-lloyd.jpg 2x"</strong>
alt="" width="100" height="150">
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
was an English <a href="/wiki/Music_hall">music hall</a> singer, ...</code></pre>
<p>The user agent can choose any of the given resources depending on the user's screen's pixel
density, zoom level, and possibly other factors such as the user's network conditions.</p>
<p>For backwards compatibility with older user agents that don't yet understand the <code
data-x="attr-img-srcset">srcset</code> attribute, one of the URLs is specified in the
<code>img</code> element's <code data-x="attr-img-src">src</code> attribute. This will result
in something useful (though perhaps lower-resolution than the user would like) being displayed
even in older user agents. For new user agents, the <code data-x="attr-img-src">src</code>
attribute participates in the resource selection, as if it was specified in <code
data-x="attr-img-srcset">srcset</code> with a <code data-x="">1x</code> descriptor.</p>
<p>The image's rendered size is given in the <code data-x="attr-dim-width">width</code> and
<code data-x="attr-dim-height">height</code> attributes, which allows the user agent to
allocate space for the image before it is downloaded.</p>
</div>
</dd>
<dt><span>Viewport-based selection</span></dt>
<dd>
<p>The <code data-x="attr-img-srcset">srcset</code> and <code
data-x="attr-img-sizes">sizes</code> attributes can be used, using the <code data-x="">w</code>
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).</p>
<div class="example">
<p>In this example, a banner image takes up the entire <span>viewport</span> width (using
appropriate CSS).</p>
<pre><code class="html"><h1><img <strong>sizes="100vw" srcset="wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"</strong>
src="wolf-400.jpg" alt="The rad wolf"></h1></code></pre>
<p>The user agent will calculate the effective pixel density of each image from the specified
<code data-x="">w</code> descriptors and the specified rendered size in the <code
data-x="attr-img-sizes">sizes</code> attribute. It can then choose any of the given resources
depending on the user's screen's pixel density, zoom level, and possibly other factors such as
the user's network conditions.</p>
<p>If the user's screen is 320 <span data-x="'px'">CSS pixels</span> wide, this is equivalent
to specifying <code data-x="">wolf-400.jpg 1.25x, wolf-800.jpg 2.5x, wolf-1600.jpg 5x</code>.
On the other hand, if the user's screen is 1200 <span data-x="'px'">CSS pixels</span> wide,
this is equivalent to specifying <code
data-x="">wolf-400.jpg 0.33x, wolf-800.jpg 0.67x, wolf-1600.jpg 1.33x</code>. By using the
<code data-x="">w</code> descriptors and the <code data-x="attr-img-sizes">sizes</code>
attribute, the user agent can choose the correct image source to download regardless of how
large the user's device is.</p>
<p>For backwards compatibility, one of the URLs is specified in the <code>img</code> element's
<code data-x="attr-img-src">src</code> attribute. In new user agents, the <code
data-x="attr-img-src">src</code> attribute is ignored when the <code
data-x="attr-img-srcset">srcset</code> attribute uses <code data-x="">w</code> descriptors.</p>
</div>
<div class="example">
<p>In this example, the web page has three layouts depending on the width of the
<span>viewport</span>. The narrow layout has one column of images (the width of each image is
about 100%), the middle layout has two columns of images (the width of each image is about
50%), and the widest layout has three columns of images, and some page margin (the width of
each image is about 33%). It breaks between these layouts when the <span>viewport</span> is
<code data-x="">30em</code> wide and <code data-x="">50em</code> wide, respectively.</p>
<pre><code class="html"><img <strong>sizes="(max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"</strong>
<strong>srcset="swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"</strong>
src="swing-400.jpg" alt="Kettlebell Swing"></code></pre>
<p>The <code data-x="attr-img-sizes">sizes</code> attribute sets up the layout breakpoints at
<code data-x="">30em</code> and <code data-x="">50em</code>, and declares the image sizes
between these breakpoints to be <code data-x="">100vw</code>, <code data-x="">50vw</code>, or
<code data-x="">calc(33vw - 100px)</code>. These sizes do not necessarily have to match up
exactly with the actual image width as specified in the CSS.</p>
<p>The user agent will pick a width from the <code data-x="attr-img-sizes">sizes</code>
attribute, using the first item with a <span><media-condition></span> (the part in
parentheses) that evaluates to true, or using the last item (<code data-x="">calc(33vw -
100px)</code>) if they all evaluate to false.</p>
<p>For example, if the <span>viewport</span> width is <code data-x="">29em</code>, then <code
data-x="">(max-width: 30em)</code> evaluates to true and <code data-x="">100vw</code> is used,
so the image size, for the purpose of resource selection, is <code data-x="">29em</code>. If
the <span>viewport</span> width is instead <code data-x="">32em</code>, then
<code data-x="">(max-width: 30em)</code> evaluates to false, but
<code data-x="">(max-width: 50em)</code> evaluates to true
and <code data-x="">50vw</code> is used, so the image size, for the purpose of resource
selection, is <code data-x="">16em</code> (half the <span>viewport</span> width). Notice that
the slightly wider <span>viewport</span> results in a smaller image because of the different
layout.</p>
<p>The user agent can then calculate the effective pixel density and choose an appropriate
resource similarly to the previous example.</p>
</div>
<div class="example">
<p>This example is the same as the previous example, but the image is <span
data-x="attr-loading-lazy-state">lazy-loaded</span>. In this case, the <code
data-x="attr-img-sizes">sizes</code> attribute can use the <code
data-x="valdef-sizes-auto">auto</code> keyword, and the user agent will use the <code
data-x="attr-dim-width">width</code> attribute (or the width specified in CSS) for the
<span>source size</span>.</p>
<pre><code class="html"><img <strong>loading="lazy" width="200" height="200" sizes="auto"</strong>
srcset="swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src="swing-400.jpg" alt="Kettlebell Swing"></code></pre>
<p>For better backwards-compatibility with legacy user agents that don't support the <code
data-x="valdef-sizes-auto">auto</code> keyword, fallback sizes can be specified if desired.</p>
<pre><code class="html"><img loading="lazy" width="200" height="200"
<strong>sizes="auto, (max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"</strong>
srcset="swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src="swing-400.jpg" alt="Kettlebell Swing"></code></pre>
</div>
</dd>
<dt><span>Art direction</span>-based selection</dt>
<dd>
<p>The <code>picture</code> element and the <code>source</code> element, together with the <code
data-x="attr-source-media">media</code> attribute, can be used to provide multiple images that
vary the image content (for instance the smaller image might be a cropped version of the bigger
image).</p>
<div class="example">
<pre><code class="html"><picture>
<source <strong>media="(min-width: 45em)"</strong> srcset="large.jpg">
<source <strong>media="(min-width: 32em)"</strong> srcset="med.jpg">
<img src="small.jpg" alt="The wolf runs through the snow.">
</picture></code></pre>
<p>The user agent will choose the first <code>source</code> element for which the media query
in the <code data-x="attr-source-media">media</code> attribute matches, and then choose an
appropriate URL from its <code data-x="attr-source-srcset">srcset</code> attribute.</p>
<p>The rendered size of the image varies depending on which resource is chosen. To specify
dimensions that the user agent can use before having downloaded the image, CSS can be used.</p>
<pre><code class="css">img { width: 300px; height: 300px }
@media (min-width: 32em) { img { width: 500px; height:300px } }
@media (min-width: 45em) { img { width: 700px; height:400px } }</code></pre>
</div>
<div class="example">
<p>This example combines <span>art direction</span>- and <span>device-pixel-ratio</span>-based
selection. A banner that takes half the <span>viewport</span> is provided in two versions,
one for wide screens and one for narrow screens.</p>
<pre><code class="html"><h1>
<picture>
<source media="(max-width: 500px)" srcset="banner-phone.jpeg, banner-phone-HD.jpeg 2x">
<img src="banner.jpeg" srcset="banner-HD.jpeg 2x" alt="The Breakfast Combo">
</picture>
</h1></code></pre>
</div>
</dd>
<dt><span>Image format-based selection</span></dt>
<dd>
<p>The <code data-x="attr-source-type">type</code> attribute on the <code>source</code> element
can be used to provide multiple images in different formats.</p>
<div class="example">
<pre><code class="html"><h2>From today's featured article</h2>
<picture>
<source srcset="/uploads/100-marie-lloyd.webp" <strong>type="image/webp"</strong>>
<source srcset="/uploads/100-marie-lloyd.jxr" <strong>type="image/vnd.ms-photo"</strong>>
<img src="/uploads/100-marie-lloyd.jpg" alt="" width="100" height="150">
</picture>
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
was an English <a href="/wiki/Music_hall">music hall</a> singer, ...</code></pre>
<p>In this example, the user agent will choose the first source that has a <code
data-x="attr-source-type">type</code> attribute with a supported MIME type. If the user agent
supports WebP images, the first <code>source</code> element will be chosen. If not, but the
user agent does support JPEG XR images, the second <code>source</code> element will be chosen.
If neither of those formats are supported, the <code>img</code> element will be chosen.</p>
</div>
</dd>
</dl>
<h6>Adaptive images</h6>
<!-- NON-NORMATIVE SECTION -->
<p>CSS and media queries can be used to construct graphical page layouts that adapt dynamically to
the user's environment, in particular to different <span>viewport</span> dimensions and pixel
densities. For content, however, CSS does not help; instead, we have the <code>img</code> element's
<code data-x="attr-img-srcset">srcset</code> attribute and the <code>picture</code> element.
This section walks through a sample case showing how to use these features.</p>
<p>Consider a situation where on wide screens (wider than 600 <span data-x="'px'">CSS
pixels</span>) a 300×150 image named <code data-x="">a-rectangle.png</code> is to be used,
but on smaller screens (600 <span data-x="'px'">CSS pixels</span> and less), a smaller
100×100 image called <code data-x="">a-square.png</code> is to be used. The markup for this
would look like this:</p>
<pre><code class="html"><figure>
<picture>
<source srcset="a-square.png" media="(max-width: 600px)">
<img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses.">
</picture>
<figcaption>Barney Frank, 2011</figcaption>
</figure></code></pre>
<p class="note">For details on what to put in the <code data-x="attr-img-alt">alt</code>
attribute, see the <a href="#alt">Requirements for providing text to act as an alternative for
images</a> section.</p>
<p>The problem with this is that the user agent does not necessarily know what dimensions to use
for the image when the image is loading. To avoid the layout having to be reflowed multiple times
as the page is loading, CSS and CSS media queries can be used to provide the dimensions:</p>
<pre><code class="html"><style>
#a { width: 300px; height: 150px; }
@media (max-width: 600px) { #a { width: 100px; height: 100px; } }
</style>
<figure>
<picture>
<source srcset="a-square.png" media="(max-width: 600px)">
<img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses." id="a">
</picture>
<figcaption>Barney Frank, 2011</figcaption>
</figure></code></pre>
<p>Alternatively, the <code data-x="attr-dim-width">width</code> and <code
data-x="attr-dim-height">height</code> attributes can be used to provide the width and height for
legacy user agents, using CSS just for the user agents that support <code>picture</code>:</p>
<pre><code class="html"><style media="(max-width: 600px)">
#a { width: 100px; height: 100px; }
</style>
<figure>
<picture>
<source srcset="a-square.png" media="(max-width: 600px)">
<img src="a-rectangle.png" width="300" height="150"
alt="Barney Frank wears a suit and glasses." id="a">
</picture>
<figcaption>Barney Frank, 2011</figcaption>
</figure></code></pre>
<hr>
<p>The <code>img</code> element is used with the <code data-x="attr-img-src">src</code> attribute,
which gives the URL of the image to use for legacy user agents that do not support the
<code>picture</code> element. This leads to a question of which image to provide in the <code
data-x="attr-img-src">src</code> attribute.</p>
<p>If the author wants the biggest image in legacy user agents, the markup could be as
follows:</p>
<pre><code class="html"><picture>
<source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
<source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
<img src="pear-desktop.jpeg" alt="The pear is juicy.">
</picture></code></pre>
<p>However, if legacy mobile user agents are more important, one can list all three images in the
<code>source</code> elements, overriding the <code data-x="attr-img-src">src</code> attribute
entirely.</p>
<pre><code class="html"><picture>
<source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
<source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
<source srcset="pear-desktop.jpeg">
<img src="pear-mobile.jpeg" alt="The pear is juicy.">
</picture></code></pre>
<p>Since at this point the <code data-x="attr-img-src">src</code> attribute is actually being
ignored entirely by <code>picture</code>-supporting user agents, the <code
data-x="attr-img-src">src</code> attribute can default to any image, including one that is neither
the smallest nor biggest:</p>
<pre><code class="html"><picture>
<source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
<source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
<source srcset="pear-desktop.jpeg">
<img src="pear-tablet.jpeg" alt="The pear is juicy.">
</picture></code></pre>
<hr>
<p>Above the <code data-x="">max-width</code> media feature is used, giving the maximum
(<span>viewport</span>) dimensions that an image is intended for. It is also possible to use <code
data-x="">min-width</code> instead.</p>
<pre><code class="html"><picture>
<source srcset="pear-desktop.jpeg" media="(min-width: 1281px)">
<source srcset="pear-tablet.jpeg" media="(min-width: 721px)">
<img src="pear-mobile.jpeg" alt="The pear is juicy.">
</picture></code></pre>
<h5 id="attributes-common-to-source-and-img-elements">Attributes common to <code>source</code>,
<code>img</code>, and <code>link</code> elements</h5>
<h6>Srcset attributes</h6>
<p>A <dfn>srcset attribute</dfn> is an attribute with requirements defined in this section.</p>
<p>If present, its value must consist of one or more <span data-x="image candidate string">image
candidate strings</span>, each separated from the next by a U+002C COMMA character (,). If an
<span>image candidate string</span> contains no descriptors and no <span>ASCII whitespace</span>
after the URL, the following <span>image candidate string</span>, if there is one, must begin with
one or more <span>ASCII whitespace</span>.</p>
<p>An <dfn>image candidate string</dfn> consists of the following components, in order, with the
further restrictions described below this list:</p>
<ol>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
<li><p>A <span>valid non-empty URL</span> that does not start or end with a U+002C COMMA
character (,), referencing a non-interactive, optionally animated, image resource that is neither
paged nor scripted.</p></li>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
<li>
<p>Zero or one of the following:</p>
<ul>
<li><p>A <dfn>width descriptor</dfn>, consisting of: <span>ASCII whitespace</span>, a
<span>valid non-negative integer</span> giving a number greater than zero representing the
<dfn>width descriptor value</dfn>, and a U+0077 LATIN SMALL LETTER W character.</p></li>
<li><p>A <dfn>pixel density descriptor</dfn>, consisting of: <span>ASCII whitespace</span>, a
<span>valid floating-point number</span> giving a number greater than zero representing the
<dfn>pixel density descriptor value</dfn>, and a U+0078 LATIN SMALL LETTER X
character.</p></li>
</ul>
</li>
<li><p>Zero or more <span>ASCII whitespace</span>.</p></li>
</ol>
<p>There must not be an <span>image candidate string</span> for an element that has the same
<span>width descriptor value</span> as another <span>image candidate string</span>'s <span>width
descriptor value</span> for the same element.</p>
<p>There must not be an <span>image candidate string</span> for an element that has the same
<span>pixel density descriptor value</span> as another <span>image candidate string</span>'s
<span>pixel density descriptor value</span> for the same element. For the purpose of this
requirement, an <span>image candidate string</span> with no descriptors is equivalent to an
<span>image candidate string</span> with a <code data-x="">1x</code> descriptor.</p>
<p>If an <span>image candidate string</span> for an element has the <span>width descriptor</span>
specified, all other <span data-x="image candidate string">image candidate strings</span> for that
element must also have the <span>width descriptor</span> specified.</p>
<p>The specified width in an <span>image candidate string</span>'s <span>width descriptor</span>
must match the <span>natural width</span> in the resource given by the
<span>image candidate string</span>'s URL, if it has a <span>natural width</span>.</p>
<p>If an element has a <span>sizes attribute</span> present, all <span data-x="image
candidate string">image candidate strings</span> for that element must have the <span>width
descriptor</span> specified.</p>
<h6>Sizes attributes</h6>
<p>A <dfn>sizes attribute</dfn> is an attribute with requirements defined in this section.</p>
<p>If present, the value must be a <span>valid source size list</span>.</p>
<p>A <dfn>valid source size list</dfn> is a string that matches the following grammar:
<ref>CSSVALUES</ref> <ref>MQ</ref></p>
<pre><code class="html"><dfn type><source-size-list></dfn> = <span><source-size></span>#? , <span><source-size-value></span>
<dfn type><source-size></dfn> = <span><media-condition></span> <span><source-size-value></span> | <span data-x="valdef-sizes-auto">auto</span>
<dfn type><source-size-value></dfn> = <span><length></span> | <span data-x="valdef-sizes-auto">auto</span></code></pre>
<p>A <span><source-size-value></span> that is a <span><length></span> must not be negative,
and must not use CSS functions other than the <span>math functions</span>.</p>
<p>The keyword <dfn><code data-x="valdef-sizes-auto">auto</code></dfn> is a width that is
computed in <span>parse a sizes attribute</span>. If present, it must be the first entry and the
entire <span><source-size-list></span> value must either be the string "<code
data-x="">auto</code>" (<span>ASCII case-insensitive</span>) or start with the string "<code
data-x="">auto,</code>" (<span>ASCII case-insensitive</span>).</p>
<p class="note">If the <code>img</code> element that initiated the image loading (with the
<span>update the image data</span> or <span data-x="img-environment-changes">react to environment
changes</span> algorithms) <span>allows auto-sizes</span> and is <span>being rendered</span>,
then <code data-x="valdef-sizes-auto">auto</code> is the <span>concrete object size</span> width.
Otherwise, the <code data-x="valdef-sizes-auto">auto</code> value is ignored and the next
<span>source size</span> is used instead, if any.</p>
<p>The <code data-x="valdef-sizes-auto">auto</code> keyword may be specified in the <code
data-x="attr-source-sizes">sizes</code> attribute of <code>source</code> elements and <code
data-x="attr-img-sizes">sizes</code> attribute of <code>img</code> elements, if the following
conditions are met. Otherwise, <code data-x="valdef-sizes-auto">auto</code> must not be
specified.</p>
<ul>
<li><p>The element is a <code>source</code> element with a following sibling
<code>img</code> element.</p></li>
<li><p>The element is an <code>img</code> element.</p></li>
<li><p>The <code>img</code> element referenced in either condition above <span>allows
auto-sizes</span>.</p></li>
</ul>
<p class="note">In addition, it is strongly encouraged to specify dimensions using the <code
data-x="attr-dim-width">width</code> and <code data-x="attr-dim-height">height</code> attributes
or with CSS. Without specified dimensions, the image will likely render with 300x150 dimensions
because <code data-x="">sizes="auto"</code> implies <code data-x="">contain-intrinsic-size: 300px
150px</code> in <a href="#img-contain-size">the Rendering section</a>.</p>
<p>The <span><source-size-value></span> gives the intended layout width of the image. The
author can specify different widths for different environments with
<span><media-condition></span>s.</p>
<p class="note">Percentages are not allowed in a <span><source-size-value></span>,
to avoid confusion about what it would be relative to.
The <span>'vw'</span> unit can be used for sizes relative to the <span>viewport</span>
width.</p>
<div w-nodev>
<h5 id="images-processing-model">Processing model</h5>
<hr>
<p>An <code>img</code> element has a <dfn>current request</dfn> and a <dfn>pending request</dfn>.
The <span>current request</span> is initially set to a new <span>image request</span>.
The <span>pending request</span> is initially set to null.</p>
<p>An <dfn export>image request</dfn> has a <dfn export for="image request"
data-x="img-req-state">state</dfn>, <dfn export for="image request"
data-x="img-req-url">current URL</dfn>, and <dfn export for="image request"
data-x="img-req-data">image data</dfn>.</p>
<p>An <span>image request</span>'s <span data-x="img-req-state">state</span> is one of the
following:</p>
<dl>
<dt><dfn data-x="img-none">Unavailable</dfn></dt>
<dd>The user agent hasn't obtained any image data,
or has obtained some or all of the image data but
hasn't yet decoded enough of the image to get the image dimensions.</dd>
<dt><dfn data-x="img-inc">Partially available</dfn></dt>
<dd>The user agent has obtained some of the image data and at least the image dimensions are
available.</dd>
<dt><dfn data-x="img-all">Completely available</dfn></dt>
<dd>The user agent has obtained all of the image data and at least the image dimensions are
available.</dd>
<dt><dfn data-x="img-error">Broken</dfn></dt>
<dd>The user agent has obtained all of the image data that it can, but it cannot even decode the
image enough to get the image dimensions (e.g. the image is corrupted, or the format is not
supported, or no data could be obtained).</dd>
</dl>
<p>An <span>image request</span>'s <span data-x="img-req-url">current URL</span> is initially the
empty string.</p>
<p>An <span>image request</span>'s <span data-x="img-req-data">image data</span> is the decoded
image data.</p>
<p>When an <span>image request</span>'s <span data-x="img-req-state">state</span> is either <span
data-x="img-inc">partially available</span> or <span data-x="img-all">completely available</span>,
the <span>image request</span> is said to be <dfn data-x="img-available">available</dfn>.</p>
<p>When an <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-all">completely available</span> and the
user agent can decode the media data without errors, then the <code>img</code> element is said to
be <dfn data-x="img-good">fully decodable</dfn>.</p>
<p>An <span>image request</span>'s <span data-x="img-req-state">state</span> is initially <span
data-x="img-none">unavailable</span>.</p>
<p>When an <code>img</code> element's <span>current request</span> is <span
data-x="img-available">available</span>, the <code>img</code> element provides a <span>paint
source</span> whose width is the image's <span data-x="density-corrected natural width and
height">density-corrected natural width</span> (if any), whose height is the image's <span
data-x="density-corrected natural width and height">density-corrected natural height</span>
(if any), and whose appearance is the natural appearance of the image.</p>
<hr>
<p>An <code>img</code> element is said to <dfn>use <code>srcset</code> or
<code>picture</code></dfn> if it has a <code data-x="attr-img-srcset">srcset</code> attribute
specified or if it has a parent that is a <code>picture</code> element.</p>
<hr>
<p>Each <code>img</code> element has a <dfn>last selected source</dfn>, which must initially be
null.</p>
<p>Each <span>image request</span> has a <dfn>current pixel density</dfn>, which must initially be
1.</p>
<p>Each <span>image request</span> has <dfn>preferred density-corrected dimensions</dfn>, which is
either a struct consisting of a width and a height or is null. It must initially be null.</p>
<p>To determine the <dfn id="density-corrected-intrinsic-width-and-height">density-corrected
natural width and height</dfn> of an <code>img</code> element <var>img</var>:</p>
<ol>
<li>
<p>Let <var>dim</var> be <var>img</var>'s <span>current request</span>'s <span>preferred
density-corrected dimensions</span>.</p>
<p class="note">The <span>preferred density-corrected dimensions</span> are set in the
<span>prepare an image for presentation</span> algorithm based on meta information in the
image.</p>
</li>
<li><p>If <var>dim</var> is null, set <var>dim</var> to <var>img</var>'s <span>natural
dimensions</span>.</p></li>
<li><p>Set <var>dim</var>'s width to <var>dim</var>'s width divided by <var>img</var>'s
<span>current request</span>'s <span>current pixel density</span>.</p></li>
<li><p>Set <var>dim</var>'s height to <var>dim</var>'s height divided by <var>img</var>'s
<span>current request</span>'s <span>current pixel density</span>.</p></li>
<li><p>Return <var>dim</var>.</p></li>
</ol>
<p class="example">For example, if the <span>current pixel density</span> is 3.125, that means
that there are 300 device pixels per <span data-x="'in'">CSS inch</span>, and thus if the image
data is 300x600, it has <span>density-corrected natural width and height</span> of 96 <span
data-x="'px'">CSS pixels</span> by 192 <span data-x="'px'">CSS pixels</span>.</p>
<p>All <code>img</code> and <code>link</code> elements are associated with a <span>source set</span>.</p>
<p>A <dfn>source set</dfn> is an ordered set of zero or more <span data-x="image source">image sources</span>
and a <span>source size</span>.</p>
<p>An <dfn>image source</dfn> is a <span>URL</span>, and optionally either a <span>pixel density
descriptor</span>, or a <span>width descriptor</span>.</p>
<p>A <dfn>source size</dfn> is a <span><source-size-value></span>.
When a <span>source size</span> has a unit relative to the <span>viewport</span>,
it must be interpreted relative to the <code>img</code> element's <span>node document</span>'s
<span>viewport</span>. Other units must be interpreted the same as in Media Queries.
<ref>MQ</ref></p>
<hr>
<p>A <dfn data-x="concept-microsyntax-parse-error">parse error</dfn> for algorithms in this
section indicates a non-fatal mismatch between input and requirements. User agents are encouraged
to expose <span data-x="concept-microsyntax-parse-error">parse error</span>s somehow.</p>
<hr>
<p>Whether the image is fetched successfully or not (e.g. whether the response status was an
<span>ok status</span>) must be ignored when determining the image's type and whether it is a
valid image.</p>
<p class="note">This allows servers to return images with error responses, and have them
displayed.</p>
<p id="img-determine-type">The user agent should apply the <span data-x="Content-Type sniffing:
image">image sniffing rules</span> to determine the type of the image, with the image's <span
data-x="Content-Type">associated Content-Type headers</span> giving the <var>official
type</var>. If these rules are not applied, then the type of the image must be the type given by
the image's <span data-x="Content-Type">associated Content-Type headers</span>.</p>
<p>User agents must not support non-image resources with the <code>img</code> element (e.g. XML
files whose <span>document element</span> is an HTML element). User agents must not run executable
code (e.g. scripts) embedded in the image resource. User agents must only display the first page
of a multipage resource (e.g. a PDF file). User agents must not allow the resource to act in an
interactive fashion, but should honour any animation in the resource.</p>
<p>This specification does not specify which image types are to be supported.</p>
<h6>When to obtain images</h6>
<p>By default, images are obtained immediately. User agents may provide users with the option to
instead obtain them on-demand. (The on-demand option might be used by bandwidth-constrained users,
for example.)</p>
<p>When obtaining images immediately, the user agent must synchronously <span>update the image
data</span> of the <code>img</code> element, with the <i>restart animation</i> flag set if so
stated, whenever that element is created or has experienced <span>relevant mutations</span>.</p>
<p>When obtaining images on demand, the user agent must <span>update the image data</span> of an
<code>img</code> element whenever it needs the image data (i.e., on demand), but only if the
<code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-none">unavailable</span>. When an
<code>img</code> element has experienced <span>relevant mutations</span>, if the user agent only
obtains images on demand, the <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> must return to <span data-x="img-none">unavailable</span>.</p>
<h6>Reacting to DOM mutations</h6>
<p>The <dfn>relevant mutations</dfn> for an <code>img</code> element are as follows:</p>
<ul>
<li><p>The element's <code data-x="attr-img-src">src</code>, <code
data-x="attr-img-srcset">srcset</code>, <code data-x="attr-dim-width">width</code>, or <code
data-x="attr-img-sizes">sizes</code> attributes are set, changed, or removed.</p></li>
<li><p>The element's <code data-x="attr-img-src">src</code> attribute is set to the same value as the previous value.
This must set the <i>restart animation</i> flag for the <span>update the image data</span> algorithm.</p></li>
<li><p>The element's <code data-x="attr-img-crossorigin">crossorigin</code> attribute's state is changed.</p></li>
<li><p>The element's <code data-x="attr-img-referrerpolicy">referrerpolicy</code> attribute's
state is changed.</p></li>
<li><p>The <code>img</code> or <code>source</code> <span>HTML element insertion steps</span>,
<span>HTML element removing steps</span>, and <span>HTML element moving steps</span> count the
mutation as a <span data-x="relevant mutations">relevant mutation</span>.</p></li>
<li><p>The element's parent is a <code>picture</code> element and a <code>source</code> element
that is a previous sibling has its <code data-x="attr-source-srcset">srcset</code>, <code
data-x="attr-source-sizes">sizes</code>, <code data-x="attr-source-media">media</code>, <code
data-x="attr-source-type">type</code>, <code data-x="attr-dim-width">width</code> or <code
data-x="attr-dim-height">height</code> attributes set, changed, or removed.</p></li>
<li><p>The element's <span data-x="concept-node-adopt-ext">adopting steps</span> are run.</p></li>
<li><p>If the element <span>allows auto-sizes</span>: the element starts or stops <span>being
rendered</span>, or its <span>concrete object size</span> width changes. This must set the
<i>maybe omit events</i> flag for the <span>update the image data</span> algorithm.</p></li>
<!-- NOT when the base URL changes (except for when adopted into a new doc) -->
</ul>
<h6>The list of available images</h6>
<p>Each <code>Document</code> object must have a <dfn>list of available images</dfn>. Each image
in this list is identified by a tuple consisting of an <span>absolute URL</span>, a <span>CORS
settings attribute</span> mode, and, if the mode is not <span data-x="attr-crossorigin-none">No
CORS</span>, an <span>origin</span>.
Each image furthermore has an <dfn>ignore higher-layer caching</dfn> flag.
User agents may copy entries from one <code>Document</code>
object's <span>list of available images</span> to another at any time (e.g. when the
<code>Document</code> is created, user agents can add to it all the images that are loaded in
other <code>Document</code>s), but must not change the keys of entries copied in this way when
doing so, and must unset the <span>ignore higher-layer caching</span> flag for the copied entry.
User agents may also remove images from such lists at any time (e.g. to save
memory).
User agents must remove entries in the <span>list of available images</span> as appropriate
given higher-layer caching semantics for the resource (e.g. the HTTP `<code
data-x="http-cache-control">Cache-Control</code>` response header) when the <span>ignore
higher-layer caching</span> flag is unset.</p>
<p class="note">The <span>list of available images</span> is intended to enable synchronous
switching when changing the <code data-x="attr-img-src">src</code> attribute to a URL that has
previously been loaded, and to avoid re-downloading images in the same document even when they
don't allow caching per HTTP. It is not used to avoid re-downloading the same image while the
previous image is still loading.</p>
<p class="note">The user agent can also store the image data separately from the <span>list of available images</span>.</p>
<p class="example">For example, if a resource has the HTTP response header
`<code data-x="">Cache-Control: must-revalidate</code>`, and its <span>ignore higher-layer
caching</span> flag is unset, the user agent would remove it from the <span>list of available
images</span> but could keep the image data separately, and use that if the server responds with a
<code data-x="">304 Not Modified</code> status.</p>
<h6>Decoding images</h6>
<p>Image data is usually encoded in order to reduce file size. This means that in order for the
user agent to present the image to the screen, the data needs to be decoded.
<dfn data-x="img-decoding-process">Decoding</dfn> is the process which converts an image's media
data into a bitmap form, suitable for presentation to the screen. Note that this process can be
slow relative to other processes involved in presenting content. Thus, the user agent can choose
when to perform decoding, in order to create the best user experience.</p>
<p>Image decoding is said to be synchronous if it prevents presentation of other content until it
is finished. Typically, this has an effect of atomically presenting the image and any other
content at the same time. However, this presentation is delayed by the amount of time it takes to
perform the decode.</p>
<p>Image decoding is said to be asynchronous if it does not prevent presentation of other content.
This has an effect of presenting non-image content faster. However, the image content is missing
on screen until the decode finishes. Once the decode is finished, the screen is updated with the
image.</p>
<p>In both synchronous and asynchronous decoding modes, the final content is presented to screen
after the same amount of time has elapsed. The main difference is whether the user agent presents
non-image content ahead of presenting the final content.</p>
<p>In order to aid the user agent in deciding whether to perform synchronous or asynchronous
decode, the <code data-x="attr-img-decoding">decoding</code> attribute can be set on
<code>img</code> elements. The possible values of the <code
data-x="attr-img-decoding">decoding</code> attribute are the following <dfn>image decoding
hint</dfn> keywords:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Description
<tbody>
<tr>
<td><dfn attr-value for="img/decoding"><code data-x="attr-img-decoding-sync">sync</code></dfn>
<td><dfn data-x="attr-img-decoding-sync-state">Sync</dfn>
<td>Indicates a preference to <span data-x="img-decoding-process">decode</span> this image
synchronously for atomic presentation with other content.
<tr>
<td><dfn attr-value for="img/decoding"><code
data-x="attr-img-decoding-async">async</code></dfn>
<td><dfn data-x="attr-img-decoding-async-state">Async</dfn>
<td>Indicates a preference to <span data-x="img-decoding-process">decode</span> this image
asynchronously to avoid delaying presentation of other content.
<tr>
<td><dfn attr-value for="img/decoding"><code data-x="attr-img-decoding-auto">auto</code></dfn>
<td><dfn data-x="attr-img-decoding-auto-state">Auto</dfn>
<td>Indicates no preference in decoding mode (the default).
</table>
<p>When <span data-x="img-decoding-process">decoding</span> an image, the user agent should
respect the preference indicated by the <code data-x="attr-img-decoding">decoding</code>
attribute's state. If the state indicated is <span
data-x="attr-img-decoding-auto-state">auto</span>, then the user agent is free to choose any
decoding behavior.</p>
<p class="note">It is also possible to control the decoding behavior using the <code
data-x="dom-img-decode">decode()</code> method. Since the <code
data-x="dom-img-decode">decode()</code> method performs <span
data-x="img-decoding-process">decoding</span> independently from the process responsible for
presenting content to screen, it is unaffected by the <code
data-x="attr-img-decoding">decoding</code> attribute.</p>
<h6>Updating the image data</h6>
<p class="note">This algorithm cannot be called from steps running <span>in parallel</span>. If
a user agent needs to call this algorithm from steps running <span>in parallel</span>, it needs to
<span data-x="queue a task">queue</span> a task to do so.</p>
<p>When the user agent is to <dfn>update the image data</dfn> of an <code>img</code> element,
optionally with the <i>restart animations</i> flag set, optionally with the <i>maybe omit
events</i> flag set, it must run the following steps:</p>
<ol>
<li>
<p>If the element's <span>node document</span> is not <span>fully active</span>, then:</p>
<ol>
<li><p>Continue running this algorithm <span>in parallel</span>.</p></li>
<li><p>Wait until the element's <span>node document</span> is <span>fully
active</span>.</p></li>
<li><p>If another instance of this algorithm for this <code>img</code> element was started after this instance
(even if it aborted and is no longer running), then return.</p></li>
<li><p><span>Queue a microtask</span> to continue this algorithm.</p></li>
</ol>
</li>
<li><p>If the user agent cannot support images, or its support for images has been disabled, then
<span>abort the image request</span> for the <span>current request</span> and the <span>pending
request</span>, set <span>current request</span>'s <span data-x="img-req-state">state</span> to
<span data-x="img-none">unavailable</span>, set <span>pending request</span> to null, and
return.</p></li>
<li><p>Let <var>previousURL</var> be the <span>current request</span>'s <span
data-x="img-req-url">current URL</span>.</p></li>
<li><p>Let <var>selected source</var> be null and <var>selected pixel density</var> be undefined.
<li><p>If the element does not <span>use <code>srcset</code> or <code>picture</code></span> and
it has a <code data-x="attr-img-src">src</code> attribute specified whose value is not the empty
string, then set <var>selected source</var> to the value of the element's <code
data-x="attr-img-src">src</code> attribute and set <var>selected pixel density</var> to
1.0.</p></li>
<li><p>Set the element's <span>last selected source</span> to <var>selected
source</var>.</p></li>
<li>
<p>If <var>selected source</var> is not null, then:</p>
<ol>
<li><p>Let <var>urlString</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given <var>selected source</var>, relative to the element's <span>node
document</span>.</p></li>
<!-- This does not change currentSrc -->
<li><p>If <var>urlString</var> is failure, then abort this inner set of steps.</p></li>
<li><p>Let <var>key</var> be a tuple consisting of <var>urlString</var>, the <code>img</code>
element's <code data-x="attr-img-crossorigin">crossorigin</code> attribute's mode, and, if that
mode is not <span data-x="attr-crossorigin-none">No CORS</span>, the <span>node
document</span>'s <span data-x="concept-document-origin">origin</span>.</p></li>
<li>
<p>If the <span>list of available images</span> contains an entry for <var>key</var>,
then:</p>
<ol>
<li><p>Set the <span>ignore higher-layer caching</span> flag for that entry.</p></li>
<li><p><span>Abort the image request</span> for the <span>current request</span> and the
<span>pending request</span>.</p></li>
<li><p>Set <span>pending request</span> to null.</p></li>
<li><p>Let <span>current request</span> be a new <span>image request</span> whose <span
data-x="img-req-data">image data</span> is that of the entry and whose <span
data-x="img-req-state">state</span> is <span data-x="img-all">completely
available</span>.</p></li>
<li><p><span data-x="prepare an image for presentation">Prepare <span>current request</span>
for presentation</span> given the <code>img</code> element.</p></li>
<li><p>Set <span>current request</span>'s <span>current pixel density</span> to <var>selected
pixel density</var>.</p></li>
<li>
<p><span>Queue an element task</span> on the <span>DOM manipulation task source</span>
given the <code>img</code> element and the following steps:</p>
<ol>
<li><p>If <i>restart animation</i> is set, then <span>restart the
animation</span>.</p></li>
<li><p>Set <span>current request</span>'s <span data-x="img-req-url">current URL</span> to
<var>urlString</var>.</p></li>
<li><p>If <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>urlString</var>, then <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-load">load</code> at the <code>img</code> element.</p></li>
</ol>
</li>
<li><p>Abort the <span>update the image data</span> algorithm.</p></li>
</ol>
</li>
</ol>
</li>
<li><p><span>Queue a microtask</span> to perform the rest of this algorithm, allowing the <span
data-x="concept-task">task</span> that invoked this algorithm to continue.</p></li>
<li>
<p>If another instance of this algorithm for this <code>img</code> element was started after
this instance (even if it aborted and is no longer running), then return.</p>
<p class="note">Only the last instance takes effect, to avoid multiple requests when, for
example, the <code data-x="attr-img-src">src</code>, <code data-x="attr-img-srcset">srcset</code>,
and <code data-x="attr-img-crossorigin">crossorigin</code> attributes are all set in
succession.</p>
</li>
<li><p>Let <var>selected source</var> and <var>selected pixel density</var> be the URL and pixel
density that results from <span data-x="select an image source">selecting an image source</span>,
respectively.</p></li>
<li>
<p>If <var>selected source</var> is null, then:</p>
<ol>
<li><p>Set the <span>current request</span>'s <span data-x="img-req-state">state</span> to
<span data-x="img-error">broken</span>, <span>abort the image request</span> for the
<span>current request</span> and the <span>pending request</span>, and set <span>pending
request</span> to null.</p></li>
<li>
<p><span>Queue an element task</span> on the <span>DOM manipulation task source</span> given
the <code>img</code> element and the following steps:</p>
<ol>
<li><p>Change the <span>current request</span>'s <span data-x="img-req-url">current
URL</span> to the empty string.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p>the element has a <code data-x="attr-img-src">src</code> attribute or it <span
data-x="use srcset or picture">uses <code>srcset</code> or
<code>picture</code></span>; and</p></li>
<li><p><i>maybe omit events</i> is not set or <var>previousURL</var> is not the empty
string,</p></li>
</ul>
<p>then <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at the <code>img</code> element.</p>
</li>
</ol>
</li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>urlString</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given <var>selected source</var>, relative to the element's <span>node
document</span>.</p></li>
<li>
<p>If <var>urlString</var> is failure, then:</p>
<ol>
<li><p><span>Abort the image request</span> for the <span>current request</span> and the
<span>pending request</span>.</p></li>
<li><p>Set the <span>current request</span>'s <span data-x="img-req-state">state</span> to
<span data-x="img-error">broken</span>.</p></li>
<li><p>Set <span>pending request</span> to null.</p></li>
<li>
<p><span>Queue an element task</span> on the <span>DOM manipulation task
source</span> given the <code>img</code> element and the following steps:</p>
<ol>
<li><p>Change the <span>current request</span>'s <span data-x="img-req-url">current
URL</span> to <var>selected source</var>.</p></li>
<li><p>If <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>selected source</var>, then <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-error">error</code> at the <code>img</code> element.</p></li>
</ol>
</li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>If the <span>pending request</span> is not null and <var>urlString</var> is the same as
the <span>pending request</span>'s <span data-x="img-req-url">current URL</span>, then
return.</p></li>
<li><p>If <var>urlString</var> is the same as the <span>current request</span>'s <span
data-x="img-req-url">current URL</span> and <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-inc">partially available</span>, then
<span>abort the image request</span> for the <span>pending request</span>, <span>queue an element
task</span> on the <span>DOM manipulation task source</span> given the <code>img</code> element
to <span>restart the animation</span> if <i>restart animation</i> is set, and return.</p></li>
<li><p><span>Abort the image request</span> for the <span>pending request</span>.</p></li>
<li><p>Set <var>image request</var> to a new <span>image request</span> whose <span
data-x="img-req-url">current URL</span> is <var>urlString</var>.</p></li>
<li><p>If <span>current request</span>'s <span data-x="img-req-state">state</span> is <span
data-x="img-none">unavailable</span> or <span data-x="img-error">broken</span>, then set the
<span>current request</span> to <var>image request</var>. Otherwise, set the <span>pending
request</span> to <var>image request</var>.</p></li>
<li><p>Let <var>request</var> be the result of <span data-x="create a potential-CORS
request">creating a potential-CORS request</span> given <var>urlString</var>, "<code
data-x="">image</code>", and the current state of the element's <code
data-x="attr-img-crossorigin">crossorigin</code> content attribute.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to the
element's <span>node document</span>'s <span>relevant settings object</span>.</p></li>
<li><p>If the element <span data-x="use srcset or picture">uses <code>srcset</code> or
<code>picture</code></span>, set <var>request</var>'s <span
data-x="concept-request-initiator">initiator</span> to "<code
data-x="">imageset</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-referrer-policy">referrer
policy</span> to the current state of the element's <code
data-x="attr-img-referrerpolicy">referrerpolicy</code> attribute.</p></li>
<li><p>Set <var>request</var>'s <span
data-x="concept-request-priority">priority</span> to the current state of the
element's <code data-x="attr-img-fetchpriority">fetchpriority</code> attribute.</p></li>
<li><p>Let <var>delay load event</var> be true if the <code>img</code>'s <span>lazy loading
attribute</span> is in the <span data-x="attr-loading-eager-state">Eager</span> state, or if
<span data-x="concept-n-noscript">scripting is disabled</span> for the <code>img</code>, and
false otherwise.</p></li>
<li>
<p>If the <span>will lazy load element steps</span> given the <code>img</code> return true,
then:</p>
<ol>
<li><p>Set the <code>img</code>'s <span>lazy load resumption steps</span> to the rest of this
algorithm starting with the step labeled <i>fetch the image</i>.</p></li>
<li><p><span>Start intersection-observing a lazy loading element</span> for the
<code>img</code> element.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<!--FETCH-->
<p><i>Fetch the image</i>: <span data-x="concept-fetch">Fetch</span> <var>request</var>. Return
from this algorithm, and run the remaining steps as part of the fetch's <i
data-x="processResponse">processResponse</i> for the <span
data-x="concept-response">response</span> <var>response</var>.</p>
<!-- TODO "Interaction with the Preload Scanner" from the picture spec -->
<p>The resource obtained in this fashion, if any, is <var>image request</var>'s <span
data-x="img-req-data">image data</span>. It can be either <span>CORS-same-origin</span> or
<span>CORS-cross-origin</span>; this affects the image's interaction with other APIs (e.g.,
when used on a <code>canvas</code>).</p>
<!-- same text in <input type=image> section and similar text elsewhere -->
<p>When <var>delay load event</var> is true, fetching the image must <span>delay the load
event</span> of the element's <span>node document</span> until the <span
data-x="concept-task">task</span> that is <span data-x="queue a task">queued</span> by the
<span>networking task source</span> once the resource has been fetched (<a
href="#img-load">defined below</a>) has been run.
<!--TODO or the fetch was aborted, presumably --></p>
<p class="warning">This, unfortunately, can be used to perform a rudimentary port scan of the
user's local network (especially in conjunction with scripting, though scripting isn't actually
necessary to carry out such an attack). User agents may implement <span
data-x="origin">cross-origin</span> access control policies that are stricter than those
described above to mitigate this attack, but unfortunately such policies are typically not
compatible with existing web content.</p>
</li>
<li>
<p>As soon as possible, jump to the first applicable entry from the following list:</p>
<dl class="switch">
<dt>If the resource type is <code>multipart/x-mixed-replace</code></dt>
<dd>
<p>The next <span data-x="concept-task">task</span> that is <span data-x="queue a
task">queued</span> by the <span>networking task source</span> while the image is being
fetched must run the following steps:</p>
<ol>
<li>
<p>If <var>image request</var> is the <span>pending request</span>
and at least one body part has been completely decoded,
<span>abort the image request</span> for the <span>current request</span>,
and <span>upgrade the pending request to the current request</span>.</p>
</li>
<li><p>Otherwise, if <var>image request</var> is the <span>pending request</span> and the
user agent is able to determine that <var>image request</var>'s image is corrupted in some
fatal way such that the image dimensions cannot be obtained, <span>abort the image
request</span> for the <span>current request</span>, <span>upgrade the pending request to the
current request</span>, and set the <span>current request</span>'s <span
data-x="img-req-state">state</span> to <span data-x="img-error">broken</span>.</p></li>
<li><p>Otherwise, if <var>image request</var> is the <span>current request</span>, its <span
data-x="img-req-state">state</span> is <span data-x="img-none">unavailable</span>, and the
user agent is able to determine <var>image request</var>'s image's width and height, set the
<span>current request</span>'s <span data-x="img-req-state">state</span> to <span
data-x="img-inc">partially available</span>.</p></li>
<li><p>Otherwise, if <var>image request</var> is the <span>current request</span>, its <span
data-x="img-req-state">state</span> is <span data-x="img-none">unavailable</span>, and the
user agent is able to determine that <var>image request</var>'s image is corrupted in some
fatal way such that the image dimensions cannot be obtained, set the <span>current
request</span>'s <span data-x="img-req-state">state</span> to <span
data-x="img-error">broken</span>.
<!--TODO: abort the fetch? fire error event?--></p>
</li>
</ol>
<p>Each <span data-x="concept-task">task</span> that is <span data-x="queue a
task">queued</span> by the <span>networking task source</span> while the image is being
fetched must update the presentation of the image, but as each new body part comes in, if the
user agent is able to determine the image's width and height, it must <span data-x="prepare an
image for presentation">prepare the <code>img</code> element's <span>current request</span>
for presentation</span> given the <code>img</code> element and replace the previous image.
Once one body part has been completely decoded, perform the following steps:</p>
<ol>
<li><p>Set the <code>img</code> element's <span>current request</span>'s <span
data-x="img-req-state">state</span> to <span data-x="img-all">completely
available</span>.</p></li>
<li><p>If <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>urlString</var>, then <span>queue an element task</span> on the <span>DOM manipulation task source</span>
given the <code>img</code> element to <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-load">load</code> at the <code>img</code> element.</p></li>
</ol>
<!--TODO what if the image is broken?
TODO change state and fire in the same task? -->
</dd>
<dt>If the resource type and data corresponds to a supported image format, <a
href="#img-determine-type">as described below</a></dt>
<dd>
<p>The next <span data-x="concept-task">task</span> that is <span data-x="queue a
task">queued</span> by the <span>networking task source</span> while the image is being
fetched must run the following steps:</p>
<ol>
<li><p>If the user agent is able to determine <var>image request</var>'s image's width and
height, and <var>image request</var> is <span>pending request</span>, set <var>image
request</var>'s <span data-x="img-req-state">state</span> to <span data-x="img-inc">partially
available</span>.</p></li>
<li><p>Otherwise, if the user agent is able to determine <var>image request</var>'s image's
width and height, and <var>image request</var> is <span>current request</span>, <span
data-x="prepare an image for presentation">prepare <var>image request</var> for
presentation</span> given the <code>img</code> element and set <var>image request</var>'s
<span data-x="img-req-state">state</span> to <span data-x="img-inc">partially
available</span>.</p></li>
<li>
<p>Otherwise, if the user agent is able to determine that <var>image request</var>'s image
is corrupted in some fatal way such that the image dimensions cannot be obtained, and
<var>image request</var> is <span>pending request</span>:</p>
<ol>
<li><p><span>Abort the image request</span> for the <span>current request</span> and the
<span>pending request</span>.</p></li>
<li><p><span>Upgrade the pending request to the current request</span>.</p></li>
<li><p>Set <span>current request</span>'s <span data-x="img-req-state">state</span> to
<span data-x="img-error">broken</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-error">error</code> at the <code>img</code> element.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if the user agent is able to determine that <var>image request</var>'s image
is corrupted in some fatal way such that the image dimensions cannot be obtained, and
<var>image request</var> is <span>current request</span>:</p>
<ol>
<li><p><span>Abort the image request</span> for <var>image request</var>.</p></li>
<li><p>If <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>urlString</var>, then <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-error">error</code> at the <code>img</code> element.</p></li>
</ol>
</li>
</ol>
<p id="img-load">That <span data-x="concept-task">task</span>, and each subsequent <span
data-x="concept-task">task</span>, that is <span data-x="queue a task">queued</span> by the
<span>networking task source</span> while the image is being fetched, if <var>image
request</var> is the <span>current request</span>, must update the presentation of the image
appropriately (e.g., if the image is a progressive JPEG, each packet can improve the
resolution of the image).</p>
<p>Furthermore, the last <span data-x="concept-task">task</span> that is <span data-x="queue a
task">queued</span> by the <span>networking task source</span> once the resource has been
fetched must additionally run these steps:</p>
<ol>
<!--
the download was successful
the user agent was able to determine the image's width and height
image request is current request or pending request
pending request might be null or non-null
-->
<li><p>If <var>image request</var> is the <span>pending request</span>,
<span>abort the image request</span> for the <span>current request</span>,
<span>upgrade the pending request to the current request</span> and
<span data-x="prepare an image for presentation">prepare <var>image request</var> for
presentation</span> given the <code>img</code> element.</p></li>
<li><p>Set <var>image request</var> to the <span data-x="img-all">completely
available</span> state.</p></li>
<li><p>Add the image to the <span>list of available images</span> using the key
<var>key</var>, with the <span>ignore higher-layer caching</span> flag set.</p></li>
<li><p>If <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>urlString</var>, then <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-load">load</code> at the <code>img</code> element.</p></li>
</ol>
</dd>
<dt>Otherwise</dt>
<dd><p>The image data is not in a supported file format; the user agent must set <var>image
request</var>'s <span data-x="img-req-state">state</span> to <span
data-x="img-error">broken</span>, <span>abort the image request</span> for the <span>current
request</span> and the <span>pending request</span>, <span>upgrade the pending request to the
current request</span> if <var>image request</var> is the <span>pending request</span>, and
then, if <i>maybe omit events</i> is not set or <var>previousURL</var> is not equal to
<var>urlString</var>, <span>queue an element task</span> on the <span>DOM manipulation task
source</span> given the <code>img</code> element to <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-error">error</code> at the <code>img</code>
element.</p></dd>
</dl>
</li>
</ol>
<p>While a user agent is running the above algorithm for an element <var>x</var>, there must be a
strong reference from the element's <span>node document</span> to the element <var>x</var>, even
if that element is not <span>connected</span>.</p>
<p>To <dfn>abort the image request</dfn> for an <span>image request</span> or null <var>image
request</var> means to run the following steps:</p>
<ol>
<li><p>If <var>image request</var> is null, then return.</p></li>
<li><p>Forget <var>image request</var>'s <span data-x="img-req-data">image data</span>, if any.</p></li>
<li><p>Abort any instance of the <span data-x="concept-fetch">fetching</span> algorithm for
<var>image request</var>, discarding any pending tasks generated by that algorithm.</p></li>
</ol>
<p>To <dfn>upgrade the pending request to the current request</dfn> for an <code>img</code> element means to run the following steps:</p>
<ol>
<li><p>Let the <code>img</code> element's <span>current request</span> be the <span>pending request</span>.</p></li>
<li><p>Let the <code>img</code> element's <span>pending request</span> be null.</p></li>
</ol>
<h6>Preparing an image for presentation</h6>
<p>To <dfn>prepare an image for presentation</dfn> for an <span>image request</span>
<var>req</var> given image element <var>img</var>:</p>
<ol>
<li><p>Let <var>exifTagMap</var> be the EXIF tags obtained from <var>req</var>'s <span
data-x="img-req-data">image data</span>, as defined by the relevant codec.
<ref>EXIF</ref></p></li>
<li><p>Let <var>physicalWidth</var> and <var>physicalHeight</var> be the width and height
obtained from <var>req</var>'s <span data-x="img-req-data">image data</span>, as defined by the
relevant codec.</p></li>
<li><p>Let <var>dimX</var> be the value of <var>exifTagMap</var>'s tag <code
data-x="">0xA002</code> (<code data-x="">PixelXDimension</code>).</p></li>
<li><p>Let <var>dimY</var> be the value of <var>exifTagMap</var>'s tag <code
data-x="">0xA003</code> (<code data-x="">PixelYDimension</code>).</p></li>
<li><p>Let <var>resX</var> be the value of <var>exifTagMap</var>'s tag <code
data-x="">0x011A</code> (<code data-x="">XResolution</code>).</p></li>
<li><p>Let <var>resY</var> be the value of <var>exifTagMap</var>'s tag <code
data-x="">0x011B</code> (<code data-x="">YResolution</code>).</p></li>
<li><p>Let <var>resUnit</var> be the value of <var>exifTagMap</var>'s tag <code
data-x="">0x0128</code> (<code data-x="">ResolutionUnit</code>).</p></li>
<li><p>If either <var>dimX</var> or <var>dimY</var> is not a positive integer, then
return.</p></li>
<li><p>If either <var>resX</var> or <var>resY</var> is not a positive floating-point number, then
return.</p></li>
<li><p>If <var>resUnit</var> is not equal to <code data-x="">2</code> (<code
data-x="">Inch</code>), then return.</p></li>
<li><p>Let <var>widthFromDensity</var> be the value of <var>physicalWidth</var>, multiplied by 72
and divided by <var>resX</var>.</p></li>
<li><p>Let <var>heightFromDensity</var> be the value of <var>physicalHeight</var>, multiplied by
72 and divided by <var>resY</var>.</p></li>
<li><p>If <var>widthFromDensity</var> is not equal to <var>dimX</var> or
<var>heightFromDensity</var> is not equal to <var>dimY</var>, then return.</p></li>
<li>
<p>If <var>req</var>'s <span data-x="img-req-data">image data</span> is
<span>CORS-cross-origin</span>, then set <var>img</var>'s <span>natural dimensions</span> to
<var>dimX</var> and <var>dimY</var>, scale <var>img</var>'s pixel data accordingly, and return.</p>
</li>
<li><p>Set <var>req</var>'s <span>preferred density-corrected dimensions</span> to a struct with
its width set to <var>dimX</var> and its height set to <var>dimY</var>.</p></li>
<li><p>Update <var>req</var>'s <code>img</code> element's presentation appropriately.</p></li>
</ol>
<p class="note">Resolution in EXIF is equivalent to <span data-x="'pt'">CSS points per
inch</span>, therefore 72 is the base for computing size from resolution.</p>
<p class="XXX">It is not yet specified what would be the case if EXIF arrives after the image is
already presented. See <a href="https://github.com/w3c/csswg-drafts/issues/4929">issue
#4929</a>.</p>
<h6>Selecting an image source</h6>
<p>To <dfn>select an image source</dfn> given an <code>img</code> element <var>el</var>:</p>
<ol>
<li><p><span>Update the source set</span> for <var>el</var>.</p></li>
<li><p>If <var>el</var>'s <span>source set</span> is empty, return null as the URL and undefined
as the pixel density.</p></li>
<li><p>Return the result of <span data-x="select an image source from a source set">selecting an
image</span> from <var>el</var>'s <span>source set</span>.</p></li>
</ol>
<p>To <dfn>select an image source from a source set</dfn> given a <span>source set</span>
<var>sourceSet</var>:</p>
<ol>
<li><p>If an entry <var>b</var> in <var>sourceSet</var> has the same associated <span>pixel
density descriptor</span> as an earlier entry <var>a</var> in <var>sourceSet</var>, then remove
entry <var>b</var>. Repeat this step until none of the entries in <var>sourceSet</var> have the
same associated <span>pixel density descriptor</span> as an earlier entry.</p></li>
<li><p>In an <span>implementation-defined</span> manner, choose one <span>image source</span>
from <var>sourceSet</var>. Let this be <var>selectedSource</var>.</p></li>
<li><p>Return <var>selectedSource</var> and its associated pixel density.</p></li>
</ol>
<h6>Creating a source set from attributes</h6>
<p>When asked to <dfn>create a source set</dfn> given a string <var>default source</var>, a string
<var>srcset</var>, a string <var>sizes</var>, and an element or null <var>img</var>:</p>
<ol>
<li><p>Let <var>source set</var> be an empty <span>source set</span>.</p></li>
<li><p>If <var>srcset</var> is not an empty string, then set
<var>source set</var> to the result of <span data-x="parse a srcset attribute">parsing</span>
<var>srcset</var>.</p></li>
<li><p>Let <span>source size</span> be the result of <span
data-x="parse a sizes attribute">parsing</span> <var>sizes</var> with <var>img</var>.</p></li>
<li><p>If <var>default source</var> is not the empty string and
<var>source set</var> does not contain an <span>image source</span> with a <span>pixel
density descriptor</span> value of 1, and no <span>image source</span> with a <span>width
descriptor</span>, append <var>default source</var> to <var>source set</var>.</p></li>
<li><p><span>Normalize the source densities</span> of <var>source set</var>.</p></li>
<li><p>Return <var>source set</var>.</p></li>
</ol>
<h6>Updating the source set</h6>
<p>When asked to <dfn>update the source set</dfn> for a given <code>img</code> or
<code>link</code> element <var>el</var>, user agents must do the following:</p>
<ol>
<li><p>Set <var>el</var>'s <span>source set</span> to an empty <span>source set</span>.</p></li>
<li><p>Let <var>elements</var> be « <var>el</var> ».</p></li>
<li><p>If <var>el</var> is an <code>img</code> element whose parent node is a
<code>picture</code> element, then <span data-x="list replace">replace</span> the contents of
<var>elements</var> with <var>el</var>'s parent node's child elements, retaining relative
order.</p></li>
<li><p>Let <var>img</var> be <var>el</var> if <var>el</var> is an <code>img</code> element,
otherwise null.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>child</var> in <var>elements</var>:</p>
<ol>
<li>
<p>If <var>child</var> is <var>el</var>:</p>
<ol>
<li><p>Let <var>default source</var> be the empty string.</p></li>
<li><p>Let <var>srcset</var> be the empty string.</p></li>
<li><p>Let <var>sizes</var> be the empty string.</p></li>
<li><p>If <var>el</var> is an <code>img</code> element that has a <code
data-x="attr-img-srcset">srcset</code> attribute, then set <var>srcset</var> to that
attribute's value.</p></li>
<li><p>Otherwise, if <var>el</var> is a <code>link</code> element that has an <code
data-x="attr-link-imagesrcset">imagesrcset</code> attribute, then set <var>srcset</var> to
that attribute's value.</p></li>
<li><p>If <var>el</var> is an <code>img</code> element that has a <code
data-x="attr-img-sizes">sizes</code> attribute, then set <var>sizes</var> to that attribute's
value.</p></li>
<li><p>Otherwise, if <var>el</var> is a <code>link</code> element that has an <code
data-x="attr-link-imagesizes">imagesizes</code> attribute, then set <var>sizes</var> to that
attribute's value.</p></li>
<li><p>If <var>el</var> is an <code>img</code> element that has a <code
data-x="attr-img-src">src</code> attribute, then set <var>default source</var> to that
attribute's value.</p></li>
<li><p>Otherwise, if <var>el</var> is a <code>link</code> element that has an <code
data-x="attr-link-href">href</code> attribute, then set <var>default source</var> to that
attribute's value.</p></li>
<li><p>Let <var>el</var>'s <span>source set</span> be the result of <span data-x="create a
source set">creating a source set</span> given <var>default source</var>, <var>srcset</var>,
<var>sizes</var>, and <var>img</var>.</p></li>
<li>
<p>Return.</p>
<p class="note">If <var>el</var> is a <code>link</code> element, then <var>elements</var>
contains only <var>el</var>, so this step will be reached immediately and the rest of the
algorithm will not run.</p>
</li>
</ol>
</li>
<li><p>If <var>child</var> is not a <code>source</code> element, then
<span>continue</span>.</p></li>
<li><p>If <var>child</var> does not have a <code data-x="attr-source-srcset">srcset</code>
attribute, <span>continue</span> to the next child.</p></li>
<li><p><span data-x="parse a srcset attribute">Parse <var>child</var>'s srcset attribute</span> and
let the returned <span>source set</span> be <var>source set</var>.</p></li>
<li><p>If <var>source set</var> has zero <span data-x="image source">image sources</span>,
<span>continue</span> to the next child.</p></li>
<li><p>If <var>child</var> has a <code data-x="attr-source-media">media</code> attribute, and
its value does not <span data-x="matches the environment">match the environment</span>,
<span>continue</span> to the next child.</p></li>
<li><p><span data-x="parse a sizes attribute">Parse <var>child</var>'s sizes attribute</span>
with <var>img</var>, and let <var>source set</var>'s <span>source size</span> be the returned
value.</p></li>
<li><p>If <var>child</var> has a <code data-x="attr-source-type">type</code> attribute, and its
value is an unknown or unsupported <span>MIME type</span>, <span>continue</span> to the next child.</p></li>
<li><p>If <var>child</var> has <code data-x="attr-dim-width">width</code> or <code
data-x="attr-dim-height">height</code> attributes, set <var>el</var>'s <span
data-x="concept-img-dimension-attribute-source">dimension attribute source</span> to
<var>child</var>. Otherwise, set <var>el</var>'s <span
data-x="concept-img-dimension-attribute-source">dimension attribute source</span> to
<var>el</var>.</p></li>
<li><p><span>Normalize the source densities</span> of <var>source set</var>.</p></li>
<li><p>Let <var>el</var>'s <span>source set</span> be <var>source set</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
</ol>
<p class="note">Each <code>img</code> element independently considers its previous sibling
<code>source</code> elements plus the <code>img</code> element itself for selecting an <span>image
source</span>, ignoring any other (invalid) elements, including other <code>img</code> elements in
the same <code>picture</code> element, or <code>source</code> elements that are following siblings
of the relevant <code>img</code> element.</p>
<h6>Parsing a srcset attribute</h6>
<p>When asked to <dfn>parse a srcset attribute</dfn> from an element, parse the value of the
element's <span>srcset attribute</span> as follows:</p>
<ol>
<li><p>Let <var>input</var> be the value passed to this algorithm.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>,
initially pointing at the start of the string.</p></li>
<li><p>Let <var>candidates</var> be an initially empty <span>source set</span>.</p></li>
<li><p><i>Splitting loop</i>: <span>Collect a sequence of code points</span> that are <span>ASCII
whitespace</span> or U+002C COMMA characters from <var>input</var> given <var>position</var>. If
any U+002C COMMA characters were collected, that is a <span
data-x="concept-microsyntax-parse-error">parse error</span>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>,
return <var>candidates</var>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are not <span>ASCII whitespace</span>
from <var>input</var> given <var>position</var>, and let that be <var>url</var>.</p></li>
<li><p>Let <var>descriptors</var> be a new empty list.</p></li>
<li>
<p>If <var>url</var> ends with U+002C (,), then:</p>
<ol>
<li><p>Remove all trailing U+002C COMMA characters from <var>url</var>.
If this removed more than one character,
that is a <span data-x="concept-microsyntax-parse-error">parse error</span>.</p></li>
</ol>
<p>Otherwise:</p>
<ol>
<li><p><i>Descriptor tokenizer</i>: <span>Skip ASCII whitespace</span> within <var>input</var>
given <var>position</var>.</p></li>
<li><p>Let <var>current descriptor</var> be the empty string.</p></li>
<li><p>Let <var>state</var> be <i>in descriptor</i>.</p></li>
<li>
<p>Let <var>c</var> be the character at <var>position</var>.
Do the following depending on the value of <var>state</var>.
For the purpose of this step, "EOF" is a special character representing
that <var>position</var> is past the end of <var>input</var>.</p>
<dl class="switch">
<dt><i>In descriptor</i></dt>
<dd>
<p>Do the following, depending on the value of <var>c</var>:</p>
<dl class="switch">
<dt><span>ASCII whitespace</span></dt>
<dd><p>If <var>current descriptor</var> is not empty,
append <var>current descriptor</var> to <var>descriptors</var>
and let <var>current descriptor</var> be the empty string.
Set <var>state</var> to <i>after descriptor</i>.</p></dd>
<dt>U+002C COMMA (,)</dt>
<dd><p>Advance <var>position</var> to the next character in <var>input</var>.
If <var>current descriptor</var> is not empty,
append <var>current descriptor</var> to <var>descriptors</var>.
Jump to the step labeled <i>descriptor parser</i>.</p></dd>
<dt>U+0028 LEFT PARENTHESIS (()</dt>
<dd><p>Append <var>c</var> to <var>current descriptor</var>.
Set <var>state</var> to <i>in parens</i>.</p></dd>
<dt>EOF</dt>
<dd><p>If <var>current descriptor</var> is not empty,
append <var>current descriptor</var> to <var>descriptors</var>.
Jump to the step labeled <i>descriptor parser</i>.</p></dd>
<dt>Anything else</dt>
<dd><p>Append <var>c</var> to <var>current descriptor</var>.</p></dd>
</dl>
</dd>
<dt><i>In parens</i></dt>
<dd>
<p>Do the following, depending on the value of <var>c</var>:</p>
<dl class="switch">
<dt>U+0029 RIGHT PARENTHESIS ())</dt>
<dd><p>Append <var>c</var> to <var>current descriptor</var>.
Set <var>state</var> to <i>in descriptor</i>.</p></dd>
<dt>EOF</dt>
<dd><p>Append <var>current descriptor</var> to <var>descriptors</var>.
Jump to the step labeled <i>descriptor parser</i>.</p></dd>
<dt>Anything else</dt>
<dd><p>Append <var>c</var> to <var>current descriptor</var>.</p></dd>
</dl>
</dd>
<dt><i>After descriptor</i></dt>
<dd>
<p>Do the following, depending on the value of <var>c</var>:</p>
<dl class="switch">
<dt><span>ASCII whitespace</span></dt>
<dd><p>Stay in this state.</p></dd>
<dt>EOF</dt>
<dd><p>Jump to the step labeled <i>descriptor parser</i>.</p></dd>
<dt>Anything else</dt>
<dd><p>Set <var>state</var> to <i>in descriptor</i>.
Set <var>position</var> to the <em>previous</em> character in <var>input</var>.</p></dd>
</dl>
</dd>
</dl>
<p>Advance <var>position</var> to the next character in <var>input</var>. Repeat this
step.</p>
<p class="note">In order to be compatible with future additions,
this algorithm supports multiple descriptors and descriptors with parens.</p>
</li>
</ol>
</li>
<li><p><i>Descriptor parser</i>: Let <var>error</var> be <i>no</i>.</p></li>
<li><p>Let <var>width</var> be <i>absent</i>.</p></li>
<li><p>Let <var>density</var> be <i>absent</i>.</p></li>
<li><p>Let <var>future-compat-h</var> be <i>absent</i>.</p></li>
<li>
<p>For each descriptor in <var>descriptors</var>,
run the appropriate set of steps from the following list:</p>
<dl class=switch>
<dt>If the descriptor consists of a <span>valid non-negative integer</span>
followed by a U+0077 LATIN SMALL LETTER W character</dt>
<dd>
<ol>
<li>
<p>If the user agent does not support the <code data-x="attr-img-sizes">sizes</code> attribute,
let <var>error</var> be <i>yes</i>.</p>
<p class="note">A conforming user agent will support the <code data-x="attr-img-sizes">sizes</code> attribute.
However, user agents typically implement and ship features in an incremental manner in practice.</p>
</li>
<li><p>If <var>width</var> and <var>density</var>
are not both <i>absent</i>,
then let <var>error</var> be <i>yes</i>.</p></li>
<li><p>Apply the <span>rules for parsing non-negative integers</span> to the descriptor. If
the result is 0, let <var>error</var> be <i>yes</i>. Otherwise, let <var>width</var> be the
result.</p></li>
</ol>
</dd>
<dt>If the descriptor consists of a <span>valid floating-point number</span>
followed by a U+0078 LATIN SMALL LETTER X character</dt>
<dd>
<ol>
<li><p>If <var>width</var>, <var>density</var> and <var>future-compat-h</var>
are not all <i>absent</i>,
then let <var>error</var> be <i>yes</i>.</p></li>
<li>
<p>Apply the <span>rules for parsing floating-point number values</span> to the descriptor.
If the result is less than 0, let <var>error</var> be <i>yes</i>. Otherwise, let
<var>density</var> be the result.</p>
<p class="note">If <var>density</var> is 0, the <span>natural dimensions</span> will be
infinite. User agents are <a href="https://infra.spec.whatwg.org/#algorithm-limits">expected
to have limits</a> in how big images can be rendered.</p>
</li>
</ol>
</dd>
<dt>If the descriptor consists of a <span>valid non-negative integer</span>
followed by a U+0068 LATIN SMALL LETTER H character</dt>
<dd>
<p>This is a <span data-x="concept-microsyntax-parse-error">parse error</span>.</p>
<ol>
<li><p>If <var>future-compat-h</var> and <var>density</var>
are not both <i>absent</i>,
then let <var>error</var> be <i>yes</i>.</p></li>
<li><p>Apply the <span>rules for parsing non-negative integers</span> to the descriptor. If
the result is 0, let <var>error</var> be <i>yes</i>. Otherwise, let
<var>future-compat-h</var> be the result.</p></li>
</ol>
</dd>
<dt>Anything else</dt>
<dd><p>Let <var>error</var> be <i>yes</i>.</p></dd>
</dl>
</li>
<li><p>If <var>future-compat-h</var> is not <i>absent</i> and <var>width</var> is <i>absent</i>,
let <var>error</var> be <i>yes</i>.</p></li>
<li><p>If <var>error</var> is still <i>no</i>,
then append a new <span>image source</span> to <var>candidates</var>
whose URL is <var>url</var>,
associated with a width <var>width</var> if not <i>absent</i>
and a pixel density <var>density</var> if not <i>absent</i>.
Otherwise, there is a <span data-x="concept-microsyntax-parse-error">parse error</span>.</p></li>
<li><p>Return to the step labeled <i>splitting loop</i>.</p></li>
</ol>
<h6>Parsing a sizes attribute</h6>
<p>When asked to <dfn>parse a sizes attribute</dfn> from an element <var>element</var>, with an
<code>img</code> element or null <var>img</var>:</p>
<ol>
<li><p>Let <var>unparsed sizes list</var> be the result of <span data-x="parse a comma-separated
list of component values">parsing a comma-separated list of component values</span> from the
value of <var>element</var>'s <span>sizes attribute</span> (or the empty string, if the attribute
is absent). <ref>CSSSYNTAX</ref></p></li>
<li><p>Let <var>size</var> be null.</p></li>
<li>
<p>For each <var>unparsed size</var> in <var>unparsed sizes list</var>:</p>
<ol>
<li><p>Remove all consecutive <span><whitespace-token></span>s
from the end of <var>unparsed size</var>.
If <var>unparsed size</var> is now empty,
then that is a <span data-x="concept-microsyntax-parse-error">parse error</span>;
<span>continue</span>.</p></li>
<li><p>If the last <span>component value</span> in <var>unparsed size</var>
is a valid non-negative <span><source-size-value></span>,
then set <var>size</var> to its value
and remove the <span>component value</span> from <var>unparsed size</var>.
Any CSS function other than the <span>math functions</span> is invalid.
Otherwise, there is a <span data-x="concept-microsyntax-parse-error">parse error</span>;
<span>continue</span>.</p></li>
<li>
<p>If <var>size</var> is <code data-x="valdef-sizes-auto">auto</code>, and <var>img</var>
is not null, and <var>img</var> is <span>being rendered</span>, and <var>img</var>
<span>allows auto-sizes</span>, then set <var>size</var> to the <span>concrete object
size</span> width of <var>img</var>, in <span data-x="'px'">CSS pixels</span>.</p>
<p class="note">If <var>size</var> is still <code data-x="valdef-sizes-auto">auto</code>,
then it will be ignored.</p>
</li>
<li>
<p>Remove all consecutive <span><whitespace-token></span>s from the end of <var>unparsed
size</var>. If <var>unparsed size</var> is now empty:</p>
<ol>
<li><p>If this was not the last item in <var>unparsed sizes list</var>, that is a <span
data-x="concept-microsyntax-parse-error">parse error</span>.</p></li>
<li><p>If <var>size</var> is not <code data-x="valdef-sizes-auto">auto</code>, then return
<var>size</var>. Otherwise, continue.</p></li>
</ol>
</li>
<li><p>Parse the remaining <span data-x="component value">component values</span> in <var>unparsed size</var>
as a <span><media-condition></span>.
If it does not parse correctly,
or it does parse correctly but the <span><media-condition></span> evaluates to false,
<span>continue</span>. <ref>MQ</ref></p></li>
<li><p>If <var>size</var> is not <code data-x="valdef-sizes-auto">auto</code>, then return
<var>size</var>. Otherwise, continue.</p></li>
</ol>
</li>
<li><p>Return <code data-x="">100vw</code>.</p></li>
</ol>
<p class="note">It is invalid to use a bare <span><source-size-value></span> that is a <span><length></span>
(without an accompanying <span><media-condition></span>)
as an entry in the <span><source-size-list></span> that is not the last entry.
However, the parsing algorithm allows it at any point in the <span><source-size-list></span>,
and will accept it immediately as the size
if the preceding entries in the list weren't used.
This is to enable future extensions,
and protect against simple author errors such as a final trailing comma.
A bare <code data-x="valdef-sizes-auto">auto</code> keyword is allowed to have other entries
following it to provide a fallback for legacy user agents.</p>
<h6>Normalizing the source densities</h6>
<p>An <span>image source</span> can have a <span>pixel density descriptor</span>, a <span>width
descriptor</span>, or no descriptor at all accompanying its URL. Normalizing a <span>source
set</span> gives every <span>image source</span> a <span>pixel density descriptor</span>.</p>
<p>When asked to <!--en-GB--><dfn id="normalise-the-source-densities">normalize the source
densities</dfn> of a <span>source set</span> <var>source set</var>, the user agent must do the
following:</p>
<ol>
<li><p>Let <var>source size</var> be <var>source set</var>'s <span>source size</span>.</p></li>
<li>
<p>For each <span>image source</span> in <var>source set</var>:</p>
<ol>
<li><p>If the <span>image source</span> has a <span>pixel density descriptor</span>, <span>continue</span> to the next
<span>image source</span>.</p></li>
<li>
<p>Otherwise, if the <span>image source</span> has a <span>width descriptor</span>, replace the <span>width
descriptor</span> with a <span>pixel density descriptor</span> with a <span data-x="pixel density descriptor
value">value</span> of the <span>width descriptor value</span> divided by <var>source size</var> and a unit
of <code data-x="">x</code>.</p>
<p class="note">If the <span>source size</span> is 0, then the density would be infinity,
which results in the <span>natural dimensions</span> being 0 by 0.</p>
</li>
<li><p>Otherwise, give the <span>image source</span> a <span>pixel density descriptor</span> of <code
data-x="">1x</code>.</p></li>
</ol>
</li>
</ol>
<h6>Reacting to environment changes</h6>
<p>The user agent may at any time run the following algorithm to update an <code>img</code>
element's image in order to <dfn data-x="img-environment-changes">react to changes in the
environment</dfn>. (User agents are <em>not required</em> to ever run this algorithm; for example,
if the user is not looking at the page any more, the user agent might want to wait until the user
has returned to the page before determining which image to use, in case the environment changes
again in the meantime.)</p>
<p class=note>User agents are encouraged to run this algorithm in particular when the user changes
the <span>viewport</span>'s size (e.g. by resizing the window or changing the page zoom), and when
an <code>img</code> element is <span data-x="node is inserted into a document">inserted into a
document</span>, so that the <span>density-corrected natural width and height</span> match the
new <span>viewport</span>, and so that the correct image is chosen when <span>art direction</span>
is involved.</p>
<ol>
<li><p><span>Await a stable state</span>. The <span>synchronous section</span>
consists of all the remaining steps of this algorithm until the algorithm says the
<span>synchronous section</span> has ended. (Steps in <span data-x="synchronous
section">synchronous sections</span> are marked with ⌛.)</p></li>
<li><p>⌛ If the <code>img</code> element does not <span>use <code>srcset</code> or
<code>picture</code></span>, its <span>node document</span> is not <span>fully active</span>, has
image data whose resource type is <code>multipart/x-mixed-replace</code>, or the <span>pending
request</span> is not null, then return.</p></li>
<!-- we don't support replacing push-JPEG images because defining what happens with
the tasks and events and so on in that case would become implausibly complicated. -->
<li><p>⌛ Let <var>selected source</var> and <var>selected pixel
density</var> be the URL and pixel density that results from <span data-x="select an image
source">selecting an image source</span>, respectively.</p></li>
<li><p>⌛ If <var>selected source</var> is null, then return.</p></li>
<!-- not sure this can ever actually happen -->
<li><p>⌛ If <var>selected source</var> and <var>selected pixel
density</var> are the same as the element's <span>last selected source</span> and <span>current
pixel density</span>, then return.</p></li> <!-- note that this check happens before
base URL resolution, so changing the base URL doesn't trigger an update if nothing else changed
-->
<li><p>⌛ Let <var>urlString</var> be the result of <span>encoding-parsing-and-serializing
a URL</span> given <var>selected source</var>, relative to the element's <span>node
document</span>.</p></li>
<li><p>⌛ If <var>urlString</var> is failure, then return.</p></li>
<li><p>⌛ Let <var>corsAttributeState</var> be the state of the element's <code
data-x="attr-img-crossorigin">crossorigin</code> content attribute.</p></li>
<li><p>⌛ Let <var>origin</var> be the <code>img</code> element's <span>node
document</span>'s <span data-x="concept-document-origin">origin</span>.</p></li>
<li><p>⌛ Let <var>client</var> be the <code>img</code> element's <span>node
document</span>'s <span>relevant settings object</span>.</p></li>
<li><p>⌛ Let <var>key</var> be a tuple consisting of <var>urlString</var>,
<var>corsAttributeState</var>, and, if <var>corsAttributeState</var> is not <span
data-x="attr-crossorigin-none">No CORS</span>, <var>origin</var>.</p></li>
<li><p>⌛ Let <var>image request</var> be a new <span>image request</span>
whose <span data-x="img-req-url">current URL</span> is <var>urlString</var>.</p></li>
<li><p>⌛ Let the element's <span>pending request</span> be <var>image request</var>.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li>
<p>If the <span>list of available images</span> contains an entry for <var>key</var>,
then set <var>image request</var>'s <span data-x="img-req-data">image data</span> to that of the entry.
Continue to the next step.</p>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>request</var> be the result of <span
data-x="create a potential-CORS request">creating a potential-CORS request</span> given
<var>urlString</var>, "<code data-x="">image</code>", and
<var>corsAttributeState</var>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to
<var>client</var>, <span data-x="concept-request-initiator">initiator</span> to "<code
data-x="">imageset</code>", and set <var>request</var>'s <span>synchronous
flag</span>.</p></li>
<li><p>Set <var>request</var>'s
<span data-x="concept-request-referrer-policy">referrer policy</span> to the current state of
the element's <code data-x="attr-img-referrerpolicy">referrerpolicy</code> attribute.</p></li>
<li><p>Set <var>request</var>'s <span
data-x="concept-request-priority">priority</span> to the current state of the element's <code
data-x="attr-img-fetchpriority">fetchpriority</code> attribute.</p></li>
<!--FETCH--><li><p>Let <var>response</var> be the result of <span
data-x="concept-fetch">fetching</span> <var>request</var>.</p></li>
<li><p>If <var>response</var>'s <span>unsafe response</span> is a <span>network error</span> or
if the image format is unsupported (as determined by applying the <span
data-x="Content-Type sniffing: image">image sniffing rules</span>, again as mentioned earlier),
or if the user agent is able to determine that <var>image request</var>'s image is corrupted in
some fatal way such that the image dimensions cannot be obtained, or if the resource type is
<code>multipart/x-mixed-replace</code>, then let <span>pending request</span> be null and abort
these steps.</p></li>
<li><p>Otherwise, <var>response</var>'s <span>unsafe response</span> is <var>image
request</var>'s <span data-x="img-req-data">image data</span>. It can be either
<span>CORS-same-origin</span> or <span>CORS-cross-origin</span>; this affects the image's
interaction with other APIs (e.g., when used on a <code>canvas</code>).</p></li>
</ol>
</li>
<li>
<p><span>Queue an element task</span> on the <span>DOM manipulation task source</span> given
the <code>img</code> element and the following steps:</p>
<ol>
<li><p>If the <code>img</code> element has experienced <span>relevant mutations</span>
since this algorithm started, then let <span>pending request</span> be null and abort these
steps.</p>
<li><p>Let the <code>img</code> element's <span>last selected source</span> be <var>selected
source</var> and the <code>img</code> element's <span>current pixel density</span> be
<var>selected pixel density</var>.</p></li>
<li><p>Set the <var>image request</var>'s <span data-x="img-req-state">state</span> to <span
data-x="img-all">completely available</span>.</p></li>
<li><p>Add the image to the <span>list of available images</span> using the key <var>key</var>,
with the <span>ignore higher-layer caching</span> flag set.</p></li>
<li><p><span>Upgrade the pending request to the current request</span>.</p></li>
<li><p><span data-x="prepare an image for presentation">Prepare <var>image request</var> for
presentation</span> given the <code>img</code> element.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at the <code>img</code> element.</p></li>
</ol>
</li>
</ol>
</div>
<h5 id="alt">Requirements for providing text to act as an alternative for images</h5>
<h6>General guidelines</h6>
<p>Except where otherwise specified, the <code data-x="attr-img-alt">alt</code> attribute must be
specified and its value must not be empty; the value must be an appropriate replacement for the
image. The specific requirements for the <code data-x="attr-img-alt">alt</code> attribute depend on
what the image is intended to represent, as described in the following sections.</p>
<p>The most general rule to consider when writing alternative text is the following: <strong>the
intent is that replacing every image with the text of its <code data-x="attr-img-alt">alt</code>
attribute does not change the meaning of the page</strong>.</p>
<p>So, in general, alternative text can be written by considering what one would have written had
one not been able to include the image.</p>
<p>A corollary to this is that the <code data-x="attr-img-alt">alt</code> attribute's value should
never contain text that could be considered the image's <em>caption</em>, <em>title</em>, or
<em>legend</em>. It is supposed to contain replacement text that could be used by users
<em>instead</em> of the image; it is not meant to supplement the image. The <code
data-x="attr-title">title</code> attribute can be used for supplemental information.</p>
<p>Another corollary is that the <code data-x="attr-img-alt">alt</code> attribute's value should
not repeat information that is already provided in the prose next to the image.</p>
<p class="note">One way to think of alternative text is to think about how you would read the page
containing the image to someone over the phone, without mentioning that there is an image present.
Whatever you say instead of the image is typically a good start for writing the alternative
text.</p>
<h6>A link or button containing nothing but the image</h6>
<p>When an <code>a</code> element that creates a <span>hyperlink</span>, or a <code>button</code>
element, has no textual content but contains one or more images, the <code
data-x="attr-img-alt">alt</code> attributes must contain text that together convey the purpose of
the link or button.</p>
<div class="example">
<p>In this example, a user is asked to pick their preferred color from a list of three. Each color
is given by an image, but for users who have configured their user agent not to display images,
the color names are used instead:</p>
<pre><code class="html"><h1>Pick your color</h1>
<ul>
<li><a href="green.html"><strong><img src="green.jpeg" alt="Green"></strong></a></li>
<li><a href="blue.html"><strong><img src="blue.jpeg" alt="Blue"></strong></a></li>
<li><a href="red.html"><strong><img src="red.jpeg" alt="Red"></strong></a></li>
</ul></code></pre>
</div>
<div class="example">
<p>In this example, each button has a set of images to indicate the kind of color output desired
by the user. The first image is used in each case to give the alternative text.</p>
<pre><code class="html"><button name="rgb"><strong><img src="red" alt="RGB"><img src="green" alt=""><img src="blue" alt=""></strong></button>
<button name="cmyk"><strong><img src="cyan" alt="CMYK"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></strong></button></code></pre>
<p>Since each image represents one part of the text, it could also be written like this:</p>
<pre><code class="html"><button name="rgb"><strong><img src="red" alt="R"><img src="green" alt="G"><img src="blue" alt="B"></strong></button>
<button name="cmyk"><strong><img src="cyan" alt="C"><img src="magenta" alt="M"><img src="yellow" alt="Y"><img src="black" alt="K"></strong></button></code></pre>
<p>However, with other alternative text, this might not work, and putting all the alternative
text into one image in each case might make more sense:</p>
<pre><code class="html"><button name="rgb"><strong><img src="red" alt="sRGB profile"><img src="green" alt=""><img src="blue" alt=""></strong></button>
<button name="cmyk"><strong><img src="cyan" alt="CMYK profile"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></strong></button></code></pre>
</div>
<h6>A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations</h6>
<p>Sometimes something can be more clearly stated in graphical form, for example as a flowchart, a
diagram, a graph, or a simple map showing directions. In such cases, an image can be given using
the <code>img</code> element, but the lesser textual version must still be given, so that users
who are unable to view the image (e.g. because they have a very slow connection, or because they
are using a text-only browser, or because they are listening to the page being read out by a
hands-free automobile voice web browser, or simply because they are blind) are still able to
understand the message being conveyed.</p>
<p>The text must be given in the <code data-x="attr-img-alt">alt</code> attribute, and must convey
the same message as the image specified in the <code data-x="attr-img-src">src</code>
attribute.</p>
<p>It is important to realize that the alternative text is a <em>replacement</em> for the image,
not a description of the image.</p>
<div class="example">
<p>In the following example we have <a href="/images/parsing-model-overview.svg">a flowchart</a>
in image form, with text in the <code data-x="attr-img-alt">alt</code> attribute rephrasing the
flowchart in prose form:</p>
<pre><code class="html"><p>In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.</p>
<p><strong><img src="images/parsing-model-overview.svg" alt="The Network
passes data to the Input Stream Preprocessor, which passes it to the
Tokenizer, which passes it to the Tree Construction stage. From there,
data goes to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to the
Tokenizer."></strong></p></code></pre>
</div>
<div class="example">
<p>Here's another example, showing a good solution and a bad solution to the problem of including
an image in a description.</p>
<p>First, here's the good solution. This sample shows how the alternative text should just be
what you would have put in the prose if the image had never existed.</p>
<pre><code class="html"><!-- This is the correct way to do things. -->
<p>
You are standing in an open field west of a house.
<strong><img src="house.jpeg" alt="The house is white, with a boarded front door."></strong>
There is a small mailbox here.
</p></code></pre>
<p>Second, here's the bad solution. In this incorrect way of doing things, the alternative text
is simply a description of the image, instead of a textual replacement for the image. It's bad
because when the image isn't shown, the text doesn't flow as well as in the first example.</p>
<pre class="bad"><code class="html"><!-- <em>This is the wrong way to do things.</em> -->
<p>
You are standing in an open field west of a house.
<img src="house.jpeg" alt="A white house, with a boarded front door.">
There is a small mailbox here.
</p></code></pre>
<p>Text such as "Photo of white house with boarded door" would be equally bad alternative text
(though it could be suitable for the <code data-x="attr-title">title</code> attribute or in the
<code>figcaption</code> element of a <code>figure</code> with this image).</p>
</div>
<h6>A short phrase or label with an alternative graphical representation: icons, logos</h6>
<p>A document can contain information in iconic form. The icon is intended to help users of visual
browsers to recognize features at a glance.</p>
<p>In some cases, the icon is supplemental to a text label conveying the same meaning. In those
cases, the <code data-x="attr-img-alt">alt</code> attribute must be present but must be empty.</p>
<div class="example">
<p>Here the icons are next to text that conveys the same meaning, so they have an empty <code
data-x="attr-img-alt">alt</code> attribute:</p>
<pre><code class="html"><nav>
<p><a href="/help/"><strong><img src="/icons/help.png" alt=""></strong> Help</a></p>
<p><a href="/configure/"><strong><img src="/icons/configuration.png" alt=""></strong>
Configuration Tools</a></p>
</nav></code></pre>
</div>
<p>In other cases, the icon has no text next to it describing what it means; the icon is supposed
to be self-explanatory. In those cases, an equivalent textual label must be given in the <code
data-x="attr-img-alt">alt</code> attribute.</p>
<div class="example">
<p>Here, posts on a news site are labeled with an icon indicating their topic.</p>
<pre><code class="html"><body>
<article>
<header>
<h1>Ratatouille wins <i>Best Movie of the Year</i> award</h1>
<p><strong><img src="movies.png" alt="Movies"></strong></p>
</header>
<p>Pixar has won yet another <i>Best Movie of the Year</i> award,
making this its 8th win in the last 12 years.</p>
</article>
<article>
<header>
<h1>Latest TWiT episode is online</h1>
<p><strong><img src="podcasts.png" alt="Podcasts"></strong></p>
</header>
<p>The latest TWiT episode has been posted, in which we hear
several tech news stories as well as learning much more about the
iPhone. This week, the panelists compare how reflective their
iPhones' Apple logos are.</p>
</article>
</body></code></pre>
</div>
<p>Many pages include logos, insignia, flags, or emblems, which stand for a particular entity such
as a company, organization, project, band, software package, country, or some such.</p>
<p>If the logo is being used to represent the entity, e.g. as a page heading, the <code
data-x="attr-img-alt">alt</code> attribute must contain the name of the entity being represented by
the logo. The <code data-x="attr-img-alt">alt</code> attribute must <em>not</em> contain text like
the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity
itself.</p>
<p>If the logo is being used next to the name of the entity that it represents, then the logo is
supplemental, and its <code data-x="attr-img-alt">alt</code> attribute must instead be empty.</p>
<p>If the logo is merely used as decorative material (as branding, or, for example, as a side
image in an article that mentions the entity to which the logo belongs), then the entry below on
purely decorative images applies. If the logo is actually being discussed, then it is being used
as a phrase or paragraph (the description of the logo) with an alternative graphical
representation (the logo itself), and the first entry above applies.</p>
<div class="example">
<p>In the following snippets, all four of the above cases are present. First, we see a logo used
to represent a company:</p>
<pre><code class="html"><h1><strong><img src="XYZ.gif" alt="The XYZ company"></strong></h1></code></pre>
<p>Next, we see a paragraph which uses a logo right next to the company name, and so doesn't have
any alternative text:
<pre><code class="html"><article>
<h2>News</h2>
<p>We have recently been looking at buying the <strong><img src="alpha.gif"
alt=""> ΑΒΓ company</strong>, a small Greek company
specializing in our type of product.</p></code></pre>
<p>In this third snippet, we have a logo being used in an aside, as part of the larger article
discussing the acquisition:</p>
<pre><code class="html"><strong><aside><p><img src="alpha-large.gif" alt=""></p></aside></strong>
<p>The ΑΒΓ company has had a good quarter, and our
pie chart studies of their accounts suggest a much bigger blue slice
than its green and orange slices, which is always a good sign.</p>
</article></code></pre>
<p>Finally, we have an opinion piece talking about a logo, and the logo is therefore described in
detail in the alternative text.</p>
<pre><code class="html"><p>Consider for a moment their logo:</p>
<strong><p><img src="/images/logo" alt="It consists of a green circle with a
green question mark centered inside it."></p></strong>
<p>How unoriginal can you get? I mean, oooooh, a question mark, how
<em>revolutionary</em>, how utterly <em>ground-breaking</em>, I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.</p></code></pre>
<p>This example shows how the alternative text should be written such that if the image isn't <i
data-x="img-available">available</i>, and the text is used instead, the text flows seamlessly into
the surrounding text, as if the image had never been there in the first place.</p>
</div>
<h6>Text that has been rendered to a graphic for typographical effect</h6>
<p>Sometimes, an image just consists of text, and the purpose of the image is not to highlight the
actual typographic effects used to render the text, but just to convey the text itself.</p>
<p>In such cases, the <code data-x="attr-img-alt">alt</code> attribute must be present but must
consist of the same text as written in the image itself.</p>
<div class="example">
<p>Consider a graphic containing the text "Earth Day", but with the letters all decorated with
flowers and plants. If the text is merely being used as a heading, to spice up the page for
graphical users, then the correct alternative text is just the same text "Earth Day", and no
mention need be made of the decorations:</p>
<pre><code class="html"><h1><strong><img src="earthdayheading.png" alt="Earth Day"></strong></h1></code></pre>
</div>
<div class="example">
<p>An illuminated manuscript might use graphics for some of its images. The alternative text in
such a situation is just the character that the image represents.</p>
<pre><code class="html"><p><img src="initials/o.svg" alt="O">nce upon a time and a long long time ago, late at
night, when it was dark, over the hills, through the woods, across a great ocean, in a land far
away, in a small house, on a hill, under a full moon...</code></pre> <!-- The End. -->
</div>
<p>When an image is used to represent a character that cannot otherwise be represented in Unicode,
for example gaiji, itaiji, or new characters such as novel currency symbols, the alternative text
should be a more conventional way of writing the same thing, e.g. using the phonetic hiragana or
katakana to give the character's pronunciation.</p>
<div class="example">
<p>In this example from 1997, a new-fangled currency symbol that looks like a curly E with two
bars in the middle instead of one is represented using an image. The alternative text gives the
character's pronunciation.</p>
<pre><code class="html"><p>Only <img src="euro.png" alt="euro ">5.99!</code></pre>
</div>
<p>An image should not be used if characters would serve an identical purpose. Only when the text
cannot be directly represented using text, e.g., because of decorations or because there is no
appropriate character (as in the case of gaiji), would an image be appropriate.</p>
<p class="note">If an author is tempted to use an image because their default system font does not
support a given character, then web fonts are a better solution than images.</p>
<h6>A graphical representation of some of the surrounding text</h6>
<p>In many cases, the image is actually just supplementary, and its presence merely reinforces the
surrounding text. In these cases, the <code data-x="attr-img-alt">alt</code> attribute must be
present but its value must be the empty string.</p>
<p>In general, an image falls into this category if removing the image doesn't make the page any
less useful, but including the image makes it a lot easier for users of visual browsers to
understand the concept.</p>
<div class="example">
<p>A flowchart that repeats the previous paragraph in graphical form:</p>
<pre><code class="html"><p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<strong><p><img src="images/parsing-model-overview.svg" alt=""></p></strong></code></pre>
<p>In these cases, it would be wrong to include alternative text that consists of just a caption.
If a caption is to be included, then either the <code data-x="attr-title">title</code> attribute
can be used, or the <code>figure</code> and <code>figcaption</code> elements can be used. In the
latter case, the image would in fact be a phrase or paragraph with an alternative graphical
representation, and would thus require alternative text.</p>
<pre><code class="html"><!-- Using the title="" attribute -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<p><strong><img src="images/parsing-model-overview.svg" alt=""
title="Flowchart representation of the parsing model."></strong></p></code></pre>
<pre><code class="html"><!-- Using <figure> and <figcaption> -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<figure>
<strong><img src="images/parsing-model-overview.svg" alt="The Network leads to
the Input Stream Preprocessor, which leads to the Tokenizer, which
leads to the Tree Construction stage. The Tree Construction stage
leads to two items. The first is Script Execution, which leads via
document.write() back to the Tokenizer. The second item from which
Tree Construction leads is the DOM. The DOM is related to the Script
Execution."></strong>
<figcaption>Flowchart representation of the parsing model.</figcaption>
</figure></code></pre>
<pre class="bad"><code class="html"><!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<p><img src="images/parsing-model-overview.svg"
alt="Flowchart representation of the parsing model."></p>
<!-- Never put the image's caption in the alt="" attribute! --></code></pre>
</div>
<div class="example">
<p>A graph that repeats the previous paragraph in graphical form:</p>
<pre><code class="html"><p>According to a study covering several billion pages,
about 62% of documents on the web in 2007 triggered the Quirks
rendering mode of web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</p>
<strong><p><img src="rendering-mode-pie-chart.png" alt=""></p></strong></code></pre>
</div>
<h6>Ancillary images</h6>
<p>Sometimes, an image is not critical to the content, but is nonetheless neither purely
decorative nor entirely redundant with the text. In these cases, the <code
data-x="attr-img-alt">alt</code> attribute must be present, and its value should either be the
empty string, or a textual representation of the information that the image conveys. If the image
has a caption giving the image's title, then the <code data-x="attr-img-alt">alt</code>
attribute's value must not be empty (as that would be quite confusing for non-visual readers).</p>
<div class="example">
<p>Consider a news article about a political figure, in which the individual's face was shown in
an image. The image is not purely decorative, as it is relevant to the story. The image is not
entirely redundant with the story either, as it shows what the politician looks like. Whether
any alternative text need be provided is an authoring decision, decided by whether the image
influences the interpretation of the prose.</p>
<p>In this first variant, the image is shown without context, and no alternative text is
provided:</p>
<pre><code class="html"><p><strong><img src="president.jpeg" alt=""></strong> Ahead of today's referendum,
the President wrote an open letter to all registered voters. In it, she admitted that the country was
divided.</p></code></pre>
<p>If the picture is just a face, there might be no value in describing it. It's of no interest
to the reader whether the individual has red hair or blond hair, whether the individual has white
skin or black skin, whether the individual has one eye or two eyes.</p>
<p>However, if the picture is more dynamic, for instance showing the politician as angry, or
particularly happy, or devastated, some alternative text would be useful in setting the tone of
the article, a tone that might otherwise be missed:</p>
<pre><code class="html"><p><strong><img src="president.jpeg" alt="The President is sad."></strong>
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</p></code></pre>
<pre><code class="html"><p><strong><img src="president.jpeg" alt="The President is happy!"></strong>
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</p></code></pre>
<p>Whether the individual was "sad" or "happy" makes a difference to how the rest of the
paragraph is to be interpreted: is she likely saying that she is unhappy with the country
being divided, or is she saying that the prospect of a divided country is good for her
political career? The interpretation varies based on the image.</p>
</div>
<div class="example">
<p>If the image has a caption, then including alternative text avoids leaving the non-visual user
confused as to what the caption refers to.</p>
<pre><code class="html"><p>Ahead of today's referendum, the President wrote an open letter to
all registered voters. In it, she admitted that the country was divided.</p>
<strong><figure>
<img src="president.jpeg"
alt="A high forehead, cheerful disposition, and dark hair round out the President's face.">
<figcaption> The President of Ruritania. Photo © 2014 PolitiPhoto. </figcaption>
</figure></strong></code></pre>
</div>
<h6>A purely decorative image that doesn't add any information</h6>
<p>If an image is decorative but isn't especially page-specific — for example an image that
forms part of a site-wide design scheme — the image should be specified in the site's CSS,
not in the markup of the document.</p>
<p>However, a decorative image that isn't discussed by the surrounding text but still has some
relevance can be included in a page using the <code>img</code> element. Such images are
decorative, but still form part of the content. In these cases, the <code
data-x="attr-img-alt">alt</code> attribute must be present but its value must be the empty
string.</p>
<div class="example">
<p>Examples where the image is purely decorative despite being relevant would include things like
a photo of the Black Rock City landscape in a blog post about an event at Burning Man, or an
image of a painting inspired by a poem, on a page reciting that poem. The following snippet shows
an example of the latter case (only the first verse is included in this snippet):</p>
<pre><code class="html"><h1>The Lady of Shalott</h1>
<strong><p><img src="shalott.jpeg" alt=""></p></strong>
<p>On either side the river lie<br>
Long fields of barley and of rye,<br>
That clothe the wold and meet the sky;<br>
And through the field the road run by<br>
To many-tower'd Camelot;<br>
And up and down the people go,<br>
Gazing where the lilies blow<br>
Round an island there below,<br>
The island of Shalott.</p></code></pre>
</div>
<h6>A group of images that form a single larger picture with no links</h6>
<p>When a picture has been sliced into smaller image files that are then displayed together to
form the complete picture again, one of the images must have its <code
data-x="attr-img-alt">alt</code> attribute set as per the relevant rules that would be appropriate
for the picture as a whole, and then all the remaining images must have their <code
data-x="attr-img-alt">alt</code> attribute set to the empty string.</p>
<div class="example">
<p>In the following example, a picture representing a company logo for <span data-x="">XYZ
Corp</span> has been split into two pieces, the first containing the letters "XYZ" and the second
with the word "Corp". The alternative text ("XYZ Corp") is all in the first image.</p>
<pre><code class="html"><h1><strong><img src="logo1.png" alt="XYZ Corp"><img src="logo2.png" alt=""></strong></h1></code></pre>
</div>
<div class="example">
<p>In the following example, a rating is shown as three filled stars and two empty stars. While
the alternative text could have been "★★★☆☆", the author has
instead decided to more helpfully give the rating in the form "3 out of 5". That is the
alternative text of the first image, and the rest have blank alternative text.</p>
<pre><code class="html"><p>Rating: <meter max=5 value=3><strong><img src="1" alt="3 out of 5"
><img src="1" alt=""><img src="1" alt=""><img src="0" alt=""
><img src="0" alt=""></strong></meter></p></code></pre>
</div>
<h6>A group of images that form a single larger picture with links</h6>
<p>Generally, <span data-x="image map">image maps</span> should be used instead of slicing an image
for links.</p>
<p>However, if an image is indeed sliced and any of the components of the sliced picture are the
sole contents of links, then one image per link must have alternative text in its <code
data-x="attr-img-alt">alt</code> attribute representing the purpose of the link.</p>
<div class="example">
<p>In the following example, a picture representing the flying spaghetti monster emblem, with
each of the left noodly appendages and the right noodly appendages in different images, so that
the user can pick the left side or the right side in an adventure.</p>
<pre><code class="html"><h1>The Church</h1>
<p>You come across a flying spaghetti monster. Which side of His
Noodliness do you wish to reach out for?</p>
<strong><p><a href="?go=left" ><img src="fsm-left.png" alt="Left side. "></a
><img src="fsm-middle.png" alt=""
><a href="?go=right"><img src="fsm-right.png" alt="Right side."></a></p></strong></code></pre>
</div>
<h6>A key part of the content</h6>
<p>In some cases, the image is a critical part of the content. This could be the case, for
instance, on a page that is part of a photo gallery. The image is the whole <em>point</em> of the
page containing it.</p>
<p>How to provide alternative text for an image that is a key part of the content depends on the
image's provenance.</p>
<dl>
<dt>The general case</dt>
<dd>
<p>When it is possible for detailed alternative text to be provided, for example if the image is
part of a series of screenshots in a magazine review, or part of a comic strip, or is a
photograph in a blog entry about that photograph, text that can serve as a substitute for the
image must be given as the contents of the <code data-x="attr-img-alt">alt</code> attribute.</p>
<div class="example">
<p>A screenshot in a gallery of screenshots for a new OS, with some alternative text:</p>
<pre><code class="html"><figure>
<strong><img src="KDE%20Light%20desktop.png"
alt="The desktop is blue, with icons along the left hand side in
two columns, reading System, Home, K-Mail, etc. A window is
open showing that menus wrap to a second line if they
cannot fit in the window. The window has a list of icons
along the top, with an address bar below it, a list of
icons for tabs along the left edge, a status bar on the
bottom, and two panes in the middle. The desktop has a bar
at the bottom of the screen with a few buttons, a pager, a
list of open applications, and a clock."></strong>
<figcaption>Screenshot of a KDE desktop.</figcaption>
</figure></code></pre>
</div>
<div class="example">
<p>A graph in a financial report:</p>
<pre><code class="html"><strong><img src="sales.gif"
title="Sales graph"
alt="From 1998 to 2005, sales increased by the following percentages
with each year: 624%, 75%, 138%, 40%, 35%, 9%, 21%"></strong></code></pre>
<p>Note that "sales graph" would be inadequate alternative text for a sales graph. Text that
would be a good <em>caption</em> is not generally suitable as replacement text.</p>
</div>
</dd>
<dt>Images that defy a complete description</dt>
<dd>
<p>In certain cases, the nature of the image might be such that providing thorough alternative
text is impractical. For example, the image could be indistinct, or could be a complex fractal,
or could be a detailed topographical map.</p>
<p>In these cases, the <code data-x="attr-img-alt">alt</code> attribute must contain some
suitable alternative text, but it may be somewhat brief.</p>
<div class="example">
<p>Sometimes there simply is no text that can do justice to an image. For example, there is
little that can be said to usefully describe a Rorschach inkblot test. However, a description,
even if brief, is still better than nothing:</p>
<pre><code class="html"><figure>
<strong><img src="/commons/a/a7/Rorschach1.jpg" alt="A shape with left-right
symmetry with indistinct edges, with a small gap in the center, two
larger gaps offset slightly from the center, with two similar gaps
under them. The outline is wider in the top half than the bottom
half, with the sides extending upwards higher than the center, and
the center extending below the sides."></strong>
<figcaption>A black outline of the first of the ten cards
in the Rorschach inkblot test.</figcaption>
</figure></code></pre>
<p>Note that the following would be a very bad use of alternative text:</p>
<pre class="bad"><code class="html"><!-- This example is wrong. Do not copy it. -->
<figure>
<img src="/commons/a/a7/Rorschach1.jpg" alt="A black outline
of the first of the ten cards in the Rorschach inkblot test.">
<figcaption>A black outline of the first of the ten cards
in the Rorschach inkblot test.</figcaption>
</figure></code></pre>
<p>Including the caption in the alternative text like this isn't useful because it effectively
duplicates the caption for users who don't have images, taunting them twice yet not helping
them any more than if they had only read or heard the caption once.</p>
</div>
<div class="example">
<p>Another example of an image that defies full description is a fractal, which, by definition,
is infinite in detail.</p>
<p>The following example shows one possible way of providing alternative text for the full view
of an image of the Mandelbrot set.</p>
<pre><code class="html"><strong><img src="ms1.jpeg" alt="The Mandelbrot set appears as a cardioid with
its cusp on the real axis in the positive direction, with a smaller
bulb aligned along the same center line, touching it in the negative
direction, and with these two shapes being surrounded by smaller bulbs
of various sizes."></strong></code></pre>
</div>
<div class="example">
<p>Similarly, a photograph of a person's face, for example in a biography, can be considered
quite relevant and key to the content, but it can be hard to fully substitute text for:</p>
<pre><code class="html"><section class="bio">
<h1>A Biography of Isaac Asimov</h1>
<p>Born <b>Isaak Yudovich Ozimov</b> in 1920, Isaac was a prolific author.</p>
<p><img src="headpics/asimov.jpeg" alt="Isaac Asimov had dark hair, a tall forehead, and wore glasses.
Later in life, he wore long white sideburns."></p>
<p>Asimov was born in Russia, and moved to the US when he was three years old.</p>
<p>...</p>
</section></code></pre>
<p>In such cases it is unnecessary (and indeed discouraged) to include a reference to the
presence of the image itself in the alternative text, since such text would be redundant with
the browser itself reporting the presence of the image. For example, if the alternative text
was "A photo of Isaac Asimov", then a conforming user agent might read that out as "(Image) A
photo of Isaac Asimov" rather than the more useful "(Image) Isaac Asimov had dark hair, a tall
forehead, and wore glasses...".</p>
</div>
</dd>
<dt id="unknown-images">Images whose contents are not known</dt>
<dd>
<p>In some unfortunate cases, there might be no alternative text available at all, either
because the image is obtained in some automated fashion without any associated alternative text
(e.g., a webcam), or because the page is being generated by a script using user-provided images
where the user did not provide suitable or usable alternative text (e.g. photograph sharing
sites), or because the author does not themself know what the images represent (e.g. a blind
photographer sharing an image on their blog).</p>
<p>In such cases, the <code data-x="attr-img-alt">alt</code> attribute may be omitted, but one of
the following conditions must be met as well:</p>
<ul>
<!-- when editing this list, search for the two other occurrences of 'critical-no-alt' -->
<!-- NOTE: the order of these steps is important; it's intended to encourage using <figcaption>
rather than data-x="" -->
<li id="figcaption-as-alt-condition"><p>The <code>img</code> element is in a
<code>figure</code> element that contains a <code>figcaption</code> element that contains
content other than <span>inter-element whitespace</span>, and, ignoring the
<code>figcaption</code> element and its descendants, the <code>figure</code> element has no
<span>flow content</span> descendants other than <span>inter-element whitespace</span> and the
<code>img</code> element.</p></li>
<li>
<p>The <code data-x="attr-title">title</code> attribute is present and has a non-empty
value.</p>
<!-- search for title-warning if modifying this paragraph -->
<p class="note">Relying on the <code data-x="attr-title">title</code> attribute is currently
discouraged as many user agents do not expose the attribute in an accessible manner as
required by this specification (e.g. requiring a pointing device such as a mouse to cause a
tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone
with a modern phone or tablet).</p>
</li>
</ul>
<p class="note">Such cases are to be kept to an absolute minimum. If there is even the slightest
possibility of the author having the ability to provide real alternative text, then it would not
be acceptable to omit the <code data-x="attr-img-alt">alt</code> attribute.</p>
<div class="example">
<p>A photo on a photo-sharing site, if the site received the image with no metadata other than
the caption, could be marked up as follows:</p>
<pre><code class="html"><figure>
<strong><img src="1100670787_6a7c664aef.jpg"></strong>
<figcaption>Bubbles traveled everywhere with us.</figcaption>
</figure></code></pre>
<p>It would be better, however, if a detailed description of the important parts of the image
obtained from the user and included on the page.</p>
</div>
<div class="example">
<p>A blind user's blog in which a photo taken by the user is shown. Initially, the user might
not have any idea what the photo they took shows:</p>
<pre><code class="html"><article>
<h1>I took a photo</h1>
<p>I went out today and took a photo!</p>
<figure>
<strong><img src="photo2.jpeg"></strong>
<figcaption>A photograph taken blindly from my front porch.</figcaption>
</figure>
</article></code></pre>
<p>Eventually though, the user might obtain a description of the image from their friends and
could then include alternative text:</p>
<pre><code class="html"><article>
<h1>I took a photo</h1>
<p>I went out today and took a photo!</p>
<figure>
<strong><img src="photo2.jpeg" alt="The photograph shows my squirrel
feeder hanging from the edge of my roof. It is half full, but there
are no squirrels around. In the background, out-of-focus trees fill the
shot. The feeder is made of wood with a metal grate, and it contains
peanuts. The edge of the roof is wooden too, and is painted white
with light blue streaks."></strong>
<figcaption>A photograph taken blindly from my front porch.</figcaption>
</figure>
</article></code></pre>
</div>
<div class="example">
<p>Sometimes the entire point of the image is that a textual description is not available, and
the user is to provide the description. For instance, the point of a CAPTCHA image is to see if
the user can literally read the graphic. Here is one way to mark up a CAPTCHA (note the <code
data-x="attr-title">title</code> attribute):</p>
<pre><code class="html"><p><label>What does this image say?
<strong><img src="captcha.cgi?id=8934" title="CAPTCHA"></strong>
<input type=text name=captcha></label>
(If you cannot see the image, you can use an <a
href="?audio">audio</a> test instead.)</p></code></pre>
<p>Another example would be software that displays images and asks for alternative text
precisely for the purpose of then writing a page with correct alternative text. Such a page
could have a table of images, like this:</p>
<pre><code class="html"><table>
<thead>
<tr> <th> Image <th> Description
<tbody>
<tr>
<td> <strong><img src="2421.png" title="Image 640 by 100, filename 'banner.gif'"></strong>
<td> <input name="alt2421">
<tr>
<td> <strong><img src="2422.png" title="Image 200 by 480, filename 'ad3.gif'"></strong>
<td> <input name="alt2422">
</table></code></pre>
<p>Notice that even in this example, as much useful information as possible is still included
in the <code data-x="attr-title">title</code> attribute.</p>
</div>
<p class="note">Since some users cannot use images at all (e.g. because they have a very slow
connection, or because they are using a text-only browser, or because they are listening to the
page being read out by a hands-free automobile voice web browser, or simply because they are
blind), the <code data-x="attr-img-alt">alt</code> attribute is only allowed to be omitted rather
than being provided with replacement text when no alternative text is available and none can be
made available, as in the above examples. Lack of effort from the part of the author is not an
acceptable reason for omitting the <code data-x="attr-img-alt">alt</code> attribute.</p>
</dd>
</dl>
<h6>An image not intended for the user</h6>
<p>Generally authors should avoid using <code>img</code> elements for purposes other than showing
images.</p>
<p>If an <code>img</code> element is being used for purposes other than showing an image, e.g. as
part of a service to count page views, then the <code data-x="attr-img-alt">alt</code> attribute
must be the empty string.</p>
<p>In such cases, the <code data-x="attr-dim-width">width</code> and <code
data-x="attr-dim-height">height</code> attributes should both be set to zero.</p>
<h6 id="an-image-in-an-e-mail-or-private-document-intended-for-a-specific-person-who-is-known-to-be-able-to-view-images">An image in an email or private document intended for a specific person who is known to be able to view images</h6>
<p><i>This section does not apply to documents that are publicly accessible, or whose target
audience is not necessarily personally known to the author, such as documents on a web site,
emails sent to public mailing lists, or software documentation.</i></p>
<p>When an image is included in a private communication (such as an HTML email) aimed at a
specific person who is known to be able to view images, the <code data-x="attr-img-alt">alt</code>
attribute may be omitted. However, even in such cases authors are strongly urged to include
alternative text (as appropriate according to the kind of image involved, as described in the
above entries), so that the email is still usable should the user use a mail client that does not
support images, or should the document be forwarded on to other users whose abilities might not
include easily seeing images.</p>
<div w-nodev>
<h6>Guidance for markup generators</h6>
<p>Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain
alternative text from their users. However, it is recognized that in many cases, this will not be
possible.</p>
<p>For images that are the sole contents of links, markup generators should examine the link
target to determine the title of the target, or the URL of the target, and use information
obtained in this manner as the alternative text.</p>
<p>For images that have captions, markup generators should use the <code>figure</code> and
<code>figcaption</code> elements, or the <code data-x="attr-title">title</code> attribute, to
provide the image's caption.</p>
<p>As a last resort, implementers should either set the <code data-x="attr-img-alt">alt</code>
attribute to the empty string, under the assumption that the image is a purely decorative image
that doesn't add any information but is still specific to the surrounding content, or omit the
<code data-x="attr-img-alt">alt</code> attribute altogether, under the assumption that the image is
a key part of the content.</p>
<p>Markup generators may specify a <dfn><code data-x="attr-img-generator-unable-to-provide-required-alt">generator-unable-to-provide-required-alt</code></dfn>
attribute on <code>img</code> elements for which they have been unable to obtain alternative text
and for which they have therefore omitted the <code data-x="attr-img-alt">alt</code> attribute. The
value of this attribute must be the empty string. Documents containing such attributes are not
conforming, but conformance checkers will <a href="#guidance-for-conformance-checkers">silently
ignore</a> this error.</p>
<p class="note">This is intended to avoid markup generators from being pressured into replacing
the error of omitting the <code data-x="attr-img-alt">alt</code> attribute with the even more
egregious error of providing phony alternative text, because state-of-the-art automated
conformance checkers cannot distinguish phony alternative text from correct alternative text.</p>
<p>Markup generators should generally avoid using the image's own filename as the alternative
text. Similarly, markup generators should avoid generating alternative text from any content that
will be equally available to presentation user agents (e.g., web browsers).</p>
<p class="note">This is because once a page is generated, it will typically not be updated,
whereas the browsers that later read the page can be updated by the user, therefore the browser is
likely to have more up-to-date and finely-tuned heuristics than the markup generator did when
generating the page.</p>
</div>
<div w-nodev>
<h6 id="guidance-for-conformance-checkers">Guidance for conformance checkers</h6>
<p>A conformance checker must report the lack of an <code data-x="attr-img-alt">alt</code>
attribute as an error unless one of the conditions listed below applies:</p>
<ul>
<!-- when editing this list, search for the two other occurrences of 'critical-no-alt' -->
<li><p>The <code>img</code> element is in a <code>figure</code> element that satisfies <a
href="#figcaption-as-alt-condition">the conditions described above</a>.</p></li>
<li><p>The <code>img</code> element has a <code data-x="attr-title">title</code> attribute with a
value that is not the empty string (also as <a href="#unknown-images">described
above</a>).</p></li>
<!-- the following are additional entries not included in the aforementioned list, as they apply
only to conformance checkers -->
<li><p>The conformance checker has been configured to assume that the document is an email or
document intended for a specific person who is known to be able to view images.</p></li>
<li><p>The <code>img</code> element has a (non-conforming) <code
data-x="attr-img-generator-unable-to-provide-required-alt">generator-unable-to-provide-required-alt</code>
attribute whose value is the empty string. A conformance checker that is not reporting the lack
of an <code data-x="attr-img-alt">alt</code> attribute as an error must also not report the
presence of the empty <code
data-x="attr-img-generator-unable-to-provide-required-alt">generator-unable-to-provide-required-alt</code>
attribute as an error. (This case does not represent a case where the document is conforming,
only that the generator could not determine appropriate alternative text — validators are
not required to show an error in this case, because such an error might encourage markup
generators to include bogus alternative text purely in an attempt to silence validators.
Naturally, conformance checkers <em>may</em> report the lack of an <code
data-x="attr-img-alt">alt</code> attribute as an error even in the presence of the <code
data-x="attr-img-generator-unable-to-provide-required-alt">generator-unable-to-provide-required-alt</code>
attribute; for example, there could be a user option to report <em>all</em> conformance errors
even those that might be the more or less inevitable result of using a markup
generator.)</p></li>
</ul>
</div>
<h4 split-filename="iframe-embed-object">The
<dfn element><code>iframe</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-iframe-src">src</code></dd>
<dd><code data-x="attr-iframe-srcdoc">srcdoc</code></dd>
<dd><code data-x="attr-iframe-name">name</code></dd>
<dd><code data-x="attr-iframe-sandbox">sandbox</code></dd>
<dd><code data-x="attr-iframe-allow">allow</code></dd>
<dd><code data-x="attr-iframe-allowfullscreen">allowfullscreen</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dd><code data-x="attr-iframe-referrerpolicy">referrerpolicy</code></dd>
<dd><code data-x="attr-iframe-loading">loading</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-iframe">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-iframe">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-iframe-src">src</span>;
[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) <span data-x="dom-iframe-srcdoc">srcdoc</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-name">name</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-iframe-sandbox">sandbox</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-allow">allow</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-iframe-allowFullscreen">allowFullscreen</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-width">width</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-height">height</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-referrerPolicy">referrerPolicy</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-loading">loading</span>;
readonly attribute <span>Document</span>? <span data-x="dom-iframe-contentDocument">contentDocument</span>;
readonly attribute <span>WindowProxy</span>? <span data-x="dom-iframe-contentWindow">contentWindow</span>;
<span>Document</span>? <span data-x="dom-media-getSVGDocument">getSVGDocument</span>();
// <a href="#HTMLIFrameElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLIFrameElement</code>.</dd>
</dl>
<!-- INTRO -->
<p>The <code>iframe</code> element <span>represents</span> its <span>content navigable</span>.</p>
<!-- SRC/SRCDOC -->
<p>The <dfn element-attr for="iframe"><code data-x="attr-iframe-src">src</code></dfn> attribute
gives the <span>URL</span> of a page that the element's <span>content navigable</span> is to
contain. The attribute, if present, must be a <span>valid non-empty URL potentially surrounded by
spaces</span>. If the <code data-x="attr-itemprop">itemprop</code> attribute is specified on an
<code>iframe</code> element, then the <code data-x="attr-iframe-src">src</code> attribute must
also be specified.</p>
<p>The <dfn for="iframe" element-attr><code data-x="attr-iframe-srcdoc">srcdoc</code></dfn>
attribute gives the content of the page that the element's <span>content navigable</span> is to
contain. The value of the attribute is used to <span data-x="create navigation params from a
srcdoc resource">construct</span> <dfn export>an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</dfn>, which is a <code>Document</code> whose
<span data-x="concept-document-url">URL</span> <span>matches <code>about:srcdoc</code></span>.</p>
<p>The <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute, if present, must have a value
using <span>the HTML syntax</span> that consists of the following syntactic components, in the
given order:</p>
<ol>
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
<li>Optionally, a <span data-x="syntax-doctype">DOCTYPE</span>.
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
<li>The <span>document element</span>, in the form of an <code>html</code> <span
data-x="syntax-elements">element</span>.</li>
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
</ol>
<p class="note">The above requirements apply in <span>XML documents</span> as well.
<div class="example">
<p>Here a blog uses the <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute in conjunction
with the <code data-x="attr-iframe-sandbox">sandbox</code> attribute described below to provide
users of user agents that support this feature with an extra layer of protection from script
injection in the blog post comments:</p>
<pre><code class="html"><article>
<h1>I got my own magazine!</h1>
<p>After much effort, I've finally found a publisher, and so now I
have my own magazine! Isn't that awesome?! The first issue will come
out in September, and we have articles about getting food, and about
getting in boxes, it's going to be great!</p>
<footer>
<p>Written by <a href="/users/cap">cap</a>, 1 hour ago.
</footer>
<article>
<footer> Thirteen minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
<iframe sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
</article>
<article>
<footer> Nine minutes ago, <a href="/users/cap">cap</a> wrote: </footer>
<iframe sandbox srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
</article>
<article>
<footer> Five minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
<iframe sandbox srcdoc="<p>hey that's earl's table.
<p>you should get earl&amp;amp;me on the next cover."></iframe>
</article></code></pre>
<p>Notice the way that quotes have to be escaped (otherwise the <code
data-x="attr-iframe-srcdoc">srcdoc</code> attribute would end prematurely), and the way raw
ampersands (e.g. in URLs or in prose) mentioned in the sandboxed content have to be
<em>doubly</em> escaped — once so that the ampersand is preserved when originally parsing
the <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute, and once more to prevent the
ampersand from being misinterpreted when parsing the sandboxed content.</p>
<p>Furthermore, notice that since the <span data-x="syntax-doctype">DOCTYPE</span> is optional in
<span data-x="an iframe srcdoc document"><code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> documents</span>, and the <code>html</code>,
<code>head</code>, and <code>body</code> elements have <a href="#syntax-tag-omission">optional
start and end tags</a>, and the <code>title</code> element is also optional in <span data-x="an iframe
srcdoc document"><code>iframe</code> <code data-x="attr-iframe-srcdoc">srcdoc</code>
documents</span>, the markup in a <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute can be
relatively succinct despite representing an entire document, since only the contents of the
<code>body</code> element need appear literally in the syntax. The other elements are still
present, but only by implication.</p>
</div>
<p class="note">In <span>the HTML syntax</span>, authors need only remember to use U+0022
QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0026
AMPERSAND (&) and U+0022 QUOTATION MARK (") characters, and to specify the <code
data-x="attr-iframe-sandbox">sandbox</code> attribute, to ensure safe embedding of content. (And
remember to escape ampersands before quotation marks, to ensure quotation marks become &quot;
and not &amp;quot;.)</p>
<p class="note">In XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In
order to prevent <a href="https://www.w3.org/TR/xml/#AVNormalize">attribute-value
normalization</a>, some of XML's whitespace characters — specifically U+0009 CHARACTER
TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be
escaped. <ref>XML</ref></p>
<p class="note">If the <code data-x="attr-iframe-src">src</code> attribute and the <code
data-x="attr-iframe-srcdoc">srcdoc</code> attribute are both specified together, the <code
data-x="attr-iframe-srcdoc">srcdoc</code> attribute takes priority. This allows authors to provide
a fallback <span>URL</span> for legacy user agents that do not support the <code
data-x="attr-iframe-srcdoc">srcdoc</code> attribute.</p>
<div w-nodev>
<hr> <!-- SRC/SRCDOC PROCESSING MODEL -->
<p>The <code>iframe</code> <span>HTML element post-connection steps</span>, given
<var>insertedNode</var>, are:</p>
<ol>
<li><p><span>Create a new child navigable</span> for <var>insertedNode</var>.</p></li>
<li><p>If <var>insertedNode</var> has a <code data-x="attr-iframe-sandbox">sandbox</code>
attribute, then <span data-x="parse a sandboxing directive">parse the sandboxing
directive</span> given the attribute's value and <var>insertedNode</var>'s
<span><code>iframe</code> sandboxing flag set</span>.</p></li>
<li><p><span>Process the <code>iframe</code> attributes</span> for <var>insertedNode</var>, with
<var data-x="process-iframe-initial-insertion">initialInsertion</var> set to true.</p></li>
</ol>
<p>The <code>iframe</code> <span>HTML element removing steps</span>, given
<var>removedNode</var>, are to <span>destroy a child navigable</span> given
<var>removedNode</var>.</p>
<p class="note">This happens without any <code data-x="event-unload">unload</code> events firing
(the element's <span>content document</span> is <em><span data-x="destroy a child
navigable">destroyed</span></em>, not <em><span data-x="unload a
document">unloaded</span></em>).</p>
<p class="XXX">Although <code>iframe</code>s are processed while in a <span>shadow tree</span>,
per the above, several other aspects of their behavior are not well-defined with regards to
shadow trees. See <a href="https://github.com/whatwg/html/issues/763">issue #763</a> for more
detail.</p>
<!-- START of section that's very similar to <frame> -->
<p>Whenever an <code>iframe</code> element with a non-null <span>content navigable</span> has its
<code data-x="attr-iframe-srcdoc">srcdoc</code> attribute set, changed, or removed, the user
agent must <span>process the <code>iframe</code> attributes</span>.</p>
<p>Similarly, whenever an <code>iframe</code> element with a non-null <span>content
navigable</span> but with no <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute specified
has its <code data-x="attr-iframe-src">src</code> attribute set, changed, or removed, the user
agent must <span>process the <code>iframe</code> attributes</span>.</p> <!-- It doesn't happen
when the base URL is changed, though. -->
<p>To <dfn>process the <code>iframe</code> attributes</dfn> for an element <var>element</var>,
with an optional boolean <dfn
data-x="process-iframe-initial-insertion"><var>initialInsertion</var></dfn> (default false):</p>
<ol>
<li>
<p>If <var>element</var>'s <code data-x="attr-iframe-srcdoc">srcdoc</code> attribute is
specified, then:</p>
<ol>
<li><p>Set <var>element</var>'s <span>current navigation was lazy loaded</span> boolean to
false.</p></li>
<li>
<p>If the <span>will lazy load element steps</span> given <var>element</var> return true,
then:</p>
<ol>
<li><p>Set <var>element</var>'s <span>lazy load resumption steps</span> to the rest of this
algorithm starting with the step labeled <i>navigate to the srcdoc resource</i>.</p></li>
<li><p>Set <var>element</var>'s <span>current navigation was lazy loaded</span> boolean to
true.</p></li>
<li><p><span>Start intersection-observing a lazy loading element</span> for
<var>element</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p><i>Navigate to the srcdoc resource</i>: <span>Navigate an <code>iframe</code> or
<code>frame</code></span> given <var>element</var>, <code>about:srcdoc</code>, the empty
string, and the value of <var>element</var>'s <code data-x="attr-iframe-srcdoc">srcdoc</code>
attribute.</p>
<p>The resulting <code>Document</code> must be considered <span>an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span>.</p>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>url</var> be the result of running the <span>shared attribute processing steps
for <code>iframe</code> and <code>frame</code> elements</span> given <var>element</var> and
<var>initialInsertion</var>.</p></li>
<li><p>If <var>url</var> is null, then return.</p></li>
<li>
<p>If <var>url</var> <span>matches <code>about:blank</code></span> and
<var>initialInsertion</var> is true, then:</p>
<ol>
<li><p>Run the <span>iframe load event steps</span> given <var>element</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>referrerPolicy</var> be the current state of <var>element</var>'s <code
data-x="attr-iframe-referrerpolicy">referrerpolicy</code> content attribute.</p></li>
<li><p>Set <var>element</var>'s <span>current navigation was lazy loaded</span> boolean to
false.</p></li>
<li>
<p>If the <span>will lazy load element steps</span> given <var>element</var> return true,
then:</p>
<ol>
<li><p>Set <var>element</var>'s <span>lazy load resumption steps</span> to the rest of this
algorithm starting with the step labeled <i>navigate</i>.</p></li>
<li><p>Set <var>element</var>'s <span>current navigation was lazy loaded</span> boolean to
true.</p></li>
<li><p><span>Start intersection-observing a lazy loading element</span> for
<var>element</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p><i>Navigate</i>: <span>Navigate an <code>iframe</code> or <code>frame</code></span>
given <var>element</var>, <var>url</var>, and <var>referrerPolicy</var>.</p></li>
</ol>
</li>
</ol>
<p id="otherwise-steps-for-iframe-or-frame-elements">The <dfn>shared attribute processing steps
for <code>iframe</code> and <code>frame</code> elements</dfn>, given an element
<var>element</var> and a boolean <var>initialInsertion</var>, are:</p>
<ol>
<li><p>Let <var>url</var> be the <span>URL record</span> <code>about:blank</code>.</p></li>
<li>
<p>If <var>element</var> has a <code data-x="attr-iframe-src">src</code> attribute specified,
and its value is not the empty string, then:</p>
<ol>
<li><p>Let <var>maybeURL</var> be the result of <span>encoding-parsing a URL</span> given that
attribute's value, relative to <var>element</var>'s <span>node document</span>.</p></li>
<li><p>If <var>maybeURL</var> is not failure, then set <var>url</var> to
<var>maybeURL</var>.</p></li>
</ol>
</li>
<li><p>If the <span>inclusive ancestor navigables</span> of <var>element</var>'s <span>node
navigable</span> contains a <span>navigable</span> whose <span data-x="nav-document">active
document</span>'s <span data-x="concept-document-url">URL</span> <span
data-x="concept-url-equals">equals</span> <var>url</var> with <i data-x="url equals exclude
fragments">exclude fragments</i> set to true, then return null.</p></li>
<!-- https://www.hixie.ch/tests/adhoc/html/frames/iframes/ 008.html and 009.html -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1969 -->
<li>
<p>If <var>url</var> <span>matches <code>about:blank</code></span> and
<var>initialInsertion</var> is true, then perform the <span>URL and history update steps</span>
given <var>element</var>'s <span>content navigable</span>'s <span data-x="nav-document">active
document</span> and <var>url</var>.</p>
<p class="note">This is necessary in case <var>url</var> is something like <code
data-x="">about:blank?foo</code>. If <var>url</var> is just plain <code
data-x="">about:blank</code>, this will do nothing.</p>
</li>
<li><p>Return <var>url</var>.</p></li>
</ol>
<p>To <dfn>navigate an <code>iframe</code> or <code>frame</code></dfn> given an element
<var>element</var>, a <span>URL</span> <var>url</var>, a <span>referrer policy</span>
<var>referrerPolicy</var>, and an optional string-or-null <var>srcdocString</var> (default
null):</p>
<ol>
<li><p>Let <var>historyHandling</var> be "<code
data-x="NavigationHistoryBehavior-auto">auto</code>".</p>
<li><p>If <var>element</var>'s <span>content navigable</span>'s <span
data-x="nav-document">active document</span> is not <span>completely loaded</span>, then set
<var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li><p>If <var>element</var> is an <code>iframe</code>, then set <var>element</var>'s <span
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</span> to
the <span>current high resolution time</span> given <var>element</var>'s
<span>node document</span>'s <span>relevant global object</span>.</p></li>
<li><p><span>Navigate</span><!--DONAV iframe or frame--> <var>element</var>'s <span>content
navigable</span> to <var>url</var> using <var>element</var>'s <span>node document</span>, with
<i data-x="navigation-hh">historyHandling</i> set to <var>historyHandling</var>, <i
data-x="navigation-referrer-policy">referrerPolicy</i> set to <var>referrerPolicy</var>, and <i
data-x="navigation-resource">documentResource</i> set to <var>srcdocString</var>.</p></li>
</ol>
<p>Each <code>Document</code> has an <dfn>iframe load in progress</dfn> flag and a <dfn>mute
iframe load</dfn> flag. When a <code>Document</code> is created, these flags must be unset for
that <code>Document</code>.</p>
<p>To run the <dfn>iframe load event steps</dfn>, given an <code>iframe</code> element
<var>element</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var>'s <span>content navigable</span> is not
null.</p></li>
<li><p>Let <var>childDocument</var> be <var>element</var>'s <span>content navigable</span>'s
<span data-x="nav-document">active document</span>.</p></li>
<li><p>If <var>childDocument</var> has its <span>mute iframe load</span> flag set, then
return.</p></li>
<li>
<p>If <var>element</var>'s <span
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</span> is
not null, then:</p>
<ol>
<li><p>Let <var>global</var> be <var>element</var>'s <span>node document</span>'s
<span>relevant global object</span>.</p></li>
<li><p>Let <var>fallbackTimingInfo</var> be a new <span
data-x="fetch-timing-info">fetch timing info</span> whose <span
data-x="fetch-timing-info-start-time">start time</span> is <var>element</var>'s <span
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</span>
and whose <span data-x="fetch-timing-info-end-time">response end time</span> is the
<span>current high resolution time</span> given <var>global</var>.</p></li>
<li><p><span>Mark resource timing</span> given <var>fallbackTimingInfo</var>, <var>url</var>,
"<code>iframe</code>", <var>global</var>, the empty string, a new
<span data-x="response-body-info">response body info</span>, and 0.</p></li>
<li><p>Set <var>element</var>'s <span
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</span>
to null.</p></li>
</ol>
</li>
<li><p>Set <var>childDocument</var>'s <span>iframe load in progress</span> flag.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at <var>element</var>.</p></li>
<li><p>Unset <var>childDocument</var>'s <span>iframe load in progress</span> flag.</p></li>
</ol>
<p class="warning">This, in conjunction with scripting, can be used to probe the URL space of the
local network's HTTP servers. User agents may implement <span data-x="origin">cross-origin</span>
access control policies that are stricter than those described above to mitigate this attack, but
unfortunately such policies are typically not compatible with existing web content.</p>
<p>If an element type <dfn>potentially delays the load event</dfn>, then for each element
<var>element</var> of that type, the user agent must <span>delay the load event</span> of
<var>element</var>'s <span>node document</span> if <var>element</var>'s <span>content
navigable</span> is non-null and any of the following are true:</p>
<ul>
<li><p><var>element</var>'s <span>content navigable</span>'s <span data-x="nav-document">active
document</span> is not <span>ready for post-load tasks</span>;</p></li>
<li><p><var>element</var>'s <span>content navigable</span>'s <span>is delaying <code
data-x="event-load">load</code> events</span> is true; or</p></li>
<li><p>anything is <span data-x="delay the load event">delaying the load event</span> of
<var>element</var>'s <span>content navigable</span>'s <span data-x="nav-document">active
document</span>.</p></li>
</ul>
<p class="note">If, during the handling of the <code data-x="event-load">load</code> event,
<var>element</var>'s <span>content navigable</span> is again <span
data-x="navigate">navigated</span>, that will further <span>delay the load event</span>.</p>
<p>Each <code>iframe</code> element has an associated <dfn>current navigation was lazy
loaded</dfn> boolean, initially false. It is set and unset in the <span>process the
<code>iframe</code> attributes</span> algorithm.</p>
<p>An <code>iframe</code> element whose <span>current navigation was lazy loaded</span> boolean is
false <span>potentially delays the load event</span>.</p>
<p>Each <code>iframe</code> element has an associated null or
<span><code>DOMHighResTimeStamp</code></span> <dfn
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</dfn>,
initially set to null.</p>
</div>
<!-- END of section that's very similar to <frame> -->
<p class="note">If, when the element is created, the <code
data-x="attr-iframe-srcdoc">srcdoc</code> attribute is not set, and the <code
data-x="attr-iframe-src">src</code> attribute is either also not set or set but its value cannot
be <span data-x="encoding-parsing a URL">parsed</span>, the element's <span>content
navigable</span> will remain at the <span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code>.</p>
<p class="note">If the user <span data-x="navigate">navigates</span> away from this page, the
<code>iframe</code>'s <span>content navigable</span>'s <span data-x="nav-wp">active
<code>WindowProxy</code></span> object will proxy new <code>Window</code> objects for new
<code>Document</code> objects, but the <code data-x="attr-iframe-src">src</code> attribute will
not change.</p>
<hr> <!-- NAME -->
<p>The <dfn element-attr for="iframe"><code data-x="attr-iframe-name">name</code></dfn>
attribute, if present, must be a <span>valid navigable target name</span>. The given value is
used to name the element's <span>content navigable</span> if present when that is <span
data-x="create a new child navigable">created</span>.</p>
<hr> <!-- SANDBOX -->
<p>The <dfn element-attr for="iframe"><code data-x="attr-iframe-sandbox">sandbox</code></dfn>
attribute, when specified, enables a set of extra restrictions on any content hosted by the
<code>iframe</code>. Its value must be an <span>unordered set of unique space-separated
tokens</span> that are <span>ASCII case-insensitive</span>. The allowed values are:</p>
<ul class="brief">
<li><code data-x="attr-iframe-sandbox-allow-downloads">allow-downloads</code></li>
<li><code data-x="attr-iframe-sandbox-allow-forms">allow-forms</code></li>
<li><code data-x="attr-iframe-sandbox-allow-modals">allow-modals</code></li>
<li><code data-x="attr-iframe-sandbox-allow-orientation-lock">allow-orientation-lock</code></li>
<li><code data-x="attr-iframe-sandbox-allow-pointer-lock">allow-pointer-lock</code></li>
<li><code data-x="attr-iframe-sandbox-allow-popups">allow-popups</code></li>
<li><code
data-x="attr-iframe-sandbox-allow-popups-to-escape-sandbox">allow-popups-to-escape-sandbox</code></li>
<li><code data-x="attr-iframe-sandbox-allow-presentation">allow-presentation</code></li>
<li><code data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code></li>
<li><code data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code></li>
<li><code data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code></li>
<li><code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code></li>
<li><code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code></li>
</ul>
<p>When the attribute is set, the content is treated as being from a unique <span
data-x="concept-origin-opaque">opaque origin</span>, forms, scripts, and various potentially
annoying APIs are disabled, and links are prevented from targeting other <span
data-x="navigable">navigables</span>. The <code
data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> keyword causes the
content to be treated as being from its real origin instead of forcing it into an <span
data-x="concept-origin-opaque">opaque origin</span>; the <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> keyword allows the
content to <span>navigate</span> its <span data-x="nav-traversable">traversable navigable</span>;
the <code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>
keyword behaves similarly but allows such <span data-x="navigate">navigation</span> only when the
browsing context's <span data-x="nav-window">active window</span> has <span>transient
activation</span>; the <code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code>
reenables navigations toward non <span>fetch scheme</span> to be <span data-x="hand-off to
external software">handed off to external software</span>; and the <code
data-x="attr-iframe-sandbox-allow-forms">allow-forms</code>, <code
data-x="attr-iframe-sandbox-allow-modals">allow-modals</code>, <code
data-x="attr-iframe-sandbox-allow-orientation-lock">allow-orientation-lock</code>, <code
data-x="attr-iframe-sandbox-allow-pointer-lock">allow-pointer-lock</code>, <code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code>, <code
data-x="attr-iframe-sandbox-allow-presentation">allow-presentation</code>, <code
data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code>, and <code
data-x="attr-iframe-sandbox-allow-popups-to-escape-sandbox">allow-popups-to-escape-sandbox</code>
keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups,
the presentation API, scripts, and the creation of unsandboxed <span
data-x="auxiliary browsing context">auxiliary browsing contexts</span> respectively. The <code
data-x="attr-iframe-sandbox-allow-downloads">allow-downloads</code> keyword allows content to
perform downloads. <ref>POINTERLOCK</ref> <ref>SCREENORIENTATION</ref> <ref>PRESENTATION</ref></p>
<p>The <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> and <code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>
keywords must not both be specified, as doing so is redundant; only <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> will have an effect
in such non-conformant markup.</p>
<p>Similarly, the <code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code>
keyword must not be specified if either <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> or <code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code> are specified, as doing so is
redundant.</p>
<p class="note">To allow <code data-x="dom-alert">alert()</code>, <code
data-x="dom-confirm">confirm()</code>, and <code data-x="dom-prompt">prompt()</code> inside
sandboxed content, both the <code data-x="attr-iframe-sandbox-allow-modals">allow-modals</code>
and <code data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> keywords need to
be specified, and the loaded URL needs to be <span>same origin</span> with the <span>top-level
origin</span>. Without the <code
data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> keyword, the content is
always treated as cross-origin, and cross-origin content <span>cannot show simple
dialogs</span>.</p>
<p class="warning">Setting both the <code
data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code> and <code
data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> keywords together when the
embedded page has the <span>same origin</span> as the page containing the <code>iframe</code>
allows the embedded page to simply remove the <code data-x="attr-iframe-sandbox">sandbox</code>
attribute and then reload itself, effectively breaking out of the sandbox altogether.</p>
<p class="warning">These flags only take effect when the <span>content navigable</span> of the
<code>iframe</code> element is <span data-x="navigate">navigated</span>. Removing them, or
removing the entire <code data-x="attr-iframe-sandbox">sandbox</code> attribute, has no effect on
an already-loaded page.</p>
<p class="warning">Potentially hostile files should not be served from the same server as the file
containing the <code>iframe</code> element. Sandboxing hostile content is of minimal help if an
attacker can convince the user to just visit the hostile content directly, rather than in the
<code>iframe</code>. To limit the damage that can be caused by hostile HTML content, it should be
served from a separate dedicated domain. Using a different domain ensures that scripts in the
files are unable to attack the site, even if the user is tricked into visiting those pages
directly, without the protection of the <code data-x="attr-iframe-sandbox">sandbox</code>
attribute.</p>
<div w-nodev>
<!-- v2: Add a new attribute that enables new restrictions, e.g.:
- disallow cross-origin loads of any kind (networking
override that only allows same-origin URLs or about:,
javascript:, data:)
- block access to 'parent.frames' from sandbox
-->
<p>When an <code>iframe</code> element's <code data-x="attr-iframe-sandbox">sandbox</code>
attribute is set or changed while it has a non-null <span>content navigable</span>, the user
agent must <span data-x="parse a sandboxing directive">parse the sandboxing directive</span>
given the attribute's value and the <code>iframe</code> element's <span><code>iframe</code>
sandboxing flag set</span>.</p>
<p>When an <code>iframe</code> element's <code data-x="attr-iframe-sandbox">sandbox</code>
attribute is removed while it has a non-null <span>content navigable</span>, the user agent must
empty the <code>iframe</code> element's <span><code>iframe</code> sandboxing flag set</span>.</p>
</div>
<div class="example">
<p>In this example, some completely-unknown, potentially hostile, user-provided HTML content is
embedded in a page. Because it is served from a separate domain, it is affected by all the normal
cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled,
forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or
windows it itself embeds).</p>
<pre><code class="html"><p>We're not scared of you! Here is your content, unedited:</p>
<iframe sandbox src="https://usercontent.example.net/getusercontent.cgi?id=12193"></iframe></code></pre>
<p class="warning">It is important to use a separate domain so that if the attacker convinces the
user to visit that page directly, the page doesn't run in the context of the site's origin, which
would make the user vulnerable to any attack found in the page.</p>
</div>
<div class="example">
<p>In this example, a gadget from another site is embedded. The gadget has scripting and forms
enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with
its originating server. The sandbox is still useful, however, as it disables plugins and popups,
thus reducing the risk of the user being exposed to malware and other annoyances.</p>
<pre><code class="html"><iframe sandbox="allow-same-origin allow-forms allow-scripts"
src="https://maps.example.com/embedded.html"></iframe></code></pre>
</div>
<div class="example">
<p>Suppose a file A contained the following fragment:</p>
<pre><code class="html"><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></code></pre>
<p>Suppose that file B contained an iframe also:</p>
<pre><code class="html"><iframe sandbox="allow-scripts" src=C></iframe></code></pre>
<p>Further, suppose that file C contained a link:</p>
<pre><code class="html"><a href=D>Link</a></code></pre>
<p>For this example, suppose all the files were served as <code>text/html</code>.</p>
<p>Page C in this scenario has all the sandboxing flags set. Scripts are disabled, because the
<code>iframe</code> in A has scripts disabled, and this overrides the <code
data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code> keyword set on the
<code>iframe</code> in B. Forms are also disabled, because the inner <code>iframe</code> (in B)
does not have the <code data-x="attr-iframe-sandbox-allow-forms">allow-forms</code> keyword
set.</p>
<p>Suppose now that a script in A removes all the <code
data-x="attr-iframe-sandbox">sandbox</code> attributes in A <!--grammar-check-override--> and B.
This would change nothing immediately. If the user clicked the link in C, loading page D into
the <code>iframe</code> in B, page D would now act as if the <code>iframe</code> in B had the
<code data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> and <code
data-x="attr-iframe-sandbox-allow-forms">allow-forms</code> keywords set, because that was the
state of the <span>content navigable</span> in the <code>iframe</code> in A when page B was
loaded.</p>
<p>Generally speaking, dynamically removing or changing the <code
data-x="attr-iframe-sandbox">sandbox</code> attribute is ill-advised, because it can make it quite
hard to reason about what will be allowed and what will not.</p>
</div>
<hr> <!-- FEATURE POLICY ATTRIBUTES: ALLOW; ALLOW FULLSCREEN / PAYMENT REQUEST / USER MEDIA -->
<p>The <dfn element-attr for="iframe"><code data-x="attr-iframe-allow">allow</code></dfn>
attribute, when specified, determines the <span data-x="concept-container-policy">container
policy</span> that will be used when the <span
data-x="concept-document-permissions-policy">permissions policy</span> for a
<code>Document</code> in the <code>iframe</code>'s <span>content navigable</span> is initialized.
Its value must be a <span data-x="concept-serialized-permissions-policy">serialized permissions
policy</span>. <ref>PERMISSIONSPOLICY</ref></p>
<div class="example">
<p>In this example, an <code>iframe</code> is used to embed a map from an online navigation
service. The <code data-x="attr-iframe-allow">allow</code> attribute is used to enable the
Geolocation API within the nested context.</p>
<pre><code class="html"><iframe src="https://maps.example.com/" allow="geolocation"></iframe></code></pre>
</div>
<p>The <dfn element-attr for="iframe"><code
data-x="attr-iframe-allowfullscreen">allowfullscreen</code></dfn> attribute is a <span>boolean
attribute</span>. When specified, it indicates that <code>Document</code> objects in the
<code>iframe</code> element's <span>content navigable</span> will be initialized with a <span
data-x="concept-document-permissions-policy">permissions policy</span> which allows the "<code
data-x="">fullscreen</code>" feature to be used from any <span>origin</span>. This is enforced by
the <span data-x="process-permissions-policy-attributes">process permissions policy
attributes</span> algorithm. <ref>PERMISSIONSPOLICY</ref></p>
<div class="example">
<p>Here, an <code>iframe</code> is used to embed a player from a video site. The <code
data-x="attr-iframe-allowfullscreen">allowfullscreen</code> attribute is needed to enable the
player to show its video fullscreen.</p>
<pre><code class="html"><article>
<header>
<p><img src="/usericons/1627591962735"> <b>Fred Flintstone</b></p>
<p><a href="/posts/3095182851" rel=bookmark>12:44</a> — <a href="#acl-3095182851">Private Post</a></p>
</header>
<p>Check out my new ride!</p>
<strong><iframe src="https://video.example.com/embed?id=92469812" allowfullscreen></iframe></strong>
</article></code></pre>
</div>
<p class="note">Neither <code data-x="attr-iframe-allow">allow</code> nor <code
data-x="attr-iframe-allowfullscreen">allowfullscreen</code> can grant access to a feature in an
<code>iframe</code> element's <span>content navigable</span> if the element's <span>node
document</span> is not already allowed to use that feature.</p>
<div w-nodev>
<p id="fullscreen-logic">To determine whether a <code>Document</code> object <var>document</var>
is <dfn export>allowed to use</dfn> the policy-controlled-feature <var>feature</var>, run these
steps:</p>
<ol>
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> is
null, then return false.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return false.</p></li>
<li><p>If the result of running <span data-x="is-feature-enabled">is feature enabled in document
for origin</span> on <var>feature</var>, <var>document</var>, and <var>document</var>'s <span
data-x="concept-document-origin">origin</span> is "<code data-x="">Enabled</code>", then return
true.</p></li>
<li><p>Return false.</p></li>
</ol>
</div>
<p class="warning">Because they only influence the <span
data-x="concept-document-permissions-policy">permissions policy</span> of the <span>content
navigable</span>'s <span data-x="nav-document">active document</span>, the <code
data-x="attr-iframe-allow">allow</code> and <code
data-x="attr-iframe-allowfullscreen">allowfullscreen</code> attributes only take effect when the
<span>content navigable</span> of the <code>iframe</code> is <span
data-x="navigate">navigated</span>. Adding or removing them has no effect on an already-loaded
document.</p>
<hr> <!-- DIM ATTRIBUTES -->
<p>The <code>iframe</code> element supports <span>dimension attributes</span> for cases where the
embedded content has specific dimensions (e.g. ad units have well-defined dimensions).</p>
<p>An <code>iframe</code> element never has <span>fallback content</span>, as it will always
<span>create a new child navigable</span>, regardless of whether the specified initial
contents are successfully used.</p>
<hr> <!-- REFERRERPOLICY ATTRIBUTE -->
<p>The <dfn element-attr for="iframe"
data-x="attr-iframe-referrerpolicy"><code>referrerpolicy</code></dfn> attribute is a
<span>referrer policy attribute</span>. Its purpose is to set the <span>referrer policy</span>
used when <span data-x="process the iframe attributes">processing the <code>iframe</code>
attributes</span>. <ref>REFERRERPOLICY</ref></p>
<p>The <dfn element-attr for="iframe" data-x="attr-iframe-loading"><code>loading</code></dfn> attribute is a <span>lazy
loading attribute</span>. Its purpose is to indicate the policy for loading <code>iframe</code>
elements that are outside the viewport.</p>
<p>When the <code data-x="attr-iframe-loading">loading</code> attribute's state is changed to the
<span data-x="attr-loading-eager-state">Eager</span> state, the user agent must run these
steps:</p>
<ol>
<li><p>Let <var>resumptionSteps</var> be the <code>iframe</code> element's <span>lazy load
resumption steps</span>.</p></li>
<li><p>If <var>resumptionSteps</var> is null, then return.</p></li>
<li><p>Set the <code>iframe</code>'s <span>lazy load resumption steps</span> to null.</p></li>
<li><p>Invoke <var>resumptionSteps</var>.</p></li>
</ol>
<hr> <!-- FALLBACK -->
<p>Descendants of <code>iframe</code> elements represent nothing. (In legacy user agents that do
not support <code>iframe</code> elements, the contents would be parsed as markup that could act as
fallback content.)</p>
<p class="note">The <span>HTML parser</span> treats markup inside <code>iframe</code> elements as
text.</p>
<div w-nodev>
<hr> <!-- DOM -->
<p>The IDL attributes <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-src">src</code></dfn>, <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-name">name</code></dfn>, <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-sandbox">sandbox</code></dfn>, and <dfn attribute
for="HTMLIFrameElement"><code data-x="dom-iframe-allow">allow</code></dfn> must
<span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-srcdoc">srcdoc</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>attribute</var> be the result of running <span
data-x="concept-element-attributes-get-by-namespace">get an attribute by namespace and local
name</span> given null, <code data-x="attr-iframe-srcdoc">srcdoc</code>'s <span
data-x="concept-attribute-local-name">local name</span>, and <span>this</span>.</p></li>
<li><p>If <var>attribute</var> is null, then return the empty string.</p></li>
<li><p>Return <var>attribute</var>'s <span
data-x="concept-attribute-value">value</span>.</p></li>
</ol>
<p>The <code data-x="dom-iframe-srcdoc">srcdoc</code> setter steps
are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, the given value, "<code data-x="">HTMLIFrameElement srcdoc</code>", and "<code
data-x="">script</code>".</p></li>
<li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span> given
<span>this</span>, <code data-x="attr-iframe-srcdoc">srcdoc</code>'s <span
data-x="concept-attribute-local-name">local name</span>, and
<var>compliantString</var>.</p></li>
</ol>
<p>The <span data-x="concept-supported-tokens">supported tokens</span> for <code
data-x="dom-iframe-sandbox">sandbox</code>'s <code>DOMTokenList</code> are the allowed
values defined in the <code data-x="attr-iframe-sandbox">sandbox</code> attribute and supported by
the user agent.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-allowFullscreen">allowFullscreen</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-iframe-allowfullscreen">allowfullscreen</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-referrerPolicy">referrerPolicy</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-iframe-referrerpolicy">referrerpolicy</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-loading">loading</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-iframe-loading">loading</code> content attribute, <span>limited to only known
values</span>.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-contentDocument">contentDocument</code></dfn> getter steps are to return the
<span>this</span>'s <span>content document</span>.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-contentWindow">contentWindow</code></dfn> getter steps are to return
<span>this</span>'s <span>content window</span>.</p>
</div>
<div class="example">
<p>Here is an example of a page using an <code>iframe</code> to include advertising from an
advertising broker:</p>
<pre><code class="html"><iframe src="https://ads.example.com/?customerid=923513721&amp;format=banner"
width="468" height="60"></iframe></code></pre>
</div>
<h4>The <dfn element><code>embed</code></dfn> element</h4>
<!-- (v2?)
we have all kinds of quirks we should define if they come up during
testing, as e.g. shown in:
http://mxr.mozilla.org/mozilla-central/source/layout/generic/nsObjectFrame.cpp
http://trac.webkit.org/browser/trunk/WebCore/html/HTMLEmbedElement.cpp
http://trac.webkit.org/browser/trunk/WebCore/rendering/RenderPartObject.cpp (updateWidget)
e.g. - 240x200 default
- the attributes/params are sent in a name-value pair list as follows (for Gecko):
+ attributes of the element, in source order
+ a synthesized 'src' attribute, if there was no 'src' but
there was a 'data', with the value of the 'data' attribute
+ the params, in source order
(WebKit does something different still)
- the HIDDEN attribute (might be moot now)
-->
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-embed-src">src</code></dd>
<dd><code data-x="attr-embed-type">type</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dd>Any other attribute that has no namespace (see prose).</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-embed">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-embed">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLEmbedElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-embed-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-embed-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-width">width</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-height">height</span>;
<span>Document</span>? <span data-x="dom-media-getSVGDocument">getSVGDocument</span>();
// <a href="#HTMLEmbedElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
</dl>
<p>The <code>embed</code> element provides an integration point for an external application or
interactive content.</p>
<p>The <dfn element-attr for="embed"><code data-x="attr-embed-src">src</code></dfn> attribute
gives the <span>URL</span> of the resource being embedded. The attribute, if present, must contain
a <span>valid non-empty URL potentially surrounded by spaces</span>.</p>
<p>If the <code data-x="attr-itemprop">itemprop</code> attribute is specified on an
<code>embed</code> element, then the <code data-x="attr-embed-src">src</code> attribute must also
be specified.</p>
<p>The <dfn element-attr for="embed"><code data-x="attr-embed-type">type</code></dfn> attribute,
if present, gives the <span>MIME type</span> by which the plugin to instantiate is selected. The
value must be a <span>valid MIME type string</span>. If both the <code
data-x="attr-embed-type">type</code> attribute and the <code data-x="attr-embed-src">src</code>
attribute are present, then the <code data-x="attr-embed-type">type</code> attribute must specify
the same type as the <span data-x="Content-Type">explicit Content-Type metadata</span> of the
resource given by the <code data-x="attr-embed-src">src</code> attribute.</p>
<div w-nodev>
<p>While any of the following conditions are occurring, any <span>plugin</span> instantiated for
the element must be removed, and the <code>embed</code> element <span>represents</span>
nothing:</p>
<ul>
<li><p>The element has neither a <code data-x="attr-embed-src">src</code> attribute nor a <code
data-x="attr-embed-type">type</code> attribute.</p></li>
<li><p>The element has a <span>media element</span> ancestor.</p></li>
<li><p>The element has an ancestor <code>object</code> element that is <em>not</em> showing its
<span>fallback content</span>.</p></li>
</ul>
<p>An <code>embed</code> element is said to be <dfn data-x="concept-embed-active">potentially
active</dfn> when the following conditions are all met simultaneously:</p>
<ul>
<li><p>The element is <span>in a document</span> or was <span>in a document</span> the last time
the <span>event loop</span> reached <a href="#step1">step 1</a>.</p></li>
<li><p>The element's <span>node document</span> is <span>fully active</span>.</p></li>
<li><p>The element has either a <code data-x="attr-embed-src">src</code> attribute set or a
<code data-x="attr-embed-type">type</code> attribute set (or both).</p></li>
<li><p>The element's <code data-x="attr-embed-src">src</code> attribute is either absent or its
value is not the empty string.</p></li>
<li><p>The element is not a descendant of a <span>media element</span>.</p></li>
<li><p>The element is not a descendant of an <code>object</code> element that is not showing its
<span>fallback content</span>.</p></li>
<li><p>The element is <span>being rendered</span>, or was <span>being rendered</span> the last
time the <span>event loop</span> reached <a href="#step1">step 1</a>.</p></li>
</ul>
<p>Whenever an <code>embed</code> element that was not <span
data-x="concept-embed-active">potentially active</span> becomes <span
data-x="concept-embed-active">potentially active</span>, and whenever a <span
data-x="concept-embed-active">potentially active</span> <code>embed</code> element that is
remaining <span data-x="concept-embed-active">potentially active</span> and has its <code
data-x="attr-embed-type">src</code> attribute set, changed, or removed or its <code
data-x="attr-embed-type">type</code> attribute set, changed, or removed, the user agent must
<span>queue an element task</span> on the <dfn>embed task source</dfn> given the element
to run <span>the <code>embed</code> element setup steps</span> for that element.</p>
<p><dfn>The <code>embed</code> element setup steps</dfn> for a given <code>embed</code> element
<var>element</var> are as follows:</p>
<ol>
<li><p>If another <span data-x="concept-task">task</span> has since been queued to run <span>the
<code>embed</code> element setup steps</span> for <var>element</var>, then return.</p></li>
<li>
<p>If <var>element</var> has a <code data-x="attr-embed-src">src</code> attribute set, then:</p>
<ol>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>element</var>'s <code data-x="attr-embed-src">src</code> attribute's value, relative to
<var>element</var>'s <span>node document</span>.</p></li>
<li><p>If <var>url</var> is failure, then return.</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is <var>element</var>'s <span>node
document</span>'s <span>relevant settings object</span>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">embed</code>",
<span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", <span data-x="concept-request-mode">mode</span> is "<code
data-x="">navigate</code>", <span data-x="concept-request-initiator-type">initiator
type</span> is "<code data-x="">embed</code>", and whose <span>use-URL-credentials flag</span>
is set.</p></li>
<li>
<p><span data-x="concept-fetch">Fetch</span> <var>request</var>, with <i
data-x="processResponse">processResponse</i> set to the following steps given <span
data-x="concept-response">response</span> <var>response</var>:</p>
<ol>
<li><p>If another <span data-x="concept-task">task</span> has since been queued to run
<span>the <code>embed</code> element setup steps</span> for <var>element</var>, then
return.</p></li>
<li><p>If <var>response</var> is a <span>network error</span>, then <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-load">load</code> at <var>element</var>, and return.</p></li>
<li><p>Let <var>type</var> be the result of determining the <span
data-x="concept-embed-type">type of content</span> given <var>element</var> and
<var>response</var>.</p></li>
<li>
<p>Switch on <var>type</var>:</p>
<dl class="switch">
<dt>null</dt>
<dd>
<ol>
<li><p><span>Display no plugin</span> for <var>element</var>.</p></li>
</ol>
</dd>
<dt>Otherwise</dt>
<dd>
<ol>
<li><p>If <var>element</var>'s <span>content navigable</span> is null, then
<span>create a new child navigable</span> for <var>element</var>.</p></li>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2291 - dynamic changes
to 'name' don't do anything -->
<li>
<p><span>Navigate</span><!-- DONAV embed--> <var>element</var>'s <span>content
navigable</span> to <var>response</var>'s <span
data-x="concept-response-url">URL</span> using <var>element</var>'s <span>node
document</span>, with <i data-x="navigation-response">response</i> set to
<var>response</var>, and <i data-x="navigation-hh">historyHandling</i> set to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
<p class="note"><var>element</var>'s <code data-x="attr-embed-src">src</code> attribute
does not get updated if the <span>content navigable</span> gets further navigated to
other locations.</p>
</li>
<li><p><var>element</var> now <span>represents</span> its <span>content
navigable</span>.</p></li>
</ol>
</dd>
</dl>
</li>
</ol>
<p>Fetching the resource must <span>delay the load event</span> of <var>element</var>'s
<span>node document</span>.</p>
</li>
</ol>
</li>
<li><p>Otherwise, <span>display no plugin</span> for <var>element</var>.</p></li>
</ol>
<p>To determine the <dfn data-x="concept-embed-type">type of the content</dfn> given an
<code>embed</code> element <var>element</var> and a <span
data-x="concept-response">response</span> <var>response</var>, run the following steps:</p>
<ol>
<li><p>If <var>element</var> has a <code data-x="attr-embed-type">type</code> attribute, and that
attribute's value is a type that a <span>plugin</span> supports, then return the value of the
<code data-x="attr-embed-type">type</code> attribute.</p></li>
<li>
<p>If the <span data-x="concept-url-path">path</span> component of <var>response</var>'s
<span data-x="concept-response-url">url</span> matches a pattern that a <span>plugin</span>
supports, then return the type that that plugin can handle.</p>
<p class="example">For example, a plugin might say that it can handle URLs with <span
data-x="concept-url-path">path</span> components that end with the four character string
"<code data-x="">.swf</code>".</p>
<!-- it's sad that we have to do extension sniffing. sigh. -->
<!-- see also <object> which has a similar step -->
</li>
<li><p>If <var>response</var> has <span data-x="Content-Type">explicit Content-Type
metadata</span>, and that value is a type that a <span>plugin</span> supports, then return that
value.</p></li>
<li><p>Return null.</p></li>
</ol>
<!-- This algorithm is a monument to bad design. Go legacy! -->
<p class="note">It is intentional that the above algorithm allows <var>response</var> to have a
non-<span>ok status</span>. This allows servers to return data for plugins even with error
responses (e.g., HTTP 500 Internal Server Error codes can still contain plugin data).</p>
<p>To <dfn>display no plugin</dfn> for an <code>embed</code> element <var>element</var>:</p>
<ol>
<li><p><span>Destroy a child navigable</span> given <var>element</var>.</p></li>
<li><p>Display an indication that no <span>plugin</span> could be found for <var>element</var>,
as the contents of <var>element</var>.</p></li>
<li><p><var>element</var> now <span>represents</span> nothing.</p></li>
</ol>
<p class="note">The <code>embed</code> element has no <span>fallback content</span>; its
descendants are ignored.</p>
<p>Whenever an <code>embed</code> element that was <span data-x="concept-embed-active">potentially
active</span> stops being <span data-x="concept-embed-active">potentially active</span>, any
<span>plugin</span> that had been instantiated for that element must be unloaded.</p>
<p>The <code>embed</code> element <span>potentially delays the load event</span>.</p>
</div>
<p>The <code>embed</code> element supports <span>dimension attributes</span>.</p>
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLEmbedElement"><code
data-x="dom-embed-src">src</code></dfn> and <dfn attribute for="HTMLEmbedElement"><code
data-x="dom-embed-type">type</code></dfn> each must <span>reflect</span> the respective content
attributes of the same name.</p>
</div>
<h4>The <dfn element><code>object</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<!-- Interactive content when showing a plugin or a child navigable, but checking that statically is hard... -->
<dd><span data-x="category-listed">Listed</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-object-data">data</code></dd>
<dd><code data-x="attr-object-type">type</code></dd>
<dd><code data-x="attr-object-name">name</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-object">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-object">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLObjectElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-object-data">data</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-name">name</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-width">width</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dim-height">height</span>;
readonly attribute <span>Document</span>? <span data-x="dom-object-contentDocument">contentDocument</span>;
readonly attribute <span>WindowProxy</span>? <span data-x="dom-object-contentWindow">contentWindow</span>;
<span>Document</span>? <span data-x="dom-media-getSVGDocument">getSVGDocument</span>();
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
// <a href="#HTMLObjectElement-partial">also has obsolete members</a>
};</code></pre>
<div w-nodev>
<p>Depending on the type of content instantiated by the
<code>object</code> element, the node also supports other
interfaces.</p>
</div>
</dd>
<dd w-dev>Uses <code>HTMLObjectElement</code>.</dd>
</dl>
<p>The <code>object</code> element can represent an external resource, which, depending on the
type of the resource, will either be treated as an image or as a <span>child
navigable</span>.</p>
<p>The <dfn element-attr for="object"><code data-x="attr-object-data">data</code></dfn> attribute
specifies the <span>URL</span> of the resource. It must be present, and must contain a
<span>valid non-empty URL potentially surrounded by spaces</span>.</p>
<p>The <dfn element-attr for="object"><code data-x="attr-object-type">type</code></dfn> attribute,
if present, specifies the type of the resource. If present, the attribute must be a <span>valid
MIME type string</span>.</p>
<p>The <dfn element-attr for="object"><code data-x="attr-object-name">name</code></dfn>
attribute, if present, must be a <span>valid navigable target name</span>. The given value is
used to name the element's <span>content navigable</span>, if applicable, and if present when the
element's <span>content navigable</span> is <span data-x="create a new child
navigable">created</span>.</p>
<div w-nodev>
<p>Whenever one of the following conditions occur:</p>
<ul>
<li>the element is created,
<li>the element is popped off the <span>stack of open elements</span> of an <span>HTML
parser</span> or <span>XML parser</span>,
<li>the element is not on the <span>stack of open elements</span> of an <span>HTML parser</span>
or <span>XML parser</span>, and it is either <span data-x="node is inserted into a
document">inserted into a document</span> or <span data-x="node is removed from a
document">removed from a document</span>,
<li>the element's <span>node document</span> changes whether it is <span>fully active</span>,
<li>one of the element's ancestor <code>object</code> elements changes to or from showing its
<span>fallback content</span>,
<li>the element's <code data-x="attr-object-classid">classid</code> attribute is set, changed, or
removed,
<li>the element's <code data-x="attr-object-classid">classid</code> attribute is not present, and
its <code data-x="attr-object-data">data</code> attribute is set, changed, or removed,
<li>neither the element's <code data-x="attr-object-classid">classid</code> attribute nor its
<code data-x="attr-object-data">data</code> attribute are present, and its <code
data-x="attr-object-type">type</code> attribute is set, changed, or removed,
<li>the element changes from <span>being rendered</span> to not being rendered, or vice versa,
</ul> <!-- Changing the base URL doesn't trigger this. -->
<p>...the user agent must <span>queue an element task</span> on the <span>DOM manipulation task
source</span> given the <code>object</code> element to run the following steps to (re)determine
what the <code>object</code> element represents. This <span data-x="concept-task">task</span>
being <span data-x="queue a task">queued</span> or actively running must <span>delay the load
event</span> of the element's <span>node document</span>. <!--As described in the algorithm, once
the algorithm starts fetching a resource, the fetch is what starts delaying the load event. But to
tide us over from when the parser finds the <object> element and the fetching begins, we have to
block the load event like this, lest the parse end before this task gets run.--></p>
<ol>
<li>
<p>If the user has indicated a preference that this <code>object</code> element's <span>fallback
content</span> be shown instead of the element's usual behavior, then jump to the step below
labeled <i>fallback</i>.</p>
<p class="note">For example, a user could ask for the element's <span>fallback content</span> to
be shown because that content uses a format that the user finds more accessible.</p>
</li>
<li><p>If the element has an ancestor <span>media element</span>, or has an ancestor
<code>object</code> element that is <em>not</em> showing its <span>fallback content</span>, or if
the element is not <span>in a document</span> whose <span data-x="concept-document-bc">browsing
context</span> is non-null, or if the element's <span>node document</span> is not <span>fully
active</span>, or if the element is still in the <span>stack of open elements</span> of an
<span>HTML parser</span> or <span>XML parser</span>, or if the element is not <span>being
rendered</span>, then jump to the step below labeled <i>fallback</i>.</p></li>
<!-- (v2?)
we may have to define magic fallback to <param> if it turns out to
be needed in testing:
<hyatt> apparently your url can come from <param>
<hyatt> not just the data attribute
<hyatt> our code looks for params with "src", "movie", "code" and "url"
<hyatt> and also tries to find the type on a param
<Hixie> oh that's you trying to have hacky activex support
<Hixie> opera does that too
<hyatt> yeah we support activex versions of plugins that are common
<hyatt> like flash and quicktime and realaudio
<Hixie> that would be a step 1b. if no data attribute, then look for a <param> to get you a URL instead.
<Hixie> and if you find one, carry on as if that was your data="".
-->
<li><p>If the <code data-x="attr-object-data">data</code> attribute is present and its value is
not the empty string, then:</p>
<ol>
<li><p>If the <code data-x="attr-object-type">type</code> attribute is present and its value is
not a type that the user agent supports, then the user agent may jump to the step below labeled
<i>fallback</i> without fetching the content to examine its real type.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given the <code
data-x="attr-object-data">data</code> attribute's value, relative to the element's <span>node
document</span>.</p></li>
<li><p>If <var>url</var> is failure, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-error">error</code> at the element and jump to the step
below labeled <i>fallback</i>.</p></li>
<!-- identical for <embed>/<object> -->
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is the element's <span>node document</span>'s
<span>relevant settings object</span>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">object</code>",
<span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", <span data-x="concept-request-mode">mode</span> is "<code
data-x="">navigate</code>", <span data-x="concept-request-initiator-type">initiator
type</span> is "<code data-x="">object</code>", and whose <span>use-URL-credentials
flag</span> is set.</p></li>
<li>
<p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var>.</p>
<!-- similar text in various places -->
<p>Fetching the resource must <span>delay the load event</span> of the element's <span>node
document</span> until the <span data-x="concept-task">task</span> that is <span data-x="queue
a task">queued</span> by the <span>networking task source</span> once the resource has been
fetched (defined next) has been run.</p>
</li>
<li><p>If the resource is not yet available (e.g. because the resource was not available in the
cache, so that loading the resource required making a request over the network), then jump to
the step below labeled <i>fallback</i>. The <span data-x="concept-task">task</span> that is
<span data-x="queue a task">queued</span> by the <span>networking task source</span> once the
resource is available must restart this algorithm from this step. Resources can load
incrementally; user agents may opt to consider a resource "available" whenever enough data has
been obtained to begin processing the resource.</p></li>
<li><p>If the load failed (e.g. there was an HTTP 404 error, there was a DNS error), <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
at the element, then jump to the step below labeled <i>fallback</i>.</p></li>
<li id="object-type-detection">
<p>Determine the <var>resource type</var>, as follows:</p>
<!-- Hopefully this step is exactly equivalent to the following:
START
|
V
Is there a Content-Type and is the UA going to obey it blindly?
| |
| YES | NO
| V YES
| Is there a type="" attribute whose value is a plugin type? ============================================-.
| | |
| | NO |
| V NO YES |
| Is there a Content type? ========-> Is there a type="" attribute? ==========> Let TYPE be type="" |
| | | attribute value |
| | YES | NO | |
V NO V | V |
+-<============== Is it text/plain or application/octet-stream? `==> Let TYPE be =====>+ |
| | | Sniffed type | |
| | text/plain | octet-stream V |
| V YES V Is TYPE |
| Does the page sniff as binary? ======> Is there a type="" attribute? application/octet-stream? |
| | | | | | |
| | NO | YES | NO | YES | NO |
| | | YES V V | |
| | application/octet-stream? =====> Extension that is plugin type? | |
| | | | | | |
| | | NO | NO | YES | |
| | V | | | |
| | Type attribute is XML or YES V | | |
| | doesn't start with image/* ======> FALLBACK | | |
| | and is not a plugin type? | | |
| | | | | |
| | | NO | | V
V V V V V Use
Use Use Use it (will be Use Use type=""
Content-Type text/plain bitmap or plugin) extension TYPE attribute
| | | | | |
| V V V V |
`================->-+========================================>-+==============>-+-<============-+-<==============+-<======'
|
V
Continue following rules in the spec, which might
result in a plugin, a browsing context, an image,
or using fallback, depending on the UA and the type.
"Extension that is plugin type?" means "Is there an extension that matches one that a plugin supports?".
Plugins are not allowed to register text/plain or application/octet-stream.
-->
<ol>
<li>
<p>Let the <var>resource type</var> be unknown.</p>
</li>
<li>
<!-- by request: https://www.w3.org/Bugs/Public/show_bug.cgi?id=8479 -->
<p>If the user agent is configured to strictly obey Content-Type headers for this resource,
and the resource has <span data-x="Content-Type">associated Content-Type metadata</span>,
then let the <var>resource type</var> be the type specified in <span
data-x="Content-Type">the resource's Content-Type metadata</span>, and jump to the step below
labeled <i>handler</i>.</p>
<p class="warning">This can introduce a vulnerability, wherein a site is trying to embed a
resource that uses a particular type, but the remote site overrides that and instead
furnishes the user agent with a resource that triggers a different type of content with different
security characteristics. <!-- e.g. the example given above, where the site is expecting
Flash with allowScriptAccess=never, and instead gets back Java with its unrestricted DOM
access --></p>
</li>
<li>
<p>Run the appropriate set of steps from the following
list:</p>
<dl class="switch">
<dt>If the resource has <span data-x="Content-Type">associated Content-Type
metadata</span></dt>
<dd>
<ol>
<li>
<p>Let <var>binary</var> be false.</p>
</li>
<li>
<p>If the type specified in <span data-x="Content-Type">the resource's Content-Type
metadata</span> is "<code>text/plain</code>", and the result of applying the <span
data-x="Content-Type sniffing: text or binary">rules for distinguishing if a resource is
text or binary</span> to the resource is that the resource is not
<code>text/plain</code>, then set <var>binary</var> to true.</p>
</li>
<li>
<p>If the type specified in <span data-x="Content-Type">the resource's Content-Type
metadata</span> is "<code>application/octet-stream</code>", then set <var>binary</var> to true.</p>
</li>
<li>
<p>If <var>binary</var> is false, then let the <var>resource
type</var> be the type specified in <span data-x="Content-Type">the resource's
Content-Type metadata</span>, and jump to the step below labeled <i>handler</i>.</p>
</li>
<li>
<p>If there is a <code data-x="attr-object-type">type</code> attribute present on the
<code>object</code> element, and its value is not <code>application/octet-stream</code>,
then run the following steps:</p>
<ol>
<li>
<p>If the attribute's value is a type that starts with "<code data-x="">image/</code>" that is
not also an <span>XML MIME type</span>, then let the <var>resource type</var> be the
type specified in that <code data-x="attr-object-type">type</code> attribute.</p>
</li>
<li>
<p>Jump to the step below labeled <i>handler</i>.</p>
</li>
</ol>
</li>
</ol>
</dd>
<dt>Otherwise, if the resource does not have <span data-x="Content-Type">associated
Content-Type metadata</span></dt>
<dd>
<ol>
<li>
<p>If there is a <code data-x="attr-object-type">type</code> attribute present on the
<code>object</code> element, then let the <var>tentative type</var> be the type
specified in that <code data-x="attr-object-type">type</code> attribute.</p>
<p>Otherwise, let <var>tentative type</var> be the <span data-x="content-type
sniffing">computed type of the resource</span>.</p>
</li>
<li>
<p>If <var>tentative type</var> is <em>not</em>
<code>application/octet-stream</code>, then let <var>resource type</var> be
<var>tentative type</var> and jump to the step below labeled
<i>handler</i>.</p>
</li>
</ol>
</dd>
</dl>
</li>
<li>
<!-- if we get to this point we know we can successfully parsed the URL, since this
algorithm is only used after fetching the resource in the steps above -->
<p>If applying the <span>URL parser</span> algorithm to the <span>URL</span> of the
specified resource (after any redirects) results in a <span>URL record</span> whose <span
data-x="concept-url-path">path</span> component matches a pattern that a <span>plugin</span>
supports, then let <var>resource type</var> be the type that that plugin can
handle.</p>
<p class="example">For example, a plugin might say that it can handle resources with <span
data-x="concept-url-path">path</span> components that end with the four character string
"<code data-x="">.swf</code>".</p>
<!-- it's sad that we have to do extension sniffing. sigh. -->
<!-- see also <embed> which has a similar step -->
</li>
</ol>
<p class="note">It is possible for this step to finish, or for one of the substeps above to
jump straight to the next step, with <var>resource type</var> still being unknown. In
both cases, the next step will trigger fallback.</p>
</li>
<li><p><i>Handler</i>: Handle the content as given by the first of the following cases that
matches:</p>
<dl class="switch">
<dt>If the <var>resource type</var> is an <span>XML MIME type</span>, or <!-- (redundant with
the next one) if the <var>resource type</var> is HTML, or --> if the <var>resource type</var>
does not start with "<code data-x="">image/</code>"</dt>
<dd>
<p>If the <code>object</code> element's <span>content navigable</span> is null, then
<span>create a new child navigable</span> for the element.</p>
<p>Let <var>response</var> be the <span data-x="concept-response">response</span> from
<span data-x="concept-fetch">fetch</span>.</p>
<p>If <var>response</var>'s <span data-x="concept-response-url">URL</span> does not <span
data-x="matches about:blank">match <code>about:blank</code></span>, then
<span>navigate</span><!-- DONAV object --> the element's <span>content navigable</span> to
<var>response</var>'s <span data-x="concept-response-url">URL</span> using the element's
<span>node document</span>, with <var data-x="navigation-hh">historyHandling</var> set to
"<code data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
<p class="note">The <code data-x="attr-object-data">data</code> attribute of the
<code>object</code> element doesn't get updated if the <span>content navigable</span> gets
further <span data-x="navigate">navigated</span> to other locations.</p>
<p>The <code>object</code> element <span>represents</span> its <span>content
navigable</span>.</p>
<!-- note that malformed XML files don't cause fallback -->
</dd>
<dt>If the <var>resource type</var> starts with "<code data-x="">image/</code>", and support
for images has not been disabled</dt>
<dd>
<p><span>Destroy a child navigable</span> given the <code>object</code> element.</p>
<p>Apply the <span data-x="content-type sniffing: image">image sniffing</span> rules to
determine the type of the image.</p>
<p>The <code>object</code> element <span>represents</span> the specified image.</p>
<p>If the image cannot be rendered, e.g. because it is malformed or in an unsupported
format, jump to the step below labeled <i>fallback</i>.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>The given <var>resource type</var> is not supported. Jump to the step below
labeled <i>fallback</i>.</p>
<p class="note">If the previous step ended with the <var>resource type</var> being
unknown, this is the case that is triggered.</p>
</dd>
</dl>
</li>
<li><p>The element's contents are not part of what the <code>object</code> element
represents.</p>
<li>
<p>If the <code>object</code> element does not represent its <span>content navigable</span>,
then once the resource is completely loaded, <span>queue an element task</span> on the
<span>DOM manipulation task source</span> given the <code>object</code> element to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code>
at the element.</p>
<p class="note">If the element <em>does</em> represent its <span>content navigable</span>,
then an analogous task will be queued when the created <code>Document</code> is <span
data-x="completely finish loading">completely finished loading</span>.</p>
</li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p><i>Fallback</i>: The <code>object</code> element <span>represents</span> the element's
children. This is the element's <span>fallback content</span>. <span>Destroy a child
navigable</span> given the element.</p></li>
</ol>
<p>Due to the algorithm above, the contents of <code>object</code> elements act as <span>fallback
content</span>, used only when referenced resources can't be shown (e.g. because it returned a 404
error). This allows multiple <code>object</code> elements to be nested inside each other,
targeting multiple user agents with different capabilities, with the user agent picking the first
one it supports.</p>
<p>The <code>object</code> element <span>potentially delays the load event</span>.</p>
</div>
<p>The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<code>object</code> element with its <span>form owner</span>.</p>
<p>The <code>object</code> element supports <span>dimension attributes</span>.</p>
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-data">data</code></dfn>, <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-type">type</code></dfn>, and <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-name">name</code></dfn> each must <span>reflect</span> the respective content
attributes of the same name.</p>
<p>The <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-contentDocument">contentDocument</code></dfn> getter steps are to return
<span>this</span>'s <span>content document</span>.</p>
<p>The <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-contentWindow">contentWindow</code></dfn> getter steps are to return
<span>this</span>'s <span>content window</span>.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-fae-form">form</code> IDL attribute
is part of the element's forms API.</p>
</div>
<div class="example">
<p>In this example, an HTML page is embedded in another using the <code>object</code>
element.</p>
<pre><code class="html"><figure>
<object data="clock.html"></object>
<figcaption>My HTML Clock</figcaption>
</figure></code></pre>
</div>
<h4 split-filename="media" id="the-video-element">The <dfn element id="video"><code>video</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd>If the element has a <code data-x="attr-media-controls">controls</code> attribute: <span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the element has a <code data-x="attr-media-src">src</code> attribute:
zero or more <code>track</code> elements, then
<span>transparent</span>, but with no <span>media element</span> descendants.</dd>
<dd>If the element does not have a <code data-x="attr-media-src">src</code> attribute: zero or more <code>source</code> elements, then
zero or more <code>track</code> elements, then
<span>transparent</span>, but with no <span>media element</span> descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-media-src">src</code></dd>
<dd><code data-x="attr-media-crossorigin">crossorigin</code></dd>
<dd><code data-x="attr-video-poster">poster</code></dd>
<dd><code data-x="attr-media-preload">preload</code></dd>
<dd><code data-x="attr-media-autoplay">autoplay</code></dd>
<dd><code data-x="attr-video-playsinline">playsinline</code></dd>
<dd><code data-x="attr-media-loop">loop</code></dd>
<dd><code data-x="attr-media-muted">muted</code></dd>
<dd><code data-x="attr-media-controls">controls</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-video">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-video">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLVideoElement</dfn> : <span>HTMLMediaElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-dim-width">width</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-dim-height">height</span>;
readonly attribute unsigned long <span data-x="dom-video-videoWidth">videoWidth</span>;
readonly attribute unsigned long <span data-x="dom-video-videoHeight">videoHeight</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-video-poster">poster</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-video-playsInline">playsInline</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLVideoElement</code>.</dd>
</dl>
<p>A <code>video</code> element is used for playing videos or movies, and audio files with
captions.</p>
<p>Content may be provided inside the <code>video</code> element<span w-nodev>. User agents
should not show this content to the user</span>; it is intended for older web browsers which do
not support <code>video</code>, so that text can be shown to the users of these older browsers
informing them of how to access the video contents.</p>
<p class="note">In particular, this content is not intended to address accessibility concerns. To
make video content accessible to the partially sighted, the blind, the hard-of-hearing, the deaf,
and those with other physical or cognitive disabilities, a variety of features are available.
Captions can be provided, either embedded in the video stream or as external files using the
<code>track</code> element. Sign-language tracks can be embedded in the video stream. Audio
descriptions can be embedded in the video stream or in text form using a <span>WebVTT file</span>
referenced using the <code>track</code> element and synthesized into speech by the user agent.
WebVTT can also be used to provide chapter titles. For users who would rather not use a media
element at all, transcripts or other textual alternatives can be provided by simply linking to
them in the prose near the <code>video</code> element. <ref>WEBVTT</ref></p>
<p>The <code>video</code> element is a <span>media element</span> whose <span>media data</span> is
ostensibly video data, possibly with associated audio data.</p>
<p>The <code data-x="attr-media-src">src</code>, <code data-x="attr-media-crossorigin">crossorigin</code>,
<code data-x="attr-media-preload">preload</code>, <code data-x="attr-media-autoplay">autoplay</code>,
<code data-x="attr-media-loop">loop</code>, <code data-x="attr-media-muted">muted</code>, and <code
data-x="attr-media-controls">controls</code> attributes are <span data-x="media element
attributes">the attributes common to all media elements</span>.</p>
<p>The <dfn element-attr for="video"><code data-x="attr-video-poster">poster</code></dfn>
attribute gives the <span>URL</span> of an image file that the user agent can show while no video
data is available. The attribute, if present, must contain a <span>valid non-empty URL
potentially surrounded by spaces</span>.</p>
<div w-nodev>
<p>If the specified resource is to be used, then, when the element is created or when the <code
data-x="attr-video-poster">poster</code> attribute is set, changed, or removed, the user agent must
run the following steps to determine the element's <dfn>poster frame</dfn> (regardless of the
value of the element's <span>show poster flag</span>):</p> <!-- thus it is unaffected by changes
to the base URL. -->
<ol>
<li><p>If there is an existing instance of this algorithm running for this <code>video</code>
element, abort that instance of this algorithm without changing the <span>poster
frame</span>.</p></li>
<li><p>If the <code data-x="attr-video-poster">poster</code> attribute's value is the empty string
or if the attribute is absent, then there is no <span>poster frame</span>; return.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given the <code
data-x="attr-video-poster">poster</code> attribute's value, relative to the element's <span>node
document</span>.</p></li>
<li><p>If <var>url</var> is failure, then return. <span class="note">There is no <span>poster
frame</span>.</span></p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is the element's <span>node document</span>'s
<span>relevant settings object</span>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">image</code>", <span
data-x="concept-request-initiator-type">initiator type</span> is "<code data-x="">video</code>",
<span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", and whose <span>use-URL-credentials flag</span> is set.
<li><p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var>. This must
<span>delay the load event</span> of the element's <span>node document</span>.</p></li>
<!-- could define how to sniff for an image here -->
<li><p>If an image is thus obtained, the <span>poster frame</span> is that image. Otherwise,
there is no <span>poster frame</span>.</p></li>
</ol>
</div>
<p class="note">The image given by the <code data-x="attr-video-poster">poster</code> attribute,
the <i data-x="poster frame">poster frame</i>, is intended to be a representative frame of the
video (typically one of the first non-blank frames) that gives the user an idea of what the video
is like.</p>
<p>The <dfn element-attr for="video"><code
data-x="attr-video-playsinline">playsinline</code></dfn> attribute is a <span>boolean
attribute</span>. If present, it serves as a hint to the user agent that the video ought to be
displayed "inline" in the document by default, constrained to the element's playback area, instead
of being displayed fullscreen or in an independent resizable window.</p>
<p class="note">The absence of the <code data-x="attr-video-playsinline">playsinline</code>
attribute does not imply that the video will display fullscreen by default. Indeed, most user
agents have chosen to play all videos inline by default, and in such user agents the <code
data-x="attr-video-playsinline">playsinline</code> attribute has no effect.</p>
<div w-nodev>
<hr>
<p>A <code>video</code> element represents what is given for the first matching condition in the
list below:</p>
<dl class="switch">
<dt>When no video data is available (the element's <code
data-x="dom-media-readyState">readyState</code> attribute is either <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, or <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> but no video data has yet been obtained at
all, or the element's <code data-x="dom-media-readyState">readyState</code> attribute is any
subsequent value but the <span>media resource</span> does not have a video channel)</dt>
<dd>The <code>video</code> element <span>represents</span> its <span>poster frame</span>, if any,
or else <span>transparent black</span> with no <span>natural dimensions</span>.</dd>
<dt>When the <code>video</code> element is <span data-x="dom-media-paused">paused</span>, the <span
data-x="current playback position">current playback position</span> is the first frame of video,
and the element's <span>show poster flag</span> is set</dt>
<dd>The <code>video</code> element <span>represents</span> its <span>poster frame</span>, if any,
or else the first frame of the video.</dd>
<dt>When the <code>video</code> element is <span data-x="dom-media-paused">paused</span>, and the
frame of video corresponding to the <span data-x="current playback position">current playback
position</span> is not available (e.g. because the video is seeking or buffering)</dt>
<dt>When the <code>video</code> element is neither <span>potentially playing</span> nor <span
data-x="dom-media-paused">paused</span> (e.g. when seeking or stalled)</dt>
<dd>The <code>video</code> element <span>represents</span> the last frame of the video to have
been rendered.</dd>
<dt>When the <code>video</code> element is <span data-x="dom-media-paused">paused</span></dt>
<dd>The <code>video</code> element <span>represents</span> the frame of video corresponding to
the <span data-x="current playback position">current playback position</span>.</dd>
<dt>Otherwise (the <code>video</code> element has a video channel and is <span>potentially
playing</span>)</dt>
<dd>The <code>video</code> element <span>represents</span> the frame of video at the continuously
increasing <span data-x="current playback position">"current" position</span>. When the
<span>current playback position</span> changes such that the last frame rendered is no longer the
frame corresponding to the <span>current playback position</span> in the video, the new frame
must be rendered.</dd>
</dl>
<p>Frames of video must be obtained from the video track that was <span
data-x="dom-VideoTrack-selected">selected</span> when the <span>event loop</span> last reached
<a href="#step1">step 1</a>.</p>
<p class="note">Which frame in a video stream corresponds to a particular playback position is
defined by the video stream's format.</p>
<p>The <code>video</code> element also <span>represents</span> any <span data-x="text track
cue">text track cues</span> whose <span>text track cue active flag</span> is set and whose
<span>text track</span> is in the <span data-x="text track showing">showing</span> mode, and any
audio from the <span>media resource</span>, at the <span>current playback position</span>.</p>
<p>Any audio associated with the <span>media resource</span> must, if played, be played
synchronized with the <span>current playback position</span>, at the element's <span>effective
media volume</span>. The user agent must play the audio from audio tracks that were <span
data-x="dom-AudioTrack-enabled">enabled</span> when the <span>event loop</span> last reached step
1.</p>
<p>In addition to the above, the user agent may provide messages to the user (such as "buffering",
"no video loaded", "error", or more detailed information) by overlaying text or icons on the video
or other areas of the element's playback area, or in another appropriate manner.</p>
<p>User agents that cannot render the video may instead make the element <span
data-x="represents">represent</span> a link to an external video playback utility or to the video
data itself.</p>
<p>When a <code>video</code> element's <span>media resource</span> has a video channel, the
element provides a <span>paint source</span> whose width is the <span>media resource</span>'s
<span data-x="concept-video-natural-width">natural width</span>, whose height is the
<span>media resource</span>'s <span data-x="concept-video-natural-height">natural
height</span>, and whose appearance is the frame of video corresponding to the <span
data-x="current playback position">current playback position</span>, if that is available, or else
(e.g. when the video is seeking or buffering) its previous appearance, if any, or else (e.g.
because the video is still loading the first frame) blackness.</p>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>video</var>.<span subdfn data-x="dom-video-videoWidth">videoWidth</span></code></dt>
<dt><code data-x=""><var>video</var>.<span subdfn data-x="dom-video-videoHeight">videoHeight</span></code></dt>
<dd>
<p>These attributes return the natural dimensions of the video, or 0 if the dimensions are not
known.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn data-x="concept-video-natural-width" id="concept-video-intrinsic-width">natural
width</dfn> and <dfn data-x="concept-video-natural-height"
id="concept-video-intrinsic-height">natural height</dfn> of the <span>media resource</span> are
the dimensions of the resource in <span data-x="'px'">CSS pixels</span> after taking into account
the resource's dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for
the format used by the resource. If an anamorphic format does not define how to apply the aspect
ratio to the video data's dimensions to obtain the "correct" dimensions, then the user agent must
apply the ratio by increasing one dimension and leaving the other unchanged.</p>
<p>The <dfn attribute for="HTMLVideoElement"><code
data-x="dom-video-videoWidth">videoWidth</code></dfn> IDL attribute must return the <span
data-x="concept-video-natural-width">natural width</span> of the video in <span
data-x="'px'">CSS pixels</span>. The <dfn attribute for="HTMLVideoElement"><code
data-x="dom-video-videoHeight">videoHeight</code></dfn> IDL attribute must return the <span
data-x="concept-video-natural-height">natural height</span> of the video in <span
data-x="'px'">CSS pixels</span>. If the element's <code
data-x="dom-media-readyState">readyState</code> attribute is <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, then the attributes must return 0.</p>
<p id="dimUpdate">Whenever the <span data-x="concept-video-natural-width">natural width</span>
or <span data-x="concept-video-natural-height">natural height</span> of the video changes
(including, for example, because the <span data-x="dom-VideoTrack-selected">selected video
track</span> was changed), if the element's <code data-x="dom-media-readyState">readyState</code>
attribute is not <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, the user agent must
<span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-resize">resize</code> at the <span>media element</span>.</p>
</div>
<p>The <code>video</code> element supports <span>dimension attributes</span>.</p>
<div w-nodev>
<p>In the absence of style rules to the contrary, video content should be rendered inside the
element's playback area such that the video content is shown centered in the playback area at the
largest possible size that fits completely within it, with the video content's aspect ratio being
preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the
video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area
that do not contain the video represent nothing.</p>
<p class="note">In user agents that implement CSS, the above requirement can be implemented by
using the <a href="#video-object-fit">style rule suggested in the Rendering section</a>.</p>
<p>The <span>natural width</span> of a <code>video</code> element's playback area is the
<span>natural width</span> of the <span>poster frame</span>, if that is available and the
element currently <span>represents</span> its poster frame; otherwise, it is the <span
data-x="concept-video-natural-width">natural width</span> of the video resource, if that is
available; otherwise the <span>natural width</span> is missing.</p>
<p>The <span>natural height</span> of a <code>video</code> element's playback area is the
<span>natural height</span> of the <span>poster frame</span>, if that is available and the
element currently <span>represents</span> its poster frame; otherwise it is the <span
data-x="concept-video-natural-height">natural height</span> of the video resource, if that is
available; otherwise the <span>natural height</span> is missing.</p>
<p>The <span>default object size</span> is a width of 300 <span data-x="'px'">CSS pixels</span>
and a height of 150 <span data-x="'px'">CSS pixels</span>. <ref>CSSIMAGES</ref></p>
<hr>
<p>User agents should provide controls to enable or disable the display of closed captions, audio
description tracks, and other additional data associated with the video stream, though such
features should, again, not interfere with the page's normal rendering.</p>
<p>User agents may allow users to view the video content in manners more suitable to the user,
such as fullscreen or in an independent resizable window. User agents may even trigger such a
viewing mode by default upon playing a video, although they should not do so when the <code
data-x="attr-video-playsinline">playsinline</code> attribute is specified. As with the other user
interface features, controls to enable this should not interfere with the page's normal rendering
unless the user agent is <span data-x="expose a user interface to the user">exposing a user
interface</span>. In such an independent viewing mode, however, user agents may make full user
interfaces visible, even if the <code data-x="attr-media-controls">controls</code> attribute is
absent.</p>
<p>User agents may allow video playback to affect system features that could interfere with the
user's experience; for example, user agents could disable screensavers while video playback is in
progress.</p>
<hr>
<p>The <dfn attribute for="HTMLVideoElement"><code data-x="dom-video-poster">poster</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-video-poster">poster</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLVideoElement"><code
data-x="dom-video-playsInline">playsInline</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-video-playsinline">playsinline</code> content attribute.</p>
</div>
<div class="example">
<p>This example shows how to detect when a video has failed to play correctly:</p>
<pre><code class="html"><script>
function failed(e) {
// video playback failed - show a message saying why
switch (e.target.error.code) {
case e.target.error.MEDIA_ERR_ABORTED:
alert('You aborted the video playback.');
break;
case e.target.error.MEDIA_ERR_NETWORK:
alert('A network error caused the video download to fail part-way.');
break;
case e.target.error.MEDIA_ERR_DECODE:
alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
break;
case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
break;
default:
alert('An unknown error occurred.');
break;
}
}
</script>
<p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
<p><a href="tgif.vid">Download the video file</a>.</p></code></pre>
</div>
<!--CODECS
<div w-nodev>
<h5>Video and audio codecs for <code>video</code> elements</h5>
<p>User agents may support any video and audio codecs and container formats.</p>
<p class="note">Certain user agents might support no codecs at all, e.g. text browsers running
over SSH connections.</p>
<!- - similar note in audio codecs section - ->
<p class="note">Implementations are free to implement support for video codecs either natively, or
using platform-specific APIs: this specification does not specify how codecs are
to be implemented.</p>
</div>
(when replacing this text, also fix "- -" nested comments)-->
<h4 id="the-audio-element">The <dfn element id="audio"><code>audio</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd>If the element has a <code data-x="attr-media-controls">controls</code> attribute: <span>Interactive content</span>.</dd>
<dd>If the element has a <code data-x="attr-media-controls">controls</code> attribute: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the element has a <code data-x="attr-media-src">src</code> attribute:
zero or more <code>track</code> elements, then
<span>transparent</span>, but with no <span>media element</span> descendants.</dd>
<dd>If the element does not have a <code data-x="attr-media-src">src</code> attribute: zero or more <code>source</code> elements, then
zero or more <code>track</code> elements, then
<span>transparent</span>, but with no <span>media element</span> descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-media-src">src</code></dd>
<dd><code data-x="attr-media-crossorigin">crossorigin</code></dd>
<dd><code data-x="attr-media-preload">preload</code></dd>
<dd><code data-x="attr-media-autoplay">autoplay</code></dd>
<dd><code data-x="attr-media-loop">loop</code></dd>
<dd><code data-x="attr-media-muted">muted</code></dd>
<dd><code data-x="attr-media-controls">controls</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-audio">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-audio">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window,
<span>LegacyFactoryFunction</span>=<span data-x="dom-Audio">Audio</span>(optional DOMString src)]
interface <dfn interface>HTMLAudioElement</dfn> : <span>HTMLMediaElement</span> {
[<span>HTMLConstructor</span>] constructor();
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLAudioElement</code>.</dd>
</dl>
<p>An <code>audio</code> element <span>represents</span> a sound or audio stream.</p>
<!-- v2 (actually v3) suggestions:
* Audio synthesis. Use cases from Charles Pritchard:
> Use a sound of varying pitch to hint to a user the location of their
> mouse (is it hovering over a button, is it x/y pixels away from the edge
> of the screen, how close is it to the center).
>
> Alter the pitch of a sound to make a very cheap midi instrument.
>
> Pre-mix a few generated sounds, because the client processor is slow.
>
> Alter the pitch of an actual audio recording, and pre-mix it, to give
> different sounding voices to pre-recorded readings of a single text. As
> has been tried for "male" "female" sound fonts.
>
> Support very simple audio codecs, and programmable synthesizers.
-->
<p>Content may be provided inside the <code>audio</code> element<span w-nodev>. User agents
should not show this content to the user</span>; it is intended for older web browsers which do
not support <code>audio</code>, so that text can be shown to the users of these older browsers
informing them of how to access the audio contents.</p>
<p class="note">In particular, this content is not intended to address accessibility concerns. To
make audio content accessible to the deaf or to those with other physical or cognitive
disabilities, a variety of features are available. If captions or a sign language video are
available, the <code>video</code> element can be used instead of the <code>audio</code> element to
play the audio, allowing users to enable the visual alternatives. Chapter titles can be provided
to aid navigation, using the <code>track</code> element and a <span>WebVTT file</span>. And,
naturally, transcripts or other textual alternatives can be provided by simply linking to them in
the prose near the <code>audio</code> element. <ref>WEBVTT</ref></p>
<p>The <code>audio</code> element is a <span>media element</span> whose <span>media data</span> is
ostensibly audio data.</p>
<p>The <code data-x="attr-media-src">src</code>, <code data-x="attr-media-crossorigin">crossorigin</code>,
<code data-x="attr-media-preload">preload</code>, <code data-x="attr-media-autoplay">autoplay</code>,
<code data-x="attr-media-loop">loop</code>, <code data-x="attr-media-muted">muted</code>, and <code
data-x="attr-media-controls">controls</code> attributes are <span data-x="media element
attributes">the attributes common to all media elements</span>.</p>
<dl class="domintro">
<dt><code data-x=""><var>audio</var> = new <span subdfn data-x="dom-Audio">Audio</span>([ <var>url</var> ])</code></dt>
<dd>
<p>Returns a new <code>audio</code> element, with the <code data-x="attr-media-src">src</code>
attribute set to the value passed in the argument, if applicable.</p>
</dd>
</dl>
<div w-nodev>
<p>A legacy factory function is provided for creating <code>HTMLAudioElement</code> objects (in
addition to the factory methods from DOM such as <code
data-x="dom-Document-createElement">createElement()</code>): <dfn><code
data-x="dom-Audio">Audio(<var>src</var>)</code></dfn>. When invoked, the legacy factory function
must perform the following steps:</p>
<ol>
<li><p>Let <var>document</var> be the <span>current global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>audio</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">audio</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span> for
<var>audio</var> using "<code data-x="attr-media-preload">preload</code>" and "<code
data-x="attr-media-preload-auto">auto</code>".</p></li>
<li><p>If <var>src</var> is given, then <span data-x="concept-element-attributes-set-value">set
an attribute value</span> for <var>audio</var> using "<code data-x="attr-media-src">src</code>"
and <var>src</var>. (This will <a href="#concept-media-load-algorithm-at-creation">cause the user
agent to invoke</a> the object's <span data-x="concept-media-load-algorithm">resource selection
algorithm</span> before returning.)</p></li>
<li><p>Return <var>audio</var>.</p></li>
</ol>
</div>
<!--CODECS
<div w-nodev>
<h5>Audio codecs for <code>audio</code> elements</h5>
<p>User agents may support any audio codecs and container formats.</p>
<p>User agents must support the WAVE container format with audio encoded using the 16 bit PCM (LE)
codec, at sampling frequencies of 11.025kHz, 22.050kHz, and 44.100kHz, and for both mono and
stereo. <a href="#- -refsWAVE">[WAVE]</a></p>
<!- -
<dt id="- -refsWAVE">WAVE</dt>
<dd>https://en.wikipedia.org/wiki/WAV? </dd>
- ->
<!- - similar note in video codecs section - ->
<p class="note">Implementations are free to implement support for audio codecs either natively, or
using platform-specific APIs: this specification does not specify how codecs are
to be implemented.</p>
</div>
(when replacing this text, also fix "- -" nested comments)-->
<h4>The <dfn element><code>track</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <span>media element</span>, before any <span>flow content</span>.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-track-kind">kind</code></dd>
<dd><code data-x="attr-track-src">src</code></dd>
<dd><code data-x="attr-track-srclang">srclang</code></dd>
<dd><code data-x="attr-track-label">label</code></dd>
<dd><code data-x="attr-track-default">default</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-track">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-track">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTrackElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-track-kind">kind</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-track-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-track-srclang">srclang</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-track-label">label</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-track-default">default</span>;
const unsigned short <span data-x="dom-track-NONE">NONE</span> = 0;
const unsigned short <span data-x="dom-track-LOADING">LOADING</span> = 1;
const unsigned short <span data-x="dom-track-LOADED">LOADED</span> = 2;
const unsigned short <span data-x="dom-track-ERROR">ERROR</span> = 3;
readonly attribute unsigned short <span data-x="dom-track-readyState">readyState</span>;
readonly attribute <span>TextTrack</span> <span data-x="dom-track-track">track</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTrackElement</code>.</dd>
</dl>
<p>The <code>track</code> element allows authors to specify explicit external timed <span
data-x="text track">text tracks</span> for <span data-x="media element">media elements</span>. It
does not <span data-x="represents">represent</span> anything on its own.</p>
<p>The <dfn element-attr for="track"><code data-x="attr-track-kind">kind</code></dfn> attribute is
an <span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="track/kind"><code
data-x="attr-track-kind-keyword-subtitles">subtitles</code></dfn>
<td><dfn data-x="attr-track-kind-subtitles">Subtitles</dfn>
<td>
Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the <span>media resource</span>'s audio track).
Overlaid on the video.
<tr>
<td><dfn attr-value for="track/kind"><code
data-x="attr-track-kind-keyword-captions">captions</code></dfn>
<td><dfn data-x="attr-track-kind-captions">Captions</dfn>
<td>
Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf).
Overlaid on the video; labeled as appropriate for the hard-of-hearing.
<tr>
<td><dfn attr-value for="track/kind"><code
data-x="attr-track-kind-keyword-descriptions">descriptions</code></dfn>
<td><dfn data-x="attr-track-kind-descriptions">Descriptions</dfn>
<td>
Textual descriptions of the video component of the <span>media resource</span>, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind).
Synthesized as audio.
<tr>
<td><dfn attr-value for="track/kind"><code
data-x="attr-track-kind-keyword-chapters">chapters</code></dfn>
<td><dfn data-x="attr-track-kind-chapters">Chapters metadata</dfn>
<td rowspan="2">
Tracks intended for use from script.
Not displayed by the user agent.
<tr>
<td><dfn attr-value for="track/kind"><code
data-x="attr-track-kind-keyword-metadata">metadata</code></dfn>
<td><dfn data-x="attr-track-kind-metadata">Metadata</dfn>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <span
data-x="attr-track-kind-subtitles">subtitles</span> state, and its <i data-x="invalid value
default">invalid value default</i> is the <span data-x="attr-track-kind-metadata">metadata</span>
state.</p>
<p>The <dfn element-attr for="track"><code data-x="attr-track-src">src</code></dfn> attribute
gives the <span>URL</span> of the text track data. The value must be a <span>valid non-empty URL
potentially surrounded by spaces</span>. This attribute must be present.</p>
<div w-nodev>
<p>The element has an associated <dfn>track URL</dfn> (a string), initially the empty string.</p>
<p>When the element's <code data-x="attr-track-src">src</code> attribute is set, run these steps:
<ol>
<li><p>Let <var>trackURL</var> be failure.</p></li>
<li><p>Let <var>value</var> be the element's <code data-x="attr-track-src">src</code> attribute
value.</p></li>
<li><p>If <var>value</var> is not the empty string, then set <var>trackURL</var> to the result of
<span>encoding-parsing-and-serializing a URL</span> given <var>value</var>, relative to the
element's <span>node document</span>.</p></li>
<li><p>Set the element's <span>track URL</span> to <var>trackURL</var> if it is not failure;
otherwise to the empty string.</p></li>
</ol>
</div>
<p>If the element's <span>track URL</span> identifies a WebVTT resource, and the element's <code
data-x="attr-track-kind">kind</code> attribute is not in the <span
data-x="attr-track-kind-chapters">chapters metadata</span> or <span
data-x="attr-track-kind-metadata">metadata</span> state, then the WebVTT file must be a
<span>WebVTT file using cue text</span>. <ref>WEBVTT</ref></p>
<p>The <dfn element-attr for="track"><code data-x="attr-track-srclang">srclang</code></dfn>
attribute gives the language of the text track data. The value must be a valid BCP 47 language
tag. This attribute must be present if the element's <code data-x="attr-track-kind">kind</code>
attribute is in the <span data-x="attr-track-kind-subtitles">subtitles</span> state.
<ref>BCP47</ref></p>
<div w-nodev>
<p>If the element has a <code data-x="attr-track-srclang">srclang</code> attribute whose value is
not the empty string, then the element's <dfn>track language</dfn> is the value of the attribute.
Otherwise, the element has no <span>track language</span>.</p>
</div>
<p>The <dfn element-attr for="track"><code data-x="attr-track-label">label</code></dfn> attribute
gives a user-readable title for the track. This title is used by user agents when listing <span
data-x="attr-track-kind-subtitles">subtitle</span>, <span
data-x="attr-track-kind-captions">caption</span>, and <span
data-x="attr-track-kind-descriptions">audio description</span> tracks in their user interface.</p>
<p>The value of the <code data-x="attr-track-label">label</code> attribute, if the attribute is
present, must not be the empty string. Furthermore, there must not be two <code>track</code>
element children of the same <span>media element</span> whose <code
data-x="attr-track-kind">kind</code> attributes are in the same state, whose <code
data-x="attr-track-srclang">srclang</code> attributes are both missing or have values that
represent the same language, and whose <code data-x="attr-track-label">label</code> attributes are
again both missing or both have the same value.</p>
<div w-nodev>
<p>If the element has a <code data-x="attr-track-label">label</code> attribute whose value is not
the empty string, then the element's <dfn>track label</dfn> is the value of the attribute.
Otherwise, the element's <span>track label</span> is an empty string.</p>
</div>
<p>The <dfn element-attr for="track"><code data-x="attr-track-default">default</code></dfn>
attribute is a <span>boolean attribute</span>, which, if specified, indicates that the track is to
be enabled if the user's preferences do not indicate that another track would be more
appropriate.</p>
<p>Each <span>media element</span> must have no more than one <code>track</code> element child
whose <code data-x="attr-track-kind">kind</code> attribute is in the <span
data-x="attr-track-kind-subtitles">subtitles</span> or <span
data-x="attr-track-kind-captions">captions</span> state and whose <code
data-x="attr-track-default">default</code> attribute is specified.</p>
<p>Each <span>media element</span> must have no more than one <code>track</code> element child
whose <code data-x="attr-track-kind">kind</code> attribute is in the <span
data-x="attr-track-kind-descriptions">description</span> state and whose <code
data-x="attr-track-default">default</code> attribute is specified.</p>
<p>Each <span>media element</span> must have no more than one <code>track</code> element child
whose <code data-x="attr-track-kind">kind</code> attribute is in the <span
data-x="attr-track-kind-chapters">chapters metadata</span> state and whose <code
data-x="attr-track-default">default</code> attribute is specified.</p>
<p class="note">There is no limit on the number of <code>track</code> elements whose <code
data-x="attr-track-kind">kind</code> attribute is in the <span
data-x="attr-track-kind-metadata">metadata</span> state and whose <code
data-x="attr-track-default">default</code> attribute is specified.</p>
<dl class="domintro">
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-readyState">readyState</span></code></dt>
<dd>
<p>Returns the <span>text track readiness state</span>, represented by a number from the
following list:</p>
<dl>
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-NONE">NONE</span> (0)</code></dt>
<dd><p>The <span>text track not loaded</span> state.</p></dd>
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-LOADING">LOADING</span> (1)</code></dt>
<dd><p>The <span>text track loading</span> state.</p></dd>
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-LOADED">LOADED</span> (2)</code></dt>
<dd><p>The <span>text track loaded</span> state.</p></dd>
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-ERROR">ERROR</span> (3)</code></dt>
<dd><p>The <span>text track failed to load</span> state.</p></dd>
</dl>
</dd>
<dt><code data-x=""><var>track</var>.<span subdfn data-x="dom-track-track">track</span></code></dt>
<dd>
<p>Returns the <code>TextTrack</code> object corresponding to the <span>text track</span> of the
<code>track</code> element.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLTrackElement"><code
data-x="dom-track-readyState">readyState</code></dfn> attribute must return the numeric value
corresponding to the <span>text track readiness state</span> of the <code>track</code> element's
<span>text track</span>, as defined by the following list:</p>
<dl>
<dt><dfn const for="HTMLTrackElement"><code data-x="dom-track-NONE">NONE</code></dfn> (numeric value 0)</dt>
<dd>The <span>text track not loaded</span> state.</dd>
<dt><dfn const for="HTMLTrackElement"><code data-x="dom-track-LOADING">LOADING</code></dfn> (numeric value 1)</dt>
<dd>The <span>text track loading</span> state.</dd>
<dt><dfn const for="HTMLTrackElement"><code data-x="dom-track-LOADED">LOADED</code></dfn> (numeric value 2)</dt>
<dd>The <span>text track loaded</span> state.</dd>
<dt><dfn const for="HTMLTrackElement"><code data-x="dom-track-ERROR">ERROR</code></dfn> (numeric value 3)</dt>
<dd>The <span>text track failed to load</span> state.</dd>
</dl>
<p>The <dfn attribute for="HTMLTrackElement"><code data-x="dom-track-track">track</code></dfn> IDL
attribute must, on getting, return the <code>track</code> element's <span>text track</span>'s
corresponding <code>TextTrack</code> object.</p>
<p>The <dfn attribute for="HTMLTrackElement"><code data-x="dom-track-src">src</code></dfn>, <dfn
attribute for="HTMLTrackElement"><code data-x="dom-track-srclang">srclang</code></dfn>, <dfn
attribute for="HTMLTrackElement"><code data-x="dom-track-label">label</code></dfn>, and <dfn
attribute for="HTMLTrackElement"><code data-x="dom-track-default">default</code></dfn> IDL
attributes must <span>reflect</span> the respective content attributes of the same name. The <dfn
attribute for="HTMLTrackElement"><code data-x="dom-track-kind">kind</code></dfn> IDL attribute
must <span>reflect</span> the content attribute of the same name, <span>limited to only known
values</span>.</p>
</div>
<div class="example">
<p>This video has subtitles in several languages:</p>
<pre><code class="html"><video src="brave.webm">
<track kind=subtitles src=brave.en.vtt srclang=en label="English">
<track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
<track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
<track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
</video></code></pre>
<p>(The <code data-x="attr-lang">lang</code> attributes on the last two describe the language of
the <code data-x="attr-track-label">label</code> attribute, not the language of the subtitles
themselves. The language of the subtitles is given by the <code
data-x="attr-track-srclang">srclang</code> attribute.)</p>
</div>
<h4>Media elements</h4>
<p><span>HTMLMediaElement</span> objects (<code>audio</code> and <code>video</code>, in this
specification) are simply known as <dfn data-x="media element" data-lt="media element"
export>media elements</dfn>.</p>
<pre><code class="idl">enum <dfn enum>CanPlayTypeResult</dfn> { "" /* <span data-x="dom-CanPlayTypeResult-nil">empty string</span> */, "<span data-x="dom-CanPlayTypeResult-maybe">maybe</span>", "<span data-x="dom-CanPlayTypeResult-probably">probably</span>" };
typedef (<span>MediaStream</span> or <span>MediaSource</span> or <span>Blob</span>) <dfn typedef>MediaProvider</dfn>;
[Exposed=Window]
interface <dfn interface>HTMLMediaElement</dfn> : <span>HTMLElement</span> {
// error state
readonly attribute <span>MediaError</span>? <span data-x="dom-media-error">error</span>;
// network state
[<span>CEReactions</span>] attribute USVString <span data-x="dom-media-src">src</span>;
attribute <span>MediaProvider</span>? <span data-x="dom-media-srcObject">srcObject</span>;
readonly attribute USVString <span data-x="dom-media-currentSrc">currentSrc</span>;
[<span>CEReactions</span>] attribute DOMString? <span data-x="dom-media-crossOrigin">crossOrigin</span>;
const unsigned short <span data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</span> = 0;
const unsigned short <span data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</span> = 1;
const unsigned short <span data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</span> = 2;
const unsigned short <span data-x="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</span> = 3;
readonly attribute unsigned short <span data-x="dom-media-networkState">networkState</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-media-preload">preload</span>;
<!--v3BUF readonly attribute double <span data-x="dom-media-bufferingRate">bufferingRate</span>;
readonly attribute boolean <span data-x="dom-media-bufferingThrottled">bufferingThrottled</span>;
--> readonly attribute <span>TimeRanges</span> <span data-x="dom-media-buffered">buffered</span>;
undefined <span data-x="dom-media-load">load</span>();
<span>CanPlayTypeResult</span> <span data-x="dom-navigator-canPlayType">canPlayType</span>(DOMString type);
// ready state
const unsigned short <span data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</span> = 0;
const unsigned short <span data-x="dom-media-HAVE_METADATA">HAVE_METADATA</span> = 1;
const unsigned short <span data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</span> = 2;
const unsigned short <span data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</span> = 3;
const unsigned short <span data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</span> = 4;
readonly attribute unsigned short <span data-x="dom-media-readyState">readyState</span>;
readonly attribute boolean <span data-x="dom-media-seeking">seeking</span>;
// playback state
attribute double <span data-x="dom-media-currentTime">currentTime</span>;
undefined <span data-x="dom-media-fastSeek">fastSeek</span>(double time);
readonly attribute unrestricted double <span data-x="dom-media-duration">duration</span>;
<span data-x="idl-object">object</span> <span data-x="dom-media-getStartDate">getStartDate</span>();
readonly attribute boolean <span data-x="dom-media-paused">paused</span>;
attribute double <span data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</span>;
attribute double <span data-x="dom-media-playbackRate">playbackRate</span>;
attribute boolean <span data-x="dom-media-preservesPitch">preservesPitch</span>;
readonly attribute <span>TimeRanges</span> <span data-x="dom-media-played">played</span>;
readonly attribute <span>TimeRanges</span> <span data-x="dom-media-seekable">seekable</span>;
readonly attribute boolean <span data-x="dom-media-ended">ended</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-media-autoplay">autoplay</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-media-loop">loop</span>;
<span data-x="idl-Promise">Promise</span><undefined> <span data-x="dom-media-play">play</span>();
undefined <span data-x="dom-media-pause">pause</span>();
// controls
[<span>CEReactions</span>] attribute boolean <span data-x="dom-media-controls">controls</span>;
attribute double <span data-x="dom-media-volume">volume</span>;
attribute boolean <span data-x="dom-media-muted">muted</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-media-defaultMuted">defaultMuted</span>;
// tracks
[SameObject] readonly attribute <span>AudioTrackList</span> <span data-x="dom-media-audioTracks">audioTracks</span>;
[SameObject] readonly attribute <span>VideoTrackList</span> <span data-x="dom-media-videoTracks">videoTracks</span>;
[SameObject] readonly attribute <span>TextTrackList</span> <span data-x="dom-media-textTracks">textTracks</span>;
<span>TextTrack</span> <span data-x="dom-media-addTextTrack">addTextTrack</span>(<span>TextTrackKind</span> kind, optional DOMString label = "", optional DOMString language = "");
};</code></pre>
<p>The <dfn>media element attributes</dfn>, <code data-x="attr-media-src">src</code>, <code
data-x="attr-media-crossorigin">crossorigin</code>, <code
data-x="attr-media-preload">preload</code>, <code data-x="attr-media-autoplay">autoplay</code>,
<code data-x="attr-media-loop">loop</code>, <code data-x="attr-media-muted">muted</code>, and
<code data-x="attr-media-controls">controls</code>, apply to all <span data-x="media
element">media elements</span>. They are defined in this section.</p>
<!-- proposed v2 (actually v3!) features:
* frame forward / backwards / step(n) while paused
* per-frame control: get current frame; set current frame
* queue of content
- pause current stream and insert content at front of queue to play immediately
- pre-download another stream
- add stream(s) to play at end of current stream
- pause playback upon reaching a certain time
- playlists, with the ability to get metadata out of them (e.g. xspf)
* general meta data, implemented as getters (don't expose the whole thing)
- getMetadata(key: string, language: string) => HTMLImageElement or string
- onmetadatachanged (no context info)
- general custom metadata store (ratings, etc.)
* video: applying CSS filters
* an event to notify people of when the video size changes
(e.g. for chained Ogg streams of multiple independent videos)
(or for when the current video track changes)
* balance and 3D position audio
* audio filters
* audio synthesis (see <audio> section for use cases)
* feedback to the script on how well the video is playing
- frames per second?
- skipped frames per second?
- an event that reports playback difficulties?
- an arbitrary quality metric?
* bufferingRate/bufferingThrottled (see v3BUF)
* events for when the user agent's controls get shown or hidden
so that the author's controls can get away of the UA's
-->
<p><span data-x="media element">Media elements</span> are used to present audio data, or video and
audio data, to the user. This is referred to as <dfn for=HTMLMediaElement export>media data</dfn>
in this section, since this section applies equally to <span data-x="media element">media
elements</span> for audio or for video.
The term <dfn>media resource</dfn> is used to refer to the complete set of media data, e.g. the
complete video file, or complete audio file.
</p>
<p>A <span>media resource</span> has an associated
<dfn data-x="media-resource-origin">origin</dfn>, which is either "<code data-x="">none</code>",
"<code data-x="">multiple</code>", "<code data-x="">rewritten</code>", or an
<span>origin</span>. It is initially set to "<code data-x="">none</code>".</p>
<p>A <span>media resource</span> can have multiple audio and video tracks. For the purposes of a
<span>media element</span>, the video data of the <span>media resource</span> is only that of the
currently selected track (if any) as given by the element's <code
data-x="dom-media-videoTracks">videoTracks</code> attribute when the <span>event loop</span> last
reached <a href="#step1">step 1</a>, and the audio data of the <span>media resource</span> is the result of mixing all
the currently enabled tracks (if any) given by the element's <code
data-x="dom-media-audioTracks">audioTracks</code> attribute when the <span>event loop</span> last
reached <a href="#step1">step 1</a>.</p>
<p class="note">Both <code>audio</code> and <code>video</code> elements can be used for both audio
and video. The main difference between the two is simply that the <code>audio</code> element has
no playback area for visual content (such as video or captions), whereas the <code>video</code>
element does.</p>
<div w-nodev>
<p>Each <span>media element</span> has a unique <dfn>media element event task source</dfn>.</p>
<p>To <dfn export>queue a media element task</dfn> with a <span>media element</span>
<var>element</var> and a series of steps <var>steps</var>, <span>queue an element task</span> on
the <span>media element</span>'s <span>media element event task source</span> given
<var>element</var> and <var>steps</var>.</p>
</div>
<h5>Error codes</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-error">error</span></code></dt>
<dd>
<p>Returns a <code>MediaError</code> object representing the current error state of the
element.</p>
<p>Returns null if there is no error.</p>
</dd>
</dl>
<div w-nodev>
<p>All <span data-x="media element">media elements</span> have an associated error status, which
records the last error the element encountered since its <span
data-x="concept-media-load-algorithm">resource selection algorithm</span> was last invoked. The
<dfn attribute for="HTMLMediaElement"><code data-x="dom-media-error">error</code></dfn> attribute,
on getting, must return the <code>MediaError</code> object created for this last error, or null if
there has not been an error.</p>
</div>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>MediaError</dfn> {
const unsigned short <span data-x="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</span> = 1;
const unsigned short <span data-x="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</span> = 2;
const unsigned short <span data-x="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</span> = 3;
const unsigned short <span data-x="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED">MEDIA_ERR_SRC_NOT_SUPPORTED</span> = 4;
readonly attribute unsigned short <span data-x="dom-MediaError-code">code</span>;
readonly attribute DOMString <span data-x="dom-MediaError-message">message</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-error">error</span>.<span subdfn data-x="dom-MediaError-code">code</span></code></dt>
<dd><p>Returns the current error's error code, from the list below.</p></dd>
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-error">error</span>.<span subdfn data-x="dom-MediaError-message">message</span></code></dt>
<dd>
<p>Returns a specific informative diagnostic message about the error condition encountered. The
message and message format are not generally uniform across different user agents. If no such
message is available, then the empty string is returned.</p>
</dd>
</dl>
<div w-nodev>
<p>Every <code>MediaError</code> object has a <dfn
data-x="concept-MediaError-message">message</dfn>, which is a string, and a <dfn
data-x="concept-MediaError-code">code</dfn>, which is one of the following:</p>
</div>
<dl>
<dt><dfn const for="MediaError"><code data-x="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</code></dfn> (numeric value 1)</dt>
<dd>The fetching process for the <span>media resource</span> was aborted by the user agent at the
user's request.</dd>
<dt><dfn const for="MediaError"><code data-x="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
<dd>A network error of some description caused the user agent to stop fetching the <span>media
resource</span>, after the resource was established to be usable.</dd>
<dt><dfn const for="MediaError"><code data-x="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
<dd>An error of some description occurred while decoding the <span>media resource</span>, after
the resource was established to be usable.</dd>
<dt><dfn const for="MediaError"><code data-x="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED">MEDIA_ERR_SRC_NOT_SUPPORTED</code></dfn> (numeric value 4)</dt>
<dd>The <span>media resource</span> indicated by the <code data-x="attr-media-src">src</code>
attribute or <span>assigned media provider object</span> was not suitable.</dd>
</dl>
<div w-nodev>
<p>To <dfn export data-x="creating a MediaError">create a <code>MediaError</code></dfn>, given an
error code which is one of the above values, return a new <code>MediaError</code> object whose
<span data-x="concept-MediaError-code">code</span> is the given error code and whose <span
data-x="concept-MediaError-message">message</span> is a string containing any details the user
agent is able to supply about the cause of the error condition, or the empty string if the user
agent is unable to supply such details. This message string must not contain only the information
already available via the supplied error code; for example, it must not simply be a translation of
the code into a string format. If no additional information is available beyond that provided by
the error code, the <span data-x="concept-MediaError-message">message</span> must be set to the
empty string.</p>
<p>The <dfn attribute for="MediaError"><code data-x="dom-MediaError-code">code</code></dfn>
getter steps are to return <span>this</span>'s <span
data-x="concept-MediaError-code">code</span>.</p>
<p>The <dfn attribute for="MediaError"><code data-x="dom-MediaError-message">message</code></dfn>
getter steps are to return <span>this</span>'s <span
data-x="concept-MediaError-message">message</span>.</p>
</div>
<h5>Location of the media resource</h5>
<p>The <dfn element-attr for="audio,video"><code data-x="attr-media-src">src</code></dfn> content
attribute on <span data-x="media element">media elements</span> gives the <span>URL</span> of the
media resource (video, audio) to show. The attribute, if present, must contain a <span>valid
non-empty URL potentially surrounded by spaces</span>.</p>
<p>If the <code data-x="attr-itemprop">itemprop</code> attribute is specified on the <span>media
element</span>, then the <code data-x="attr-media-src">src</code> attribute must also be
specified.</p>
<p>The <dfn element-attr for="audio,video"><code
data-x="attr-media-crossorigin">crossorigin</code></dfn> content attribute on <span data-x="media
element">media elements</span> is a <span>CORS settings attribute</span>.</p>
<div w-nodev>
<p id="concept-media-load-algorithm-at-creation">If a <span>media element</span> is created with a
<code data-x="attr-media-src">src</code> attribute, the user agent must <span>immediately</span> invoke the
<span>media element</span>'s <span data-x="concept-media-load-algorithm">resource selection
algorithm</span>.</p>
<p>If a <code data-x="attr-media-src">src</code> attribute of a <span>media element</span> is set
or changed, the user agent must invoke the <span>media element</span>'s <span>media element load
algorithm</span>. (<em>Removing</em> the <code data-x="attr-media-src">src</code> attribute does
not do this, even if there are <code>source</code> elements present.)</p>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-src">src</code></dfn> IDL
attribute on <span data-x="media element">media elements</span> must <span>reflect</span> the
content attribute of the same name.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-crossOrigin">crossOrigin</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-media-crossorigin">crossorigin</code> content attribute, <span>limited to
only known values</span>.</p>
</div>
<p>A <dfn>media provider object</dfn> is an object that can represent a <span>media
resource</span>, separate from a <span>URL</span>. <code>MediaStream</code> objects,
<code>MediaSource</code> objects, and <code>Blob</code> objects are all <span data-x="media
provider object">media provider objects</span>.</p>
<div w-nodev>
<p>Each <span>media element</span> can have an <dfn>assigned media provider object</dfn>, which is a
<span>media provider object</span>. When a <span>media element</span> is created, it has no
<span>assigned media provider object</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-srcObject">srcObject</span> [ = <var>source</var> ]</code></dt>
<dd>
<p>Allows the <span>media element</span> to be assigned a <span>media provider
object</span>.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-currentSrc">currentSrc</span></code></dt>
<dd>
<p>Returns the <span>URL</span> of the current <span>media resource</span>, if any.</p>
<p>Returns the empty string when there is no <span>media resource</span>, or it doesn't have a
<span>URL</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-currentSrc">currentSrc</code></dfn> IDL attribute must initially be set to the
empty string. Its value is changed by the <span data-x="concept-media-load-algorithm">resource
selection algorithm</span> defined below.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-srcObject">srcObject</code></dfn> IDL attribute, on getting, must return the
element's <span>assigned media provider object</span>, if any, or null otherwise. On setting, it
must set the element's <span>assigned media provider object</span> to the new value, and then
invoke the element's <span>media element load algorithm</span>.</p>
</div>
<p class="note">There are three ways to specify a <span>media resource</span>: the <code
data-x="dom-media-srcObject">srcObject</code> IDL attribute, the <code
data-x="attr-media-src">src</code> content attribute, and <code>source</code> elements. The IDL
attribute takes priority, followed by the content attribute, followed by the elements.</p>
<h5>MIME types</h5>
<p>A <span>media resource</span> can be described in terms of its <em>type</em>, specifically a
<span>MIME type</span>, in some cases with a <code data-x="">codecs</code> parameter. (Whether the
<code data-x="">codecs</code> parameter is allowed or not depends on the MIME type.)
<ref>RFC6381</ref></p>
<p>Types are usually somewhat incomplete descriptions; for example "<code
data-x="">video/mpeg</code>" doesn't say anything except what the container type is, and even a
type like "<code data-x="">video/mp4; codecs="avc1.42E01E, mp4a.40.2"</code>" doesn't
include information like the actual bitrate (only the maximum bitrate). Thus, given a type, a user
agent can often only know whether it <em>might</em> be able to play media of that type (with
varying levels of confidence), or whether it definitely <em>cannot</em> play media of that
type.</p>
<p><dfn>A type that the user agent knows it cannot render</dfn> is one that describes a resource
that the user agent definitely does not support, for example because it doesn't recognize the
container type, or it doesn't support the listed codecs.</p>
<p>The <span>MIME type</span> "<code>application/octet-stream</code>" with no parameters is never
<span>a type that the user agent knows it cannot render</span>. User agents must treat that type
as equivalent to the lack of any explicit <span data-x="Content-Type">Content-Type metadata</span>
when it is used to label a potential <span>media resource</span>.</p>
<p class="note">Only the <span>MIME type</span> "<code>application/octet-stream</code>" with no
parameters is special-cased here; if any parameter appears with it, it will be treated just like
any other <span>MIME type</span>. This is a deviation from the rule <!-- in RFC 2046, section 1,
paragraph 3 --> that unknown <span>MIME type</span> parameters <!--non-normative-->should be
ignored.</p> <!-- but not really a "willful violation" since it's not that the types are not being
ignored, just that before the type is handled as a type, there's a special case for a particular
set of strings -->
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-navigator-canPlayType">canPlayType</span>(<var>type</var>)</code></dt>
<dd>
<p>Returns the empty string (a negative response), "maybe", or "probably" based on how confident
the user agent is that it can play media resources of the given type.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLMediaElement"><code
data-x="dom-navigator-canPlayType">canPlayType(<var>type</var>)</code></dfn> method must return
<dfn data-x="dom-CanPlayTypeResult-nil">the empty string</dfn> if <var>type</var> is <span>a type
that the user agent knows it cannot render</span> or is the type
"<code>application/octet-stream</code>"; it must return "<dfn enum-value
for="CanPlayTypeResult"><code data-x="dom-CanPlayTypeResult-probably">probably</code></dfn>" if
the user agent is confident that the type represents a <span>media resource</span> that it can
render if used in with this <code>audio</code> or <code>video</code> element; and it must return
"<dfn enum-value for="CanPlayTypeResult"><code
data-x="dom-CanPlayTypeResult-maybe">maybe</code></dfn>" otherwise. Implementers are encouraged to
return "<code data-x="dom-CanPlayTypeResult-maybe">maybe</code>" unless the type can be
confidently established as being supported or not. Generally, a user agent should never return
"<code data-x="dom-CanPlayTypeResult-probably">probably</code>" for a type that allows the <code
data-x="">codecs</code> parameter if that parameter is not present.</p>
</div>
<div class="example">
<p>This script tests to see if the user agent supports a (fictional) new format to dynamically
decide whether to use a <code>video</code> element:</p>
<pre><code class="html"><section id="video">
<p><a href="playing-cats.nfv">Download video</a></p>
</section>
<script>
const videoSection = document.getElementById('video');
const videoElement = document.createElement('video');
const support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
if (support === "probably") {
videoElement.setAttribute("src", "playing-cats.nfv");
videoSection.replaceChildren(videoElement);
}
</script></code></pre>
</div>
<p class="note">The <code data-x="attr-source-type">type</code> attribute of the
<code>source</code> element allows the user agent to avoid downloading resources that use formats
it cannot render.</p>
<h5>Network states</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-networkState">networkState</span></code></dt>
<dd>
<p>Returns the current state of network activity for the element, from the codes in the list
below.</p>
</dd>
</dl>
<div w-nodev>
<p>As <span data-x="media element">media elements</span> interact with the network, their current
network activity is represented by the <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-networkState">networkState</code></dfn> attribute. On getting, it must return
the current network state of the element, which must be one of the following values:</p>
</div>
<dl>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
<dd>The element has not yet been initialized. All attributes are in their initial states.</dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
<dd>The element<span w-nodev>'s <span data-x="concept-media-load-algorithm">resource
selection algorithm</span> is active and</span> has selected a <span data-x="media
resource">resource</span>, but it is not actually using the network at this time.</dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
<dd>The user agent is actively trying to download data.</dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
<dd>The element<span w-nodev>'s <span data-x="concept-media-load-algorithm">resource
selection algorithm</span> is active, but it</span> has not yet found a <span data-x="media
resource">resource</span> to use.</dd>
</dl>
<div w-nodev>
<p>The <span data-x="concept-media-load-algorithm">resource selection algorithm</span> defined
below describes exactly when the <code data-x="dom-media-networkState">networkState</code>
attribute changes value and what events fire to indicate changes in this state.</p>
</div>
<h5>Loading the media resource</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-load">load</span>()</code></dt>
<dd>
<p>Causes the element to reset and start selecting and loading a new <span>media resource</span>
from scratch.</p>
</dd>
</dl>
<div w-nodev>
<p>All <span data-x="media element">media elements</span> have a <dfn>can autoplay flag</dfn>,
which must begin in the true state, and a <dfn>delaying-the-load-event flag</dfn>, which must
begin in the false state. While the <span>delaying-the-load-event flag</span> is true, the element
must <span>delay the load event</span> of its document.</p>
<p>When the <dfn method for="HTMLMediaElement"><code data-x="dom-media-load">load()</code></dfn>
method on a <span>media element</span> is invoked, the user agent must run the <span>media element
load algorithm</span>.</p>
<p>A <span>media element</span> has an associated boolean <dfn>is currently stalled</dfn>, which
is initially false.</p>
<p>The <dfn>media element load algorithm</dfn> consists of the following steps.</p>
<ol>
<li><p>Set this element's <span>is currently stalled</span> to false.</p></li>
<li><p>Abort any already-running instance of the <span
data-x="concept-media-load-algorithm">resource selection algorithm</span> for this
element.</p></li>
<li><p>Let <var>pending tasks</var> be a list of all <span data-x="concept-task">tasks</span>
from the <span>media element</span>'s <span>media element event task source</span> in one of the
<span data-x="task queue">task queues</span>.</p></li>
<li><p>For each task in <var>pending tasks</var> that would <span>resolve pending play
promises</span> or <span>reject pending play promises</span>, immediately resolve or reject those
promises in the order the corresponding tasks were queued.</p></li>
<li>
<p>Remove each <span data-x="concept-task">task</span> in <var>pending tasks</var> from its
<span>task queue</span>.</p>
<p class="note">Basically, pending events and callbacks are discarded and promises in-flight to
be resolved/rejected are resolved/rejected immediately when the media element starts loading a
new resource.</p>
</li>
<!--
<p>If there are any <span data-x="concept-task">tasks</span> that were <span data-x="queue a
task">queued</span> by the <span data-x="concept-media-load-algorithm">resource selection
algorithm</span> (including the algorithms that it itself invokes) for this same <span>media
element</span> from the <span>DOM manipulation task source</span> in one of the <span
data-x="task queue">task queues</span>, then remove those tasks.</p>
-->
<li><p>If the <span>media element</span>'s <code
data-x="dom-media-networkState">networkState</code> is set to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code> or <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code>, <span>queue a media element task</span>
given the <span>media element</span> to <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-media-abort">abort</code> at the <span>media element</span>.</p></li>
<li>
<p>If the <span>media element</span>'s <code data-x="dom-media-networkState">networkState</code>
is not set to <code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, then:</p>
<ol>
<li><p><span>Queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-emptied">emptied</code> at the <span>media element</span>.</p></li>
<li><p>If a fetching process is in progress for the <span>media
element</span>, the user agent should stop it.</p></li>
<li><p>If the <span>media element</span>'s <span>assigned media provider object</span> is a
<code>MediaSource</code> object, then <span data-x="Detaching from a media
element">detach</span> it.</p></li>
<!--(no point doing this, since we always call the resource selection algorithm immediately
at the end of this algorithm, and that switches it to NETWORK_NO_SOURCE and sets the flag)
<li><p>Set the <code data-x="dom-media-networkState">networkState</code> attribute to <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>.</p></li>
<li><p>Set the element's <span>show poster flag</span> to true.</p></li>
-->
<li><p><span>Forget the media element's media-resource-specific tracks</span>.</p></li>
<li><p>If <code data-x="dom-media-readyState">readyState</code> is not set to <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, then set it to that state.</p></li>
<li>
<p>If the <code data-x="dom-media-paused">paused</code> attribute is false, then:</p>
<ol>
<li><p>Set the <code data-x="dom-media-paused">paused</code> attribute to true.</p></li>
<li><p><span>Take pending play promises</span> and <span>reject pending play promises</span>
with the result and an <span>"<code>AbortError</code>"</span>
<code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>If <code data-x="dom-media-seeking">seeking</code> is true, set it to false.</p></li>
<li>
<p>Set the <span>current playback position</span> to 0.</p>
<p>Set the <span>official playback position</span> to 0.</p>
<p>If this changed the <span>official playback position</span>, then <span>queue a media
element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the <span>media element</span>.</p>
</li>
<li><p>Set the <span>timeline offset</span> to Not-a-Number (NaN).</p></li>
<li>
<p>Update the <code data-x="dom-media-duration">duration</code> attribute to Not-a-Number
(NaN).</p>
<p class="note">The user agent <a href="#durationChange">will not</a> fire a <code
data-x="event-media-durationchange">durationchange</code> event for this particular change of
the duration.</p>
</li>
</ol>
</li>
<li><p>Set the <code data-x="dom-media-playbackRate">playbackRate</code> attribute to the value of
the <code data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code> attribute.</p></li>
<li><p>Set the <code data-x="dom-media-error">error</code> attribute to null and the
<span>can autoplay flag</span> to true.</p></li>
<li><p>Invoke the <span>media element</span>'s <span
data-x="concept-media-load-algorithm">resource selection algorithm</span>.</li>
<li>
<p class="note">Playback of any previously playing <span>media resource</span> for this element
stops.</p>
</li>
</ol>
<p>The <dfn data-x="concept-media-load-algorithm">resource selection algorithm</dfn> for a
<span>media element</span> is as follows. This algorithm is always invoked as part of a <span data-x="concept-task">task</span>, but one
of the first steps in the algorithm is to return and continue running the remaining steps
<span>in parallel</span>. In addition, this algorithm interacts
closely with the <span>event loop</span> mechanism; in particular, it has <span data-x="synchronous
section">synchronous sections</span> (which are triggered as part of the <span>event loop</span>
algorithm). Steps in such sections are marked with ⌛.</p>
<ol>
<!-- precondition: networkState == NETWORK_EMPTY or we're coming straight from the algorithm above
(where setting it to empty is commented out) -->
<li><p>Set the element's <code data-x="dom-media-networkState">networkState</code> attribute to
the <code data-x="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</code> value.</p></li>
<li><p>Set the element's <span>show poster flag</span> to true.</p></li>
<li><p>Set the <span>media element</span>'s <span>delaying-the-load-event flag</span> to true
(this <span data-x="delay the load event">delays the load event</span>).</p></li>
<li><p><span>Await a stable state</span>, allowing the <span
data-x="concept-task">task</span> that invoked this algorithm to continue. The <span>synchronous
section</span> consists of all the remaining steps of this algorithm until the algorithm says the
<span>synchronous section</span> has ended. (Steps in <span data-x="synchronous
section">synchronous sections</span> are marked with ⌛.)</p></li>
<li>
<p>⌛ If the <span>media element</span>'s <span>blocked-on-parser</span> flag is false,
then <span>populate the list of pending text tracks</span>.</p>
</li>
<li>
<p>⌛ If the <span>media element</span> has an <span>assigned media provider
object</span>, then let <var>mode</var> be <i>object</i>.</p>
<p>⌛ Otherwise, if the <span>media element</span> has no <span>assigned media provider
object</span> but has a <code data-x="attr-media-src">src</code>
attribute, then let <var>mode</var> be <i>attribute</i>.</p>
<p>⌛ Otherwise, if the <span>media element</span> does not have an <span>assigned media provider
object</span> and does not have a <code
data-x="attr-media-src">src</code> attribute, but does have a <code>source</code> element child, then
let <var>mode</var> be <i>children</i> and let <var>candidate</var>
be the first such <code>source</code> element child in <span>tree order</span>.</p>
<p>⌛ Otherwise, the <span>media element</span> has no <span>assigned media provider
object</span> and has neither a <code
data-x="attr-media-src">src</code> attribute nor a <code>source</code> element child:</p>
<ol>
<li><p>⌛ Set the <code data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>.</p></li>
<li><p>⌛ Set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<!-- no need to set the <span>show poster flag</span> to true since we set it up there already -->
<li><p>End the <span>synchronous section</span> and return.</li>
</ol>
</li>
<li><p>⌛ Set the <span>media element</span>'s <code
data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>.</p></li>
<li><p>⌛ <span>Queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-loadstart">loadstart</code> at the <span>media element</span>.</p></li>
<li>
<p>Run the appropriate steps from the following list:</p>
<dl class="switch">
<dt>If <var>mode</var> is <i>object</i></dt>
<dd>
<ol>
<li><p>⌛ Set the <code data-x="dom-media-currentSrc">currentSrc</code> attribute to
the empty string.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li><p>Run the <span data-x="concept-media-load-resource">resource fetch algorithm</span>
with the <span>assigned media provider object</span>. If that algorithm returns without
aborting <em>this</em> one, then the load failed.</p></li>
<li><p><i>Failed with media provider</i>: Reaching this step indicates that the media
resource failed to load. <span>Take pending play promises</span> and <span>queue a media
element task</span> given the <span>media element</span> to run the <span>dedicated media
source failure steps</span> with the result.</p></li>
<li><p>Wait for the <span data-x="concept-task">task</span> queued by the previous step to have
executed.</p></li>
<li><p>Return. The element won't attempt to load another resource until this
algorithm is triggered again.</p></li>
</ol>
</dd>
<dt>If <var>mode</var> is <i>attribute</i></dt>
<dd>
<ol>
<li><p>⌛ If the <code data-x="attr-media-src">src</code>
attribute's value is the empty string, then end the <span>synchronous section</span>, and jump
down to the <i>failed with attribute</i> step below.</p></li>
<li><p>⌛ Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span>
given the <code data-x="attr-media-src">src</code> attribute's value, relative to the
<span>media element</span>'s <span>node document</span> when the <code
data-x="attr-media-src">src</code> attribute was last changed.</p>
<!-- i.e. changing <base> after src="" has no effect, but this is a terrible way of
specifying that. We should more eagerly parse instead? -->
<li><p>⌛ If <var>urlRecord</var> is not failure, then set the <code
data-x="dom-media-currentSrc">currentSrc</code> attribute to the result of applying the <span
data-x="concept-url-serializer">URL serializer</span> to <var>urlRecord</var>.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li><p>If <var>urlRecord</var> is not failure, then run the <span
data-x="concept-media-load-resource">resource fetch algorithm</span> with
<var>urlRecord</var>. If that algorithm returns without aborting <em>this</em> one, then the
load failed.</p></li>
<li><p><i>Failed with attribute</i>: Reaching this step indicates that the media resource
failed to load or that <var>urlRecord</var> is failure. <span>Take pending play
promises</span> and <span>queue a media element task</span> given the <span>media
element</span> to run the <span>dedicated media source failure steps</span> with the
result.</p></li>
<li><p>Wait for the <span data-x="concept-task">task</span> queued by the previous step to have
executed.</p></li>
<li><p>Return. The element won't attempt to load another resource until this
algorithm is triggered again.</p></li>
<!-- it took its ball and went home, sulking. -->
</ol>
</dd>
<dt>Otherwise (<var>mode</var> is <i>children</i>)</dt>
<dd>
<ol>
<li>
<p>⌛ Let <var>pointer</var> be a position defined by two adjacent nodes in the
<span>media element</span>'s child list, treating the start of the list (before the first
child in the list, if any) and end of the list (after the last child in the list, if any) as
nodes in their own right. One node is the node before <var>pointer</var>, and the
other node is the node after <var>pointer</var>. Initially, let <var>pointer</var> be the position between the <var>candidate</var> node and the
next node, if there are any, or the end of the list, if it is the last node.</p>
<p>As nodes are <span data-x="concept-node-insert-ext">inserted</span>, <span
data-x="concept-node-remove-ext">removed</span>, and <span
data-x="concept-node-move-ext">moved</span> into the <span>media element</span>,
<var>pointer</var> must be updated as follows:</p>
<dl>
<dt>If a new node is <span data-x="concept-node-insert-ext">inserted</span> or <span
data-x="concept-node-move-ext">moved</span> between the two nodes that define
<var>pointer</var></dt>
<dd>Let <var>pointer</var> be the point between the node before <var>pointer</var> and the
new node. In other words, insertions at <var>pointer</var> go after
<var>pointer</var>.</dd>
<dt>If the node before <var>pointer</var> is removed</dt>
<dd>Let <var>pointer</var> be the point between the node after <var>pointer</var> and the
node before the node after <var>pointer</var>. In other words, <var>pointer</var> doesn't
move relative to the remaining nodes.</dd>
<dt>If the node after <var>pointer</var> is removed</dt>
<dd>Let <var>pointer</var> be the point between the node before <var>pointer</var> and the
node after the node before <var>pointer</var>. Just as with the previous case,
<var>pointer</var> doesn't move relative to the remaining nodes.</dd>
</dl>
<p>Other changes don't affect <var>pointer</var>.</p>
</li>
<li><p>⌛ <i>Process candidate</i>: If <var>candidate</var> does not have a
<code data-x="attr-source-src">src</code> attribute, or if its <code
data-x="attr-source-src">src</code> attribute's value is the empty string, then end the
<span>synchronous section</span>, and jump down to the <i>failed with elements</i> step
below.</p></li>
<li><p>⌛ If <var>candidate</var> has a <code data-x="attr-source-media">media</code>
attribute whose value does not <span data-x="matches the environment">match the
environment</span>, then end the <span>synchronous section</span>, and jump down to the
<i>failed with elements</i> step below.</p></li>
<li><p>⌛ Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span>
given <var>candidate</var>'s <code data-x="attr-media-src">src</code> attribute's value,
relative to <var>candidate</var>'s <span>node document</span> when the <code
data-x="attr-media-src">src</code> attribute was last changed.</p>
<!-- i.e. changing <base> after src="" has no effect, but this is a terrible way of
specifying that. We should more eagerly parse instead? -->
<li><p>⌛ If <var>urlRecord</var> is failure, then end the <span>synchronous
section</span>, and jump down to the <i>failed with elements</i> step below.</p></li>
<li><p>⌛ If <var>candidate</var> has a <code
data-x="attr-source-type">type</code> attribute whose value, when parsed as a <span>MIME
type</span> (including any codecs described by the <code data-x="">codecs</code> parameter, for
types that define that parameter), represents <span>a type that the user agent knows it cannot
render</span>, then end the <span>synchronous section</span>, and jump down to the <i>failed with elements</i> step below.</p></li>
<li><p>⌛ Set the <code data-x="dom-media-currentSrc">currentSrc</code> attribute to
the result of applying the <span data-x="concept-url-serializer">URL serializer</span> to
<var>urlRecord</var>.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li><p>Run the <span data-x="concept-media-load-resource">resource fetch algorithm</span>
with <var>urlRecord</var>. If that algorithm returns without aborting <em>this</em> one,
then the load failed.</p></li>
<li><p><i>Failed with elements</i>: <span>Queue a media element task</span> given the
<span>media element</span> to <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-source-error">error</code> at <var>candidate</var>.</p></li>
<li><p><span>Await a stable state</span>. The <span>synchronous section</span>
consists of all the remaining steps of this algorithm until the algorithm says the
<span>synchronous section</span> has ended. (Steps in <span data-x="synchronous
section">synchronous sections</span> are marked with ⌛.)</p></li>
<li><p>⌛ <span>Forget the media element's media-resource-specific
tracks</span>.</p></li>
<li><p>⌛ <i>Find next candidate</i>: Let <var>candidate</var> be
null.</p></li>
<li><p>⌛ <i>Search loop</i>: If the node after <var>pointer</var> is
the end of the list, then jump to the <i>waiting</i> step below.</p></li>
<li><p>⌛ If the node after <var>pointer</var> is a <code>source</code> element,
let <var>candidate</var> be that element.</p></li>
<li><p>⌛ Advance <var>pointer</var> so that the node before <var>pointer</var> is now the node that was after <var>pointer</var>, and the node
after <var>pointer</var> is the node after the node that used to be after <var>pointer</var>, if any.</p></li>
<li><p>⌛ If <var>candidate</var> is null, jump back to the <i>search
loop</i> step. Otherwise, jump back to the <i>process candidate</i> step.</p></li>
<li><p>⌛ <i>Waiting</i>: Set the element's <code
data-x="dom-media-networkState">networkState</code> attribute to the <code
data-x="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</code> value.</p></li>
<li><p>⌛ Set the element's <span>show poster flag</span> to true.</p></li>
<li><p>⌛ <span>Queue a media element task</span> given the <span>media element</span>
to set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li><p>Wait until the node after <var>pointer</var> is a node other than the end of
the list. (This step might wait forever.)</p></li>
<li><p><span>Await a stable state</span>. The <span>synchronous section</span>
consists of all the remaining steps of this algorithm until the algorithm says the
<span>synchronous section</span> has ended. (Steps in <span data-x="synchronous
section">synchronous sections</span> are marked with ⌛.)</p></li>
<li><p>⌛ Set the element's <span>delaying-the-load-event flag</span> back to true (this
<span data-x="delay the load event">delays the load event</span> again, in case it hasn't been
fired yet).</p>
<li><p>⌛ Set the <code data-x="dom-media-networkState">networkState</code> back to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>.</p></li>
<li><p>⌛ Jump back to the <i>find next candidate</i> step above.</p></li>
</ol>
</dd>
</dl>
<p>The <dfn>dedicated media source failure steps</dfn> with a list of promises
<var>promises</var> are the following steps:</p>
<ol>
<li><p>Set the <code data-x="dom-media-error">error</code> attribute to the result of
<span>creating a <code>MediaError</code></span> with <code
data-x="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED">MEDIA_ERR_SRC_NOT_SUPPORTED</code>.</p></li>
<li><p><span>Forget the media element's media-resource-specific tracks</span>.</p></li>
<li><p>Set the element's <code data-x="dom-media-networkState">networkState</code> attribute to
the <code data-x="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</code> value.</p></li>
<li><p>Set the element's <span>show poster flag</span> to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-error">error</code> at the <span>media element</span>.</p></li>
<li><p><span>Reject pending play promises</span> with <var>promises</var> and a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>verify a media response</dfn> given a <span data-x="concept-response">response</span>
<var>response</var>, a <span>media resource</span> <var>resource</var>, and
"<code data-x="">entire resource</code>" or a
(number, number or "<code data-x="">until end</code>") tuple <var>byteRange</var>:</p>
<ol>
<li><p>If <var>response</var> is a <span>network error</span>, then return false.</p></li>
<li><p>If <var>byteRange</var> is "<code data-x="">entire resource</code>", then return
true.</p></li>
<li><p>Let <var>internalResponse</var> be <var>response</var>'s
<span>unsafe response</span>.</p></li>
<li><p>If <var>internalResponse</var>'s <span data-x="concept-response-status">status</span> is
200, then return true.</p></li>
<li><p>If <var>internalResponse</var>'s <span data-x="concept-response-status">status</span> is
not 206, then return false.</p></li>
<li>
<p>If the result of <span
data-x="extract content-range values">extracting content-range values</span> from
<var>internalResponse</var> is failure, then return false.</p>
<p class="note">Note that the extracted values are not used, and in particular are not compared
to <var>byteRange</var>. So this step serves as syntactic validation of the `<code
data-x="http-content-range">Content-Range</code>` header, but if the `<code
data-x="http-content-range">Content-Range</code>` values on the response mismatch the `<code
data-x="http-range">Range</code>` values on the request, that is not considered a failure.</p>
</li>
<li><p>Let <var>origin</var> be "<code data-x="">rewritten</code>" if
<var>internalResponse</var>'s <span data-x="concept-response-url">URL</span> is null; otherwise
<var>internalResponse</var>'s <span data-x="concept-response-url">URL</span>'s
<span data-x="concept-url-origin">origin</span>.</p></li>
<li><p>Let <var>previousOrigin</var> be <var>resource</var>'s
<span data-x="media-resource-origin">origin</span>.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>previousOrigin</var> is "<code data-x="">none</code>";</p></li>
<li><p><var>origin</var> and <var>previousOrigin</var> are "<code data-x="">rewritten</code>";
or</p></li>
<li><p><var>origin</var> and <var>previousOrigin</var> are <span
data-x="origin">origins</span>, and <var>origin</var> is <span>same origin</span> with
<var>previousOrigin</var>,</p></li>
</ul>
<p>then set <var>resource</var>'s <span data-x="media-resource-origin">origin</span> to
<var>origin</var>.</p>
<p>Otherwise, if <var>response</var> is <span>CORS-cross-origin</span>, then return false.</p>
<p>Otherwise, set <var>resource</var>'s <span data-x="media-resource-origin">origin</span> to
"<code data-x="">multiple</code>".</p>
<p class="note">This ensures that opaque responses with range headers do not leak information
by being patched together with other responses from different origins.</p>
</li>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn data-x="concept-media-load-resource" export>resource fetch algorithm</dfn> for a
<span>media element</span> and a given <span>URL record</span> or <span>media provider
object</span> is as follows:</p>
<ol>
<li><p>Let <var>mode</var> be <i>remote</i>.</p></li>
<li>
<p>If the algorithm was invoked with <span>media provider object</span>, then set
<var>mode</var> to <i>local</i>.</p>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>object</var> be the result of <span data-x="blob-url-obtain-object">obtaining
a blob object</span> using the <span>URL record</span>'s <span
data-x="concept-url-blob-entry">blob URL entry</span> and the <span>media element</span>'s
<span>node document</span>'s <span>relevant settings object</span>.</p></li>
<li><p>If <var>object</var> is a <span>media provider object</span>, then set <var>mode</var>
to <i>local</i>.</p></li>
</ol>
</li>
<li><p>If <var>mode</var> is <i>remote</i>, then let the <var>current media resource</var> be the
resource given by the <span>URL record</span> passed to this algorithm; otherwise, let the
<var>current media resource</var> be the resource given by the <span>media provider
object</span>. Either way, the <var>current media resource</var> is now the element's <span>media
resource</span>.</p></li>
<li><p>Remove all <span data-x="media-resource-specific text track">media-resource-specific text
tracks</span> from the <span>media element</span>'s <span>list of pending text tracks</span>, if
any.</p>
<li>
<p>Run the appropriate steps from the following list:</p>
<dl class="switch">
<dt>If <var>mode</var> is remote</dt>
<dd>
<ol>
<li>
<p>Optionally, run the following substeps. This is the expected behavior if the user agent
intends to not attempt to fetch the resource until the user requests it explicitly (e.g. as
a way to implement the <code data-x="attr-media-preload">preload</code> attribute's <code
data-x="attr-media-preload-none">none</code> keyword).</p>
<ol>
<li><p>Set the <code data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code>.</p></li>
<li><p><span>Queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-suspend">suspend</code> at the element.</p></li>
<li><p><span>Queue a media element task</span> given the <span>media element</span> to set
the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<li><p>Wait for the task to be run.</p></li>
<li><p>Wait for an <span>implementation-defined</span> event (e.g., the user requesting
that the media element begin playback).</p></li>
<li><p>Set the element's <span>delaying-the-load-event flag</span> back to true (this <span
data-x="delay the load event">delays the load event</span> again, in case it hasn't been fired
yet).</p>
<li><p>Set the <code data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>.</p></li>
</ol>
</li>
<li><p>Let <var>destination</var> be "<code data-x="">audio</code>" if the <span>media
element</span> is an <code>audio</code> element, or "<code data-x="">video</code>"
otherwise.</p>
<li><p>Let <var>request</var> be the result of <span
data-x="create a potential-CORS request">creating a potential-CORS request</span> given
<var>current media resource</var>'s <span>URL record</span>, <var>destination</var>, and the
current state of <span>media element</span>'s
<code data-x="attr-script-crossorigin">crossorigin</code> content attribute.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to the
<span>media element</span>'s <span>node document</span>'s <span>relevant settings
object</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to <var>destination</var>.</p></li>
<li><p>Let <var>byteRange</var>, which is "<code data-x="">entire resource</code>" or a
(number, number or "<code data-x="">until end</code>") tuple, be the byte range required to satisfy
missing data in <span>media data</span>. This value is <span>implementation-defined</span>
and may rely on codec, network conditions or other heuristics. The user-agent may determine
to fetch the resource in full, in which case <var>byteRange</var> would be
"<code data-x="">entire resource</code>", to fetch from a byte offset until the end,
in which case <var>byteRange</var> would be
(number, "<code data-x="">until end</code>"), or to fetch a range between two byte offsets,
im which case <var>byteRange</var> would be a (number, number) tuple representing the two
offsets.</p></li>
<li>
<p>If <var>byteRange</var> is not "<code data-x="">entire resource</code>", then:</p>
<ol>
<li><p>If <var>byteRange</var>[1] is "<code data-x="">until end</code>" then
<span>add a range header</span> to <var>request</var> given
<var>byteRange</var>[0].</p></li>
<li><p>Otherwise, <span>add a range header</span> to <var>request</var> given
<var>byteRange</var>[0] and <var>byteRange</var>[1].</p></li>
</ol>
</li>
<li>
<!--FETCH--><p><span data-x="concept-fetch">Fetch</span> <var>request</var>, with
<i data-x="processResponse">processResponse</i> set to the following steps given
<span data-x="concept-response">response</span> <var>response</var>:</p>
<ol>
<li><p>Let <var>global</var> be the <span>media element</span>'s
<span>node document</span>'s <span>relevant global object</span>.</p></li>
<li><p>Let <var>updateMedia</var> be to <span>queue a media element task</span> given
the <span>media element</span> to run the first appropriate steps from the
<span>media data processing steps list</span> below. (A new task is used for
this so that the work described below occurs relative to the appropriate
<span>media element event task source</span> rather than using the
<span>networking task source</span>.)</p>
<li><p>Let <var>processEndOfMedia</var> be the following step: If the fetching process has
completed without errors, including decoding the media data, and if all of the data is
available to the user agent without network access, then, the user agent must move on to
the <i>final step</i> below. This might never happen, e.g. when streaming an infinite
resource such as web radio, or if the resource is longer than the user agent's ability to
cache data.</p></li>
<li><p>If the result of <span data-x="verify a media response">verifying</span>
<var>response</var> given the <var>current media resource</var> and <var>byteRange</var>
is false, then abort these steps.</p></li>
<li><p>Otherwise, <span data-x="body-incrementally-read">incrementally read</span>
<var>response</var>'s <span data-x="concept-response-body">body</span> given
<var>updateMedia</var>, <var>processEndOfMedia</var>, an empty algorithm, and
<var>global</var>.</p></li>
<li><p>Update the <span>media data</span> with the contents of <var>response</var>'s
<span>unsafe response</span> obtained in this fashion. <var>response</var> can be
<span>CORS-same-origin</span> or <span>CORS-cross-origin</span>; this affects whether
subtitles referenced in the <span>media data</span> are exposed in the API and, for
<code>video</code> elements, whether a<code>canvas</code> gets tainted when the video is
drawn on it.</p></li>
</ol>
<p>The <dfn export id="stall-timeout">media element stall timeout</dfn> is an
<span>implementation-defined</span> length of time, which should be about three seconds.
When a <span>media element</span> that is actively attempting to obtain <span>media
data</span> has failed to receive any data for a duration equal to the <span>media element
stall timeout</span>, the user agent must <span>queue a media element task</span> given the
<span>media element</span> to:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-stalled">stalled</code> at the element.</p></li>
<li><p>Set the element's <span>is currently stalled</span> to true.</p></li>
</ol>
<p>User agents may allow users to selectively block or slow <span>media data</span> downloads.
When a <span>media element</span>'s download has been blocked altogether, the user agent must
act as if it was stalled (as opposed to acting as if the connection was closed). The rate of the
download may also be throttled automatically by the user agent, e.g. to balance the download
with other connections sharing the same bandwidth.</p>
<p id="resourceSuspend">User agents may decide to not download more content at any time,
e.g. after buffering five minutes of a one hour media resource, while waiting for the user
to decide whether to play the resource or not, while waiting for user input in an
interactive resource, or when the user navigates away from the page. When a <span>media
element</span>'s download has been suspended, the user agent must <span>queue a media
element task</span> given the <span>media element</span> to set the <code
data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> and <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-suspend">suspend</code> at the element. If and when downloading of the
resource resumes, the user agent must <span>queue a media element task</span> given the
<span>media element</span> to set the <code
data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>. Between the queuing of these
tasks, the load is suspended (so <code data-x="event-media-progress">progress</code> events
don't fire, as described above).</p>
<p class="note">The <code data-x="attr-media-preload">preload</code> attribute provides a hint
regarding how much buffering the author thinks is advisable, even in the absence of the <code
data-x="attr-media-autoplay">autoplay</code> attribute.</p>
<p>When a user agent decides to completely suspend a download, e.g., if it is waiting until
the user starts playback before downloading any further content, the user agent must
<span>queue a media element task</span> given the <span>media element</span> to set the
element's <span>delaying-the-load-event flag</span> to false. This stops <span data-x="delay
the load event">delaying the load event</span>.</p>
<p>Although the above steps give an algorithm for issuing requests, the user agent may use
other means besides those exact ones, especially in the face of error conditions. For
example, the user agent may reconnect to the server or switch to a streaming protocol. The
user agent must only consider the resource erroneous, and proceed into the error branches
of the above steps, if the user agent has given up trying to fetch the resource.</p>
<p>To determine the format of the <span>media resource</span>, the user agent must use the
<span data-x="Content-Type sniffing: video">rules for sniffing audio and video specifically</span>.</p>
<p>While the load is not suspended (see below), every 350ms (±200ms) or for every byte
received, whichever is <em>least</em> frequent, <span>queue a media element task</span>
given the <span>media element</span> to:
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-progress">progress</code> at the element.</p></li>
<li><p>Set the element's <span>is currently stalled</span> to false.</p></li>
</ol>
<p>While the user agent might still need network access to obtain parts of the <span>media
resource</span>, the user agent must remain on this step.</p>
<p class="example">For example, if the user agent has discarded the first half of a video, the
user agent will remain at this step even once the <span data-x="ended playback">playback has
ended</span>, because there is always the chance the user will seek back to the start. In fact,
in this situation, once <span data-x="ended playback">playback has ended</span>, the user agent
will end up firing a <code data-x="event-media-suspend">suspend</code> event, as described
earlier.</p>
</li>
</ol>
</dd>
<dt>Otherwise (<var>mode</var> is <i>local</i>)</dt>
<dd>
<p>The resource described by the <var>current media resource</var>, if any, contains the
<span>media data</span>. It is <span>CORS-same-origin</span>. </p>
<p>If the <var>current media resource</var> is a raw data stream (e.g. from a
<code>File</code> object), then to determine the format of the <span>media resource</span>,
the user agent must use the <span data-x="Content-Type sniffing: video">rules for sniffing
audio and video specifically</span>. Otherwise, if the data stream is pre-decoded, then the
format is the format given by the relevant specification.</p>
<p>Whenever new data for the <var>current media resource</var> becomes available, <span>queue
a media element task</span> given the <span>media element</span> to run the first appropriate
steps from the <span>media data processing steps list</span> below.</p>
<p>When the <var>current media resource</var> is permanently exhausted (e.g. all the bytes of
a <code>Blob</code> have been processed), if there were no decoding errors, then the user
agent must move on to the <i>final step</i> below. This might never happen, e.g. if the
<var>current media resource</var> is a <code>MediaStream</code>.</p>
</dd>
</dl>
<p>The <dfn>media data processing steps list</dfn> is as follows:</p>
<dl class="switch">
<dt>If the <span>media data</span> cannot be fetched at all, due to network errors, causing the
user agent to give up trying to fetch the resource</dt>
<dt>If the <span>media data</span> can be fetched but is found by inspection to be in an
unsupported format, or can otherwise not be rendered at all</dt>
<dd>
<p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in other protocols), and other fatal
network errors that occur before the user agent has established whether the <var>current media resource</var> is usable, as well as the file using an unsupported
container format, or using unsupported codecs for all the data, must cause the user agent to
execute the following steps:</p>
<ol>
<li><p>The user agent should cancel the fetching process.</p></li>
<li><p>Abort this subalgorithm, returning to the <span
data-x="concept-media-load-algorithm">resource selection algorithm</span>.</p>
</ol>
</dd>
<dt id="found-another-audio-track">If the <span>media resource</span> is found to have an audio
track</dt>
<dd>
<ol>
<li><p>Create an <code>AudioTrack</code> object to represent the audio track.</p></li>
<li><p>Update the <span>media element</span>'s <code
data-x="dom-media-audioTracks">audioTracks</code> attribute's <code>AudioTrackList</code>
object with the new <code>AudioTrack</code> object.</p></li>
<li><p>Let <var>enable</var> be <i>unknown</i>.</p></li>
<li>
<p>If either the <span>media resource</span> or the <span>URL</span> of the <var>current
media resource</var> indicate a particular set of audio tracks to enable, or if the user
agent has information that would facilitate the selection of specific audio tracks to
improve the user's experience, then: if this audio track is one of the ones to enable, then
set <var>enable</var> to <i>true</i>, otherwise, set <var>enable</var>
to <i>false</i>.</p>
<p class="example">This could be triggered by <span>media fragment syntax</span>, but it
could also be triggered e.g. by the user agent selecting a 5.1 surround sound audio track
over a stereo audio track.</p>
</li>
<li><p>If <var>enable</var> is still <i>unknown</i>, then, if the <span>media
element</span> does not yet have an <span data-x="dom-AudioTrack-enabled">enabled</span>
audio track, then set <var>enable</var> to <i>true</i>, otherwise, set <var>enable</var> to <i>false</i>.</p></li>
<li><p>If <var>enable</var> is <i>true</i>, then enable this audio track,
otherwise, do not enable this audio track.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at this <code>AudioTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code>
attribute initialized to the new <code>AudioTrack</code> object.</p></li>
</ol>
</dd>
<dt id="found-another-video-track">If the <span>media resource</span> is found to have a video
track</dt>
<dd>
<ol>
<li><p>Create a <code>VideoTrack</code> object to represent the video track.</p></li>
<li><p>Update the <span>media element</span>'s <code
data-x="dom-media-videoTracks">videoTracks</code> attribute's <code>VideoTrackList</code>
object with the new <code>VideoTrack</code> object.</p></li>
<li><p>Let <var>enable</var> be <i>unknown</i>.</p></li>
<li>
<p>If either the <span>media resource</span> or the <span>URL</span> of the <var>current
media resource</var> indicate a particular set of video tracks to enable, or if the user
agent has information that would facilitate the selection of specific video tracks to
improve the user's experience, then: if this video track is the first such video track, then
set <var>enable</var> to <i>true</i>, otherwise, set <var>enable</var>
to <i>false</i>.</p>
<p class="example">This could again be triggered by <span>media fragment syntax</span>.</p>
</li>
<li><p>If <var>enable</var> is still <i>unknown</i>, then, if the <span>media
element</span> does not yet have a <span data-x="dom-VideoTrack-selected">selected</span>
video track, then set <var>enable</var> to <i>true</i>, otherwise, set <var>enable</var> to <i>false</i>.</p></li>
<li><p>If <var>enable</var> is <i>true</i>, then select this track and unselect any
previously selected video tracks, otherwise, do not select this video track. If other tracks
are unselected, then <a href="#toggle-video-track">a <code
data-x="event-media-change">change</code> event will be fired</a>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at this <code>VideoTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code>
attribute initialized to the new <code>VideoTrack</code> object.</p></li>
</ol>
</dd>
<dt id="getting-media-metadata">Once enough of the <span>media data</span> has been fetched to
determine the duration of the <span>media resource</span>, its dimensions, and other
metadata</dt>
<dd>
<p>This indicates that the resource is usable. The user agent must follow these substeps:</p>
<ol>
<li>
<p><span>Establish the media timeline</span> for the purposes of the <span>current playback
position</span> and the <span>earliest possible position</span>, based on the <span>media data</span>.</p>
</li>
<li>
<p>Update the <span>timeline offset</span> to the date and time that corresponds to the zero
time in the <span>media timeline</span> established in the previous step, if any. If no
explicit time and date is given by the <span>media resource</span>, the <span>timeline
offset</span> must be set to Not-a-Number (NaN).</p>
</li>
<li><p>Set the <span>current playback position</span> and the <span>official playback
position</span> to the <span>earliest possible position</span>.</p></li>
<li>
<p>Update the <code data-x="dom-media-duration">duration</code> attribute with the time of
the last frame of the resource, if known, on the <span>media timeline</span> established
above. If it is not known (e.g. a stream that is in principle infinite), update the <code
data-x="dom-media-duration">duration</code> attribute to the value positive Infinity.</p>
<p class="note">The user agent <a href="#durationChange">will</a> <span>queue a media
element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-durationchange">durationchange</code> at the element at this point.</p>
</li>
<li>
<p>For <code>video</code> elements, set the <code
data-x="dom-video-videoWidth">videoWidth</code> and <code
data-x="dom-video-videoHeight">videoHeight</code> attributes, and <span>queue a media
element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-resize">resize</code> at the <span>media element</span>.</p>
<p class="note">Further <code data-x="event-media-resize">resize</code> events will be fired
if the dimensions subsequently change.</p>
</li>
<li>
<p>Set the <code data-x="dom-media-readyState">readyState</code> attribute to <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code>.</p>
<p class="note">A <code data-x="event-media-loadedmetadata">loadedmetadata</code> DOM event
<a href="#fire-loadedmetadata">will be fired</a> as part of setting the <code
data-x="dom-media-readyState">readyState</code> attribute to a new value.</p>
</li>
<li><p>Let <var>jumped</var> be false.</p></li>
<li><p>If the <span>media element</span>'s <span>default playback start position</span> is
greater than zero, then <span data-x="dom-media-seek">seek</span> to that time, and let <var>jumped</var> be true.</p></li>
<li><p>Let the <span>media element</span>'s <span>default playback
start position</span> be zero.</p></li>
<li><p>Let the <var>initial playback position</var> be zero.</p></li>
<li>
<p>If either the <span>media resource</span> or the <span>URL</span> of the <var>current
media resource</var> indicate a particular start time, then set the <var>initial playback
position</var> to that time and, if <var>jumped</var> is still false, <span
data-x="dom-media-seek">seek</span> to that time.</p>
<p class="example">For example, with media formats that support <span>media fragment
syntax</span>, the <span data-x="concept-url-fragment">fragment</span> can be used to
indicate a start position.</p>
</li>
<li><p>If there is no <span data-x="dom-AudioTrack-enabled">enabled</span> audio track, then
enable an audio track. This <a href="#toggle-audio-track">will cause a <code
data-x="event-media-change">change</code> event to be fired</a>.</p></li>
<li><p>If there is no <span data-x="dom-VideoTrack-selected">selected</span> video track,
then select a video track. This <a href="#toggle-video-track">will cause a <code
data-x="event-media-change">change</code> event to be fired</a>.</p></li>
</ol>
<p>Once the <code data-x="dom-media-readyState">readyState</code> attribute reaches <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code>, <a href="#fire-loadeddata">after
the <code data-x="event-media-loadeddata">loadeddata</code> event has been fired</a>, set the
element's <span>delaying-the-load-event flag</span> to false. This stops <span data-x="delay
the load event">delaying the load event</span>.</p>
<p class="note">A user agent that is attempting to reduce network usage while still fetching
the metadata for each <span>media resource</span> would also stop buffering at this point,
following <a href="#resourceSuspend">the rules described previously</a>, which involve the
<code data-x="dom-media-networkState">networkState</code> attribute switching to the <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> value and a <code
data-x="event-media-suspend">suspend</code> event firing.</p>
<p class="note">The user agent is <em>required</em> to determine the duration of the
<span>media resource</span> and go through this step before playing.</p> <!-- actually defined
in the 'duration' section -->
</dd>
<dt>Once the entire <span>media resource</span> has been fetched (but potentially before any of
it has been decoded)</dt>
<dd>
<p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-progress">progress</code> at the <span>media element</span>.</p>
<p>Set the <code data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> and <span
data-x="concept-event-fire">fire an event</span> named
<code data-x="event-media-suspend">suspend</code> at the <span>media element</span>.</p>
<p>If the user agent ever discards any <span>media data</span> and then needs to resume the
network activity to obtain it again, then it must <span>queue a media element task</span>
given the <span>media element</span> to set the <code
data-x="dom-media-networkState">networkState</code> to <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>.</p>
<p class="note">If the user agent can keep the <span>media resource</span> loaded, then the
algorithm will continue to its <i>final step</i> below, which aborts the algorithm.</p>
</dd>
<dt>If the connection is interrupted after some <span>media data</span> has been received,
causing the user agent to give up trying to fetch the resource</dt>
<dd>
<p>Fatal network errors that occur after the user agent has established whether the <var>current media resource</var> is usable (i.e. once the <span>media element</span>'s
<code data-x="dom-media-readyState">readyState</code> attribute is no longer <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>) must cause the user agent to execute the
following steps:</p>
<ol>
<li><p>The user agent should cancel the fetching process.</p></li>
<li><p>Set the <code data-x="dom-media-error">error</code> attribute to the result of
<span>creating a <code>MediaError</code></span> with <code
data-x="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</code>.</p></li>
<li><p>Set the element's <code data-x="dom-media-networkState">networkState</code> attribute
to the <code data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> value.</p></li>
<li><p>Set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-error">error</code> at the <span>media element</span>.</p></li>
<li><p>Abort the overall <span data-x="concept-media-load-algorithm">resource selection
algorithm</span>.</p></li>
</ol>
</dd>
<dt id="fatal-decode-error">If the <span>media data</span> is corrupted</dt>
<dd>
<p>Fatal errors in decoding the <span>media data</span> that occur after the user agent has
established whether the <var>current media resource</var> is usable (i.e. once the <span>media element</span>'s
<code data-x="dom-media-readyState">readyState</code> attribute is no longer <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>) must cause the
user agent to execute the following steps:</p>
<ol>
<li><p>The user agent should cancel the fetching process.</p></li>
<li><p>Set the <code data-x="dom-media-error">error</code> attribute to the result of
<span>creating a <code>MediaError</code></span> with <code
data-x="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</code>.</p></li>
<li><p>Set the element's <code data-x="dom-media-networkState">networkState</code> attribute
to the <code data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> value.</p></li>
<li><p>Set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-error">error</code> at the <span>media element</span>.</p></li>
<li><p>Abort the overall <span data-x="concept-media-load-algorithm">resource selection
algorithm</span>.</p></li>
</ol>
</dd>
<dt>If the <span>media data</span> fetching process is aborted by the user</dt>
<dd>
<p>The fetching process is aborted by the user, e.g. because the user
pressed a "stop" button, the user agent must execute the following steps. These steps are not
followed if the <code data-x="dom-media-load">load()</code> method itself is invoked while
these steps are running, as the steps above handle that particular kind of abort.</p>
<ol>
<li><p>The user agent should cancel the fetching process.</p></li>
<li><p>Set the <code data-x="dom-media-error">error</code> attribute to the result of
<span>creating a <code>MediaError</code></span> with <code
data-x="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</code>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-abort">abort</code> at the <span>media element</span>.</p></li>
<li>
<p>If the <span>media element</span>'s <code data-x="dom-media-readyState">readyState</code>
attribute has a value equal to <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, set
the element's <code data-x="dom-media-networkState">networkState</code> attribute to the
<code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> value, set the element's
<span>show poster flag</span> to true, and <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-media-emptied">emptied</code> at the element.</p>
<p>Otherwise, set the element's <code data-x="dom-media-networkState">networkState</code>
attribute to the <code data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code> value.</p>
</li>
<li><p>Set the element's <span>delaying-the-load-event flag</span> to false. This stops <span
data-x="delay the load event">delaying the load event</span>.</p></li>
<li><p>Abort the overall <span data-x="concept-media-load-algorithm">resource selection
algorithm</span>.</p></li>
</ol>
</dd>
<dt id="non-fatal-media-error">If the <span>media data</span> can be fetched but has non-fatal
errors or uses, in part, codecs that are unsupported, preventing the user agent from rendering
the content completely correctly but not preventing playback altogether</dt>
<dd>
<p>The server returning data that is partially usable but cannot be optimally rendered must
cause the user agent to render just the bits it can handle, and ignore the rest.</p>
<!-- v2: fire a 'warning' event and set the 'error' flag to 'MEDIA_ERR_SUBOPTIMAL' or something -->
</dd>
<dt id="found-a-media-resource-specific-timed-track">If the <span>media resource</span> is
found to declare a <span>media-resource-specific text track</span> that the user agent
supports</dt>
<dd>
<p>If the <span>media data</span> is <span>CORS-same-origin</span>, run the <span>steps to
expose a media-resource-specific text track</span> with the relevant data.</p>
<p class="note">Cross-origin videos do not expose their subtitles, since that would allow
attacks such as hostile sites reading subtitles from confidential videos on a user's
intranet.</p>
</dd>
</dl>
</li>
<!-- this step is mentioned above, search for "final step" -->
<li><p><i>Final step</i>: If the user agent ever reaches this step (which can only happen if the entire resource
gets loaded and kept available): abort the overall <span
data-x="concept-media-load-algorithm">resource selection algorithm</span>.</p></li>
</ol>
<p>When a <span>media element</span> is to <dfn>forget the media element's media-resource-specific
tracks</dfn>, the user agent must remove from the <span>media element</span>'s <span>list of text
tracks</span> all the <span data-x="media-resource-specific text track">media-resource-specific
text tracks</span>, then empty the <span>media element</span>'s <code
data-x="dom-media-audioTracks">audioTracks</code> attribute's <code>AudioTrackList</code> object,
then empty the <span>media element</span>'s <code data-x="dom-media-videoTracks">videoTracks</code>
attribute's <code>VideoTrackList</code> object. No events (in particular, no <code
data-x="event-media-removetrack">removetrack</code> events) are fired as part of this; the <code
data-x="event-media-error">error</code> and <code data-x="event-media-emptied">emptied</code>
events, fired by the algorithms that invoke this one, can be used instead.</p>
</div>
<hr>
<p>The <dfn element-attr for="audio,video"><code data-x="attr-media-preload">preload</code></dfn>
attribute is an <span>enumerated attribute</span> with the following keywords and
states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="audio/preload,video/preload"><code
data-x="attr-media-preload-auto">auto</code></dfn>
<td rowspan=2><dfn data-x="attr-media-preload-auto-state">Automatic</dfn>
<td rowspan=2>Hints to the user agent that the user agent can put the user's needs first without risk to the server, up to and including optimistically downloading the entire resource.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="audio/preload,video/preload"><code
data-x="attr-media-preload-none">none</code></dfn>
<td><dfn data-x="attr-media-preload-none-state">None</dfn>
<td>Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimize unnecessary traffic.
This state does not provide a hint regarding how aggressively to actually download the media resource if buffering starts anyway (e.g. once the user hits "play").
<tr>
<td><dfn attr-value for="audio/preload,video/preload"><code
data-x="attr-media-preload-metadata">metadata</code></dfn>
<td><dfn data-x="attr-media-preload-metadata-state">Metadata</dfn>
<td>Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, track list, duration, etc.), and maybe even the first few frames, is reasonable. If the user agent precisely fetches no more than the metadata, then the <span>media element</span> will end up with its <code data-x="dom-media-readyState">readyState</code> attribute set to <code data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code>; typically though, some frames will be obtained as well and it will probably be <code data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or <code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>.
When the media resource is playing, hints to the user agent that bandwidth is to be considered scarce, e.g. suggesting throttling the download so that the media data is obtained at the slowest possible rate that still maintains consistent playback.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both
<span>implementation-defined</span>, though the <span
data-x="attr-media-preload-metadata-state">Metadata</span> state is suggested as a compromise
between reducing server load and providing an optimal user experience.</p>
<p>The attribute can be changed even once the <span>media resource</span> is being buffered or
played; the descriptions in the table above are to be interpreted with that in mind.</p>
<p class="note">Authors might switch the attribute from "<code
data-x="attr-media-preload-none">none</code>" or "<code
data-x="attr-media-preload-metadata">metadata</code>" to "<code
data-x="attr-media-preload-auto">auto</code>" dynamically once the user begins playback. For
example, on a page with many videos this might be used to indicate that the many videos are not to
be downloaded unless requested, but that once one <em>is</em> requested it is to be downloaded
aggressively.</p>
<div w-nodev>
<p>The <code data-x="attr-media-preload">preload</code> attribute is intended to provide a hint to
the user agent about what the author thinks will lead to the best user experience. The attribute
may be ignored altogether, for example based on explicit user preferences or based on the
available connectivity.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-preload">preload</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name, <span>limited to
only known values</span>.</p>
</div>
<p class="note">The <code data-x="attr-media-autoplay">autoplay</code> attribute can override the
<code data-x="attr-media-preload">preload</code> attribute (since if the media plays, it naturally
has to buffer first, regardless of the hint given by the <code
data-x="attr-media-preload">preload</code> attribute). Including both is not an error, however.</p>
<hr>
<!--v3BUF (when readding this, also add a domintro block)
<p>The <dfn><code data-x="dom-media-bufferingRate">bufferingRate</code></dfn> attribute must return
the average number of bits received per second for the current download over the past few seconds.
If there is no download in progress, the attribute must return 0.</p>
<p>The <dfn><code data-x="dom-media-bufferingThrottled">bufferingThrottled</code></dfn> attribute
must return true if the user agent is intentionally throttling the bandwidth used by the download
(including when throttling to zero to pause the download altogether), and false otherwise.</p>
<hr>
-->
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-buffered">buffered</span></code></dt>
<dd>
<p>Returns a <code>TimeRanges</code> object that represents the ranges of the <span>media
resource</span> that the user agent has buffered.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-buffered">buffered</code></dfn> attribute must return a new static
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of the
<span>media resource</span>, if any, that the user agent has buffered, at the time the attribute
is evaluated. Users agents must accurately determine the ranges available, even for media streams
where this can only be determined by tedious inspection.</p>
<p class="note">Typically this will be a single range anchored at the zero point, but if, e.g. the
user agent uses HTTP range requests in response to seeking, then there could be multiple
ranges.</p>
<p>User agents may discard previously buffered data.</p>
<p class="note">Thus, a time position included within a range of the objects return by the <code
data-x="dom-media-buffered">buffered</code> attribute at one time can end up being not included in
the range(s) of objects returned by the same attribute at later times.</p>
<p class="warning">Returning a new object each time is a bad pattern for attribute getters and is
only enshrined here as it would be costly to change it. It is not to be copied to new APIs.</p>
</div>
<h5>Offsets into the media resource</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-duration">duration</span></code></dt>
<dd>
<p>Returns the length of the <span>media resource</span>, in seconds, assuming that the start of
the <span>media resource</span> is at time zero.</p>
<p>Returns NaN if the duration isn't available.</p>
<p>Returns Infinity for unbounded streams.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-currentTime">currentTime</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>official playback position</span>, in seconds.</p>
<p>Can be set, to seek to the given time.</p>
</dd>
</dl>
<div w-nodev>
<p>A <span>media resource</span> has a <dfn>media timeline</dfn> that maps times (in seconds) to
positions in the <span>media resource</span>. The origin of a timeline is its earliest defined
position. The duration of a timeline is its last defined position.</p>
<p><dfn id="defineTimeline" data-x="establish the media timeline">Establishing the media
timeline</dfn>: if the <span>media resource</span> somehow specifies an explicit timeline whose
origin is not negative (i.e. gives each frame a specific time offset and gives the first frame a
zero or positive offset), then the <span>media timeline</span> should be that timeline. (Whether
the <span>media resource</span> can specify a timeline or not depends on the <span data-x="media
resource">media resource's</span> format.) If the <span>media resource</span> specifies an
explicit start time <em>and date</em>, then that time and date should be considered the zero point
in the <span>media timeline</span>; the <span>timeline offset</span> will be the time and date,
exposed using the <code data-x="dom-media-getStartDate">getStartDate()</code> method.</p>
<p>If the <span>media resource</span> has a discontinuous timeline, the user agent must extend the
timeline used at the start of the resource across the entire resource, so that the <span>media
timeline</span> of the <span>media resource</span> increases linearly starting from the
<span>earliest possible position</span> (as defined below), even if the underlying <span>media
data</span> has out-of-order or even overlapping time codes.</p>
<p class="example">For example, if two clips have been concatenated into one video file, but the
video format exposes the original times for the two clips, the video data might expose a timeline
that goes, say, 00:15..00:29 and then 00:05..00:38. However, the user agent would not expose those
times; it would instead expose the times as 00:15..00:29 and 00:29..01:02, as a single video.</p>
<p>
<!--INSERT TRACKING-->
In the rare case of a <span>media resource</span> that does not have an explicit timeline, the
zero time on the <span>media timeline</span> should correspond to the first frame of the
<span>media resource</span>. In the even rarer case of a <span>media resource</span> with no
explicit timings of any kind, not even frame durations, the user agent must itself determine the
time for each frame in an <span>implementation-defined</span> manner.</p>
<p class="note">An example of a file format with no explicit timeline but with explicit frame
durations is the Animated GIF format. An example of a file format with no explicit timings at all
is the JPEG-push format (<code>multipart/x-mixed-replace</code> with JPEG frames, often
used as the format for MJPEG streams).</p>
<p>If, in the case of a resource with no timing information, the user agent will nonetheless be
able to seek to an earlier point than the first frame originally provided by the server, then the
zero time should correspond to the earliest seekable time of the <span>media resource</span>;
otherwise, it should correspond to the first frame received from the server (the point in the
<span>media resource</span> at which the user agent began receiving the stream).</p>
<p class="note">At the time of writing, there is no known format that lacks explicit frame time
offsets yet still supports seeking to a frame before the first frame sent by the server.</p>
<div class="example">
<p>Consider a stream from a TV broadcaster, which begins streaming on a sunny Friday afternoon in
October, and always sends connecting user agents the media data on the same media timeline, with
its zero time set to the start of this stream. Months later, user agents connecting to this
stream will find that the first frame they receive has a time with millions of seconds. The <code
data-x="dom-media-getStartDate">getStartDate()</code> method would always return the date that the
broadcast started; this would allow controllers to display real times in their scrubber (e.g.
"2:30pm") rather than a time relative to when the broadcast began ("8 months, 4 hours, 12
minutes, and 23 seconds").</p>
<p>Consider a stream that carries a video with several concatenated fragments, broadcast by a
server that does not allow user agents to request specific times but instead just streams the
video data in a predetermined order, with the first frame delivered always being identified as
the frame with time zero. If a user agent connects to this stream and receives fragments defined
as covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00 UTC and 2010-02-12 14:25:00
UTC to 2010-02-12 14:35:00 UTC, it would expose this with a <span>media timeline</span> starting
at 0s and extending to 3,600s (one hour). Assuming the streaming server disconnected at the end
of the second clip, the <code data-x="dom-media-duration">duration</code> attribute would then
return 3,600. The <code data-x="dom-media-getStartDate">getStartDate()</code> method would return a
<code>Date</code> object with a time corresponding to 2010-03-20 23:15:00 UTC. However, if a
different user agent connected five minutes later, <em>it</em> would (presumably) receive
fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21 00:05:00 UTC and 2010-02-12
14:25:00 UTC to 2010-02-12 14:35:00 UTC, and would expose this with a <span>media timeline</span>
starting at 0s and extending to 3,300s (fifty five minutes). In this case, the <code
data-x="dom-media-getStartDate">getStartDate()</code> method would return a <code>Date</code> object
with a time corresponding to 2010-03-20 23:20:00 UTC.</p>
<p>In both of these examples, the <code data-x="dom-media-seekable">seekable</code> attribute
would give the ranges that the controller would want to actually display in its UI; typically, if
the servers don't support seeking to arbitrary times, this would be the range of time from the
moment the user agent connected to the stream up to the latest frame that the user agent has
obtained; however, if the user agent starts discarding earlier information, the actual range
might be shorter.</p>
</div>
<p>In any case, the user agent must ensure that the <span>earliest possible position</span> (as
defined below) using the established <span>media timeline</span>, is greater than or equal to
zero.</p>
<p>The <span>media timeline</span> also has an associated clock. Which clock is used is user-agent
defined, and may be <span>media resource</span>-dependent, but it should approximate the user's
wall clock.</p>
<p><span data-x="media element">Media elements</span> have a <dfn>current playback position</dfn>,
which must initially (i.e. in the absence of <span>media data</span>) be zero seconds. The
<span>current playback position</span> is a time on the <span>media timeline</span>.</p>
<p><span data-x="media element">Media elements</span> also have an <dfn>official playback
position</dfn>, which must initially be set to zero seconds. The <span>official playback
position</span> is an approximation of the <span>current playback position</span> that is kept
stable while scripts are running.</p>
<p><span data-x="media element">Media elements</span> also have a <dfn>default playback start
position</dfn>, which must initially be set to zero seconds. This time is used to allow the
element to be seeked even before the media is loaded.</p>
<p>Each <span>media element</span> has a <dfn>show poster flag</dfn>. When a <span>media
element</span> is created, this flag must be set to true. This flag is used to control when the
user agent is to show a poster frame for a <code>video</code> element instead of showing the video
contents.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-currentTime">currentTime</code></dfn> attribute must, on getting, return the
<span>media element</span>'s <span>default playback start position</span>, unless that is zero, in
which case it must return the element's <span>official playback position</span>. The returned
value must be expressed in seconds. On setting, if the <span>media element</span>'s <code
data-x="dom-media-readyState">readyState</code> is <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, then it must set the <span>media
element</span>'s <span>default playback start position</span> to the new value; otherwise, it must
set the <span>official playback position</span> to the new value and then <span
data-x="dom-media-seek">seek</span> to the new value. The new value must be interpreted as being
in seconds.</p>
<p>If the <span>media resource</span> is a streaming resource, then the user agent might be unable
to obtain certain parts of the resource after it has expired from its buffer. Similarly, some
<span data-x="media resource">media resources</span> might have a <span>media timeline</span> that
doesn't start at zero. The <dfn>earliest possible position</dfn> is the earliest position in the
stream or resource that the user agent can ever obtain again. It is also a time on the <span>media
timeline</span>.</p>
<p class="note">The <span>earliest possible position</span> is not explicitly exposed in the API;
it corresponds to the start time of the first range in the <code
data-x="dom-media-seekable">seekable</code> attribute's <code>TimeRanges</code> object, if any, or
the <span>current playback position</span> otherwise.</p>
<p>When the <span>earliest possible position</span> changes, then: if the <span>current playback
position</span> is before the <span>earliest possible position</span>, the user agent must <span
data-x="dom-media-seek">seek</span> to the <span>earliest possible position</span>; otherwise, if
the user agent has not fired a <code data-x="event-media-timeupdate">timeupdate</code> event at
the element in the past 15 to 250ms and is not still running event handlers for such an event,
then the user agent must <span>queue a media element task</span> given the <span>media
element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element.</p>
<p class="note">Because of the above requirement and the requirement in the <span
data-x="concept-media-load-resource">resource fetch algorithm</span> that kicks in <a
href="#getting-media-metadata">when the metadata of the clip becomes known</a>, the <span>current
playback position</span> can never be less than the <span>earliest possible position</span>.</p>
<!-- see https://www.w3.org/Bugs/Public/show_bug.cgi?id=14492 -->
<!-- basically this is to handle very-long-running streams that use different video and audio
tracks per TV show -->
<p>If at any time the user agent learns that an audio or video track has ended and all <span>media
data</span> relating to that track corresponds to parts of the <span>media timeline</span> that
are <em>before</em> the <span>earliest possible position</span>, the user agent may <span>queue a
media element task</span> given the <span>media element</span> to run these steps:</p>
<ol>
<li><p>Remove the track from the <code data-x="dom-media-audioTracks">audioTracks</code>
attribute's <code>AudioTrackList</code> object or the <code
data-x="dom-media-videoTracks">videoTracks</code> attribute's <code>VideoTrackList</code> object
as appropriate.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-removetrack">removetrack</code> at the <span>media element</span>'s
aforementioned <code>AudioTrackList</code> or <code>VideoTrackList</code> object, using
<code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code> attribute
initialized to the <code>AudioTrack</code> or <code>VideoTrack</code> object representing the
track.</p></li>
</ol>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-duration">duration</code></dfn> attribute must return the time of the end of the
<span>media resource</span>, in seconds, on the <span>media timeline</span>. If no <span>media
data</span> is available, then the attributes must return the Not-a-Number (NaN) value. If the
<span>media resource</span> is not known to be bounded (e.g. streaming radio, or a live event with
no announced end time), then the attribute must return the positive Infinity value.</p>
<p>The user agent must determine the duration of the <span>media resource</span> before playing
any part of the <span>media data</span> and before setting <code
data-x="dom-media-readyState">readyState</code> to a value greater than or equal to <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code>, even if doing so requires fetching multiple
parts of the resource.</p>
<p id="durationChange">When the length of the <span>media resource</span> changes to a known value
(e.g. from being unknown to known, or from a previously established length to a new length) the
user agent must <span>queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-durationchange">durationchange</code> at the <span>media element</span>. (The
event is not fired when the duration is reset as part of loading a new media resource.) If the
duration is changed such that the <span>current playback position</span> ends up being greater
than the time of the end of the <span>media resource</span>, then the user agent must also <span
data-x="dom-media-seek">seek</span> to the time of the end of the <span>media resource</span>.</p>
<p class="example">If an "infinite" stream ends for some reason, then the duration would change
from positive Infinity to the time of the last frame or sample in the stream, and the <code
data-x="event-media-durationchange">durationchange</code> event would be fired. Similarly, if the
user agent initially estimated the <span>media resource</span>'s duration instead of determining
it precisely, and later revises the estimate based on new information, then the duration would
change and the <code data-x="event-media-durationchange">durationchange</code> event would be
fired.</p>
<p>Some video files also have an explicit date and time corresponding to the zero time in the
<span>media timeline</span>, known as the <dfn>timeline offset</dfn>. Initially, the
<span>timeline offset</span> must be set to Not-a-Number (NaN).</p>
<p>The <dfn method for="HTMLMediaElement"><code
data-x="dom-media-getStartDate">getStartDate()</code></dfn> method must return <span
data-x="create a Date object">a new <code>Date</code> object</span> representing the current
<span>timeline offset</span>.</p>
</div>
<hr>
<p>The <dfn element-attr for="audio,video"><code data-x="attr-media-loop">loop</code></dfn>
attribute is a <span>boolean attribute</span> that, if specified, indicates that the <span>media
element</span> is to seek back to the start of the <span>media resource</span> upon reaching the
end.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-loop">loop</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>
</div>
<h5>Ready states</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-readyState">readyState</span></code></dt>
<dd>
<p>Returns a value that expresses the current state of the element with respect to rendering the
<span>current playback position</span>, from the codes in the list below.</p>
</dd>
</dl>
<div w-nodev>
<p><span data-x="media element">Media elements</span> have a <i>ready state</i>, which describes to
what degree they are ready to be rendered at the <span>current playback position</span>. The
possible values are as follows; the ready state of a media element at any particular time is the
greatest value describing the state of the element:</p>
</div>
<dl>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
<dd><p>No information regarding the <span>media resource</span> is available. No data for the
<span>current playback position</span> is available. <span data-x="media element">Media
elements</span> whose <code data-x="dom-media-networkState">networkState</code> attribute are set
to <code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> are always in the <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code> state.</p></dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code></dfn> (numeric value 1)</dt>
<dd><p>Enough of the resource has been obtained that the duration of the resource is available.
In the case of a <code>video</code> element, the dimensions of the video are also available. No
<span>media data</span> is available for the immediate <span>current playback
position</span>.</p></dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
<dd><p>Data for the immediate <span>current playback position</span> is available, but either not
enough data is available that the user agent could successfully advance the <span>current
playback position</span> in the <span>direction of playback</span> at all without immediately
reverting to the <code data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> state, or there is no
more data to obtain in the <span>direction of playback</span>. For example, in video this
corresponds to the user agent having data from the current frame, but not the next frame, when
the <span>current playback position</span> is at the end of the current frame; and to when <span
data-x="ended playback">playback has ended</span>.</p></dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
<dd><p>Data for the immediate <span>current playback position</span> is available, as well as
enough data for the user agent to advance the <span>current playback position</span> in the
<span>direction of playback</span> at least a little without immediately reverting to the <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> state, and <span>the text tracks are
ready</span>. For example, in video this corresponds to the user agent having data for at least
the current frame and the next frame when the <span>current playback position</span> is at the
instant in time between the two frames, or to the user agent having the video data for the
current frame and audio data to keep playing at least a little when the <span>current playback
position</span> is in the middle of a frame. The user agent cannot be in this state if <span
data-x="ended playback">playback has ended</span>, as the <span>current playback position</span>
can never advance in this case.</p></dd>
<dt><dfn const for="HTMLMediaElement"><code data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
<dd>
<p>All the conditions described for the <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> state are met, and, in addition,
either of the following conditions is also true:</p>
<ul>
<li>The user agent estimates that data is being fetched at a rate where the <span>current
playback position</span>, if it were to advance at the element's <code
data-x="dom-media-playbackRate">playbackRate</code>, would not overtake the available data
before playback reaches the end of the <span>media resource</span>.</li>
<li>The user agent has entered a state where waiting longer will not result in further data
being obtained, and therefore nothing would be gained by delaying playback any further. (For
example, the buffer might be full.)</li>
</ul>
</dd>
</dl>
<p class="note">In practice, the difference between <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> and <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> is negligible. Really the only time
the difference is relevant is when painting a <code>video</code> element onto a
<code>canvas</code>, where it distinguishes the case where something will be drawn (<code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or greater) from the case where
nothing is drawn (<code data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> or less). Similarly,
the difference between <code data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> (only
the current frame) and <code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> (at least
this frame and the next) can be negligible (in the extreme, only one frame). The only time that
distinction really matters is when a page provides an interface for "frame-by-frame"
navigation.</p>
<div w-nodev>
<p>When the ready state of a <span>media element</span> whose <code
data-x="dom-media-networkState">networkState</code> is not <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> changes, the user agent must follow the steps
given below:</p>
<ol>
<li>
<p>Apply the first applicable set of substeps from the following list:</p>
<dl class="switch">
<!-- going up to metadata -->
<dt>If the previous ready state was <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>,
and the new ready state is <code data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code></dt>
<dd id="fire-loadedmetadata">
<p><span>Queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-loadedmetadata">loadedmetadata</code> at the element.</p>
<p class="note">Before this task is run, as part of the <span>event loop</span> mechanism, the
rendering will have been updated to resize the <code>video</code> element if appropriate.</p>
</dd>
<!-- going up to current for the first time -->
<dt id="handling-first-frame-available">If the previous ready state was <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> and the new ready state is <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or greater</dt>
<dd>
<p id="fire-loadeddata">If this is the first time this occurs for this <span>media
element</span> since the <code data-x="dom-media-load">load()</code> algorithm was last
invoked, the user agent must <span>queue a media element task</span> given the <span>media
element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-loadeddata">loadeddata</code> at the element.</p>
<p>If the new ready state is <code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>
or <code data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code>, then the relevant steps
below must then be run also.</p>
</dd>
<!-- going down -->
<dt>If the previous ready state was <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or more, and the new ready state is
<code data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or less</dt>
<dd>
<p id="fire-waiting-when-waiting">If the <span>media element</span> was <span>potentially
playing</span> before its <code data-x="dom-media-readyState">readyState</code> attribute
changed to a value lower than <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>, and the element has not
<span>ended playback</span>, and playback has not <span>stopped due to errors</span>,
<span>paused for user interaction</span>, or <span>paused for in-band content</span>, the user
agent must <span>queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element, and <span>queue a media
element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-waiting">waiting</code> at the element.</p>
</dd>
<!-- going up to future -->
<dt>If the previous ready state was <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or less, and the new ready state
is <code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code></dt>
<dd>
<p>The user agent must <span>queue a media element task</span> given the <span>media
element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-canplay">canplay</code> at the element.</p>
<p>If the element's <code data-x="dom-media-paused">paused</code> attribute is false, the user
agent must <span>notify about playing</span> for the element.</p>
</dd>
<!-- going up to enough -->
<dt>If the new ready state is <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code></dt>
<dd>
<p>If the previous ready state was <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or less, the user agent must
<span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-canplay">canplay</code> at the element, and, if the element's <code
data-x="dom-media-paused">paused</code> attribute is false, <span>notify about playing</span>
for the element.</p>
<p>The user agent must <span>queue a media element task</span> given the <span>media
element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-canplaythrough">canplaythrough</code> at the element.</p>
<p>If the element is not <span>eligible for autoplay</span>, then the user agent must abort
these substeps.</p>
<p>The user agent may run the following substeps:</p>
<ol>
<li>Set the <code data-x="dom-media-paused">paused</code> attribute to false.</li>
<li>If the element's <span>show poster flag</span> is true, set it to false and run the
<i data-x="time marches on">time marches on</i> steps.</li>
<li><span>Queue a media element task</span> given the element to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-play">play</code> at the element.</li>
<li><span>Notify about playing</span> for the element.</li>
</ol>
<p>Alternatively, if the element is a <code>video</code> element, the user agent may start
observing whether the element <span data-x="intersect the viewport">intersects the
viewport</span>. When the element starts <span data-x="intersect the viewport">intersecting
the viewport</span>, if the element is still <span>eligible for autoplay</span>, run the
substeps above. Optionally, when the element stops <span data-x="intersect the
viewport">intersecting the viewport</span>, if the <span>can autoplay flag</span> is still
true and the <code data-x="attr-media-autoplay">autoplay</code> attribute is still specified,
run the following substeps:</p>
<ol>
<li>Run the <span>internal pause steps</span> and set the <span>can autoplay flag</span> to
true.</li>
<li><span>Queue a media element task</span> given the element to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-pause">pause</code> at the element.</li>
</ol>
<p class="note">The substeps for playing and pausing can run multiple times as the element
starts or stops <span data-x="intersect the viewport">intersecting the viewport</span>, as
long as the <span>can autoplay flag</span> is true.</p>
<p class="note">User agents do not need to support autoplay, and it is suggested that user
agents honor user preferences on the matter. Authors are urged to use the <code
data-x="attr-media-autoplay">autoplay</code> attribute rather than using script to force the
video to play, so as to allow the user to override the behavior if so desired.</p>
</dd>
</dl>
</li>
</ol>
</div>
<p class="note">It is possible for the ready state of a media element to jump between these states
discontinuously. For example, the state of a media element can jump straight from <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> to <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code> without passing through the <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> and <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> states.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-readyState">readyState</code></dfn> IDL attribute must, on getting, return the
value described above that describes the current ready state of the <span>media
element</span>.</p>
</div>
<p>The <dfn element-attr for="audio,video"><code
data-x="attr-media-autoplay">autoplay</code></dfn> attribute is a <span>boolean attribute</span>.
When present, the user agent <span w-nodev>(as described in the algorithm described herein)</span>
will automatically begin playback of the <span>media resource</span> as soon as it can do so
without stopping.</p>
<p class="note">Authors are urged to use the <code data-x="attr-media-autoplay">autoplay</code>
attribute rather than using script to trigger automatic playback, as this allows the user to
override the automatic playback when it is not desired, e.g. when using a screen reader. Authors
are also encouraged to consider not using the automatic playback behavior at all, and instead to
let the user agent wait for the user to start playback explicitly.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-autoplay">autoplay</code></dfn> IDL attribute must <span>reflect</span> the
content attribute of the same name.</p>
</div>
<h5>Playing the media resource</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-paused">paused</span></code></dt>
<dd><p>Returns true if playback is paused; false otherwise.</p></dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-ended">ended</span></code></dt>
<dd><p>Returns true if playback has reached the end of the <span>media resource</span>.</p></dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the default rate of playback, for when the user is not fast-forwarding or reversing
through the <span>media resource</span>.</p>
<p>Can be set, to change the default rate of playback.</p>
<p>The default rate has no direct effect on playback, but if the user switches to a fast-forward
mode, when they return to the normal playback mode, it is expected that the rate of playback
will be returned to the default rate of playback.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-playbackRate">playbackRate</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current rate playback, where 1.0 is normal speed.</p>
<p>Can be set, to change the rate of playback.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-preservesPitch">preservesPitch</span></code></dt>
<dd>
<p>Returns true if pitch-preserving algorithms are used when the <code
data-x="dom-media-playbackRate">playbackRate</code> is not 1.0. The default value is true.</p>
<p>Can be set to false to have the <span>media resource</span>'s audio pitch change up or down
depending on the <code data-x="dom-media-playbackRate">playbackRate</code>. This is useful for
aesthetic and performance reasons.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-played">played</span></code></dt>
<dd>
<p>Returns a <code>TimeRanges</code> object that represents the ranges of the <span>media
resource</span> that the user agent has played.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-play">play</span>()</code></dt>
<dd>
<p>Sets the <code data-x="dom-media-paused">paused</code> attribute to false, loading the
<span>media resource</span> and beginning playback if necessary. If the playback had ended, will
restart it from the start.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-pause">pause</span>()</code></dt>
<dd>
<p>Sets the <code data-x="dom-media-paused">paused</code> attribute to true, loading the
<span>media resource</span> if necessary.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-paused">paused</code></dfn>
attribute represents whether the <span>media element</span> is paused or not. The attribute must
initially be true.</p>
<p>A <span>media element</span> is a <dfn>blocked media element</dfn> if its <code
data-x="dom-media-readyState">readyState</code> attribute is in the <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code> state, the <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> state, or the <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> state, or if the element has
<span>paused for user interaction</span> or <span>paused for in-band content</span>.</p>
<p>A <span>media element</span> is said to be <dfn export for="media element">potentially
playing</dfn> when its <code data-x="dom-media-paused">paused</code> attribute is false, the
element has not <span>ended playback</span>, playback has not <span>stopped due to errors</span>,
and the element is not a <span>blocked media element</span>.</p>
<p class="note">A <code data-x="event-media-waiting">waiting</code> DOM event <a
href="#fire-waiting-when-waiting">can be fired</a> as a result of an element that is
<span>potentially playing</span> stopping playback due to its <code
data-x="dom-media-readyState">readyState</code> attribute changing to a value lower than <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>.</p>
<p>A <span>media element</span> is said to be <dfn>eligible for autoplay</dfn> when all of the
following are true:</p>
<ul>
<li><p>its <span>can autoplay flag</span> is true;</p></li>
<li><p>its <code data-x="dom-media-paused">paused</code> attribute is true;</p></li>
<li><p>it has an <code data-x="attr-media-autoplay">autoplay</code> attribute
specified;</p></li>
<li><p>its <span>node document</span>'s <span>active sandboxing flag set</span> does not have
the <span>sandboxed automatic features browsing context flag</span> set; and</p></li>
<li><p>its <span>node document</span> is <span>allowed to use</span> the "<code
data-x="autoplay-feature">autoplay</code>" feature.</p></li>
</ul>
<p>A <span>media element</span> is said to be <dfn>allowed to play</dfn> if the user agent and the
system allow media playback in the current context.</p>
<p class="example">For example, a user agent could allow playback only when the <span>media
element</span>'s <code>Window</code> object has <span>transient activation</span>, but an
exception could be made to allow playback while <span
data-x="concept-media-muted">muted</span>.</p>
<p>A <span>media element</span> is said to have <dfn>ended playback</dfn> when:</p>
<ul>
<li><p>The element's <code data-x="dom-media-readyState">readyState</code> attribute is <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> or greater, and</p>
<li>
<p>Either:</p>
<ul>
<li><p>The <span>current playback position</span> is the end of the <span>media
resource</span>, and</p></li>
<li><p>The <span>direction of playback</span> is forwards, and</p></li>
<li><p>The <span>media element</span> does not have a <code
data-x="attr-media-loop">loop</code> attribute specified.</p></li>
</ul>
<p>Or:</p>
<ul>
<li><p>The <span>current playback position</span> is the <span>earliest possible
position</span>, and</p></li>
<li><p>The <span>direction of playback</span> is backwards.</p></li>
</ul>
</li>
</ul>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-ended">ended</code></dfn>
attribute must return true if, the last time the <span>event loop</span> reached <a
href="#step1">step 1</a>, the <span>media element</span> had <span>ended playback</span> and the
<span>direction of playback</span> was forwards, and false otherwise.</p>
<p>A <span>media element</span> is said to have <dfn>stopped due to errors</dfn> when the
element's <code data-x="dom-media-readyState">readyState</code> attribute is <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> or greater, and the user agent <a
href="#non-fatal-media-error">encounters a non-fatal error</a> during the processing of the
<span>media data</span>, and due to that error, is not able to play the content at the
<span>current playback position</span>.</p>
<p>A <span>media element</span> is said to have <dfn>paused for user interaction</dfn> when its
<code data-x="dom-media-paused">paused</code> attribute is false, the <code
data-x="dom-media-readyState">readyState</code> attribute is either <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code> and the user agent has reached a point
in the <span>media resource</span> where the user has to make a selection for the resource to
continue.</p>
<p>It is possible for a <span>media element</span> to have both <span>ended playback</span> and
<span>paused for user interaction</span> at the same time.</p>
<p>When a <span>media element</span> that is <span>potentially playing</span> stops playing
because it has <span>paused for user interaction</span>, the user agent must <span>queue a media
element task</span> given the <span>media element</span> to <span data-x="concept-event-fire">fire
an event</span> named <code data-x="event-media-timeupdate">timeupdate</code> at the element.</p>
<p>A <span>media element</span> is said to have <dfn>paused for in-band content</dfn> when its
<code data-x="dom-media-paused">paused</code> attribute is false, the <code
data-x="dom-media-readyState">readyState</code> attribute is either <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code> and the user agent has suspended
playback of the <span>media resource</span> in order to play content that is temporally anchored
to the <span>media resource</span> and has a nonzero length, or to play content that is
temporally anchored to a segment of the <span>media resource</span> but has a length longer than
that segment.</p>
<p class="example">One example of when a <span>media element</span> would be <span>paused for
in-band content</span> is when the user agent is playing <span
data-x="attr-track-kind-descriptions">audio descriptions</span> from an external WebVTT file, and
the synthesized speech generated for a cue is longer than the time between the <span>text track
cue start time</span> and the <span>text track cue end time</span>.</p>
<hr>
<p id="reaches-the-end">When the <span>current playback position</span> reaches the end of the
<span>media resource</span> when the <span>direction of playback</span> is forwards, then the user
agent must follow these steps:</p>
<ol>
<li><p>If the <span>media element</span> has a <code data-x="attr-media-loop">loop</code>
attribute specified, then <span data-x="dom-media-seek">seek</span> to the <span>earliest
possible position</span> of the <span>media resource</span> and return.</p></li>
<!-- v2/v3: We should fire a 'looping' event here to explain why this immediately fires a
'playing' event, otherwise the 'playing' event that fires from the readyState going from
HAVE_CURRENT_DATA back to HAVE_FUTURE_DATA will seem inexplicable (since the normally matching
'ended' given below event doesn't fire in the loop case). -->
<li><p>As defined above, the <code data-x="dom-media-ended">ended</code> IDL attribute starts
returning true once the <span>event loop</span> returns to <a href="#step1">step 1</a>.</p></li>
<li>
<p><span>Queue a media element task</span> given the <span>media element</span> and the
following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the <span>media element</span>.</p></li>
<li>
<p>If the <span>media element</span> has <span>ended playback</span>, the <span>direction of
playback</span> is forwards, and <span data-x="dom-media-paused">paused</span> is false,
then:</p>
<ol>
<li><p>Set the <code data-x="dom-media-paused">paused</code> attribute to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-pause">pause</code> at the <span>media element</span>.</p></li>
<li><p><span>Take pending play promises</span> and <span>reject pending play promises</span>
with the result and an <span>"<code>AbortError</code>"</span>
<code>DOMException</code>.</p></li>
</ol>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-ended">ended</code> at the <span>media element</span>.</p></li>
</ol>
</li>
</ol>
<p>When the <span>current playback position</span> reaches the <span>earliest possible
position</span> of the <span>media resource</span> when the <span>direction of playback</span> is
backwards, then the user agent must only <span>queue a media element task</span> given the
<span>media element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element.</p>
<p class="note">The word "reaches" here does not imply that the <span>current playback
position</span> needs to have changed during normal playback; it could be via <span
data-x="dom-media-seek">seeking</span>, for instance.</p>
<hr>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code></dfn> attribute gives the
desired speed at which the <span>media resource</span> is to play, as a multiple of its intrinsic
speed. The attribute is mutable: on getting it must return the last value it was set to, or 1.0 if
it hasn't yet been set; on setting the attribute must be set to the new value.</p>
<p class="note">The <code data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code> is used
by the user agent when it <span data-x="expose a user interface to the user">exposes a user
interface to the user</span>.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-playbackRate">playbackRate</code></dfn> attribute gives the effective playback
rate, which is the speed at which the <span>media resource</span> plays, as a multiple of its
intrinsic speed. If it is not equal to the <code
data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code>, then the implication is that
the user is using a feature such as fast forward or slow motion playback. The attribute is
mutable: on getting it must return the last value it was set to, or 1.0 if it hasn't yet been set;
on setting, the user agent must follow these steps:</p>
<ol>
<li><p>If the given value is not supported by the user agent, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <code data-x="dom-media-playbackRate">playbackRate</code> to the new value, and if the
element is <span>potentially playing</span>, change the playback speed.</p></li>
</ol>
<p id="rateUpdate">When the <code
data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code> or <code
data-x="dom-media-playbackRate">playbackRate</code> attributes change value (either by being set
by script or by being changed directly by the user agent, e.g. in response to user control) the
user agent must <span>queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-ratechange">ratechange</code> at the <span>media element</span>. The user
agent must process attribute changes smoothly and must not introduce any perceivable gaps or
muting of playback in response.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-preservesPitch">preservesPitch</code></dfn> getter steps are to return true if a
pitch-preserving algorithm is in effect during playback. The setter steps are to correspondingly
switch the pitch-preserving algorithm on or off, without any perceivable gaps or muting of
playback. By default, such a pitch-preserving algorithm must be in effect (i.e., the getter will
initially return true).</p>
<hr>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-played">played</code></dfn>
attribute must return a new static <span>normalized <code>TimeRanges</code> object</span> that
represents the ranges of points on the <span>media timeline</span> of the <span>media
resource</span> reached through the usual monotonic increase of the <span>current playback
position</span> during normal playback, if any, at the time the attribute is evaluated.</p>
<p class="warning">Returning a new object each time is a bad pattern for attribute getters and is
only enshrined here as it would be costly to change it. It is not to be copied to new APIs.</p>
<hr>
<p>Each <span>media element</span> has a <dfn>list of pending play promises</dfn>, which must
initially be empty.</p>
<p>To <dfn>take pending play promises</dfn> for a <span>media element</span>, the user agent must
run the following steps:</p>
<ol>
<li><p>Let <var>promises</var> be an empty list of promises.</p></li>
<li><p>Copy the <span>media element</span>'s <span>list of pending play promises</span> to
<var>promises</var>.</p></li>
<li><p>Clear the <span>media element</span>'s <span>list of pending play
promises</span>.</p></li>
<li>Return <var>promises</var>.</li>
</ol>
<p>To <dfn>resolve pending play promises</dfn> for a <span>media element</span> with a list of
promises <var>promises</var>, the user agent must resolve each promise in <var>promises</var> with
undefined.</p>
<p>To <dfn>reject pending play promises</dfn> for a <span>media element</span> with a list of
promises <var>promises</var> and an exception name <var>error</var>, the user agent must reject
each promise in <var>promises</var> with <var>error</var>.</p>
<p>To <dfn>notify about playing</dfn> for a <span>media element</span>, the user agent must run
the following steps:</p>
<ol>
<li><p><span>Take pending play promises</span> and let <var>promises</var> be the
result.</p></li>
<li>
<p><span>Queue a media element task</span> given the element and the following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-playing">playing</code> at the element.</p></li>
<li><p><span>Resolve pending play promises</span> with <var>promises</var>.</p></li>
</ol>
</li>
</ol>
<p>When the <dfn method for="HTMLMediaElement"><code data-x="dom-media-play">play()</code></dfn>
method on a <span>media element</span> is invoked, the user agent must run the following
steps.</p>
<ol>
<li><p>If the <span>media element</span> is not <span>allowed to play</span>, then return
<span>a promise rejected with</span> a <span>"<code>NotAllowedError</code>"</span>
<code>DOMException</code>.</p></li>
<li>
<p>If the <span>media element</span>'s <code data-x="dom-media-error">error</code> attribute is
not null and its <span data-x="concept-MediaError-code">code</span> is <code
data-x="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED">MEDIA_ERR_SRC_NOT_SUPPORTED</code>, then
return <span>a promise rejected with</span> a <span>"<code>NotSupportedError</code>"</span>
<code>DOMException</code>.</p>
<p class="note">This means that the <span>dedicated media source failure steps</span> have run.
Playback is not possible until the <span>media element load algorithm</span> clears the <code
data-x="dom-media-error">error</code> attribute.</p>
</li>
<li><p>Let <var>promise</var> be a new promise and append <var>promise</var> to the <span>list of
pending play promises</span>.</p></li>
<li><p>Run the <span>internal play steps</span> for the <span>media element</span>.</p></li>
<li><p>Return <var>promise</var>.</p></li>
</ol>
<p>The <dfn>internal play steps</dfn> for a <span>media element</span> are as follows:</p>
<ol>
<li><p>If the <span>media element</span>'s <code
data-x="dom-media-networkState">networkState</code> attribute has the value <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, invoke the <span>media element</span>'s
<span data-x="concept-media-load-algorithm">resource selection algorithm</span>.</p></li>
<li>
<p>If the <span data-x="ended playback">playback has ended</span> and the <span>direction of
playback</span> is forwards, <span data-x="dom-media-seek">seek</span> to the <span>earliest
possible position</span> of the <span>media resource</span>.</p>
<p class="note">This <a href="#seekUpdate">will cause</a> the user agent to <span>queue a media
element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the <span>media element</span>.</p>
<!-- if we're already playing at this point, it might also fire 'waiting' -->
</li>
<li>
<p>If the <span>media element</span>'s <code data-x="dom-media-paused">paused</code> attribute
is true, then:</p>
<ol>
<li><p>Change the value of <code data-x="dom-media-paused">paused</code> to false.</p></li>
<li><p>If the <span>show poster flag</span> is true, set the element's <span>show poster
flag</span> to false and run the <i data-x="time marches on">time marches on</i> steps.</p></li>
<li><p><span>Queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-play">play</code> at the element.</p></li>
<li>
<p>If the <span>media element</span>'s <code data-x="dom-media-readyState">readyState</code>
attribute has the value <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code>, or <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code>, <span>queue a media element
task</span> given the <span>media element</span> to <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-media-waiting">waiting</code> at the element.</p>
<p>Otherwise, the <span>media element</span>'s <code
data-x="dom-media-readyState">readyState</code> attribute has the value <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code>: <span>notify about playing</span>
for the element.</p>
</li>
</ol>
</li>
<li>
<p>Otherwise, if the <span>media element</span>'s <code
data-x="dom-media-readyState">readyState</code> attribute has the value <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code>, <span>take pending play
promises</span> and <span>queue a media element task</span> given the <span>media element</span>
to <span>resolve pending play promises</span> with the result.</p>
<p class="note">The media element is already playing. However, it's possible that
<var>promise</var> will be <span data-x="reject pending play promises">rejected</span> before
the queued task is run.</p>
</li>
<li><p>Set the <span>media element</span>'s <span>can autoplay flag</span> to false.</p></li>
</ol>
<hr>
<p>When the <dfn method for="HTMLMediaElement"><code data-x="dom-media-pause">pause()</code></dfn>
method is invoked, and when the user agent is required to pause the <span>media element</span>,
the user agent must run the following steps:</p>
<ol>
<li><p>If the <span>media element</span>'s <code
data-x="dom-media-networkState">networkState</code> attribute has the value <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, invoke the <span>media element</span>'s
<span data-x="concept-media-load-algorithm">resource selection algorithm</span>.</p></li>
<li><p>Run the <span>internal pause steps</span> for the <span>media element</span>.</p></li>
</ol>
<p>The <dfn>internal pause steps</dfn> for a <span>media element</span> are as follows:</p>
<ol>
<li><p>Set the <span>media element</span>'s <span>can autoplay flag</span> to false.</p></li>
<li><p>If the <span>media element</span>'s <code data-x="dom-media-paused">paused</code> attribute
is false, run the following steps:</p>
<ol>
<li><p>Change the value of <code data-x="dom-media-paused">paused</code> to true.</p></li>
<li><p><span>Take pending play promises</span> and let <var>promises</var> be the
result.</p></li>
<li>
<p><span>Queue a media element task</span> given the <span>media element</span> and the
following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-pause">pause</code> at the element.</p></li>
<li><p><span>Reject pending play promises</span> with <var>promises</var> and an
<span>"<code>AbortError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>Set the <span>official playback position</span> to the <span>current playback
position</span>.</p></li>
</ol>
</li>
</ol>
<hr>
<p>If the element's <code data-x="dom-media-playbackRate">playbackRate</code> is positive or zero,
then the <dfn>direction of playback</dfn> is forwards. Otherwise, it is backwards.</p>
<p id="media-playback">When a <span>media element</span> is <span>potentially playing</span> and
its <code>Document</code> is a <span>fully active</span> <code>Document</code>, its <span>current
playback position</span> must increase monotonically at the element's <code
data-x="dom-media-playbackRate">playbackRate</code> units of media time per unit time of the
<span>media timeline</span>'s clock. (This specification always refers to this as an
<i>increase</i>, but that increase could actually be a <em>de</em>crease if the element's <code
data-x="dom-media-playbackRate">playbackRate</code> is negative.)</p>
<p class="note">The element's <code data-x="dom-media-playbackRate">playbackRate</code> can be
0.0, in which case the <span>current playback position</span> doesn't move, despite playback not
being paused (<code data-x="dom-media-paused">paused</code> doesn't become true, and the <code
data-x="event-media-pause">pause</code> event doesn't fire).</p>
<p class="note">This specification doesn't define how the user agent achieves the appropriate
playback rate — depending on the protocol and media available, it is plausible that the user
agent could negotiate with the server to have the server provide the media data at the appropriate
rate, so that (except for the period between when the rate is changed and when the server updates
the stream's playback rate) the client doesn't actually have to drop or interpolate any
frames.</p>
<p>Any time the user agent <span data-x="await a stable state">provides a stable state</span>,
the <span>official playback position</span> must be set to the <span>current playback
position</span>.</p> <!-- cross-ref is intentionally to the other term, to help find this -->
<p>While the <span>direction of playback</span> is backwards, any corresponding audio must be
<span data-x="concept-media-muted">muted</span>. While the element's <code
data-x="dom-media-playbackRate">playbackRate</code> is so low or so high that the user agent
cannot play audio usefully, the corresponding audio must also be <span
data-x="concept-media-muted">muted</span>. If the element's <code
data-x="dom-media-playbackRate">playbackRate</code> is not 1.0 and <code
data-x="dom-media-preservesPitch">preservesPitch</code> is true, the user agent must apply pitch
adjustment to preserve the original pitch of the audio. Otherwise, the user agent must speed up
or slow down the audio without any pitch adjustment.</p>
<p>When a <span>media element</span> is <span>potentially playing</span>, its audio data played
must be synchronized with the <span>current playback position</span>, at the element's
<span>effective media volume</span>. The user agent must play the audio from audio tracks that
were enabled when the <span>event loop</span> last reached <a href="#step1">step 1</a>.</p>
<p>When a <span>media element</span> is not <span>potentially playing</span>, audio must not play
for the element.</p>
<p><span data-x="media element">Media elements</span> that are <span>potentially playing</span>
while not <span>in a document</span> must not play any video, but should play any audio component.
Media elements must not stop playing just because all references to them have been removed; only
once a media element is in a state where no further audio could ever be played by that element may
the element be garbage collected.</p>
<p class="note">It is possible for an element to which no explicit references exist to play audio,
even if such an element is not still actively playing: for instance, it could be unpaused but
stalled waiting for content to buffer, or it could be still buffering, but with a
<code data-x="event-media-suspend">suspend</code> event listener that begins playback. Even a
media element whose <span>media resource</span> has no audio tracks could eventually play audio
again if it had an event listener that changes the <span>media resource</span>.</p>
<hr>
<p>Each <span>media element</span> has a <dfn>list of newly introduced cues</dfn>, which must be
initially empty. Whenever a <span>text track cue</span> is added to the <span data-x="text track
list of cues">list of cues</span> of a <span>text track</span> that is in the <span>list of text
tracks</span> for a <span>media element</span>, that <span data-x="text track cue">cue</span> must
be added to the <span>media element</span>'s <span>list of newly introduced cues</span>. Whenever
a <span>text track</span> is added to the <span>list of text tracks</span> for a <span>media
element</span>, all of the <span data-x="text track cue">cues</span> in that <span>text
track</span>'s <span data-x="text track list of cues">list of cues</span> must be added to the
<span>media element</span>'s <span>list of newly introduced cues</span>. When a <span>media
element</span>'s <span>list of newly introduced cues</span> has new cues added while the
<span>media element</span>'s <span>show poster flag</span> is not set, then the user agent must
run the <i data-x="time marches on">time marches on</i> steps.</p>
<p>When a <span>text track cue</span> is removed from the <span data-x="text track list of
cues">list of cues</span> of a <span>text track</span> that is in the <span>list of text
tracks</span> for a <span>media element</span>, and whenever a <span>text track</span> is removed
from the <span>list of text tracks</span> of a <span>media element</span>, if the <span>media
element</span>'s <span>show poster flag</span> is not set, then the user agent must run the
<i data-x="time marches on">time marches on</i> steps.</p>
<p>When the <span>current playback position</span> of a <span>media element</span> changes (e.g.
due to playback or seeking), the user agent must run the <i data-x="time marches on">time marches
on</i> steps. To support use cases that depend on the timing accuracy of cue event firing, such as
synchronizing captions with shot changes in a video, user agents should fire cue events as close
as possible to their position on the media timeline, and ideally within 20 milliseconds. If the
<span>current playback position</span> changes while the steps are running, then the user agent
must wait for the steps to complete, and then must immediately rerun the steps. These steps are
thus run as often as possible or needed.</p>
<p class="note">If one iteration takes a long time, this can cause short duration
<span data-x="text track cue">cues</span> to be skipped over as the user agent rushes ahead to
"catch up", so these cues will not appear in the <code
data-x="dom-TextTrack-activeCues">activeCues</code> list.</p>
<p>The <dfn><i>time marches on</i></dfn> steps are as follows:</p>
<ol>
<li><p>Let <var>current cues</var> be a list of <span data-x="text track
cue">cues</span>, initialized to contain all the <span data-x="text track cue">cues</span> of all
the <span data-x="text track hidden">hidden</span> or <span data-x="text track
showing">showing</span> <span data-x="text track">text tracks</span> of the <span>media
element</span> (not the <span data-x="text track disabled">disabled</span> ones) whose <span
data-x="text track cue start time">start times</span> are less than or equal to the <span>current
playback position</span> and whose <span data-x="text track cue end time">end times</span> are
greater than the <span>current playback position</span>.</p></li>
<li><p>Let <var>other cues</var> be a list of <span data-x="text track cue">cues</span>,
initialized to contain all the <span data-x="text track cue">cues</span> of <span data-x="text
track hidden">hidden</span> and <span data-x="text track showing">showing</span> <span data-x="text
track">text tracks</span> of the <span>media element</span> that are not present in <var>current cues</var>.</p></li>
<li><p>Let <var>last time</var> be the <span>current playback position</span> at the
time this algorithm was last run for this <span>media element</span>, if this is not the first
time it has run.</p></li>
<li><p>If the <span>current playback position</span> has, since the last time this algorithm was
run, only changed through its usual monotonic increase during normal playback, then let
<var>missed cues</var> be the list of <span data-x="text track cue">cues</span> in <var>other
cues</var> whose <span data-x="text track cue start time">start times</span> are greater than or
equal to <var>last time</var> and whose <span data-x="text track cue end time">end times</span>
are less than or equal to the <span>current playback position</span>. Otherwise, let <var>missed
cues</var> be an empty list.</p></li>
<li><p>Remove all the <span data-x="text track cue">cues</span> in <var>missed cues</var>
that are also in the <span>media element</span>'s <span>list of newly introduced cues</span>, and
then empty the element's <span>list of newly introduced cues</span>.</p></li>
<li><p>If the time was reached through the usual monotonic increase of the <span>current playback
position</span> during normal playback, and if the user agent has not fired a <code
data-x="event-media-timeupdate">timeupdate</code> event at the element in the past 15 to 250ms
and is not still running event handlers for such an event, then the user agent must <span>queue a
media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element. (In the other cases, such as
explicit seeks, relevant events get fired as part of the overall process of changing the
<span>current playback position</span>.)</p>
<p class="note">The event thus is not to be fired faster than about 66Hz or slower than 4Hz
(assuming the event handlers don't take longer than 250ms to run). User agents are encouraged to
vary the frequency of the event based on the system load and the average cost of processing the
event each time, so that the UI updates are not any more frequent than the user agent can
comfortably handle while decoding the video.</p></li>
<li><p>If all of the <span data-x="text track cue">cues</span> in <var>current cues</var>
have their <span>text track cue active flag</span> set, none of the <span data-x="text track
cue">cues</span> in <var>other cues</var> have their <span>text track cue active
flag</span> set, and <var>missed cues</var> is empty, then return.</p></li>
<li>
<p>If the time was reached through the usual monotonic increase of the <span>current playback
position</span> during normal playback, and there are <span data-x="text track cue">cues</span>
in <var>other cues</var> that have their <span>text track cue pause-on-exit flag</span>
set and that either have their <span>text track cue active flag</span> set or are also in <var>missed cues</var>, then <span>immediately</span> <span data-x="dom-media-pause">pause</span> the
<span>media element</span>. <!-- "pause" can in theory call load(), but never can it do so as
part of this invocation, since we wouldn't be in this algorithm if the media element was empty.
So, no need to couch all this in a task. --></p>
<p class="note">In the other cases, such as explicit seeks, playback is not paused by going past
the end time of a <span data-x="text track cue">cue</span>, even if that <span data-x="text track
cue">cue</span> has its <span>text track cue pause-on-exit flag</span> set.</p>
</li>
<li>
<p>Let <var>events</var> be a list of <span data-x="concept-task">tasks</span>,
initially empty. Each <span data-x="concept-task">task</span> in this list will be associated
with a <span>text track</span>, a <span>text track cue</span>, and a time, which are used to
sort the list before the <span data-x="concept-task">tasks</span> are queued.</p>
<p>Let <var>affected tracks</var> be a list of <span data-x="text track">text
tracks</span>, initially empty.</p>
<p>When the steps below say to <dfn>prepare an event</dfn> named <var>event</var> for a
<span>text track cue</span> <var>target</var> with a time <var>time</var>, the
user agent must run these steps:</p>
<ol>
<li><p>Let <var>track</var> be the <span>text track</span> with which the <span>text
track cue</span> <var>target</var> is associated.</p></li>
<li><p>Create a <span data-x="concept-task">task</span> to <span
data-x="concept-event-fire">fire an event</span> named <var>event</var> at
<var>target</var>.</p></li>
<li><p>Add the newly created <span data-x="concept-task">task</span> to <var>events</var>, associated with the time <var>time</var>, the <span>text
track</span> <var>track</var>, and the <span>text track cue</span> <var>target</var>.</p></li>
<li><p>Add <var>track</var> to <var>affected tracks</var>.</p></li>
</ol>
</li>
<li><p>For each <span data-x="text track cue">text track cue</span> in <var>missed
cues</var>, <span>prepare an event</span> named <code data-x="event-media-enter">enter</code> for the
<code>TextTrackCue</code> object with the <span>text track cue start time</span>.</p></li>
<li><p>For each <span data-x="text track cue">text track cue</span> in <var>other
cues</var> that either has its <span>text track cue active flag</span> set or is in <var>missed cues</var>, <span>prepare an event</span> named <code
data-x="event-media-exit">exit</code> for the <code>TextTrackCue</code> object with the later of the
<span>text track cue end time</span> and the <span>text track cue start time</span>.</p></li>
<li><p>For each <span data-x="text track cue">text track cue</span> in <var>current
cues</var> that does not have its <span>text track cue active flag</span> set, <span>prepare an
event</span> named <code data-x="event-media-enter">enter</code> for the <code>TextTrackCue</code>
object with the <span>text track cue start time</span>.</p></li>
<li>
<p>Sort the <span data-x="concept-task">tasks</span> in <var>events</var> in ascending
time order (<span data-x="concept-task">tasks</span> with earlier times first).</p>
<p>Further sort <span data-x="concept-task">tasks</span> in <var>events</var> that have
the same time by the relative <span>text track cue order</span> of the <span data-x="text track
cue">text track cues</span> associated with these <span data-x="concept-task">tasks</span>.</p>
<p>Finally, sort <span data-x="concept-task">tasks</span> in <var>events</var> that have the
same time and same <span>text track cue order</span> by placing <span
data-x="concept-task">tasks</span> that fire <code data-x="event-media-enter">enter</code>
events before those that fire <code data-x="event-media-exit">exit</code> events.</p>
</li>
<li><p><span>Queue a media element task</span> given the <span>media element</span> for each
<span data-x="concept-task">task</span> in <var>events</var>, in list order.</p></li>
<li><p>Sort <var>affected tracks</var> in the same order as the <span data-x="text
track">text tracks</span> appear in the <span>media element</span>'s <span>list of text
tracks</span>, and remove duplicates.</p>
<li><p>For each <span>text track</span> in <var>affected tracks</var>, in the list order,
<span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-cuechange">cuechange</code> at the <code>TextTrack</code> object, and, if the
<span>text track</span> has a corresponding <code>track</code> element, to then <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-cuechange">cuechange</code> at the <code>track</code> element as well.</p></li>
<li><p>Set the <span>text track cue active flag</span> of all the <span data-x="text track
cue">cues</span> in the <var>current cues</var>, and unset the <span>text track cue
active flag</span> of all the <span data-x="text track cue">cues</span> in the <var>other
cues</var>.</p></li>
<li><p>Run the <span>rules for updating the text track rendering</span> of each of the <span
data-x="text track">text tracks</span> in <var>affected tracks</var> that are <span data-x="text
track showing">showing</span>, providing the <span>text track</span>'s <span>text track
language</span> as the fallback language if it is not the empty string. For example, for <span
data-x="text track">text tracks</span> based on WebVTT, the <span>rules for updating the display
of WebVTT text tracks</span>. <ref>WEBVTT</ref></p></li>
</ol>
<p>For the purposes of the algorithm above, a <span>text track cue</span> is considered to be part
of a <span>text track</span> only if it is listed in the <span>text track list of cues</span>, not
merely if it is associated with the <span>text track</span>.</p>
<p class="note">If the <span>media element</span>'s <span>node document</span> stops being a
<span>fully active</span> document, then the playback will <a href="#media-playback">stop</a>
until the document is active again.</p>
<p>When a <span>media element</span> is <span data-x="node is removed from a document">removed
from a <code>Document</code></span>, the user agent must run the following steps:</p>
<ol>
<li><p><span>Await a stable state</span>, allowing the <span
data-x="concept-task">task</span> that removed the <span>media element</span> from the
<code>Document</code> to continue. The <span>synchronous section</span> consists of all the
remaining steps of this algorithm. (Steps in the <span>synchronous section</span> are marked with
⌛.)</p></li>
<li><p>⌛ If the <span>media element</span> is <span>in a document</span>, return.</p></li>
<li><p>⌛ Run the <span>internal pause steps</span> for the <span>media element</span>.</p>
</ol>
</div>
<h5>Seeking</h5>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-seeking">seeking</span></code></dt>
<dd><p>Returns true if the user agent is currently seeking.</p></dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-seekable">seekable</span></code></dt>
<dd>
<p>Returns a <code>TimeRanges</code> object that represents the ranges of the <span>media
resource</span> to which it is possible for the user agent to seek.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-fastSeek">fastSeek</span>(<var>time</var>)</code></dt>
<dd>
<p>Seeks to near the given <var>time</var> as fast as possible, trading precision for speed. (To
seek to a precise time, use the <code data-x="dom-media-currentTime">currentTime</code>
attribute.)</p>
<p>This does nothing if the media resource has not been loaded.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-seeking">seeking</code></dfn>
attribute must initially have the value false.</p>
<p>The <dfn method for="HTMLMediaElement"><code
data-x="dom-media-fastSeek">fastSeek(<var>time</var>)</code></dfn> method must <span
data-x="dom-media-seek">seek</span> to the time given by <var>time</var>, with the
<i>approximate-for-speed</i> flag set.</p>
<p>When the user agent is required to <dfn data-x="dom-media-seek">seek</dfn> to a particular <var>new playback position</var> in the <span>media resource</span>, optionally with the
<i>approximate-for-speed</i> flag set, it means that the user agent must run the following steps.
This algorithm interacts closely with the <span>event loop</span> mechanism; in particular, it has
a <span>synchronous section</span> (which is triggered as part of the <span>event loop</span>
algorithm). Steps in that section are marked with ⌛.</p>
<ol>
<li><p>Set the <span>media element</span>'s <span>show poster flag</span> to false.</p></li>
<li><p>If the <span>media element</span>'s <code data-x="dom-media-readyState">readyState</code>
is <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>, return.</p></li>
<li><p>If the element's <code data-x="dom-media-seeking">seeking</code> IDL attribute is true,
then another instance of this algorithm is already running. Abort that other instance of the
algorithm without waiting for the step that it is running to complete.</p></li>
<li><p>Set the <code data-x="dom-media-seeking">seeking</code> IDL attribute to true.</p></li>
<li><p>If the seek was in response to a DOM method call or setting of an IDL attribute, then
continue the script. The remainder of these steps must be run <span>in parallel</span>. With the exception
of the steps marked with ⌛, they could be aborted at any time by another instance of this
algorithm being invoked.</p></li>
<li><p>If the <var>new playback position</var> is later than the end of the <span>media
resource</span>, then let it be the end of the <span>media resource</span> instead.</p></li>
<li><p>If the <var>new playback position</var> is less than the <span>earliest possible
position</span>, let it be that position instead.</p></li>
<li><p>If the (possibly now changed) <var>new playback position</var> is not in one of
the ranges given in the <code data-x="dom-media-seekable">seekable</code> attribute, then let it
be the position in one of the ranges given in the <code
data-x="dom-media-seekable">seekable</code> attribute that is the nearest to the <var>new
playback position</var>. If two positions both satisfy that constraint (i.e. the <var>new playback position</var> is exactly in the middle between two ranges in the <code
data-x="dom-media-seekable">seekable</code> attribute) then use the position that is closest to
the <span>current playback position</span>. If there are no ranges given in the <code
data-x="dom-media-seekable">seekable</code> attribute then set the <code
data-x="dom-media-seeking">seeking</code> IDL attribute to false and return.</p></li>
<li>
<p>If the <i>approximate-for-speed</i> flag is set, adjust the <var>new playback
position</var> to a value that will allow for playback to resume promptly. If <var>new
playback position</var> before this step is before <span>current playback position</span>, then
the adjusted <var>new playback position</var> must also be before the <span>current
playback position</span>. Similarly, if the <var>new playback position</var> before
this step is after <span>current playback position</span>, then the adjusted <var>new
playback position</var> must also be after the <span>current playback position</span>.</p>
<p class="example">For example, the user agent could snap to a nearby key frame, so that it
doesn't have to spend time decoding then discarding intermediate frames before resuming
playback.</p>
</li>
<li><p><span>Queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-seeking">seeking</code> at the element.</p></li>
<li>
<p>Set the <span>current playback position</span> to the <var>new playback
position</var>.</p>
<p class="note">If the <span>media element</span> was <span>potentially playing</span>
immediately before it started seeking, but seeking caused its <code
data-x="dom-media-readyState">readyState</code> attribute to change to a value lower than <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>, then a <code
data-x="event-media-waiting">waiting</code> event <a href="#fire-waiting-when-waiting">will be
fired</a> at the element.</p> <!-- also, timeupdate -->
<p class="note">This step sets the <span>current playback position</span>, and thus can
immediately trigger other conditions, such as the rules regarding when playback "<a
href="#reaches-the-end">reaches the end of the media resource</a>" (part of the logic that
handles looping), even before the user agent is actually able to render the media data for that
position (as determined in the next step).</p>
<p class="note">The <code data-x="dom-media-currentTime">currentTime</code> attribute returns
the <span>official playback position</span>, not the <span>current playback position</span>, and
therefore gets updated before script execution, separate from this algorithm.</p>
</li>
<li><p>Wait until the user agent has established whether or not the <span>media data</span> for
the <var>new playback position</var> is available, and, if it is, until it has decoded
enough data to play back that position.</p></li>
<li><p><span>Await a stable state</span>. The <span>synchronous section</span> consists of all
the remaining steps of this algorithm. (Steps in the <span>synchronous section</span> are marked
with ⌛.)</p></li>
<li><p>⌛ Set the <code data-x="dom-media-seeking">seeking</code> IDL attribute to
false.</p></li>
<li><p>⌛ Run the <span>time marches on</span> steps.</p></li>
<li id="seekUpdate"><p>⌛ <span>Queue a media element task</span> given the <span>media
element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-timeupdate">timeupdate</code> at the element.</p></li>
<li><p>⌛ <span>Queue a media element task</span> given the <span>media element</span> to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-seeked">seeked</code> at the element.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-seekable">seekable</code></dfn> attribute must return a new static
<span>normalized <code>TimeRanges</code> object</span> that represents the ranges of the
<span>media resource</span>, if any, that the user agent is able to seek to, at the time the
attribute is evaluated.</p>
<p class="note">If the user agent can seek to anywhere in the <span>media resource</span>, e.g.
because it is a simple movie file and the user agent and the server support HTTP Range requests,
then the attribute would return an object with one range, whose start is the time of the first
frame (the <span>earliest possible position</span>, typically zero), and whose end is the same as
the time of the first frame plus the <code data-x="dom-media-duration">duration</code> attribute's
value (which would equal the time of the last frame, and might be positive Infinity).</p>
<p class="note">The range might be continuously changing, e.g. if the user agent is buffering a
sliding window on an infinite stream. This is the behavior seen with DVRs viewing live TV, for
instance.</p>
<p class="warning">Returning a new object each time is a bad pattern for attribute getters and is
only enshrined here as it would be costly to change it. It is not to be copied to new APIs.</p>
<p>User agents should adopt a very liberal and optimistic view of what is seekable. User
agents should also buffer recent content where possible to enable seeking to be fast.</p>
<p class="example">For instance, consider a large video file served on an HTTP server without
support for HTTP Range requests. A browser <em>could</em> implement this by only buffering the
current frame and data obtained for subsequent frames, never allow seeking, except for seeking to
the very start by restarting the playback. However, this would be a poor implementation. A high
quality implementation would buffer the last few minutes of content (or more, if sufficient
storage space is available), allowing the user to jump back and rewatch something surprising
without any latency, and would in addition allow arbitrary seeking by reloading the file from the
start if necessary, which would be slower but still more convenient than having to literally
restart the video and watch it all the way through just to get to an earlier unbuffered spot.</p>
<p><span data-x="media resource">Media resources</span> might be internally scripted or
interactive. Thus, a <span>media element</span> could play in a non-linear fashion. If this
happens, the user agent must act as if the algorithm for <span
data-x="dom-media-seek">seeking</span> was used whenever the <span>current playback position</span>
changes in a discontinuous fashion (so that the relevant events fire).</p>
</div>
<h5>Media resources with multiple media tracks</h5>
<p>A <span>media resource</span> can have multiple embedded audio and video tracks. For example,
in addition to the primary video and audio tracks, a <span>media resource</span> could have
foreign-language dubbed dialogues, director's commentaries, audio descriptions, alternative
angles, or sign-language overlays.</p>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-audioTracks">audioTracks</span></code></dt>
<dd>
<p>Returns an <code>AudioTrackList</code> object representing the audio tracks available in the
<span>media resource</span>.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-videoTracks">videoTracks</span></code></dt>
<dd>
<p>Returns a <code>VideoTrackList</code> object representing the video tracks available in the
<span>media resource</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-audioTracks">audioTracks</code></dfn> attribute of a <span>media element</span>
must return a <span>live</span> <code>AudioTrackList</code> object representing the audio tracks
available in the <span>media element</span>'s <span>media resource</span>.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-videoTracks">videoTracks</code></dfn> attribute of a <span>media element</span>
must return a <span>live</span> <code>VideoTrackList</code> object representing the video tracks
available in the <span>media element</span>'s <span>media resource</span>.</p>
<p class="note">There are only ever one <code>AudioTrackList</code> object and one
<code>VideoTrackList</code> object per <span>media element</span>, even if another <span>media
resource</span> is loaded into the element: the objects are reused. (The <code>AudioTrack</code>
and <code>VideoTrack</code> objects are not, though.)</p>
</div>
<h6><code>AudioTrackList</code> and <code>VideoTrackList</code> objects</h6>
<p>The <code>AudioTrackList</code> and <code>VideoTrackList</code> interfaces are used by
attributes defined in the previous section.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>AudioTrackList</dfn> : <span>EventTarget</span> {
readonly attribute unsigned long <span data-x="dom-AudioTrackList-length">length</span>;
<a href="#dom-tracklist-item">getter</a> <span>AudioTrack</span> (unsigned long index);
<span>AudioTrack</span>? <span data-x="dom-AudioTrackList-getTrackById">getTrackById</span>(DOMString id);
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onchange">onchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onaddtrack">onaddtrack</span>;
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onremovetrack">onremovetrack</span>;
};
[Exposed=Window]
interface <dfn interface>AudioTrack</dfn> {
readonly attribute DOMString <span data-x="dom-AudioTrack-id">id</span>;
readonly attribute DOMString <span data-x="dom-AudioTrack-kind">kind</span>;
readonly attribute DOMString <span data-x="dom-AudioTrack-label">label</span>;
readonly attribute DOMString <span data-x="dom-AudioTrack-language">language</span>;
attribute boolean <span data-x="dom-AudioTrack-enabled">enabled</span>;
};
[Exposed=Window]
interface <dfn interface>VideoTrackList</dfn> : <span>EventTarget</span> {
readonly attribute unsigned long <span data-x="dom-VideoTrackList-length">length</span>;
<a href="#dom-tracklist-item">getter</a> <span>VideoTrack</span> (unsigned long index);
<span>VideoTrack</span>? <span data-x="dom-VideoTrackList-getTrackById">getTrackById</span>(DOMString id);
readonly attribute long <span data-x="dom-VideoTrackList-selectedIndex">selectedIndex</span>;
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onchange">onchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onaddtrack">onaddtrack</span>;
attribute <span>EventHandler</span> <span data-x="handler-TrackList-onremovetrack">onremovetrack</span>;
};
[Exposed=Window]
interface <dfn interface>VideoTrack</dfn> {
readonly attribute DOMString <span data-x="dom-VideoTrack-id">id</span>;
readonly attribute DOMString <span data-x="dom-VideoTrack-kind">kind</span>;
readonly attribute DOMString <span data-x="dom-VideoTrack-label">label</span>;
readonly attribute DOMString <span data-x="dom-VideoTrack-language">language</span>;
attribute boolean <span data-x="dom-VideoTrack-selected">selected</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-audioTracks">audioTracks</span>.<span subdfn data-x="dom-AudioTrackList-length">length</span></code></dt>
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-videoTracks">videoTracks</span>.<span subdfn data-x="dom-VideoTrackList-length">length</span></code></dt>
<dd><p>Returns the number of tracks in the list.</p></dd>
<dt><code data-x=""><var>audioTrack</var> = <var>media</var>.<span data-x="dom-media-audioTracks">audioTracks</span>[<var>index</var>]</code></dt>
<dt><code data-x=""><var>videoTrack</var> = <var>media</var>.<span data-x="dom-media-videoTracks">videoTracks</span>[<var>index</var>]</code></dt>
<dd><p>Returns the specified <code>AudioTrack</code> or <code>VideoTrack</code> object.</p></dd>
<dt><code data-x=""><var>audioTrack</var> = <var>media</var>.<span data-x="dom-media-audioTracks">audioTracks</span>.<span subdfn data-x="dom-AudioTrackList-getTrackById">getTrackById</span>(<var>id</var>)</code></dt>
<dt><code data-x=""><var>videoTrack</var> = <var>media</var>.<span data-x="dom-media-videoTracks">videoTracks</span>.<span subdfn data-x="dom-VideoTrackList-getTrackById">getTrackById</span>(<var>id</var>)</code></dt>
<dd>
<p>Returns the <code>AudioTrack</code> or <code>VideoTrack</code> object with the given
identifier, or null if no track has that identifier.</p>
</dd>
<dt><code data-x=""><var>audioTrack</var>.<span subdfn data-x="dom-AudioTrack-id">id</span></code></dt>
<dt><code data-x=""><var>videoTrack</var>.<span subdfn data-x="dom-VideoTrack-id">id</span></code></dt>
<dd>
<p>Returns the ID of the given track. This is the ID that can be used with a <span
data-x="concept-url-fragment">fragment</span> if the format supports <span>media fragment
syntax</span>, and that can be used with the <code data-x="">getTrackById()</code> method.</p>
</dd>
<dt><code data-x=""><var>audioTrack</var>.<span subdfn data-x="dom-AudioTrack-kind">kind</span></code></dt>
<dt><code data-x=""><var>videoTrack</var>.<span subdfn data-x="dom-VideoTrack-kind">kind</span></code></dt>
<dd><p>Returns the category the given track falls into. The <a
href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p></dd>
<dt><code data-x=""><var>audioTrack</var>.<span subdfn data-x="dom-AudioTrack-label">label</span></code></dt>
<dt><code data-x=""><var>videoTrack</var>.<span subdfn data-x="dom-VideoTrack-label">label</span></code></dt>
<dd><p>Returns the label of the given track, if known, or the empty string otherwise.</p></dd>
<dt><code data-x=""><var>audioTrack</var>.<span subdfn data-x="dom-AudioTrack-language">language</span></code></dt>
<dt><code data-x=""><var>videoTrack</var>.<span subdfn data-x="dom-VideoTrack-language">language</span></code></dt>
<dd><p>Returns the language of the given track, if known, or the empty string otherwise.</p></dd>
<dt><code data-x=""><var>audioTrack</var>.<span subdfn data-x="dom-AudioTrack-enabled">enabled</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if the given track is active, and false otherwise.</p>
<p>Can be set, to change whether the track is enabled or not. If multiple audio tracks are
enabled simultaneously, they are mixed.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-videoTracks">videoTracks</span>.<span subdfn data-x="dom-VideoTrackList-selectedIndex">selectedIndex</span></code></dt>
<dd><p>Returns the index of the currently selected track, if any, or −1
otherwise.</p></dd>
<dt><code data-x=""><var>videoTrack</var>.<span subdfn data-x="dom-VideoTrack-selected">selected</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if the given track is active, and false otherwise.</p>
<p>Can be set, to change whether the track is selected or not. Either zero or one video track is
selected; selecting a new track while a previous one is selected will unselect the previous
one.</p>
</dd>
</dl>
<div w-nodev>
<p>An <code>AudioTrackList</code> object represents a dynamic list of zero or more audio tracks,
of which zero or more can be enabled at a time. Each audio track is represented by an
<code>AudioTrack</code> object.</p>
<p>A <code>VideoTrackList</code> object represents a dynamic list of zero or more video tracks, of
which zero or one can be selected at a time. Each video track is represented by a
<code>VideoTrack</code> object.</p>
<p>Tracks in <code>AudioTrackList</code> and <code>VideoTrackList</code> objects must be
consistently ordered. If the <span>media resource</span> is in a format that defines an order,
then that order must be used; otherwise, the order must be the relative order in which the tracks
are declared in the <span>media resource</span>. The order used is called the <i>natural order</i>
of the list.</p>
<p class="note">Each track in one of these objects thus has an index; the first has the index
0, and each subsequent track is numbered one higher than the previous one. If a <span>media
resource</span> dynamically adds or removes audio or video tracks, then the indices of the tracks
will change dynamically. If the <span>media resource</span> changes entirely, then all the
previous tracks will be removed and replaced with new tracks.</p>
<p>The <code>AudioTrackList</code> <dfn attribute for="AudioTrackList"><code
data-x="dom-AudioTrackList-length">length</code></dfn> and <code>VideoTrackList</code>
<dfn attribute for="VideoTrackList"><code data-x="dom-VideoTrackList-length">length</code></dfn>
attribute getters must return the number of tracks represented by their objects at the time of
getting.</p>
<p>The <span>supported property indices</span> of <code>AudioTrackList</code> and
<code>VideoTrackList</code> objects at any instant are the numbers from zero to the number of
tracks represented by the respective object minus one, if any tracks are represented. If an
<code>AudioTrackList</code> or <code>VideoTrackList</code> object represents no tracks, it has no
<span>supported property indices</span>.</p>
<p id="dom-tracklist-item">To <span>determine the value of an indexed property</span> for a
given index <var>index</var> in an <code>AudioTrackList</code> or <code>VideoTrackList</code>
object <var>list</var>, the user agent must return the <code>AudioTrack</code> or
<code>VideoTrack</code> object that represents the <var>index</var>th track in <var>list</var>.</p>
<p>The <code>AudioTrackList</code> <dfn method for="AudioTrackList"><code
data-x="dom-AudioTrackList-getTrackById">getTrackById(<var>id</var>)</code></dfn> and
<code>VideoTrackList</code> <dfn method for="VideoTrackList"><code
data-x="dom-VideoTrackList-getTrackById">getTrackById(<var>id</var>)</code></dfn> methods must
return the first <code>AudioTrack</code> or <code>VideoTrack</code> object (respectively) in the
<code>AudioTrackList</code> or <code>VideoTrackList</code> object (respectively) whose identifier
is equal to the value of the <var>id</var> argument (in the natural order of the list, as defined
above). When no tracks match the given argument, the methods must return null.</p>
<p>The <code>AudioTrack</code> and <code>VideoTrack</code> objects represent specific tracks of a
<span>media resource</span>. Each track can have an identifier, category, label, and language.
These aspects of a track are permanent for the lifetime of the track; even if a track is removed
from a <span>media resource</span>'s <code>AudioTrackList</code> or <code>VideoTrackList</code>
objects, those aspects do not change.</p>
<p>In addition, <code>AudioTrack</code> objects can each be enabled or disabled; this is the audio
track's <i>enabled state</i>. When an <code>AudioTrack</code> is created, its <i>enabled state</i>
must be set to false (disabled). The <span data-x="concept-media-load-resource">resource fetch
algorithm</span> can override this.</p>
<p>Similarly, a single <code>VideoTrack</code> object per <code>VideoTrackList</code> object can
be selected, this is the video track's <i>selection state</i>. When a <code>VideoTrack</code> is
created, its <i>selection state</i> must be set to false (not selected). The <span
data-x="concept-media-load-resource">resource fetch algorithm</span> can override this.</p>
<p>The <code>AudioTrack</code> <dfn attribute for="AudioTrack"><code
data-x="dom-AudioTrack-id">id</code></dfn> and <code>VideoTrack</code> <dfn attribute
for="VideoTrack"><code data-x="dom-VideoTrack-id">id</code></dfn> attributes must return the
identifier of the track, if it has one, or the empty string otherwise. If the <span>media
resource</span> is in a format that supports <span>media fragment syntax</span>, the identifier
returned for a particular track must be the same identifier that would enable the track if used as
the name of a track in the track dimension of such a <span
data-x="concept-url-fragment">fragment</span>. <ref>INBAND</ref></p>
<p class="example">For example, in Ogg files, this would be the Name header field of the track.
<ref>OGGSKELETONHEADERS</ref></p>
<p>The <code>AudioTrack</code> <dfn attribute for="AudioTrack"><code
data-x="dom-AudioTrack-kind">kind</code></dfn> and <code>VideoTrack</code> <dfn attribute
for="VideoTrack"><code data-x="dom-VideoTrack-kind">kind</code></dfn> attributes must return the
category of the track, if it has one, or the empty string otherwise.</p>
<p>The category of a track is the string given in the first column of the table below that is the
most appropriate for the track based on the definitions in the table's second and third columns,
as determined by the metadata included in the track in the <span>media resource</span>. The cell
in the third column of a row says what the category given in the cell in the first column of that
row applies to; a category is only appropriate for an audio track if it applies to audio tracks,
and a category is only appropriate for video tracks if it applies to video tracks. Categories must
only be returned for <code>AudioTrack</code> objects if they are appropriate for audio, and must
only be returned for <code>VideoTrack</code> objects if they are appropriate for video.</p>
<p>For Ogg files, the Role header field of the track gives the relevant metadata. For DASH media
resources, the <code data-x="">Role</code> element conveys the information. For WebM, only the
<code data-x="">FlagDefault</code> element currently maps to a value. <cite>Sourcing In-band
Media Resource Tracks from Media Containers into HTML</cite> has further details.
<ref>OGGSKELETONHEADERS</ref> <ref>DASH</ref> <ref>WEBMCG</ref> <ref>INBAND</ref></p>
</div>
<table id="dom-TrackList-getKind-categories">
<caption>Return values for <code>AudioTrack</code>'s <code data-x="dom-AudioTrack-kind">kind</code> and <code>VideoTrack</code>'s <code data-x="dom-VideoTrack-kind">kind</code></caption>
<thead>
<tr>
<th>Category
<th>Definition
<th>Applies to...</th>
<th>Examples
<tbody>
<tr>
<td>"<dfn><code data-x="value-track-kind-alternate">alternative</code></dfn>"
<td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
<td>Audio and video.
<td>Ogg: "audio/alternate" or "video/alternate"; DASH: "alternate" without "main" and "commentary" roles, and, for audio, without the "dub" role (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-caption">captions</code></dfn>"
<td>A version of the main video track with captions burnt in. (For legacy content; new content would use text tracks.)
<td>Video only.
<td>DASH: "caption" and "main" roles together (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-descriptions">descriptions</code></dfn>"
<td>An audio description of a video track.
<td>Audio only.
<td>Ogg: "audio/audiodesc".
<tr>
<td>"<dfn><code data-x="value-track-kind-main">main</code></dfn>"
<td>The primary audio or video track.
<td>Audio and video.
<td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set; DASH: "main" role without "caption", "subtitle", and "dub" roles (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-main-desc">main-desc</code></dfn>"
<td>The primary audio track, mixed with audio descriptions.
<td>Audio only.
<td>AC3 audio in MPEG-2 TS: bsmod=2 and full_svc=1. <!-- see https://www.w3.org/Bugs/Public/show_bug.cgi?id=17797#c1 -->
<tr>
<td>"<dfn><code data-x="value-track-kind-sign">sign</code></dfn>"
<td>A sign-language interpretation of an audio track.
<td>Video only.
<td>Ogg: "video/sign".
<tr>
<td>"<dfn><code data-x="value-track-kind-subtitle">subtitles</code></dfn>"
<td>A version of the main video track with subtitles burnt in. (For legacy content; new content would use text tracks.)
<td>Video only.
<td>DASH: "subtitle" and "main" roles together (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-translation">translation</code></dfn>"
<td>A translated version of the main audio track.
<td>Audio only.
<td>Ogg: "audio/dub". DASH: "dub" and "main" roles together (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-commentary">commentary</code></dfn>"
<td>Commentary on the primary audio or video track, e.g. a director's commentary.
<td>Audio and video.
<td>DASH: "commentary" role without "main" role (other roles ignored).
<tr>
<td>"<dfn><code data-x="value-track-kind-none"></code></dfn>" (empty string)
<td>No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.
<td>Audio and video.
<td>
</table>
<div w-nodev>
<p>The <code>AudioTrack</code> <dfn attribute for="AudioTrack"><code
data-x="dom-AudioTrack-label">label</code></dfn> and <code>VideoTrack</code> <dfn attribute
for="VideoTrack"><code data-x="dom-VideoTrack-label">label</code></dfn> attributes must return the
label of the track, if it has one, or the empty string otherwise. <ref>INBAND</ref></p>
<p>The <code>AudioTrack</code> <dfn attribute for="AudioTrack"><code
data-x="dom-AudioTrack-language">language</code></dfn> and <code>VideoTrack</code> <dfn attribute
for="VideoTrack"><code data-x="dom-VideoTrack-language">language</code></dfn> attributes must
return the BCP 47 language tag of the language of the track, if it has one, or the empty string
otherwise. If the user agent is not able to express that language as a BCP 47 language tag (for
example because the language information in the <span>media resource</span>'s format is a
free-form string without a defined interpretation), then the method must return the empty string,
as if the track had no language. <ref>INBAND</ref></p>
<p>The <code>AudioTrack</code> <dfn attribute for="AudioTrack"><code
data-x="dom-AudioTrack-enabled">enabled</code></dfn> attribute, on getting, must return true if
the track is currently enabled, and false otherwise. On setting, it must enable the track if the
new value is true, and disable it otherwise. (If the track is no longer in an
<code>AudioTrackList</code> object, then the track being enabled or disabled has no effect beyond
changing the value of the attribute on the <code>AudioTrack</code> object.)</p>
<p id="toggle-audio-track">Whenever an audio track in an <code>AudioTrackList</code> that was
disabled is enabled, and whenever one that was enabled is disabled, the user agent must
<span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-change">change</code> at the <code>AudioTrackList</code> object.</p>
<p>An audio track that has no data for a particular position on the <span>media timeline</span>,
or that does not exist at that position, must be interpreted as being silent at that point on the
timeline.</p>
<p>The <code>VideoTrackList</code> <dfn attribute for="VideoTrackList"><code
data-x="dom-VideoTrackList-selectedIndex">selectedIndex</code></dfn> attribute must return the
index of the currently selected track, if any. If the <code>VideoTrackList</code> object does not
currently represent any tracks, or if none of the tracks are selected, it must instead return
−1.</p>
<p>The <code>VideoTrack</code> <dfn attribute for="VideoTrack"><code
data-x="dom-VideoTrack-selected">selected</code></dfn> attribute, on getting, must return true if
the track is currently selected, and false otherwise. On setting, it must select the track if the
new value is true, and unselect it otherwise. If the track is in a <code>VideoTrackList</code>,
then all the other <code>VideoTrack</code> objects in that list must be unselected. (If the track
is no longer in a <code>VideoTrackList</code> object, then the track being selected or unselected
has no effect beyond changing the value of the attribute on the <code>VideoTrack</code>
object.)</p>
<p id="toggle-video-track">Whenever a track in a <code>VideoTrackList</code> that was previously
not selected is selected, and whenever the selected track in a <code>VideoTrackList</code> is
unselected without a new track being selected in its stead, the user agent must <span>queue a
media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-change">change</code> at the <code>VideoTrackList</code> object. This <span
data-x="concept-task">task</span> must be <span data-x="queue an element task">queued</span>
before the <span data-x="concept-task">task</span> that fires the <code
data-x="event-media-resize">resize</code> event, if any.</p>
<p>A video track that has no data for a particular position on the <span>media timeline</span>
must be interpreted as being <span>transparent black</span> at that point on the timeline, with
the same dimensions as the last frame before that position, or, if the position is before all the
data for that track, the same dimensions as the first frame for that track. A track that does not
exist at all at the current position must be treated as if it existed but had no data.</p>
<p class="example">For instance, if a video has a track that is only introduced after one hour of
playback, and the user selects that track then goes back to the start, then the user agent will
act as if that track started at the start of the <span>media resource</span> but was simply
transparent until one hour in.</p>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported, as <span>event handler IDL attributes</span>,
by all objects implementing the <code>AudioTrackList</code> and <code>VideoTrackList</code>
interfaces:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="AudioTrackList,VideoTrackList"><code data-x="handler-TrackList-onchange">onchange</code></dfn> <td> <code data-x="event-media-change">change</code>
<tr><td><dfn attribute for="AudioTrackList,VideoTrackList"><code data-x="handler-TrackList-onaddtrack">onaddtrack</code></dfn> <td> <code data-x="event-media-addtrack">addtrack</code>
<tr><td><dfn attribute for="AudioTrackList,VideoTrackList"><code data-x="handler-TrackList-onremovetrack">onremovetrack</code></dfn> <td> <code data-x="event-media-removetrack">removetrack</code>
</table>
<!-- v2 should also fire an event when the list changes (but note that that should be on the media element event task source) -->
</div>
<h6>Selecting specific audio and video tracks declaratively</h6>
<p>The <code data-x="dom-media-audioTracks">audioTracks</code> and <code
data-x="dom-media-videoTracks">videoTracks</code> attributes allow scripts to select which track
should play, but it is also possible to select specific tracks declaratively, by specifying
particular tracks in the <span data-x="concept-url-fragment">fragment</span> of the
<span>URL</span> of the <span>media resource</span>. The format of the <span
data-x="concept-url-fragment">fragment</span> depends on the <span>MIME type</span> of the
<span>media resource</span>. <ref>RFC2046</ref> <ref>URL</ref></p>
<div class="example">
<p>In this example, a video that uses a format that supports <span>media fragment syntax</span>
is embedded in such a way that the alternative angles labeled "Alternative" are enabled instead
of the default video track.</p>
<pre><code class="html"><video src="myvideo#track=Alternative"></video></code></pre>
</div>
<h5>Timed text tracks</h5>
<h6>Text track model</h6>
<p>A <span>media element</span> can have a group of associated <dfn data-x="text track">text
tracks</dfn>, known as the <span>media element</span>'s <dfn>list of text tracks</dfn>. The <span
data-x="text track">text tracks</span> are sorted as follows:</p>
<ol>
<li><p>The <span data-x="text track">text tracks</span> corresponding to <code>track</code>
element children of the <span>media element</span>, in <span>tree order</span>.</p></li>
<li><p>Any <span data-x="text track">text tracks</span> added using the <code
data-x="dom-media-addTextTrack">addTextTrack()</code> method, in the order they were added,
oldest first.</p></li>
<li><p>Any <span data-x="media-resource-specific text track">media-resource-specific text
tracks</span> (<span data-x="text track">text tracks</span> corresponding to data in the
<span>media resource</span>), in the order defined by the <span>media resource</span>'s format
specification.</p></li>
</ol>
<p>A <span>text track</span> consists of:</p>
<dl>
<dt><dfn data-x="text track kind">The kind of text track</dfn>
<dd>
<p>This decides how the track is handled by the user agent. The kind is represented by a string.
The possible strings are:</p>
<ul class="brief">
<li><dfn><code data-x="dom-TextTrack-kind-subtitles">subtitles</code></dfn>
<li><dfn><code data-x="dom-TextTrack-kind-captions">captions</code></dfn>
<li><dfn><code data-x="dom-TextTrack-kind-descriptions">descriptions</code></dfn>
<li><dfn><code data-x="dom-TextTrack-kind-chapters">chapters</code></dfn>
<li><dfn><code data-x="dom-TextTrack-kind-metadata">metadata</code></dfn>
</ul>
<p>The <span data-x="text track kind">kind of track</span> can change dynamically, in the case of
a <span>text track</span> corresponding to a <code>track</code> element.</p>
</dd>
<dt><dfn data-x="text track label">A label</dfn>
<dd>
<p>This is a human-readable string intended to identify the track for the user.</p>
<p>The <span data-x="text track label">label of a track</span> can change dynamically, in the
case of a <span>text track</span> corresponding to a <code>track</code> element.</p>
<p>When a <span>text track label</span> is the empty string, the user agent should automatically
generate an appropriate label from the text track's other properties (e.g. the kind of text
track and the text track's language) for use in its user interface. This automatically-generated
label is not exposed in the API.</p>
</dd>
<dt><dfn data-x="text track in-band metadata track dispatch type">An in-band metadata track dispatch type</dfn>
<dd>
<p>This is a string extracted from the <span>media resource</span> specifically for in-band
metadata tracks to enable such tracks to be dispatched to different scripts in the document.</p>
<p class="example">For example, a traditional TV station broadcast streamed on the web and
augmented with web-specific interactive features could include text tracks with metadata for ad
targeting, trivia game data during game shows, player states during sports games, recipe
information during food programs, and so forth. As each program starts and ends, new tracks
might be added or removed from the stream, and as each one is added, the user agent could bind
them to dedicated script modules using the value of this attribute.</p>
<p>Other than for in-band metadata text tracks, the <span data-x="text track in-band metadata
track dispatch type">in-band metadata track dispatch type</span> is the empty string. How this
value is populated for different media formats is described in <span>steps to expose a
media-resource-specific text track</span>.</p>
</dd>
<dt><dfn data-x="text track language">A language</dfn>
<dd>
<p>This is a string (a BCP 47 language tag) representing the language of the text track's cues.
<ref>BCP47</ref></p>
<p>The <span data-x="text track language">language of a text track</span> can change dynamically,
in the case of a <span>text track</span> corresponding to a <code>track</code> element.</p>
</dd>
<dt><dfn data-x="text track readiness state">A readiness state</dfn>
<dd>
<p>One of the following:</p>
<dl>
<dt><dfn data-x="text track not loaded">Not loaded</dfn>
<dd>
<p>Indicates that the text track's cues have not been obtained.</p>
</dd>
<dt><dfn data-x="text track loading">Loading</dfn>
<dd>
<p>Indicates that the text track is loading and there have been no fatal errors encountered so
far. Further cues might still be added to the track by the parser.</p>
</dd>
<dt><dfn data-x="text track loaded">Loaded</dfn>
<dd>
<p>Indicates that the text track has been loaded with no fatal errors.</p>
</dd>
<dt><dfn data-x="text track failed to load">Failed to load</dfn>
<dd>
<p>Indicates that the text track was enabled, but when the user agent attempted to obtain it,
this failed in some way (e.g., <span>URL</span> could not be <span data-x="encoding-parsing a
URL">parsed</span>, network error, unknown text track format). Some or all of the cues are
likely missing and will not be obtained.</p>
</dd>
</dl>
<p>The <span data-x="text track readiness state">readiness state</span> of a <span>text
track</span> changes dynamically as the track is obtained.</p>
</dd>
<dt><dfn data-x="text track mode">A mode</dfn>
<dd>
<p>One of the following:</p>
<dl>
<dt><dfn data-x="text track disabled">Disabled</dfn>
<dd>
<p>Indicates that the text track is not active. Other than for the purposes of exposing the
track in the DOM, the user agent is ignoring the text track. No cues are active, no events are
fired, and the user agent will not attempt to obtain the track's cues.</p>
</dd>
<dt><dfn data-x="text track hidden">Hidden</dfn>
<dd>
<p>Indicates that the text track is active, but that the user agent is not actively displaying
the cues. If no attempt has yet been made to obtain the track's cues, the user agent will
perform such an attempt momentarily. The user agent is maintaining a list of which cues are
active, and events are being fired accordingly.</p>
</dd>
<dt><dfn data-x="text track showing">Showing</dfn>
<dd>
<p>Indicates that the text track is active. If no attempt has yet been made to obtain the
track's cues, the user agent will perform such an attempt momentarily. The user agent is
maintaining a list of which cues are active, and events are being fired accordingly. In
addition, for text tracks whose <span data-x="text track kind">kind</span> is <code
data-x="dom-TextTrack-kind-subtitles">subtitles</code> or <code
data-x="dom-TextTrack-kind-captions">captions</code>, the cues are being overlaid on the video
as appropriate; for text tracks whose <span data-x="text track kind">kind</span> is <code
data-x="dom-TextTrack-kind-descriptions">descriptions</code>, the user agent is making the
cues available to the user in a non-visual fashion; and for text tracks whose <span
data-x="text track kind">kind</span> is <code
data-x="dom-TextTrack-kind-chapters">chapters</code>, the user agent is making available to
the user a mechanism by which the user can navigate to any point in the <span>media
resource</span> by selecting a cue.</p>
</dd>
</dl>
</dd>
<dt><dfn data-x="text track list of cues">A list of zero or more cues</dfn>
<dd>
<p>A list of <span data-x="text track cue">text track cues</span>, along with <dfn>rules for
updating the text track rendering</dfn>. For example, for WebVTT, the <span>rules for updating
the display of WebVTT text tracks</span>. <ref>WEBVTT</ref> </p>
<p>The <span data-x="text track list of cues">list of cues of a text track</span> can change
dynamically, either because the <span>text track</span> has <span data-x="text track not
loaded">not yet been loaded</span> or is still <span data-x="text track loading">loading</span>,
or due to DOM manipulation.</p>
</dd>
</dl>
<p>Each <span>text track</span> has a corresponding <code>TextTrack</code> object.</p>
<hr>
<p>Each <span>media element</span> has a <dfn>list of pending text tracks</dfn>, which must
initially be empty, a <dfn>blocked-on-parser</dfn> flag, which must initially be false, and a
<dfn>did-perform-automatic-track-selection</dfn> flag, which must also initially be false.</p>
<p>When the user agent is required to <dfn>populate the list of pending text tracks</dfn> of a
<span>media element</span>, the user agent must add to the element's <span>list of pending text
tracks</span> each <span>text track</span> in the element's <span>list of text tracks</span> whose
<span>text track mode</span> is not <span data-x="text track disabled">disabled</span> and whose
<span>text track readiness state</span> is <!--either <span data-x="text track not loaded">not
loaded</span> or [there can't be any in the 'not loaded' state that are not 'disabled']--> <span
data-x="text track loading">loading</span>.</p>
<p>Whenever a <code>track</code> element's parent node changes, the user agent must remove the
corresponding <span>text track</span> from any <span>list of pending text tracks</span> that it is
in.</p>
<p>Whenever a <span>text track</span>'s <span>text track readiness state</span> changes to either
<span data-x="text track loaded">loaded</span> or <span data-x="text track failed to load">failed to
load</span>, the user agent must remove it from any <span>list of pending text tracks</span> that
it is in.</p>
<p>When a <span>media element</span> is created by an <span>HTML parser</span> or <span>XML
parser</span>, the user agent must set the element's <span>blocked-on-parser</span> flag to true.
When a <span>media element</span> is popped off the <span>stack of open elements</span> of an
<span>HTML parser</span> or <span>XML parser</span>, the user agent must <span>honor user
preferences for automatic text track selection</span>, <span>populate the list of pending text
tracks</span>, and set the element's <span>blocked-on-parser</span> flag to false.</p>
<p>The <span data-x="text track">text tracks</span> of a <span>media element</span> are <dfn
data-x="the text tracks are ready">ready</dfn> when both the element's <span>list of pending text
tracks</span> is empty and the element's <span>blocked-on-parser</span> flag is false.</p>
<p>Each <span>media element</span> has a <dfn>pending text track change notification flag</dfn>,
which must initially be unset.</p>
<p>Whenever a <span>text track</span> that is in a <span>media element</span>'s <span>list of text
tracks</span> has its <span>text track mode</span> change value, the user agent must run the
following steps for the <span>media element</span>:</p>
<ol>
<li><p>If the <span>media element</span>'s <span>pending text track change notification
flag</span> is set, return.</p></li>
<li><p>Set the <span>media element</span>'s <span>pending text track change notification
flag</span>.</p></li>
<li>
<p><span>Queue a media element task</span> given the <span>media element</span> to run these
steps:</p>
<ol>
<li><p>Unset the <span>media element</span>'s <span>pending text track change notification
flag</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-change">change</code> at the <span>media element</span>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code>
object.</p></li>
</ol>
</li>
<li><p>If the <span>media element</span>'s <span>show poster flag</span> is not set, run the
<i data-x="time marches on">time marches on</i> steps.</p></li>
</ol>
<p>The <span>task source</span> for the <span data-x="concept-task">tasks</span> listed in this
section is the <span>DOM manipulation task source</span>.</p>
<hr>
<p>A <dfn>text track cue</dfn> is the unit of time-sensitive data in a <span>text track</span>,
corresponding for instance for subtitles and captions to the text that appears at a particular
time and disappears at another time.</p>
<p>Each <span>text track cue</span> consists of:</p>
<dl>
<dt><dfn data-x="text track cue identifier">An identifier</dfn>
<dd>
<p>An arbitrary string.</p>
</dd>
<dt><dfn data-x="text track cue start time">A start time</dfn>
<dd>
<p>The time, in seconds and fractions of a second, that describes the beginning of the range of
the <span>media data</span> to which the cue applies.</p>
</dd>
<dt><dfn data-x="text track cue end time">An end time</dfn>
<dd>
<p>The time, in seconds and fractions of a second, that describes the end of the range of the
<span>media data</span> to which the cue applies, or positive Infinity for an <span>unbounded
text track cue</span>.</p>
</dd>
<dt><dfn data-x="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
<dd>
<p>A boolean indicating whether playback of the <span>media resource</span> is to pause when the
end of the range to which the cue applies is reached.</p>
</dd>
<dt>Some additional format-specific data</dt>
<dd>
<p>Additional fields, as needed for the format, including the actual data of the cue. For
example, WebVTT has a <span>text track cue writing direction</span> and so forth.
<ref>WEBVTT</ref></p>
</dd>
</dl>
<p>An <dfn data-x="unbounded text track cue">unbounded text track cue</dfn> is a text track cue
with a <span>text track cue end time</span> set to positive Infinity. An active <span>unbounded
text track cue</span> cannot become inactive through the usual monotonic increase of the
<span>current playback position</span> during normal playback (e.g. a metadata cue for a chapter in a live
event with no announced end time.)</p>
<p class="note">The <span>text track cue start time</span> and <span>text track cue end
time</span> can be negative. (The <span>current playback position</span> can never be negative,
though, so cues entirely before time zero cannot be active.)</p>
<p>Each <span>text track cue</span> has a corresponding <code>TextTrackCue</code> object (or more
specifically, an object that inherits from <code>TextTrackCue</code> — for example, WebVTT
cues use the <code>VTTCue</code> interface). A <span>text track cue</span>'s in-memory
representation can be dynamically changed through this <code>TextTrackCue</code> API.
<ref>WEBVTT</ref></p>
<p>A <span>text track cue</span> is associated with <span>rules for updating the text track
rendering</span>, as defined by the specification for the specific kind of <span>text track
cue</span>. These rules are used specifically when the object representing the cue is added to a
<code>TextTrack</code> object using the <code data-x="dom-TextTrack-addCue">addCue()</code>
method.</p>
<p>In addition, each <span>text track cue</span> has two pieces of dynamic information:</p>
<dl>
<dt>The <dfn data-x="text track cue active flag">active flag</dfn>
<dd>
<p>This flag must be initially unset. The flag is used to ensure events are fired appropriately
when the cue becomes active or inactive, and to make sure the right cues are rendered.</p>
<p>The user agent must synchronously unset this flag whenever the <span>text track cue</span> is
removed from its <span>text track</span>'s <span>text track list of cues</span>; whenever the
<span>text track</span> itself is removed from its <span>media element</span>'s <span>list of
text tracks</span> or has its <span>text track mode</span> changed to <span data-x="text track
disabled">disabled</span>; and whenever the <span>media element</span>'s <code
data-x="dom-media-readyState">readyState</code> is changed back to <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>. When the flag is unset in this way for one
or more cues in <span data-x="text track">text tracks</span> that were <span data-x="text track
showing">showing</span> prior to the relevant incident, the user agent must, after having unset
the flag for all the affected cues, apply the <span>rules for updating the text track
rendering</span> of those <span data-x="text track">text tracks</span>. For example, for <span
data-x="text track">text tracks</span> based on WebVTT, the <span>rules for updating the display
of WebVTT text tracks</span>. <ref>WEBVTT</ref></p> </dd>
<dt>The <dfn data-x="text track cue display state">display state</dfn>
<dd>
<p>This is used as part of the rendering model, to keep cues in a consistent position. It must
initially be empty. Whenever the <span>text track cue active flag</span> is unset, the user
agent must empty the <span>text track cue display state</span>.</p>
</dd>
</dl>
<p>The <span data-x="text track cue">text track cues</span> of a <span>media element</span>'s
<span data-x="text track">text tracks</span> are ordered relative to each other in the <dfn>text
track cue order</dfn>, which is determined as follows: first group the <span data-x="text track
cue">cues</span> by their <span>text track</span>, with the groups being sorted in the same order
as their <span data-x="text track">text tracks</span> appear in the <span>media element</span>'s
<span>list of text tracks</span>; then, within each group, <span data-x="text track
cue">cues</span> must be sorted by their <span data-x="text track cue start time">start
time</span>, earliest first; then, any <span data-x="text track cue">cues</span> with the same
<span data-x="text track cue start time">start time</span> must be sorted by their <span
data-x="text track cue end time">end time</span>, latest first; and finally, any <span
data-x="text track cue">cues</span> with identical <span data-x="text track cue end time">end
times</span> must be sorted in the order they were last added to their respective <span>text track
list of cues</span>, oldest first (so e.g. for cues from a WebVTT file, that would initially be
the order in which the cues were listed in the file). <ref>WEBVTT</ref></p>
<h6>Sourcing in-band text tracks</h6>
<p>A <dfn>media-resource-specific text track</dfn> is a <span>text track</span> that corresponds
to data found in the <span>media resource</span>.</p>
<div w-nodev>
<p>Rules for processing and rendering such data are defined by the relevant specifications, e.g.
the specification of the video format if the <span>media resource</span> is a video. Details for
some legacy formats can be found in <cite>Sourcing In-band Media Resource Tracks from Media
Containers into HTML</cite>. <ref>INBAND</ref></p>
<p>When a <span>media resource</span> contains data that the user agent recognizes and supports as
being equivalent to a <span>text track</span>, the user agent <a
href="#found-a-media-resource-specific-timed-track">runs</a> the <dfn>steps to expose a
media-resource-specific text track</dfn> with the relevant data, as follows.</p>
<!-- this runs synchronously from a fetch task -->
<ol>
<li><p>Associate the relevant data with a new <span>text track</span> and its corresponding new
<code>TextTrack</code> object. The <span>text track</span> is a <span>media-resource-specific
text track</span>.</p></li>
<li><p>Set the new <span>text track</span>'s <span data-x="text track kind">kind</span>, <span
data-x="text track label">label</span>, and <span data-x="text track language">language</span>
based on the semantics of the relevant data, as defined by the relevant specification. If there
is no label in that data, then the <span data-x="text track label">label</span> must be set to the
empty string.</p></li>
<li><p>Associate the <span>text track list of cues</span> with the <span>rules for updating the
text track rendering</span> appropriate for the format in question.</p>
<li>
<p>If the new <span>text track</span>'s <span data-x="text track kind">kind</span> is <code
data-x="dom-TextTrack-kind-chapters">chapters</code> or <code
data-x="dom-TextTrack-kind-metadata">metadata</code>, then set the <span>text track in-band
metadata track dispatch type</span> as follows, based on the type of the <span>media
resource</span>:</p>
<dl class="switch">
<dt>If the <span>media resource</span> is an Ogg file</dt>
<dd>The <span>text track in-band metadata track dispatch type</span> must be set to the value
of the Name header field. <ref>OGGSKELETONHEADERS</ref></dd>
<dt>If the <span>media resource</span> is a WebM file</dt>
<dd>The <span>text track in-band metadata track dispatch type</span> must be set to the value
of the <code data-x="">CodecID</code> element. <ref>WEBMCG</ref></dd>
<dt>If the <span>media resource</span> is an MPEG-2 file</dt>
<dd>Let <var>stream type</var> be the value of the "stream_type" field describing the text
track's type in the file's program map section, interpreted as an 8-bit unsigned integer. Let
<var>length</var> be the value of the "ES_info_length" field for the track in the same part of
the program map section, interpreted as an integer as defined by <cite>Generic coding of moving
pictures and associated audio information</cite>. Let <var>descriptor bytes</var> be the
<var>length</var> bytes following the "ES_info_length" field. The <span>text track in-band
metadata track dispatch type</span> must be set to the concatenation of the <var>stream
type</var> byte and the zero or more <var>descriptor bytes</var> bytes, expressed in
hexadecimal using <span data-x="ASCII upper hex digit">ASCII upper hex digits</span>.
<ref>MPEG2</ref>
</dd>
<dt>If the <span>media resource</span> is an MPEG-4 file</dt>
<dd>Let the
first <code data-x="">stsd</code> box of the
first <code data-x="">stbl</code> box of the
first <code data-x="">minf</code> box of the
first <code data-x="">mdia</code> box of the
<span>text track</span>'s <code data-x="">trak</code> box in the
first <code data-x="">moov</code> box
of the file be the <i>stsd box</i>, if any.
If the file has no <i>stsd box</i>, or if the <i>stsd box</i> has neither a <code
data-x="">mett</code> box nor a <code data-x="">metx</code> box, then the <span>text track
in-band metadata track dispatch type</span> must be set to the empty string.
Otherwise, if the <i>stsd box</i> has a <code data-x="">mett</code> box then the <span>text
track in-band metadata track dispatch type</span> must be set to the concatenation of the
string "<code data-x="">mett</code>", a U+0020 SPACE character, and the value of the first <code
data-x="">mime_format</code> field of the first <code data-x="">mett</code> box of the <i>stsd
box</i>, or the empty string if that field is absent in that box.
Otherwise, if the <i>stsd box</i> has no <code data-x="">mett</code> box but has a <code
data-x="">metx</code> box then the <span>text track in-band metadata track dispatch type</span>
must be set to the concatenation of the string "<code data-x="">metx</code>", a U+0020 SPACE
character, and the value of the first <code data-x="">namespace</code> field of the first <code
data-x="">metx</code> box of the <i>stsd box</i>, or the empty string if that field is absent in
that box.
<ref>MPEG4</ref>
</dd>
</dl>
</li>
<li><p>Populate the new <span>text track</span>'s <span data-x="text track list of cues">list of
cues</span> with the cues parsed so far, following the <span>guidelines for exposing
cues</span>, and begin updating it dynamically as necessary.</p></li>
<li><p>Set the new <span>text track</span>'s <span data-x="text track readiness state">readiness
state</span> to <span data-x="text track loaded">loaded</span>.</p></li> <!-- otherwise, you'll
have to load the whole media file just to start playing the first frame... -->
<li><p>Set the new <span>text track</span>'s <span data-x="text track mode">mode</span> to the
mode consistent with the user's preferences and the requirements of the relevant specification
for the data.</p>
<p class="note">For instance, if there are no other active subtitles, and this is a forced
subtitle track (a subtitle track giving subtitles in the audio track's primary language, but
only for audio that is actually in another language), then those subtitles might be activated
here.</p>
</li> <!-- it's too late to apply the normal heuristic, so we don't bother -->
<li><p>Add the new <span>text track</span> to the <span>media element</span>'s <span>list of text
tracks</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at the <span>media element</span>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code>
attribute initialized to the <span>text track</span>'s <code>TextTrack</code> object.</p></li>
</ol>
<!-- removetrack: we don't currently ever remove an in-band text track, because it might have been
manipulated or might be about to be manipulated. If we made in-band text tracks readonly, we could
probably get away with cleaning them up when they fall into the time before the earliest possible
position and are known to be over and done with. -->
<!-- if, after in-band text tracks have been found, there's no out-of-band text tracks, then apply
user prefs? -->
</div>
<div w-nodev>
<h6>Sourcing out-of-band text tracks</h6>
<p>When a <code>track</code> element is created, it must be associated with a new <span>text
track</span> (with its value set as defined below) and its corresponding new
<code>TextTrack</code> object.</p>
<p>The <span>text track kind</span> is determined from the state of the element's <code
data-x="attr-track-kind">kind</code> attribute according to the following table; for a state given
in a cell of the first column, the <span data-x="text track kind">kind</span> is the string given
in the second column:</p>
<table>
<thead>
<tr>
<th>State
<th>String
<tbody>
<tr>
<td><span data-x="attr-track-kind-subtitles">Subtitles</span>
<td><code data-x="dom-TextTrack-kind-subtitles">subtitles</code>
<tr>
<td><span data-x="attr-track-kind-captions">Captions</span>
<td><code data-x="dom-TextTrack-kind-captions">captions</code>
<tr>
<td><span data-x="attr-track-kind-descriptions">Descriptions</span>
<td><code data-x="dom-TextTrack-kind-descriptions">descriptions</code>
<tr>
<td><span data-x="attr-track-kind-chapters">Chapters metadata</span>
<td><code data-x="dom-TextTrack-kind-chapters">chapters</code>
<tr>
<td><span data-x="attr-track-kind-metadata">Metadata</span>
<td><code data-x="dom-TextTrack-kind-metadata">metadata</code>
</table>
<p>The <span>text track label</span> is the element's <span>track label</span>.</p>
<p>The <span>text track language</span> is the element's <span>track language</span>, if any, or
the empty string otherwise.</p>
<p>As the <code data-x="attr-track-kind">kind</code>, <code data-x="attr-track-label">label</code>,
and <code data-x="attr-track-srclang">srclang</code> attributes are set, changed, or removed, the
<span>text track</span> must update accordingly, as per the definitions above.</p>
<p class="note">Changes to the <span>track URL</span> are handled in the algorithm below.</p>
<p>The <span>text track readiness state</span> is initially <span data-x="text track not
loaded">not loaded</span>, and the <span>text track mode</span> is initially <span data-x="text
track disabled">disabled</span>.</p>
<p>The <span>text track list of cues</span> is initially empty. It is dynamically modified when
the referenced file is parsed. Associated with the list are the <span>rules for updating the text
track rendering</span> appropriate for the format in question; for WebVTT, this is the <span>rules
for updating the display of WebVTT text tracks</span>. <ref>WEBVTT</ref></p>
<p>When a <code>track</code> element's parent element changes and the new parent is a <span>media
element</span>, then the user agent must add the <code>track</code> element's corresponding
<span>text track</span> to the <span>media element</span>'s <span>list of text tracks</span>, and
then <span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at the <span>media element</span>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code> attribute
initialized to the <span>text track</span>'s <code>TextTrack</code> object.</p>
<p>When a <code>track</code> element's parent element changes and the old parent was a <span>media
element</span>, then the user agent must remove the <code>track</code> element's corresponding
<span>text track</span> from the <span>media element</span>'s <span>list of text tracks</span>,
and then <span>queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-removetrack">removetrack</code> at the <span>media element</span>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code> attribute
initialized to the <span>text track</span>'s <code>TextTrack</code> object.</p>
<!-- removetrack -->
<hr>
<p>When a <span>text track</span> corresponding to a <code>track</code> element is added to a
<span>media element</span>'s <span>list of text tracks</span>, the user agent must <span>queue a
media element task</span> given the <span>media element</span> to run the following steps for the
<span>media element</span>:</p>
<ol>
<li><p>If the element's <span>blocked-on-parser</span> flag is true, then return.</p></li>
<li><p>If the element's <span>did-perform-automatic-track-selection</span> flag is true, then
return.</p></li>
<li><p><span>Honor user preferences for automatic text track selection</span> for this
element.</p></li>
</ol>
<p>When the user agent is required to <dfn>honor user preferences for automatic text track
selection</dfn> for a <span>media element</span>, the user agent must run the following steps:</p>
<ol>
<li><p><span>Perform automatic text track selection</span> for <code
data-x="dom-TextTrack-kind-subtitles">subtitles</code> and <code
data-x="dom-TextTrack-kind-captions">captions</code>.</p></li>
<li><p><span>Perform automatic text track selection</span> for <code
data-x="dom-TextTrack-kind-descriptions">descriptions</code>.</p></li>
<li><p>If there are any <span data-x="text track">text tracks</span> in the <span>media
element</span>'s <span>list of text tracks</span> whose <span>text track kind</span> is <code
data-x="dom-TextTrack-kind-metadata">chapters</code> or <code
data-x="dom-TextTrack-kind-metadata">metadata</code> that correspond to <code>track</code>
elements with a <code data-x="attr-track-default">default</code> attribute set whose <span>text
track mode</span> is set to <span data-x="text track disabled">disabled</span>, then set the
<span>text track mode</span> of all such tracks to <span data-x="text track
hidden">hidden</span>.</p></li>
<li><p>Set the element's <span>did-perform-automatic-track-selection</span> flag to
true.</p></li>
</ol>
<p>When the steps above say to <dfn>perform automatic text track selection</dfn> for one or more
<span data-x="text track kind">text track kinds</span>, it means to run the following steps:</p>
<ol>
<li><p>Let <var>candidates</var> be a list consisting of the <span data-x="text
track">text tracks</span> in the <span>media element</span>'s <span>list of text tracks</span>
whose <span>text track kind</span> is one of the kinds that were passed to the algorithm, if any,
in the order given in the <span>list of text tracks</span>.</p></li>
<li><p>If <var>candidates</var> is empty, then return.</p></li>
<li><p>If any of the <span data-x="text track">text tracks</span> in <var>candidates</var> have a <span>text track mode</span> set to <span data-x="text track
showing">showing</span>, return.</p></li>
<li>
<p>If the user has expressed an interest in having a track from <var>candidates</var>
enabled based on its <span>text track kind</span>, <span>text track language</span>, and
<span>text track label</span>, then set its <span>text track mode</span> to <span data-x="text
track showing">showing</span><!--, and if there are any <span data-x="text track">text
tracks</span> in <var>candidates</var> that correspond to <code>track</code> elements
with a <code data-x="attr-track-default">default</code> attribute set whose <span>text track
mode</span> is set to <span data-x="text track disabled">disabled</span>, then additionally set
the <span>text track mode</span> of the first such track to <span data-x="text track
hidden">hidden</span>-->.</p> <!-- the idea behind the commented out stuff is that we still get
events and stuff: we can expect authors to forget that default doesn't mean that it'll always be
turned on, and that they'll still rely on events firing even if it doesn't show. But it is
commented out, because we can equally expect authors to expect only one track is getting events,
so we've got problems either way, and might as well go with the simpler behavior. -->
<p class="note">For example, the user could have set a browser preference to the effect of "I
want French captions whenever possible", or "If there is a subtitle track with 'Commentary' in
the title, enable it", or "If there are audio description tracks available, enable one, ideally
in Swiss German, but failing that in Standard Swiss German or Standard German".</p>
<p>Otherwise, if there are any <span data-x="text track">text tracks</span> in <var>candidates</var> that correspond to <code>track</code> elements with a <code
data-x="attr-track-default">default</code> attribute set whose <span>text track mode</span> is
set to <span data-x="text track disabled">disabled</span>, then set the <span>text track
mode</span> of the first such track to <span data-x="text track showing">showing</span>.</p>
</li>
</ol>
<p>When a <span>text track</span> corresponding to a <code>track</code> element experiences any of
the following circumstances, the user agent must <span>start the <code>track</code> processing
model</span> for that <span>text track</span> and its <code>track</code> element:
<ul>
<li>The <code>track</code> element is created.</li>
<li>The <span>text track</span> has its <span>text track mode</span> changed.</li>
<li>The <code>track</code> element's parent element changes and the new parent is a <span>media
element</span>.</li>
</ul>
<p>When a user agent is to <dfn>start the <code>track</code> processing model</dfn> for a
<span>text track</span> and its <code>track</code> element, it must run the following algorithm.
This algorithm interacts closely with the <span>event loop</span> mechanism; in particular, it has
a <span>synchronous section</span> (which is triggered as part of the <span>event loop</span>
algorithm). The steps in that section are marked with ⌛.</p>
<ol>
<li><p>If another occurrence of this algorithm is already running for this <span>text
track</span> and its <code>track</code> element, return, letting that other algorithm
take care of this element.</p></li>
<li><p>If the <span>text track</span>'s <span>text track mode</span> is not set to one of <span
data-x="text track hidden">hidden</span> or <span data-x="text track showing">showing</span>,
then return.</p></li>
<li><p>If the <span>text track</span>'s <code>track</code> element does not have a <span>media
element</span> as a parent, return.</p></li>
<li><p>Run the remainder of these steps <span>in parallel</span>, allowing whatever caused these steps to
run to continue.</p></li>
<li><p><i>Top</i>: <span>Await a stable state</span>. The <span>synchronous section</span>
consists of the following steps. (The steps in the <span>synchronous section</span> are marked
with ⌛.)</p></li>
<li><p>⌛ Set the <span>text track readiness state</span> to <span data-x="text track
loading">loading</span>.</p></li>
<li><p>⌛ Let <var>URL</var> be the <span>track URL</span> of the
<code>track</code> element.</p></li>
<li><p>⌛ If the <code>track</code> element's parent is a <span>media element</span> then
let <var>corsAttributeState</var> be the state of the parent <span>media element</span>'s <code
data-x="attr-media-crossorigin">crossorigin</code> content attribute. Otherwise, let
<var>corsAttributeState</var> be <span data-x="attr-crossorigin-none">No CORS</span>.</p></li>
<li><p>End the <span>synchronous section</span>, continuing the remaining steps
<span>in parallel</span>.</p></li>
<li>
<p>If <var>URL</var> is not the empty string, then:
<ol>
<li><p>Let <var>request</var> be the result of <span
data-x="create a potential-CORS request">creating a potential-CORS request</span> given
<var>URL</var>, "<code data-x="">track</code>", and <var>corsAttributeState</var>, and with the
<i>same-origin fallback flag</i> set.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to the
<code>track</code> element's <span>node document</span>'s <span>relevant settings
object</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to "<code data-x="">track</code>".</p></li>
<li><p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var>.</p></li>
</ol>
<p>The <span data-x="concept-task">tasks</span> <span data-x="queue a task">queued</span> by the
fetching algorithm on the <span>networking task source</span> to process the data as it is being
fetched must <!--<span data-x="Content-Type sniffing">-->determine the <!--computed--> type of
the resource<!--</span>-->. If the <!--computed--> type of the resource is not a supported text
track format, the load will fail, as described below. Otherwise, the resource's data must be
passed to the appropriate parser (e.g., the <span>WebVTT parser</span><!-- if the file starts
with the "<code data-x="">WEBVTT</code>" signature-->) as it is received, with the <span>text
track list of cues</span> being used for that parser's output. <ref>WEBVTT</ref></p><!-- see
also critical block below, and the word "computed" in the paragraph after that -->
<p class="note">The appropriate parser will incrementally update the <span>text track list of
cues</span> during these <span>networking task
source</span> <span data-x="concept-task">tasks</span>, as each such task is
run with whatever data has been received from the network).</p>
<p class="critical">This specification does not currently say whether or how to check the MIME
types of text tracks, or whether or how to perform file type sniffing using the actual file
data. Implementers differ in their intentions on this matter and it is therefore unclear what
the right solution is. In the absence of any requirement here, the HTTP specifications' strict
requirement to follow the Content-Type header prevails ("Content-Type specifies the media type
of the underlying data." ... "If and only if the media type is not given by a Content-Type
field, the recipient MAY attempt to guess the media type via inspection of its content
and<!---->/<!---->or the name extension(s) of the URI used to identify the resource.").</p>
<p>If fetching fails for any reason (network error, the server returns an error code, CORS
fails, etc.), or if <var>URL</var> is the empty string, then <span>queue an element task</span>
on the <span>DOM manipulation task source</span> given the <span>media element</span> to first
change the <span>text track readiness state</span> to <span data-x="text track failed to
load">failed to load</span> and then <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-track-error">error</code> at the <code>track</code> element.</p>
<!-- can't be the media element one, since there might not be a media element by this point -->
<p>If fetching does not fail, but the <!--computed--> type of the resource is not a supported
text track format, or the file was not successfully processed (e.g., the format in question is
an XML format and the file contained a well-formedness error that <cite>XML</cite> requires be
detected and reported to the application), then the <span data-x="concept-task">task</span> that
is <span data-x="queue an element task">queued</span> on the <span>networking task source</span>
in which the aforementioned problem is found must change the <span>text track readiness
state</span> to <span data-x="text track failed to load">failed to load</span> and <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-track-error">error</code> at the <code>track</code> element.</p>
<p>If fetching does not fail, and the file was successfully processed, then the final <span
data-x="concept-task">task</span> that is <span data-x="queue an element task">queued</span> by
the <span>networking task source</span>, after it has finished parsing the data, must change the
<span>text track readiness state</span> to <span data-x="text track loaded">loaded</span>, and
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-track-load">load</code> at the <code>track</code> element.</p>
<p>If, while fetching is ongoing, either:</p>
<ul>
<li>the <span>track URL</span> changes so that it is no longer equal to <var>URL</var>, while the <span>text track mode</span> is set to <span data-x="text track
hidden">hidden</span> or <span data-x="text track showing">showing</span>; or</li>
<li>the <span>text track mode</span> changes to <span data-x="text track hidden">hidden</span>
or <span data-x="text track showing">showing</span>, while the <span>track URL</span> is not
equal to <var>URL</var></li>
</ul>
<p>...then the user agent must abort <span data-x="concept-fetch">fetching</span>, discarding
any pending <span data-x="concept-task">tasks</span> generated by that algorithm (and in
particular, not adding any cues to the <span>text track list of cues</span> after the moment the
URL changed), and then <span>queue an element task</span> on the <span>DOM manipulation task
source</span> given the <code>track</code> element that first changes the <span>text track
readiness state</span> to <span data-x="text track failed to load">failed to load</span> and
then <span data-x="concept-event-fire">fires an event</span> named <code
data-x="event-track-error">error</code> at the <code>track</code> element. <!-- can't be the
media element one, since there might not be a media element by this point --></p>
</li>
<li><p>Wait until the <span>text track readiness state</span> is no longer set to <span
data-x="text track loading">loading</span>.</p></li>
<li><p>Wait until the <span>track URL</span> is no longer equal to <var>URL</var>, at
the same time as the <span>text track mode</span> is set to <span data-x="text track
hidden">hidden</span> or <span data-x="text track showing">showing</span>.</p></li>
<li><p>Jump to the step labeled <i>top</i>.</p></li>
</ol>
<p>Whenever a <code>track</code> element has its <code data-x="attr-track-src">src</code> attribute
set, changed, or removed, the user agent must <span>immediately</span> empty the element's <span>text
track</span>'s <span>text track list of cues</span>. (This also causes the algorithm above to stop
adding cues from the resource being obtained using the previously given URL, if any.)</p>
</div>
<div w-nodev>
<h6><dfn>Guidelines for exposing cues</dfn> in various formats as <span data-x="text track
cue">text track cues</span></h6>
<p>How a specific format's text track cues are to be interpreted for the purposes of processing by
an HTML user agent is defined by that format. In the absence of such a specification, this section
provides some constraints within which implementations can attempt to consistently expose such
formats.</p>
<p>To support the <span>text track</span> model of HTML, each unit of timed data is converted to a
<span>text track cue</span>. Where the mapping of the format's features to the aspects of a
<span>text track cue</span> as defined in this specification are not defined, implementations must
ensure that the mapping is consistent with the definitions of the aspects of a <span>text track
cue</span> as defined above, as well as with the following constraints:</p>
<dl>
<dt>The <span>text track cue identifier</span>
<dd>
<p>Should be set to the empty string if the format has no obvious analogue to a per-cue
identifier.</p>
</dd>
<dt>The <span>text track cue pause-on-exit flag</span>
<dd>
<p>Should be set to false.</p>
</dd>
</dl>
</div>
<h6>Text track API</h6>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TextTrackList</dfn> : <span>EventTarget</span> {
readonly attribute unsigned long <span data-x="dom-TextTrackList-length">length</span>;
<a href="#dom-texttracklist-item">getter</a> <span>TextTrack</span> (unsigned long index);
<span>TextTrack</span>? <span data-x="dom-TextTrackList-getTrackById">getTrackById</span>(DOMString id);
attribute <span>EventHandler</span> <span data-x="handler-TextTrackList-onchange">onchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-TextTrackList-onaddtrack">onaddtrack</span>;
attribute <span>EventHandler</span> <span data-x="handler-TextTrackList-onremovetrack">onremovetrack</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-textTracks">textTracks</span>.<span data-x="">length</span></code></dt>
<dd>
<p>Returns the number of <span data-x="text track">text tracks</span> associated with the
<span>media element</span> (e.g. from <code>track</code> elements). This is the number of <span
data-x="text track">text tracks</span> in the <span>media element</span>'s <span>list of text
tracks</span>.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span data-x="dom-media-textTracks">textTracks[</span> <var>n</var> <span data-x="">]</span></code></dt>
<dd>
<p>Returns the <code>TextTrack</code> object representing the <var>n</var>th <span>text
track</span> in the <span>media element</span>'s <span>list of text tracks</span>.</p>
</dd>
<dt><code data-x=""><var>textTrack</var> = <var>media</var>.<span data-x="dom-media-textTracks">textTracks</span>.<span subdfn data-x="dom-TextTrackList-getTrackById">getTrackById</span>(<var>id</var>)</code></dt>
<dd>
<p>Returns the <code>TextTrack</code> object with the given identifier, or null if no track has
that identifier.</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>TextTrackList</code> object represents a dynamically updating list of <span data-x="text
track">text tracks</span> in a given order.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-textTracks">textTracks</code></dfn> attribute of <span data-x="media
element">media elements</span> must return a <code>TextTrackList</code> object representing the
<code>TextTrack</code> objects of the <span data-x="text track">text tracks</span> in the
<span>media element</span>'s <span>list of text tracks</span>, in the same order as in the
<span>list of text tracks</span>.</p>
<p>The <dfn attribute for="TextTrackList"><code
data-x="dom-TextTrackList-length">length</code></dfn> attribute of a <code>TextTrackList</code>
object must return the number of <span data-x="text track">text tracks</span> in the list
represented by the <code>TextTrackList</code> object.</p>
<p>The <span>supported property indices</span> of a <code>TextTrackList</code> object at any
instant are the numbers from zero to the number of <span data-x="text track">text tracks</span> in
the list represented by the <code>TextTrackList</code> object minus one, if any. If there are no
<span data-x="text track">text tracks</span> in the list, there are no <span>supported property
indices</span>.</p>
<p id="dom-texttracklist-item">To <span>determine the value of an indexed property</span> of a
<code>TextTrackList</code> object for a given index <var>index</var>, the user agent must return
the <var>index</var>th <span>text track</span> in the list represented by the
<code>TextTrackList</code> object.</p>
<p>The <dfn method for="TextTrackList"><code
data-x="dom-TextTrackList-getTrackById">getTrackById(<var>id</var>)</code></dfn> method must
return the first <code>TextTrack</code> in the <code>TextTrackList</code> object whose <code
data-x="dom-TextTrack-id">id</code> IDL attribute would return a value equal to the value of the
<var>id</var> argument. When no tracks match the given argument, the method must return null.</p>
</div>
<hr>
<pre><code class="idl">enum <dfn enum>TextTrackMode</dfn> {<!--
--> "<span data-x="dom-TextTrack-disabled">disabled</span>", <!--
--> "<span data-x="dom-TextTrack-hidden">hidden</span>", <!--
--> "<span data-x="dom-TextTrack-showing">showing</span>" };
enum <dfn enum>TextTrackKind</dfn> {<!--
--> "<span data-x="dom-TextTrack-kind-subtitles">subtitles</span>", <!--
--> "<span data-x="dom-TextTrack-kind-captions">captions</span>", <!--
--> "<span data-x="dom-TextTrack-kind-descriptions">descriptions</span>", <!--
--> "<span data-x="dom-TextTrack-kind-chapters">chapters</span>", <!--
--> "<span data-x="dom-TextTrack-kind-metadata">metadata</span>" };
[Exposed=Window]
interface <dfn interface>TextTrack</dfn> : <span>EventTarget</span> {
readonly attribute <span>TextTrackKind</span> <span data-x="dom-TextTrack-kind">kind</span>;
readonly attribute DOMString <span data-x="dom-TextTrack-label">label</span>;
readonly attribute DOMString <span data-x="dom-TextTrack-language">language</span>;
readonly attribute DOMString <span data-x="dom-TextTrack-id">id</span>;
readonly attribute DOMString <span data-x="dom-TextTrack-inBandMetadataTrackDispatchType">inBandMetadataTrackDispatchType</span>;
attribute <span>TextTrackMode</span> <span data-x="dom-TextTrack-mode">mode</span>;
readonly attribute <span>TextTrackCueList</span>? <span data-x="dom-TextTrack-cues">cues</span>;
readonly attribute <span>TextTrackCueList</span>? <span data-x="dom-TextTrack-activeCues">activeCues</span>;
undefined <span data-x="dom-TextTrack-addCue">addCue</span>(<span>TextTrackCue</span> cue);
undefined <span data-x="dom-TextTrack-removeCue">removeCue</span>(<span>TextTrackCue</span> cue);
attribute <span>EventHandler</span> <span data-x="handler-TextTrack-oncuechange">oncuechange</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>textTrack</var> = <var>media</var>.<span subdfn data-x="dom-media-addTextTrack">addTextTrack</span>(<var>kind</var> [, <var>label</var> [, <var>language</var> ] ])</code></dt>
<dd>
<p>Creates and returns a new <code>TextTrack</code> object, which is also added to the
<span>media element</span>'s <span>list of text tracks</span>.</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-kind">kind</span></code></dt>
<dd><p>Returns the <span>text track kind</span> string.</p></dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-label">label</span></code></dt>
<dd>
<p>Returns the <span>text track label</span>, if there is one, or the empty string otherwise
(indicating that a custom label probably needs to be generated from the other attributes of the
object if the object is exposed to the user).</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-language">language</span></code></dt>
<dd><p>Returns the <span>text track language</span> string.</p></dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-id">id</span></code></dt>
<dd>
<p>Returns the ID of the given track.</p>
<p>For in-band tracks, this is the ID that can be used with a <span
data-x="concept-url-fragment">fragment</span> if the format supports <span>media fragment
syntax</span>, and that can be used with the <code
data-x="dom-TextTrackList-getTrackById">getTrackById()</code> method.</p>
<p>For <code>TextTrack</code> objects corresponding to <code>track</code> elements, this is the
ID of the <code>track</code> element.</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-inBandMetadataTrackDispatchType">inBandMetadataTrackDispatchType</span></code></dt>
<dd><p>Returns the <span>text track in-band metadata track dispatch type</span> string.</p></dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-mode">mode</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>text track mode</span>, represented by a string from the following
list:</p>
<dl>
<dt>"<code data-x="dom-TextTrack-disabled">disabled</code>"</dt>
<dd><p>The <span>text track disabled</span> mode.</p></dd>
<dt>"<code data-x="dom-TextTrack-hidden">hidden</code>"</dt>
<dd><p>The <span>text track hidden</span> mode.</p></dd>
<dt>"<code data-x="dom-TextTrack-showing">showing</code>"</dt>
<dd><p>The <span>text track showing</span> mode.</p></dd>
</dl>
<p>Can be set, to change the mode.</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-cues">cues</span></code></dt>
<dd>
<p>Returns the <span>text track list of cues</span>, as a <code>TextTrackCueList</code>
object.</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-activeCues">activeCues</span></code></dt>
<dd>
<p>Returns the <span data-x="text track cue">text track cues</span> from the <span>text track
list of cues</span> that are currently active (i.e. that start before the <span>current playback
position</span> and end after it), as a <code>TextTrackCueList</code> object.</p>
</dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-addCue">addCue</span>(<var>cue</var>)</code></dt>
<dd><p>Adds the given cue to <var>textTrack</var>'s <span>text track list of
cues</span>.</p></dd>
<dt><code data-x=""><var>textTrack</var>.<span subdfn data-x="dom-TextTrack-removeCue">removeCue</span>(<var>cue</var>)</code></dt>
<dd><p>Removes the given cue from <var>textTrack</var>'s <span>text track list of
cues</span>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLMediaElement"><code
data-x="dom-media-addTextTrack">addTextTrack(<var>kind</var>, <var>label</var>,
<var>language</var>)</code></dfn> method of <span data-x="media element">media elements</span>,
when invoked, must run the following steps:</p>
<ol>
<li>
<p>Create a new <code>TextTrack</code> object.</p>
</li>
<li>
<p>Create a new <span>text track</span> corresponding to the new object, and set its <span>text
track kind</span> to <var>kind</var>, its <span>text track label</span> to <var>label</var>, its <span>text track language</span> to <var>language</var>, its
<span>text track readiness state</span> to the <span>text track loaded</span> state, its
<span>text track mode</span> to the <span>text track hidden</span> mode, and its <span>text
track list of cues</span> to an empty list.</p>
<p>Initially, the <span>text track list of cues</span> is not associated with any <span>rules
for updating the text track rendering</span>. When a <span>text track cue</span> is added to it,
the <span>text track list of cues</span> has its rules permanently set accordingly.</p>
</li>
<li>
<p>Add the new <span>text track</span> to the <span>media element</span>'s <span>list of text
tracks</span>.</p>
</li>
<li>
<p><span>Queue a media element task</span> given the <span>media element</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at the <span>media element</span>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code>
attribute initialized to the new <span>text track</span>'s <code>TextTrack</code> object.</p>
</li>
<li>
<p>Return the new <code>TextTrack</code> object.</p>
</li>
</ol>
<hr>
<p>The <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-kind">kind</code></dfn>
attribute must return the <span>text track kind</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents.</p>
<p>The <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-label">label</code></dfn>
attribute must return the <span>text track label</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents.</p>
<p>The <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-language">language</code></dfn>
attribute must return the <span>text track language</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents.</p>
<p>The <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-id">id</code></dfn> attribute
returns the track's identifier, if it has one, or the empty string otherwise. For tracks that
correspond to <code>track</code> elements, the track's identifier is the value of the element's
<code data-x="attr-id">id</code> attribute, if any. For in-band tracks, the track's identifier is
specified by the <span>media resource</span>. If the <span>media resource</span> is in a format
that supports <span>media fragment syntax</span>, the identifier returned for a particular track
must be the same identifier that would enable the track if used as the name of a track in the
track dimension of such a <span data-x="concept-url-fragment">fragment</span>.</p>
<p>The <dfn attribute for="TextTrack"><code
data-x="dom-TextTrack-inBandMetadataTrackDispatchType">inBandMetadataTrackDispatchType</code></dfn>
attribute must return the <span>text track in-band metadata track dispatch type</span> of the
<span>text track</span> that the <code>TextTrack</code> object represents.</p>
<p>The <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-mode">mode</code></dfn>
attribute, on getting, must return the string corresponding to the <span>text track mode</span> of
the <span>text track</span> that the <code>TextTrack</code> object represents, as defined by the
following list:</p>
<dl>
<dt>"<dfn enum-value for="TextTrackMode" data-x="dom-TextTrack-disabled"><code>disabled</code></dfn>"</dt>
<dd>The <span>text track disabled</span> mode.</dd>
<dt>"<dfn enum-value for="TextTrackMode" data-x="dom-TextTrack-hidden"><code>hidden</code></dfn>"</dt>
<dd>The <span>text track hidden</span> mode.</dd>
<dt>"<dfn enum-value for="TextTrackMode" data-x="dom-TextTrack-showing"><code>showing</code></dfn>"</dt>
<dd>The <span>text track showing</span> mode.</dd>
</dl>
<p>On setting, if the new value isn't equal to what the attribute would currently return, the new
value must be processed as follows:</p>
<dl class="switch">
<dt>If the new value is "<code data-x="dom-TextTrack-disabled">disabled</code>"</dt>
<dd>
<p>Set the <span>text track mode</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents to the <span>text track disabled</span> mode.</p>
</dd>
<dt>If the new value is "<code data-x="dom-TextTrack-hidden">hidden</code>"</dt>
<dd>
<p>Set the <span>text track mode</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents to the <span>text track hidden</span> mode.</p>
</dd>
<dt>If the new value is "<code data-x="dom-TextTrack-showing">showing</code>"</dt>
<dd>
<p>Set the <span>text track mode</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents to the <span>text track showing</span> mode.</p>
</dd>
</dl>
<p>If the <span>text track mode</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents is not the <span>text track disabled</span> mode, then
the <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-cues">cues</code></dfn> attribute
must return a <span>live</span> <code>TextTrackCueList</code> object that represents the subset of
the <span>text track list of cues</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents whose <span data-x="text track cue end time">end
times</span> occur at or after the <span>earliest possible position when the script
started</span>, in <span>text track cue order</span>. Otherwise, it must return null. For each
<code>TextTrack</code> object, when an object is returned, the same <code>TextTrackCueList</code>
object must be returned each time.</p>
<p>The <dfn>earliest possible position when the script started</dfn> is whatever the
<span>earliest possible position</span> was the last time the <span>event loop</span> reached step
1.</p>
<p>If the <span>text track mode</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents is not the <span>text track disabled</span> mode, then
the <dfn attribute for="TextTrack"><code data-x="dom-TextTrack-activeCues">activeCues</code></dfn>
attribute must return a <span>live</span> <code>TextTrackCueList</code> object that represents the
subset of the <span>text track list of cues</span> of the <span>text track</span> that the
<code>TextTrack</code> object represents whose <span>active flag was set when the script
started</span>, in <span>text track cue order</span>. Otherwise, it must return null. For each
<code>TextTrack</code> object, when an object is returned, the same <code>TextTrackCueList</code>
object must be returned each time.</p>
<p>A <span>text track cue</span>'s <dfn>active flag was set when the script started</dfn> if its
<span>text track cue active flag</span> was set the last time the <span>event loop</span> reached
<a href="#step1">step 1</a>.</p>
<hr>
<p>The <dfn method for="TextTrack"><code
data-x="dom-TextTrack-addCue">addCue(<var>cue</var>)</code></dfn> method of <code>TextTrack</code>
objects, when invoked, must run the following steps:</p>
<ol>
<li><p>If the <span>text track list of cues</span> does not yet have any associated <span>rules
for updating the text track rendering</span>, then associate the <span>text track list of
cues</span> with the <span>rules for updating the text track rendering</span> appropriate to <var>cue</var>.</p>
<li><p>If <span>text track list of cues</span>' associated <span>rules for updating the text
track rendering</span> are not the same <span>rules for updating the text track rendering</span>
as appropriate for <var>cue</var>, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p>
<li><p>If the given <var>cue</var> is in a <span>text track list of cues</span>, then
remove <var>cue</var> from that <span>text track list of cues</span>.</p></li>
<li><p>Add <var>cue</var> to the <code>TextTrack</code> object's <span>text track</span>'s
<span>text track list of cues</span>.</p></li>
</ol>
<p>The <dfn method for="TextTrack"><code
data-x="dom-TextTrack-removeCue">removeCue(<var>cue</var>)</code></dfn> method of
<code>TextTrack</code> objects, when invoked, must run the following steps:</p>
<ol>
<li><p>If the given <var>cue</var> is not in the <code>TextTrack</code> object's <span>text
track</span>'s <span>text track list of cues</span>, then throw a
<span>"<code>NotFoundError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Remove <var>cue</var> from the <code>TextTrack</code> object's <span>text track</span>'s
<span>text track list of cues</span>.</p></li>
</ol>
</div>
<div class="example">
<p>In this example, an <code>audio</code> element is used to play a specific sound-effect from a
sound file containing many sound effects. A cue is used to pause the audio, so that it ends
exactly at the end of the clip, even if the browser is busy running some script. If the page had
relied on script to pause the audio, then the start of the next clip might be heard if the
browser was not able to run the script at the exact time specified.</p>
<pre><code class="js">var sfx = new Audio('sfx.wav');
var sounds = sfx.addTextTrack('metadata');
// add sounds we care about
function addFX(start, end, name) {
var cue = new VTTCue(start, end, '');
cue.id = name;
cue.pauseOnExit = true;
sounds.addCue(cue);
}
addFX(12.783, 13.612, 'dog bark');
addFX(13.612, 15.091, 'kitten mew');
function playSound(id) {
sfx.currentTime = sounds.getCueById(id).startTime;
sfx.play();
}
// play a bark as soon as we can
sfx.oncanplaythrough = function () {
playSound('dog bark');
}
// meow when the user tries to leave,
// and have the browser ask them to stay
window.onbeforeunload = function (e) {
playSound('kitten mew');
e.preventDefault();
}</code></pre>
</div>
<hr>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TextTrackCueList</dfn> {
readonly attribute unsigned long <span data-x="dom-TextTrackCueList-length">length</span>;
<a href="#dom-texttrackcuelist-item">getter</a> <span>TextTrackCue</span> (unsigned long index);
<span>TextTrackCue</span>? <span data-x="dom-TextTrackCueList-getCueById">getCueById</span>(DOMString id);
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>cuelist</var>.<span subdfn data-x="dom-TextTrackCueList-length">length</span></code></dt>
<dd><p>Returns the number of <span data-x="text track cue">cues</span> in the list.</p></dd>
<dt><code data-x=""><var>cuelist</var>[<var>index</var>]</code></dt>
<dd>
<p>Returns the <span>text track cue</span> with index <var>index</var> in the list. The cues are
sorted in <span>text track cue order</span>.</p>
</dd>
<dt><code data-x=""><var>cuelist</var>.<span subdfn data-x="dom-TextTrackCueList-getCueById">getCueById</span>(<var>id</var>)</code></dt>
<dd>
<p>Returns the first <span>text track cue</span> (in <span>text track cue order</span>) with
<span>text track cue identifier</span> <var>id</var>.</p>
<p>Returns null if none of the cues have the given identifier or if the argument is the empty
string.</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>TextTrackCueList</code> object represents a dynamically updating list of <span
data-x="text track cue">text track cues</span> in a given order.</p>
<p>The <dfn attribute for="TextTrackCueList"><code
data-x="dom-TextTrackCueList-length">length</code></dfn> attribute must return the number of <span
data-x="text track cue">cues</span> in the list represented by the <code>TextTrackCueList</code>
object.</p>
<p>The <span>supported property indices</span> of a <code>TextTrackCueList</code> object at any
instant are the numbers from zero to the number of <span data-x="text track cue">cues</span> in the
list represented by the <code>TextTrackCueList</code> object minus one, if any. If there are no
<span data-x="text track cue">cues</span> in the list, there are no <span>supported property
indices</span>.</p>
<p id="dom-texttrackcuelist-item">To <span>determine the value of an indexed property</span> for a
given index <var>index</var>, the user agent must return the <var>index</var>th <span>text track
cue</span> in the list represented by the <code>TextTrackCueList</code> object.</p>
<p>The <dfn method for="TextTrackCueList"><code
data-x="dom-TextTrackCueList-getCueById">getCueById(<var>id</var>)</code></dfn> method, when
called with an argument other than the empty string, must return the first <span>text track
cue</span> in the list represented by the <code>TextTrackCueList</code> object whose <span>text
track cue identifier</span> is <var>id</var>, if any, or null otherwise. If the argument is the
empty string, then the method must return null.</p>
</div>
<hr>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {
readonly attribute <span>TextTrack</span>? <span data-x="dom-TextTrackCue-track">track</span>;
attribute DOMString <span data-x="dom-TextTrackCue-id">id</span>;
attribute double <span data-x="dom-TextTrackCue-startTime">startTime</span>;
attribute unrestricted double <span data-x="dom-TextTrackCue-endTime">endTime</span>;
attribute boolean <span data-x="dom-TextTrackCue-pauseOnExit">pauseOnExit</span>;
attribute <span>EventHandler</span> <span data-x="handler-TextTrackCue-onenter">onenter</span>;
attribute <span>EventHandler</span> <span data-x="handler-TextTrackCue-onexit">onexit</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-track">track</span></code></dt>
<dd>
<p>Returns the <code>TextTrack</code> object to which this <span>text track cue</span> belongs,
if any, or null otherwise.</p>
</dd>
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-id">id</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>text track cue identifier</span>.</p>
<p>Can be set.</p>
</dd>
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-startTime">startTime</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>text track cue start time</span>, in seconds.</p>
<p>Can be set.</p>
</dd>
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-endTime">endTime</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>text track cue end time</span>, in seconds.</p>
<p>Returns positive Infinity for an <span>unbounded text track cue</span>.</p>
<p>Can be set.</p>
</dd>
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-pauseOnExit">pauseOnExit</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if the <span>text track cue pause-on-exit flag</span> is set, false
otherwise.</p>
<p>Can be set.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="TextTrackCue"><code data-x="dom-TextTrackCue-track">track</code></dfn>
attribute, on getting, must return the <code>TextTrack</code> object of the <span>text
track</span> in whose <span data-x="text track list of cues">list of cues</span> the <span>text
track cue</span> that the <code>TextTrackCue</code> object represents finds itself, if any; or
null otherwise.</p>
<p>The <dfn attribute for="TextTrackCue"><code data-x="dom-TextTrackCue-id">id</code></dfn>
attribute, on getting, must return the <span>text track cue identifier</span> of the <span>text
track cue</span> that the <code>TextTrackCue</code> object represents. On setting, the <span>text
track cue identifier</span> must be set to the new value.</p>
<p>The <dfn attribute for="TextTrackCue"><code
data-x="dom-TextTrackCue-startTime">startTime</code></dfn> attribute, on getting, must return the
<span>text track cue start time</span> of the <span>text track cue</span> that the
<code>TextTrackCue</code> object represents, in seconds. On setting, the <span>text track cue
start time</span> must be set to the new value, interpreted in seconds; then, if the
<code>TextTrackCue</code> object's <span>text track cue</span> is in a <span>text track</span>'s
<span data-x="text track list of cues">list of cues</span>, and that <span>text track</span> is in
a <span>media element</span>'s <span>list of text tracks</span>, and the <span>media
element</span>'s <span>show poster flag</span> is not set, then run the <i data-x="time marches
on">time marches on</i> steps for that <span>media element</span>.</p>
<p>The <dfn attribute for="TextTrackCue"><code
data-x="dom-TextTrackCue-endTime">endTime</code></dfn> attribute, on getting, must return the
<span>text track cue end time</span> of the <span>text track cue</span> that the
<code>TextTrackCue</code> object represents, in seconds or positive Infinity. On setting, if the
new value is negative Infinity or a Not-a-Number (NaN) value, then throw a <a
href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-typeerror">TypeError
</a> exception. Otherwise, the <span>text track cue end time</span> must be set to the new value.
Then, if the <code>TextTrackCue</code> object's <span>text track cue</span> is in a <span>text
track</span>'s <span data-x="text track list of cues">list of cues</span>, and that <span>text
track</span> is in a <span>media element</span>'s <span>list of text tracks</span>, and the
<span>media element</span>'s <span>show poster flag</span> is not set, then run the <i
data-x="time marches on">time marches on</i> steps for that <span>media element</span>.</p>
<p>The <dfn attribute for="TextTrackCue"><code
data-x="dom-TextTrackCue-pauseOnExit">pauseOnExit</code></dfn> attribute, on getting, must return
true if the <span>text track cue pause-on-exit flag</span> of the <span>text track cue</span> that
the <code>TextTrackCue</code> object represents is set; or false otherwise. On setting, the
<span>text track cue pause-on-exit flag</span> must be set if the new value is true, and must be
unset otherwise.</p>
<h6 id="cue-events">Event handlers for objects of the text track APIs</h6>
<p>The following are the <span>event handlers</span> that (and their corresponding <span
data-x="event handler event type">event handler event types</span>) <span w-nodev>that must
be</span> supported, as <span>event handler IDL attributes</span>, by all objects implementing the
<code>TextTrackList</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="TextTrackList"><code data-x="handler-TextTrackList-onchange">onchange</code></dfn> <td> <code data-x="event-media-change">change</code>
<tr><td><dfn attribute for="TextTrackList"><code data-x="handler-TextTrackList-onaddtrack">onaddtrack</code></dfn> <td> <code data-x="event-media-addtrack">addtrack</code>
<tr><td><dfn attribute for="TextTrackList"><code data-x="handler-TextTrackList-onremovetrack">onremovetrack</code></dfn> <td> <code data-x="event-media-removetrack">removetrack</code>
</table>
<p>The following are the <span>event handlers</span> that (and their corresponding <span
data-x="event handler event type">event handler event types</span>) <span w-nodev>that must
be</span> supported, as <span>event handler IDL attributes</span>, by all objects implementing the
<code>TextTrack</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="TextTrack"><code data-x="handler-TextTrack-oncuechange">oncuechange</code></dfn> <td> <code data-x="event-media-cuechange">cuechange</code>
</table>
<p>The following are the <span>event handlers</span> (and their corresponding <span
data-x="event handler event type">event handler event types</span>) <span w-nodev>that must
be</span> supported, as <span>event handler IDL attributes</span>, by all objects implementing the
<code>TextTrackCue</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="TextTrackCue"><code data-x="handler-TextTrackCue-onenter">onenter</code></dfn> <td> <code data-x="event-media-enter">enter</code>
<tr><td><dfn attribute for="TextTrackCue"><code data-x="handler-TextTrackCue-onexit">onexit</code></dfn> <td> <code data-x="event-media-exit">exit</code>
</table>
</div>
<h6>Best practices for metadata text tracks</h6>
<!-- NON-NORMATIVE SECTION -->
<p>Text tracks can be used for storing data relating to the media data, for interactive or
augmented views.</p>
<p>For example, a page showing a sports broadcast could include information about the current
score. Suppose a robotics competition was being streamed live. The image could be overlaid with
the scores, as follows:</p>
<p><iframe src="data:text/html;charset=utf-8,%3C!DOCTYPE%20html%3E%0A%3Cstyle%3E%0A%20body%2C%20html%20%7B%20margin%3A%200%3B%20padding%3A%200%3B%20overflow%3A%20hidden%3B%20%7D%0A%20div%20%7B%20width%3A%20600px%3B%20height%3A%20400px%3B%20position%3A%20relative%3B%20%7D%0A%20p%20%7B%20position%3A%20absolute%3B%20top%3A%200%3B%20margin%3A%200.25em%3B%20font%3A%20small-caps%20900%202em%20sans-serif%3B%20text-shadow%3A%20white%200%200%204px%3B%20%7D%0A%20span%20%7B%20display%3A%20block%3B%20%7D%0A%20.left%20%7B%20color%3A%20red%3B%20left%3A%200%3B%20text-align%3A%20left%3B%20%7D%0A%20.right%20%7B%20color%3A%20blue%3B%20right%3A%200%3B%20text-align%3A%20right%3B%20%7D%0A%20.middle%20%7B%20color%3A%20white%3B%20top%3A%20auto%3B%20bottom%3A%200%3B%20left%3A%200%3B%20right%3A%200%3B%20text-align%3A%20center%3B%20text-shadow%3A%20black%200%200%204px%3B%20%7D%0A%20.middle%20span%20%7B%20display%3A%20inline-block%3B%20margin%3A%200%201em%3B%20font-size%3A%200.75em%3B%20text-transform%3A%20uppercase%3B%20%7D%0A%3C%2Fstyle%3E%0A%3Cdiv%3E%0A%20%3Cimg%20src%3D%22https%3A%2F%2Fhtml.spec.whatwg.org%2Fimages%2Frobots.jpeg%22%3E%0A%20%3Cp%20class%3D%22score%20left%22%3E%3Cspan%3ERed%20Alliance%3C%2Fspan%3E%20%3Cspan%3E78%3C%2Fspan%3E%3C%2Fp%3E%0A%20%3Cp%20class%3D%22score%20right%22%3E%3Cspan%3EBlue%20Alliance%3C%2Fspan%3E%20%3Cspan%3E66%3C%2Fspan%3E%3C%2Fp%3E%0A%20%3Cp%20class%3D%22score%20middle%22%3E%3Cspan%3EQual%20Match%2037%3C%2Fspan%3E%20%3Cspan%3EFriday%2014%3A21%3C%2Fspan%3E%0A%3C%2Fdiv%3E" width="600" height="400"></iframe>
<p>In order to make the score display render correctly whenever the user seeks to an arbitrary
point in the video, the metadata text track cues need to be as long as is appropriate for the
score. For example, in the frame above, there would be maybe one cue that lasts the length of the
match that gives the match number, one cue that lasts until the blue alliance's score changes, and
one cue that lasts until the red alliance's score changes. If the video is just a stream of the
live event, the time in the bottom right would presumably be automatically derived from the
current video time, rather than based on a cue. However, if the video was just the highlights,
then that might be given in cues also.</p>
<p>The following shows what fragments of this could look like in a WebVTT file:</p>
<pre>WEBVTT
...
05:10:00.000 --> 05:12:15.000
matchtype:qual
matchnumber:37
...
05:11:02.251 --> 05:11:17.198
red:78
05:11:03.672 --> 05:11:54.198
blue:66
05:11:17.198 --> 05:11:25.912
red:80
05:11:25.912 --> 05:11:26.522
red:83
05:11:26.522 --> 05:11:26.982
red:86
05:11:26.982 --> 05:11:27.499
red:89
...</pre>
<p>The key here is to notice that the information is given in cues that span the length of time to
which the relevant event applies. If, instead, the scores were given as zero-length (or very
brief, nearly zero-length) cues when the score changes, for example saying "red+2" at
05:11:17.198, "red+3" at 05:11:25.912, etc, problems arise: primarily, seeking is much harder to
implement, as the script has to walk the entire list of cues to make sure that no notifications
have been missed; but also, if the cues are short it's possible the script will never see that
they are active unless it listens to them specifically.</p>
<p>When using cues in this manner, authors are encouraged to use the <code
data-x="event-media-cuechange">cuechange</code> event to update the current annotations. (In
particular, using the <code data-x="event-media-timeupdate">timeupdate</code> event would be less
appropriate as it would require doing work even when the cues haven't changed, and, more
importantly, would introduce a higher latency between when the metadata cues become active and
when the display is updated, since <code data-x="event-media-timeupdate">timeupdate</code> events
are rate-limited.)</p>
<h5>Identifying a track kind through a URL</h5>
<p>Other specifications or formats that need a <span>URL</span> to identify the return values of
the <code>AudioTrack</code> <code data-x="dom-AudioTrack-kind">kind</code> or
<code>VideoTrack</code> <code data-x="dom-VideoTrack-kind">kind</code> IDL attributes, or identify
the <span data-x="text track kind">kind of text track</span>, must use the
<code>about:html-kind</code> <span>URL</span>.</p>
<h5>User interface</h5>
<p>The <dfn element-attr for="audio,video"><code
data-x="attr-media-controls">controls</code></dfn> attribute is a <span>boolean attribute</span>.
If present, it indicates that the author has not provided a scripted controller and would like the
user agent to provide its own set of controls.</p>
<div w-nodev>
<p>If the attribute is present, or if <span data-x="concept-n-noscript">scripting is
disabled</span> for the <span>media element</span>, then the user agent should <dfn>expose a user
interface to the user</dfn>. This user interface should include features to begin playback, pause
playback, seek to an arbitrary position in the content (if the content supports arbitrary
seeking), change the volume, change the display of closed captions or embedded sign-language
tracks, select different audio tracks or turn on audio descriptions, and show the media content in
manners more suitable to the user (e.g. fullscreen video or in an independent resizable window).
Other controls may also be made available.</p>
<p>Even when the attribute is absent, however, user agents may provide controls to affect playback
of the media resource (e.g. play, pause, seeking, track selection, and volume controls), but such
features should not interfere with the page's normal rendering. For example, such features could
be exposed in the <span>media element</span>'s context menu, platform media keys, or a remote
control. The user agent may implement this simply by <span data-x="expose a user interface to the
user">exposing a user interface to the user</span> as described above (as if the <code
data-x="attr-media-controls">controls</code> attribute was present).</p>
<p>If the user agent <span data-x="expose a user interface to the user">exposes a user interface to
the user</span> by displaying controls over the <span>media element</span>, then the user agent
should suppress any user interaction events while the user agent is interacting with this
interface. (For example, if the user clicks on a video's playback control, <code
data-x="event-mousedown">mousedown</code> events and so forth would not simultaneously be fired at
elements on the page.)</p>
<p>Where possible (specifically, for starting, stopping, pausing, and unpausing playback, for
seeking, for changing the rate of playback, for fast-forwarding or rewinding, for listing,
enabling, and disabling text tracks, and for muting or changing the volume of the audio), user
interface features exposed by the user agent must be implemented in terms of the DOM API described
above, so that, e.g., all the same events fire.</p>
<p>Features such as fast-forward or rewind must be implemented by only changing the <code
data-x="">playbackRate</code> attribute (and not the <code data-x="">defaultPlaybackRate</code>
attribute).</p>
<p>Seeking must be implemented in terms of <span data-x="dom-media-seek">seeking</span> to the
requested position in the <span>media element</span>'s <span>media timeline</span>. For media
resources where seeking to an arbitrary position would be slow, user agents are encouraged to use
the <i>approximate-for-speed</i> flag when seeking in response to the user manipulating an
approximate position interface such as a seek bar.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-controls">controls</code></dfn> IDL attribute must <span>reflect</span> the
content attribute of the same name.</p>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-volume">volume</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current playback volume, as a number in the range 0.0 to 1.0, where 0.0 is the
quietest and 1.0 the loudest.</p>
<p>Can be set, to change the volume.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the new
value is not in the range 0.0 .. 1.0.</p>
</dd>
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-media-muted">muted</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if audio is muted, overriding the <code data-x="dom-media-volume">volume</code>
attribute, and false if the <code data-x="dom-media-volume">volume</code> attribute is being
honored.</p>
<p>Can be set, to change whether the audio is muted or not.</p>
</dd>
</dl>
<div w-nodev>
<p>A <span>media element</span> has a <dfn data-x="concept-media-volume">playback volume</dfn>, which is a fraction in the range 0.0 (silent) to 1.0 (loudest).
Initially, the volume should be 1.0, but user agents may remember the last set value across
sessions, on a per-site basis or otherwise, so the volume may start at other values.</p>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-volume">volume</code></dfn>
IDL attribute must return the <span data-x="concept-media-volume">playback volume</span> of any
audio portions of the <span>media element</span>. On setting, if the new value is in the range 0.0
to 1.0 inclusive, the <span>media element</span>'s <span data-x="concept-media-volume">playback
volume</span> must be set to the new value. If the new value is outside the range 0.0 to 1.0
inclusive, then, on setting, an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code> must be thrown instead.</p>
<p>A <span>media element</span> can also be <dfn for="media element" data-x="concept-media-muted"
export>muted</dfn>. If anything is muting the element, then it is muted. (For example, when the
<span>direction of playback</span> is backwards, the element is muted.)</p>
<p>The <dfn attribute for="HTMLMediaElement"><code data-x="dom-media-muted">muted</code></dfn> IDL
attribute must return the value to which it was last set. When a <span>media element</span> is
created, if the element has a <code data-x="attr-media-muted">muted</code> content attribute
specified, then the <code data-x="dom-media-muted">muted</code> IDL attribute should be set to
true; otherwise, the user agents may set the value to the user's preferred value (e.g. remembering
the last set value across sessions, on a per-site basis or otherwise). While the <code
data-x="dom-media-muted">muted</code> IDL attribute is set to true, the <span>media element</span>
must be <span data-x="concept-media-muted">muted</span>.</p>
<p>Whenever either of the values that would be returned by the <code
data-x="dom-media-volume">volume</code> and <code data-x="dom-media-muted">muted</code> IDL
attributes change, the user agent must <span>queue a media element task</span> given the
<span>media element</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-media-volumechange">volumechange</code> at the <span>media element</span>. Then, if
the <span>media element</span> is not <span>allowed to play</span>, the user agent must run the
<span>internal pause steps</span> for the <span>media element</span>.</p>
<p>A user agent has an associated <dfn>volume locked</dfn> (a boolean). Its value is
<span>implementation-defined</span> and determines whether the <span
data-x="concept-media-volume">playback volume</span> takes effect.</p>
<p>An element's <dfn for=HTMLMediaElement export>effective media volume</dfn> is determined as
follows:</p>
<ol>
<li><p>If the user has indicated that the user agent is to override the volume of the element,
then return the volume desired by the user.</p></li>
<li><p>If the user agent's <span>volume locked</span> is true, then return the system
volume.</p></li>
<li><p>If the element's audio output is <span data-x="concept-media-muted">muted</span>, then
return zero.</p></li>
<li><p>Let <var>volume</var> be the <span data-x="concept-media-volume">playback
volume</span> of the audio portions of the <span>media element</span>, in range 0.0 (silent) to
1.0 (loudest).</p></li>
<li><p>Return <var>volume</var>, interpreted relative to the range 0.0 to 1.0, with 0.0 being
silent, and 1.0 being the loudest setting, values in between increasing in loudness. The range
need not be linear. The loudest setting may be lower than the system's loudest possible setting;
for example the user could have set a maximum volume.</p></li>
</ol>
</div>
<p>The <dfn element-attr for="audio,video"><code data-x="attr-media-muted">muted</code></dfn>
content attribute on <span data-x="media element">media elements</span> is a <span>boolean
attribute</span> that controls the default state of the audio output of the <span>media
resource</span>, potentially overriding user preferences.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLMediaElement"><code
data-x="dom-media-defaultMuted">defaultMuted</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-media-muted">muted</code> content attribute.</p>
</div>
<p class="note">This attribute has no dynamic effect (it only controls the default state of the
element).</p>
<div class="example">
<p>This video (an advertisement) autoplays, but to avoid annoying users, it does so without
sound, and allows the user to turn the sound on. The user agent can pause the video if it's
unmuted without a user interaction.</p>
<pre><code class="html"><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></code></pre>
</div>
<h5>Time ranges</h5>
<p>Objects implementing the <code>TimeRanges</code> interface
represent a list of ranges (periods) of time.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TimeRanges</dfn> {
readonly attribute unsigned long <span data-x="dom-TimeRanges-length">length</span>;
double <span data-x="dom-TimeRanges-start">start</span>(unsigned long index);
double <span data-x="dom-TimeRanges-end">end</span>(unsigned long index);
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>media</var>.<span subdfn data-x="dom-TimeRanges-length">length</span></code></dt>
<dd><p>Returns the number of ranges in the object.</p></dd>
<dt><code data-x=""><var>time</var> = <var>media</var>.<span subdfn data-x="dom-TimeRanges-start">start</span>(<var>index</var>)</code></dt>
<dd>
<p>Returns the time for the start of the range with the given index.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the index
is out of range.</p>
</dd>
<dt><code data-x=""><var>time</var> = <var>media</var>.<span subdfn data-x="dom-TimeRanges-end">end</span>(<var>index</var>)</code></dt>
<dd>
<p>Returns the time for the end of the range with the given index.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the index
is out of range.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="TimeRanges"><code data-x="dom-TimeRanges-length">length</code></dfn>
IDL attribute must return the number of ranges represented by the object.</p>
<p>The <dfn method for="TimeRanges"><code
data-x="dom-TimeRanges-start">start(<var>index</var>)</code></dfn> method must return the position
of the start of the <var>index</var>th range represented by the object, in seconds measured from
the start of the timeline that the object covers.</p>
<p>The <dfn method for="TimeRanges"><code
data-x="dom-TimeRanges-end">end(<var>index</var>)</code></dfn> method must return the position of
the end of the <var>index</var>th range represented by the object, in seconds measured from the
start of the timeline that the object covers.</p>
<p>These methods must throw <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>s
if called with an <var>index</var> argument greater than or equal to the number of ranges
represented by the object.</p>
<p>When a <code>TimeRanges</code> object is said to be a <dfn
id="normalised-timeranges-object" export><!-- en-GB -->normalized <code>TimeRanges</code> object</dfn>,
the ranges it represents must obey the following criteria:</p>
<ul>
<li>The start of a range must be greater than the end of all earlier ranges.</li>
<li>The start of a range must be less than or equal to the end of that same range.</li>
</ul>
<p>In other words, the ranges in such an object are ordered, don't overlap, and don't touch
(adjacent ranges are folded into one bigger range). A range can be empty (referencing just a
single moment in time), e.g. to indicate that only one frame is currently buffered in the case
that the user agent has discarded the entire <span>media resource</span> except for the current
frame, when a <span>media element</span> is paused.</p>
<p>Ranges in a <code>TimeRanges</code> object must be inclusive.</p>
<p class="example">Thus, the end of a range would be equal to the start of a following adjacent
(touching but not overlapping) range. Similarly, a range covering a whole timeline anchored at
zero would have a start equal to zero and an end equal to the duration of the timeline.</p>
<p>The timelines used by the objects returned by the <code
data-x="dom-media-buffered">buffered</code>, <code data-x="dom-media-seekable">seekable</code>, and
<code data-x="dom-media-played">played</code> IDL attributes of <span data-x="media element">media
elements</span> must be that element's <span>media timeline</span>.</p>
</div>
<h5>The <code>TrackEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TrackEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>TrackEventInit</span> eventInitDict = {});
readonly attribute (<span>VideoTrack</span> or <span>AudioTrack</span> or <span>TextTrack</span>)? <span data-x="dom-TrackEvent-track">track</span>;
};
dictionary <dfn dictionary>TrackEventInit</dfn> : <span>EventInit</span> {
(<span>VideoTrack</span> or <span>AudioTrack</span> or <span>TextTrack</span>)? track = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-TrackEvent-track">track</span></code></dt>
<dd>
<p>Returns the track object (<code>TextTrack</code>, <code>AudioTrack</code>, or
<code>VideoTrack</code>) to which the event relates.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="TrackEvent"><code data-x="dom-TrackEvent-track">track</code></dfn>
attribute must return the value it was initialized to. It represents the context information for
the event.</p>
</div>
<h5 id="mediaevents">Events summary</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The following events fire on <span data-x="media element">media elements</span> as part of the
processing model described above:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<th>Preconditions
<tbody>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-loadstart">loadstart</code></dfn>
<td><code>Event</code>
<td>The user agent begins looking for <span>media data</span>, as part of the <span
data-x="concept-media-load-algorithm">resource selection algorithm</span>.
<td><code data-x="dom-media-networkState">networkState</code> equals <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-progress">progress</code></dfn>
<td><code>Event</code>
<td>The user agent is fetching <span>media data</span>.
<td><code data-x="dom-media-networkState">networkState</code> equals <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-suspend">suspend</code></dfn>
<td><code>Event</code>
<td>The user agent is intentionally not currently fetching <span>media data</span>.
<td><code data-x="dom-media-networkState">networkState</code> equals <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-abort">abort</code></dfn>
<td><code>Event</code>
<td>The user agent stops fetching the <span>media data</span> before it is completely
downloaded, but not due to an error.
<td><code data-x="dom-media-error">error</code> is an object with the code <code
data-x="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</code>. <code
data-x="dom-media-networkState">networkState</code> equals either <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> or <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code>, depending on when the download was aborted.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-error">error</code></dfn>
<td><code>Event</code>
<td>An error occurs while fetching the <span>media data</span> or the type of the resource
is not a supported media format.
<td><code data-x="dom-media-error">error</code> is an object with the code <code
data-x="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</code> or higher. <code
data-x="dom-media-networkState">networkState</code> equals either <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> or <code
data-x="dom-media-NETWORK_IDLE">NETWORK_IDLE</code>, depending on when the download was aborted.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-emptied">emptied</code></dfn>
<td><code>Event</code>
<td>A <span>media element</span> whose <code data-x="dom-media-networkState">networkState</code>
was previously not in the <code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code> state has
just switched to that state (either because of a fatal error during load that's about to be
reported, or because the <code data-x="dom-media-load">load()</code> method was invoked while
the <span data-x="concept-media-load-algorithm">resource selection algorithm</span> was already
running).
<td><code data-x="dom-media-networkState">networkState</code> is <code
data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>; all the IDL attributes are in their
initial states.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-stalled">stalled</code></dfn>
<td><code>Event</code>
<td>The user agent is trying to fetch <span>media data</span>, but data is unexpectedly not
forthcoming.
<td><code data-x="dom-media-networkState">networkState</code> is <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>.
<tbody>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-loadedmetadata">loadedmetadata</code></dfn>
<td><code>Event</code>
<td>The user agent has just determined the duration and dimensions of the <span>media
resource</span> and <span>the text tracks are ready</span>.
<td><code data-x="dom-media-readyState">readyState</code> is newly equal to <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code> or greater for the first time.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-loadeddata">loadeddata</code></dfn>
<td><code>Event</code>
<td>The user agent can render the <span>media data</span> at the <span>current playback
position</span> for the first time.
<td><code data-x="dom-media-readyState">readyState</code> newly increased to <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or greater for the first time.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-canplay">canplay</code></dfn>
<td><code>Event</code>
<td>The user agent can resume playback of the <span>media data</span>, but estimates that if
playback were to be started now, the <span>media resource</span> could not be rendered at the
current playback rate up to its end without having to stop for further buffering of content.
<td><code data-x="dom-media-readyState">readyState</code> newly increased to <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> or greater.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-canplaythrough">canplaythrough</code></dfn>
<td><code>Event</code>
<td>The user agent estimates that if playback were to be started now, the <span>media
resource</span> could be rendered at the current playback rate all the way to its end without
having to stop for further buffering.
<td><code data-x="dom-media-readyState">readyState</code> is newly equal to <code
data-x="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</code>.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-playing">playing</code></dfn>
<td><code>Event</code>
<td>Playback is ready to start after having been paused or delayed due to lack of <span>media
data</span>.
<td><code data-x="dom-media-readyState">readyState</code> is newly greater than or equal to
<code data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code> and <code
data-x="dom-media-paused">paused</code> is false, or <code
data-x="dom-media-paused">paused</code> is newly false and <code
data-x="dom-media-readyState">readyState</code> is greater than or equal to <code
data-x="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</code>. Even if this event fires, the
element might still not be <span>potentially playing</span>, e.g. if the element is
<span>paused for user interaction</span> or <span>paused for in-band content</span>.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-waiting">waiting</code></dfn>
<td><code>Event</code>
<td>Playback has stopped because the next frame is not available, but the user agent expects
that frame to become available in due course.
<td><code data-x="dom-media-readyState">readyState</code> is less than or equal to <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code>, and <code
data-x="dom-media-paused">paused</code> is false. Either <code
data-x="dom-media-seeking">seeking</code> is true, or the <span>current playback position</span>
is not contained in any of the ranges in <code data-x="dom-media-buffered">buffered</code>. It
is possible for playback to stop for other reasons without <code
data-x="dom-media-paused">paused</code> being false, but those reasons do not fire this event
(and when those situations resolve, a separate <code data-x="event-media-playing">playing</code>
event is not fired either): e.g., <span data-x="ended playback">playback has ended</span>, or
playback <span>stopped due to errors</span>, or the element has <span>paused for user
interaction</span> or <span>paused for in-band content</span>.
<tbody>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-seeking">seeking</code></dfn>
<td><code>Event</code>
<td>The <code data-x="dom-media-seeking">seeking</code> IDL attribute changed to true, and the user agent has started seeking to a new position.
<td>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-seeked">seeked</code></dfn>
<td><code>Event</code>
<td>The <code data-x="dom-media-seeking">seeking</code> IDL attribute changed to false after the <span>current playback position</span> was changed.
<td>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-ended">ended</code></dfn>
<td><code>Event</code>
<td>Playback has stopped because the end of the <span>media resource</span> was reached.
<td><code data-x="dom-media-currentTime">currentTime</code> equals the end of the <span>media
resource</span>; <code data-x="dom-media-ended">ended</code> is true.
<tbody>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-durationchange">durationchange</code></dfn>
<td><code>Event</code>
<td>The <code data-x="dom-media-duration">duration</code> attribute has just been updated.
<td>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-timeupdate">timeupdate</code></dfn>
<td><code>Event</code>
<td>The <span>current playback position</span> changed as part of normal playback or in an especially interesting way, for example discontinuously.
<td>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-play">play</code></dfn>
<td><code>Event</code>
<td>The element is no longer paused. Fired after the <code data-x="dom-media-play">play()</code>
method has returned, or when the <code data-x="attr-media-autoplay">autoplay</code> attribute
has caused playback to begin.
<td><code data-x="dom-media-paused">paused</code> is newly false.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-pause">pause</code></dfn>
<td><code>Event</code>
<td>The element has been paused. Fired after the <code data-x="dom-media-pause">pause()</code>
method has returned.
<td><code data-x="dom-media-paused">paused</code> is newly true.
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-ratechange">ratechange</code></dfn>
<td><code>Event</code>
<td>Either the <code data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</code> or the
<code data-x="dom-media-playbackRate">playbackRate</code> attribute has just been updated.
<td>
<tbody>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-resize">resize</code></dfn>
<td><code>Event</code>
<td>One or both of the <code data-x="dom-video-videoWidth">videoWidth</code> and <code
data-x="dom-video-videoHeight">videoHeight</code> attributes have just been updated.
<td><span>Media element</span> is a <code>video</code> element; <code
data-x="dom-media-readyState">readyState</code> is not <code
data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code>
<tr>
<td><dfn event for="HTMLMediaElement"><code data-x="event-media-volumechange">volumechange</code></dfn>
<td><code>Event</code>
<td>Either the <code data-x="dom-media-volume">volume</code> attribute or the <code
data-x="dom-media-muted">muted</code> attribute has changed. Fired after the relevant
attribute's setter has returned.
<td>
</table>
<p>The following event fires on <code>source</code> elements:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<tbody>
<tr>
<td><dfn event for="HTMLSourceElement"><code data-x="event-source-error">error</code></dfn>
<td><code>Event</code>
<td>An error occurs while fetching the <span>media data</span> or the type of the resource
is not a supported media format.
</table>
<p>The following events fire on <code>AudioTrackList</code>, <code>VideoTrackList</code>, and
<code>TextTrackList</code> objects:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<tbody>
<tr>
<td><dfn event for="AudioTrackList,VideoTrackList,TextTrackList"><code data-x="event-media-change">change</code></dfn>
<td><code>Event</code>
<td>One or more tracks in the track list have been enabled or disabled.
<tr>
<td><dfn event for="AudioTrackList,VideoTrackList,TextTrackList"><code data-x="event-media-addtrack">addtrack</code></dfn>
<td><code>TrackEvent</code>
<td>A track has been added to the track list.
<tr>
<td><dfn event for="AudioTrackList,VideoTrackList,TextTrackList"><code data-x="event-media-removetrack">removetrack</code></dfn>
<td><code>TrackEvent</code>
<td>A track has been removed from the track list.
</table>
<p>The following event fires on <code>TextTrack</code> objects and <code>track</code> elements:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<tbody>
<tr>
<td><dfn event for="TextTrack,HTMLTrackElement"><code data-x="event-media-cuechange">cuechange</code></dfn>
<td><code>Event</code>
<td>One or more cues in the track have become active or stopped being active.
</table>
<p>The following events fire on <code>track</code> elements:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<tbody>
<tr>
<td><dfn event for="HTMLTrackElement"><code data-x="event-track-error">error</code></dfn>
<td><code>Event</code>
<td>An error occurs while fetching the track data or the type of the resource is not supported text track format.
<tr>
<td><dfn event for="HTMLTrackElement"><code data-x="event-track-load">load</code></dfn>
<td><code>Event</code>
<td>A track data has been fetched and successfully processed.
</table>
<p>The following events fire on <code>TextTrackCue</code> objects:</p>
<table>
<thead>
<tr>
<th>Event name
<th>Interface
<th>Fired when...
<tbody>
<tr>
<td><dfn event for="TextTrackCue"><code data-x="event-media-enter">enter</code></dfn>
<td><code>Event</code>
<td>The cue has become active.
<tr>
<td><dfn event for="TextTrackCue"><code data-x="event-media-exit">exit</code></dfn>
<td><code>Event</code>
<td>The cue has stopped being active.
</table>
<div w-nodev>
<h5>Security and privacy considerations</h5>
<p>The main security and privacy implications of the <code>video</code> and <code>audio</code>
elements come from the ability to embed media cross-origin. There are two directions that threats
can flow: from hostile content to a victim page, and from a hostile page to victim content.</p>
<hr>
<p>If a victim page embeds hostile content, the threat is that the content might contain scripted
code that attempts to interact with the <code>Document</code> that embeds the content. To avoid
this, user agents must ensure that there is no access from the content to the embedding page. In
the case of media content that uses DOM concepts, the embedded content must be treated as if it
was in its own unrelated <span>top-level traversable</span>.</p>
<p class="example">For instance, if an SVG animation was embedded in a <code>video</code> element,
the user agent would not give it access to the DOM of the outer page. From the perspective of
scripts in the SVG resource, the SVG file would appear to be in a lone top-level traversable
with no parent.</p>
<hr>
<p>If a hostile page embeds victim content, the threat is that the embedding page could obtain
information from the content that it would not otherwise have access to. The API does expose some
information: the existence of the media, its type, its duration, its size, and the performance
characteristics of its host. Such information is already potentially problematic, but in practice
the same information can more or less be obtained using the <code>img</code> element, and so it
has been deemed acceptable.</p>
<p>However, significantly more sensitive information could be obtained if the user agent further
exposes metadata within the content, such as subtitles. That information is therefore only exposed
if the video resource uses CORS. The <code data-x="attr-media-crossorigin">crossorigin</code>
attribute allows authors to enable CORS. <ref>FETCH</ref></p>
<p class="example">Without this restriction, an attacker could trick a user running within a
corporate network into visiting a site that attempts to load a video from a previously leaked
location on the corporation's intranet. If such a video included confidential plans for a new
product, then being able to read the subtitles would present a serious confidentiality breach.</p>
</div>
<h5>Best practices for authors using media elements</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Playing audio and video resources on small devices such as set-top boxes or mobile phones is
often constrained by limited hardware resources in the device. For example, a device might only
support three simultaneous videos. For this reason, it is a good practice to release resources
held by <span data-x="media element">media elements</span> when they are done playing, either by
being very careful about removing all references to the element and allowing it to be garbage
collected, or, even better, by setting the element's <code data-x="attr-media-src">src</code>
attribute to an empty string. In cases where <code data-x="dom-media-srcObject">srcObject</code>
was set, instead set the <code data-x="dom-media-srcObject">srcObject</code> to null.</p>
<p>Similarly, when the playback rate is not exactly 1.0, hardware, software, or format limitations
can cause video frames to be dropped and audio to be choppy or muted.</p>
<div w-nodev>
<h5>Best practices for implementers of media elements</h5>
<!-- NON-NORMATIVE SECTION -->
<p>How accurately various aspects of the <span>media element</span> API are implemented is
considered a quality-of-implementation issue.</p>
<p>For example, when implementing the <code data-x="dom-media-buffered">buffered</code> attribute,
how precise an implementation reports the ranges that have been buffered depends on how carefully
the user agent inspects the data. Since the API reports ranges as times, but the data is obtained
in byte streams, a user agent receiving a variable-bitrate stream might only be able to determine
precise times by actually decoding all of the data. User agents aren't required to do this,
however; they can instead return estimates (e.g. based on the average bitrate seen so far) which
get revised as more information becomes available.</p>
<p>As a general rule, user agents are urged to be conservative rather than optimistic. For
example, it would be bad to report that everything had been buffered when it had not.</p>
<p>Another quality-of-implementation issue would be playing a video backwards when the codec is
designed only for forward playback (e.g. there aren't many key frames, and they are far apart, and
the intervening frames only have deltas from the previous frame). User agents could do a poor job,
e.g. only showing key frames; however, better implementations would do more work and thus do a
better job, e.g. actually decoding parts of the video forwards, storing the complete frames, and
then playing the frames backwards.</p>
<p>Similarly, while implementations are allowed to drop buffered data at any time (there is no
requirement that a user agent keep all the media data obtained for the lifetime of the media
element), it is again a quality of implementation issue: user agents with sufficient resources to
keep all the data around are encouraged to do so, as this allows for a better user experience. For
example, if the user is watching a live stream, a user agent could allow the user only to view the
live video; however, a better user agent would buffer everything and allow the user to seek
through the earlier material, pause it, play it forwards and backwards, etc.</p>
<hr>
<p>When a <span>media element</span> that is paused is <span data-x="node is removed from a
document">removed from a document</span> and not reinserted before the next time the <span>event
loop</span> reaches <a href="#step1">step 1</a>, implementations that are resource constrained are encouraged to take
that opportunity to release all hardware resources (like video planes, networking resources, and
data buffers) used by the <span>media element</span>. (User agents still have to keep track of the
playback position and so forth, though, in case playback is later restarted.)</p>
</div>
<h4 split-filename="image-maps">The <dfn element><code>map</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-map-name">name</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-map">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-map">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLMapElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-map-name">name</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-map-areas">areas</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLMapElement</code>.</dd>
</dl>
<p>The <code>map</code> element, in conjunction with an <code>img</code> element and any
<code>area</code> element descendants, defines an <span>image map</span>. The element
<span>represents</span> its children.</p>
<p>The <dfn element-attr for="map"><code data-x="attr-map-name">name</code></dfn> attribute gives
the map a name so that it can be <span>referenced</span>. The attribute must be present and must
have a non-empty value with no <span>ASCII whitespace</span>. The value of the <code
data-x="attr-map-name">name</code> attribute must not be equal to the value of the <code
data-x="attr-map-name">name</code> attribute of another <code>map</code> element in the same
<span>tree</span>. If the <code data-x="attr-id">id</code> attribute is also specified, both
attributes must have the same value.</p>
<dl class="domintro">
<dt><code data-x=""><var>map</var>.<span subdfn data-x="dom-map-areas">areas</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>area</code> elements in the
<code>map</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLMapElement"><code data-x="dom-map-areas">areas</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>map</code> element, whose
filter matches only <code>area</code> elements.</p>
<p>The IDL attribute <dfn attribute for="HTMLMapElement"><code
data-x="dom-map-name">name</code></dfn> must <span>reflect</span> the content attribute of the
same name.</p>
</div>
<div class="example">
<p>Image maps can be defined in conjunction with other content on the page, to ease maintenance.
This example is of a page with an image map at the top of the page and a corresponding set of
text links at the bottom.</p>
<pre><code class="html"><!DOCTYPE HTML>
<HTML LANG="EN">
<TITLE>Babies™: Toys</TITLE>
<HEADER>
<H1>Toys</H1>
<IMG SRC="/images/menu.gif"
ALT="Babies™ navigation menu. Select a department to go to its page."
USEMAP="#NAV">
</HEADER>
...
<FOOTER>
<MAP NAME="NAV">
<P>
<A HREF="/clothes/">Clothes</A>
<AREA ALT="Clothes" COORDS="0,0,100,50" HREF="/clothes/"> |
<A HREF="/toys/">Toys</A>
<AREA ALT="Toys" COORDS="100,0,200,50" HREF="/toys/"> |
<A HREF="/food/">Food</A>
<AREA ALT="Food" COORDS="200,0,300,50" HREF="/food/"> |
<A HREF="/books/">Books</A>
<AREA ALT="Books" COORDS="300,0,400,50" HREF="/books/">
</P>
</MAP>
</FOOTER></code></pre>
</div>
<h4>The <dfn element><code>area</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected, but only if there is a <code>map</code> element ancestor.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-area-alt">alt</code></dd>
<dd><code data-x="attr-area-coords">coords</code></dd>
<dd><code data-x="attr-area-shape">shape</code></dd>
<dd><code data-x="attr-hyperlink-href">href</code></dd>
<dd><code data-x="attr-hyperlink-target">target</code></dd>
<dd><code data-x="attr-hyperlink-download">download</code></dd>
<dd><code data-x="attr-hyperlink-ping">ping</code></dd>
<dd><code data-x="attr-hyperlink-rel">rel</code></dd>
<dd><code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If the element has an <code data-x="attr-hyperlink-href">href</code> attribute: <a
href="https://w3c.github.io/html-aria/#el-area">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-area">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-area-no-href">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-area-no-href">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLAreaElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-alt">alt</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-coords">coords</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-shape">shape</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-target">target</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-download">download</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-area-ping">ping</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-rel">rel</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-area-relList">relList</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-area-referrerPolicy">referrerPolicy</span>;
// <a href="#HTMLAreaElement-partial">also has obsolete members</a>
};
<span>HTMLAreaElement</span> includes <span>HTMLHyperlinkElementUtils</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLAreaElement</code>.</dd>
</dl>
<p>The <code>area</code> element <span>represents</span> either a hyperlink with some text and a
corresponding area on an <span>image map</span>, or a dead area on an image map.</p>
<p>An <code>area</code> element with a parent node must have a <code>map</code> element
ancestor.</p>
<p>If the <code>area</code> element has an <code data-x="attr-hyperlink-href">href</code>
attribute, then the <code>area</code> element represents a <span>hyperlink</span>. In this case,
the <dfn element-attr for="area"><code data-x="attr-area-alt">alt</code></dfn> attribute must be
present. It specifies the text of the hyperlink. Its value must be text that, when presented with
the texts specified for the other hyperlinks of the <span>image map</span>, and with the
alternative text of the image, but without the image itself, provides the user with the same kind
of choice as the hyperlink would when used without its text but with its shape applied to the
image. The <code data-x="attr-area-alt">alt</code> attribute may be left blank if there is another
<code>area</code> element in the same <span>image map</span> that points to the same resource and
has a non-blank <code data-x="attr-area-alt">alt</code> attribute.</p>
<p>If the <code>area</code> element has no <code data-x="attr-hyperlink-href">href</code>
attribute, then the area represented by the element cannot be selected, and the <code
data-x="attr-area-alt">alt</code> attribute must be omitted.</p>
<p>In both cases, the <code data-x="attr-area-shape">shape</code> and <code
data-x="attr-area-coords">coords</code> attributes specify the area.</p>
<p>The <dfn element-attr for="area"><code data-x="attr-area-shape">shape</code></dfn> attribute is
an <span>enumerated attribute</span> with the following keywords and states:</p>
<table class="yesno">
<thead>
<tr>
<th>Keyword
<th w-nodev>Conforming
<th>State
<th w-nodev>Brief description
<tbody>
<tr>
<td><dfn><code data-x="attr-area-shape-keyword-circle">circle</code></dfn>
<td w-nodev>
<td w-nodev rowspan=2><span data-x="attr-area-shape-circle">Circle state</span>
<td w-dev><span data-x="attr-area-shape-circle">Circle state</span>
<td w-nodev rowspan=2>Designates a circle, using exactly three integers in the <code
data-x="attr-area-coords">coords</code> attribute.
<tr w-nodev>
<td><dfn><code data-x="attr-area-shape-keyword-circ">circ</code></dfn>
<td class="no">No
<tr>
<td><dfn><code data-x="attr-area-shape-keyword-default">default</code></dfn>
<td w-nodev>
<td><span data-x="attr-area-shape-default">Default state</span>
<td w-nodev>This area is the whole image. (The <code data-x="attr-area-coords">coords</code>
attribute is not used.)
<tr>
<td><dfn><code data-x="attr-area-shape-keyword-poly">poly</code></dfn>
<td w-nodev>
<td w-nodev rowspan=2><span data-x="attr-area-shape-poly">Polygon state</span>
<td w-dev><span data-x="attr-area-shape-poly">Polygon state</span>
<td w-nodev rowspan=2>Designates a polygon, using at-least six integers in the <code
data-x="attr-area-coords">coords</code> attribute.
<tr w-nodev>
<td><dfn><code data-x="attr-area-shape-keyword-polygon">polygon</code></dfn>
<td class="no">No
<tr>
<td><dfn><code data-x="attr-area-shape-keyword-rect">rect</code></dfn>
<td w-nodev>
<td w-nodev rowspan=2><span data-x="attr-area-shape-rect">Rectangle state</span>
<td w-dev><span data-x="attr-area-shape-rect">Rectangle state</span>
<td w-nodev rowspan=2>Designates a rectangle, using exactly four integers in the <code
data-x="attr-area-coords">coords</code> attribute.
<tr w-nodev>
<td><dfn><code data-x="attr-area-shape-keyword-rectangle">rectangle</code></dfn>
<td class="no">No
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-area-shape-rect">rectangle</span> state.</p>
<p>The <dfn element-attr for="area"><code data-x="attr-area-coords">coords</code></dfn> attribute
must, if specified, contain a <span>valid list of floating-point numbers</span>. This attribute
gives the coordinates for the shape described by the <code data-x="attr-area-shape">shape</code>
attribute. <span w-nodev>The processing for this attribute is described as part of the <span>image
map</span> processing model.</span></p>
<!-- v2: It was suggested by John S. Urban that coords should support percentages as well as
pixels, so that one could use the same image map for images of various sizes. -->
<p>In the <dfn attr-value for="area/shape" data-x="attr-area-shape-circle">circle state</dfn>,
<code>area</code> elements must have a <code data-x="attr-area-coords">coords</code> attribute
present, with three integers, the last of which must be non-negative. The first integer must be
the distance in <span data-x="'px'">CSS pixels</span> from the left edge of the image to the
center of the circle, the second integer must be the distance in <span data-x="'px'">CSS
pixels</span> from the top edge of the image to the center of the circle, and the third integer
must be the radius of the circle, again in <span data-x="'px'">CSS pixels</span>.</p>
<p>In the <dfn attr-value for="area/shape" data-x="attr-area-shape-default">default state</dfn>,
<code>area</code> elements must not have a <code data-x="attr-area-coords">coords</code>
attribute. (The area is the whole image.)</p>
<p>In the <dfn attr-value for="area/shape" data-x="attr-area-shape-poly">polygon state</dfn>,
<code>area</code> elements must have a <code data-x="attr-area-coords">coords</code> attribute
with at least six integers, and the number of integers must be even. Each pair of integers must
represent a coordinate given as the distances from the left and the top of the image in <span
data-x="'px'">CSS pixels</span> respectively, and all the coordinates together must represent the
points of the polygon, in order.</p>
<p>In the <dfn attr-value for="area/shape" data-x="attr-area-shape-rect">rectangle state</dfn>,
<code>area</code> elements must have a <code data-x="attr-area-coords">coords</code> attribute
with exactly four integers, the first of which must be less than the third, and the second of
which must be less than the fourth. The four points must represent, respectively, the distance
from the left edge of the image to the left side of the rectangle, the distance from the top edge
to the top side, the distance from the left edge to the right side, and the distance from the top
edge to the bottom side, all in <span data-x="'px'">CSS pixels</span>.</p>
<div w-nodev>
<p>When user agents allow users to <span data-x="following hyperlinks">follow hyperlinks</span> or
<span data-x="downloading hyperlinks">download hyperlinks</span> created using the
<code>area</code> element, the <code data-x="attr-hyperlink-href">href</code>, <code
data-x="attr-hyperlink-target">target</code>, <code
data-x="attr-hyperlink-download">download</code>, and <code
data-x="attr-hyperlink-ping">ping</code> attributes decide how the link is followed. The <code
data-x="attr-hyperlink-rel">rel</code> attribute may be used to indicate to the user the likely
nature of the target resource before the user follows the link.</p>
</div>
<p>The <code data-x="attr-hyperlink-target">target</code>, <code
data-x="attr-hyperlink-download">download</code>, <code data-x="attr-hyperlink-ping">ping</code>,
<code data-x="attr-hyperlink-rel">rel</code>, and <code
data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code> attributes must be omitted if the
<code data-x="attr-hyperlink-href">href</code> attribute is not present.</p>
<p>If the <code data-x="attr-itemprop">itemprop</code> attribute is specified on an
<code>area</code> element, then the <code data-x="attr-hyperlink-href">href</code> attribute must
also be specified.</p>
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-alt">alt</code></dfn>, <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-coords">coords</code></dfn>, <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-shape">shape</code></dfn>, <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-target">target</code></dfn>, <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-download">download</code></dfn>, <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-ping">ping</code></dfn>, and <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-rel">rel</code></dfn>, each must <span>reflect</span> the respective content
attributes of the same name.</p>
<p>The IDL attribute <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-rellist">relList</code></dfn> must <span>reflect</span> the <code
data-x="attr-hyperlink-rel">rel</code> content attribute.</p>
<p>The IDL attribute <dfn attribute for="HTMLAreaElement"><code
data-x="dom-area-referrerPolicy">referrerPolicy</code></dfn> must <span>reflect</span> the <code
data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code> content attribute, <span>limited to
only known values</span>.</p>
</div>
<h4 id="image-maps">Image maps</h4>
<!-- TESTS
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/smallcats%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%3E%0A%3Cmap%20name%3Da%3E%0A%20%3Carea%20onclick%3Dw%28%271%27%29%20coords%3D%270%25%200%25%20100%25%20100%25%27%20href%3Djavascript%3A%3E%0A%3C/map%3E
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cbody%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/smallcats%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/sample%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cmap%20name%3Da%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%20%3Carea%20onclick%3Dw%28%271%27%29%20coords%3D%270%200%2050%2050%27%20href%3Djavascript%3A%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3C/map%3E%0A%3Cscript%3E%0A%20var%20x%20%3D%20document.getElementsByTagName%28%27img%27%29%5B0%5D%3B%0A%20x.parentNode.appendChild%28x%29%3B%0A%20document.getElementsByTagName%28%27area%27%29%5B0%5D.focus%28%29%3B%0A%3C/script%3E
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3Ex%3Cmap%3E%3Carea%20shape%3Dpolyg%20coords%3D%221%2C2%203%22%3E%3C/map%3E%0A%3Cscript%3Ex%20%3D%20document.getElementsByTagName%28%27area%27%29%5B0%5D%3B%20w%28x.shape%20+%20%27%20%27%20+%20x.coords%29%3C/script%3E
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0D%0A%3Cp%3E%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/astrophy/128%22%20usemap%3D%23a%3E%0D%0A%3Cmap%20name%3Da%3E%3Carea%20shape%3Dcirc%20coords%3D%2220%2C20%2C10%25%22%20href%3D%23%3E%3Carea%20shape%3Dcirc%20coords%3D%2220%2C20%2C10%22%20href%3D%23%3E%3C/map%3E%0D%0A%3Cscript%3Edocument.write%28document.getElementsByTagName%28%27area%27%29%5B0%5D.coords%29%3C/script%3E
-->
<div w-nodev>
<h5>Authoring</h5>
</div>
<p>An <dfn>image map</dfn> allows geometric areas on an image to be associated with <span
data-x="hyperlink">hyperlinks</span>.</p>
<p>An image, in the form of an <code>img</code> element, may be associated with an image map (in
the form of a <code>map</code> element) by specifying a <dfn element-attr for="img"><code
data-x="attr-hyperlink-usemap">usemap</code></dfn> attribute on the <code>img</code> element. The
<code data-x="attr-hyperlink-usemap">usemap</code> attribute, if specified, must be a <span>valid
hash-name reference</span> to a <code>map</code> element.</p>
<div class="example">
<p>Consider an image that looks as follows:</p>
<p><img src="/images/sample-usemap.png" width="600" height="150" alt="A line with four shapes in it, equally spaced: a red hollow box, a green circle, a blue triangle, and a yellow four-pointed star."></p>
<p>If we wanted just the colored areas to be clickable, we could do it as follows:</p>
<pre><code class="html"><p>
Please select a shape:
<img src="shapes.png" usemap="#shapes"
alt="Four shapes are available: a red hollow box, a green circle, a blue triangle, and a yellow four-pointed star.">
<map name="shapes">
<area shape=rect coords="50,50,100,100"> <!-- the hole in the red box -->
<area shape=rect coords="25,25,125,125" href="red.html" alt="Red box.">
<area shape=circle coords="200,75,50" href="green.html" alt="Green circle.">
<area shape=poly coords="325,25,262,125,388,125" href="blue.html" alt="Blue triangle.">
<area shape=poly coords="450,25,435,60,400,75,435,90,450,125,465,90,500,75,465,60"
href="yellow.html" alt="Yellow star.">
</map>
</p></code></pre>
</div>
<div w-nodev>
<h5 id="image-map-processing-model"><span id="processing-model"></span>Processing model</h5>
<p>If an <code>img</code> element has a <code data-x="attr-hyperlink-usemap">usemap</code>
attribute specified, user agents must process it as follows:</p>
<ol>
<li><p>Parse the attribute's value using the <span>rules for parsing a hash-name reference</span>
to a <code>map</code> element, with the element as the context node. This will return either an
element (the <var>map</var>) or null.</p></li>
<li><p>If that returned null, then return. The image is not associated with an image
map after all.</p></li>
<li><p>Otherwise, the user agent must collect all the <code>area</code> elements that are
descendants of the <var>map</var>. Let those be the <var>areas</var>.</p></li>
</ol>
<p>Having obtained the list of <code>area</code> elements that form the image map (the <var>areas</var>), interactive user agents must process the list in one of two ways.</p>
<p>If the user agent intends to show the text that the <code>img</code> element represents, then
it must use the following steps.</p>
<ol>
<li><p>Remove all the <code>area</code> elements in <var>areas</var> that have no <code
data-x="attr-hyperlink-href">href</code> attribute.</p></li>
<li><p>Remove all the <code>area</code> elements in <var>areas</var> that have no <code
data-x="attr-area-alt">alt</code> attribute, or whose <code data-x="attr-area-alt">alt</code>
attribute's value is the empty string, <em>if</em> there is another <code>area</code> element in
<var>areas</var> with the same value in the <code
data-x="attr-hyperlink-href">href</code> attribute and with a non-empty <code
data-x="attr-area-alt">alt</code> attribute.</li>
<li><p>Each remaining <code>area</code> element in <var>areas</var> represents a
<span>hyperlink</span>. Those hyperlinks should all be made available to the user in a manner
associated with the text of the <code>img</code>.</p>
<p>In this context, user agents may represent <code>area</code> and <code>img</code> elements
with no specified <code data-x="">alt</code> attributes, or whose <code data-x="">alt</code>
attributes are the empty string or some other non-visible text, in an
<span>implementation-defined</span> fashion intended to indicate the lack of suitable
author-provided text.</p></li>
</ol>
<p>If the user agent intends to show the image and allow interaction with the image to select
hyperlinks, then the image must be associated with a set of layered shapes, taken from the
<code>area</code> elements in <var>areas</var>, in reverse <span>tree order</span> (so the last
specified <code>area</code> element in the <var>map</var> is the bottom-most shape, and
the first element in the <var>map</var>, in <span>tree order</span>, is the top-most shape).</p>
<p>Each <code>area</code> element in <var>areas</var> must be processed as follows to
obtain a shape to layer onto the image:</p>
<ol>
<li><p>Find the state that the element's <code data-x="attr-area-shape">shape</code> attribute
represents.</p></li>
<li><p>Use the <span>rules for parsing a list of floating-point numbers</span> to parse the
element's <code data-x="attr-area-coords">coords</code> attribute, if it is present, and let the
result be the <var>coords</var> list. If the attribute is absent, let the <var>coords</var> list
be the empty list.</p></li>
<li>
<p>If the number of items in the <var>coords</var> list is less than the minimum number
given for the <code>area</code> element's current state, as per the following table, then the
shape is empty; return.</p>
<table>
<thead>
<tr>
<th>State
<th>Minimum number of items
<tbody>
<tr>
<td><span data-x="attr-area-shape-circle">Circle state</span>
<td>3
<tr>
<td><span data-x="attr-area-shape-default">Default state</span>
<td>0
<tr>
<td><span data-x="attr-area-shape-poly">Polygon state</span>
<td>6
<tr>
<td><span data-x="attr-area-shape-rect">Rectangle state</span>
<td>4
</table>
</li>
<li>
<p>Check for excess items in the <var>coords</var> list as per the entry in the
following list corresponding to the <code data-x="attr-area-shape">shape</code> attribute's
state:</p>
<dl class="switch">
<dt><span data-x="attr-area-shape-circle">Circle state</span></dt>
<dd>Drop any items in the list beyond the third.</dd>
<dt><span data-x="attr-area-shape-default">Default state</span></dt>
<dd>Drop all items in the list.</dd>
<dt><span data-x="attr-area-shape-poly">Polygon state</span></dt>
<dd>Drop the last item if there's an odd number of items.</dd>
<dt><span data-x="attr-area-shape-rect">Rectangle state</span></dt>
<dd>Drop any items in the list beyond the fourth.</dd>
</dl>
</li>
<li><p>If the <code data-x="attr-area-shape">shape</code> attribute represents the <span
data-x="attr-area-shape-rect">rectangle state</span>, and the first number in the list is
numerically greater than the third number in the list, then swap those two numbers around.</p></li>
<li><p>If the <code data-x="attr-area-shape">shape</code> attribute represents the <span
data-x="attr-area-shape-rect">rectangle state</span>, and the second number in the list is
numerically greater than the fourth number in the list, then swap those two numbers around.</p></li>
<li><p>If the <code data-x="attr-area-shape">shape</code> attribute represents the <span
data-x="attr-area-shape-circle">circle state</span>, and the third number in the list is less than
or equal to zero, then the shape is empty; return.</p></li>
<li><p>Now, the shape represented by the element is the one described for the entry in the list
below corresponding to the state of the <code data-x="attr-area-shape">shape</code> attribute:</p>
<dl class="switch">
<dt><span data-x="attr-area-shape-circle">Circle state</span></dt>
<dd>
<p>Let <var>x</var> be the first number in <var>coords</var>, <var>y</var> be the second number, and <var>r</var> be the third number.</p>
<p>The shape is a circle whose center is <var>x</var> <span data-x="'px'">CSS pixels</span>
from the left edge of the image and <var>y</var> <span data-x="'px'">CSS pixels</span> from
the top edge of the image, and whose radius is <var>r</var> <span data-x="'px'">CSS
pixels</span>.</p>
</dd>
<dt><span data-x="attr-area-shape-default">Default state</span></dt>
<dd>
<p>The shape is a rectangle that exactly covers the entire image.</p>
</dd>
<dt><span data-x="attr-area-shape-poly">Polygon state</span></dt>
<dd>
<p>Let <var>x<sub><var>i</var></sub></var> be the <span
data-x="">(2<var>i</var>)</span>th entry in <var>coords</var>, and <var>y<sub><var>i</var></sub></var> be the <span data-x="">(2<var>i</var>+1)</span>th entry in <var>coords</var> (the first entry in <var>coords</var> being the one with index 0).</p>
<p>Let <var>the coordinates</var> be (<var>x<sub><var>i</var></sub></var>, <var>y<sub><var>i</var></sub></var>),
interpreted in <span data-x="'px'">CSS pixels</span> measured from the top left of the image,
for all integer values of <var>i</var> from 0 to <span data-x="">(<var>N</var>/2)-1</span>,
where <var>N</var> is the number of items in <var>coords</var>.</p>
<p>The shape is a polygon whose vertices are given by <var>the coordinates</var>, and whose
interior is established using the even-odd rule. <ref>GRAPHICS</ref></p>
<!--
browsers implement the even-odd rule / even winding rule:
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cimg%20usemap%3D%22%23x%22%20src%3D%22/resources/images/sample%22%3E%0A%3Cmap%20name%3D%22x%22%3E%0A%20%20%3Carea%20shape%3Dpolygon%20coords%3D%220%2C0%200%2C100%20100%2C100%20100%2C2%201%2C2%202%2C1%202%2C99%2099%2C99%2099%2C0%22%20href%3Da%3E%0A%3C/map%3E%0A
-->
</dd>
<dt><span data-x="attr-area-shape-rect">Rectangle state</span></dt>
<dd>
<p>Let <var>x<sub>1</sub></var> be the first number in <var>coords</var>, <var>y<sub>1</sub></var> be the second number, <var>x<sub>2</sub></var> be the third number, and <var>y<sub>2</sub></var> be the fourth number.</p>
<p>The shape is a rectangle whose top-left corner is given by the coordinate (<var>x<sub>1</sub></var>, <var>y<sub>1</sub></var>) and whose
bottom right corner is given by the coordinate (<var>x<sub>2</sub></var>,
<var>y<sub>2</sub></var>), those coordinates being interpreted as <span data-x="'px'">CSS
pixels</span> from the top left corner of the image.</p>
</dd>
</dl>
<p>For historical reasons, the coordinates must be interpreted relative to the
<em>displayed</em> image after any stretching caused by the CSS <span>'width'</span> and
<span>'height'</span> properties (or, for non-CSS browsers, the image element's <code
data-x="">width</code> and <code data-x="">height</code> attributes — CSS browsers map
those attributes to the aforementioned CSS properties).</p>
<p class="note">Browser zoom features and transforms applied using CSS or SVG do not affect the
coordinates.</p>
</li>
</ol>
<p>Pointing device interaction with an image associated with a set of layered shapes per the above
algorithm must result in the relevant user interaction events being first fired to the top-most
shape covering the point that the pointing device indicated, if any, or to the image element
itself, if there is no shape covering that point. User agents may also allow individual
<code>area</code> elements representing <span data-x="hyperlink">hyperlinks</span> to be selected
and activated (e.g. using a keyboard).</p>
<p class="note">Because a <code>map</code> element (and its <code>area</code> elements) can be
associated with multiple <code>img</code> elements, it is possible for an <code>area</code>
element to correspond to multiple <i data-x="focusable area">focusable areas</i> of the
document.</p>
<p>Image maps are <span>live</span>; if the DOM is mutated, then the user agent must act as if it
had rerun the algorithms for image maps.</p>
</div>
<h4 split-filename="embedded-content-other">MathML</h4>
<p>The <span>MathML <code>math</code></span> element falls into the <span>embedded content</span>,
<span>phrasing content</span>, <span>flow content</span>, and <span>palpable content</span>
categories for the purposes of the content models in this specification.</p>
<p>When the <span>MathML <code>annotation-xml</code></span> element contains elements from the
<span>HTML namespace</span>, such elements must all be <span>flow content</span>.</p>
<p>When the MathML token elements (<code data-x="MathML mi">mi</code>, <code data-x="MathML
mo">mo</code>, <code data-x="MathML mn">mn</code>, <code data-x="MathML ms">ms</code>, and <code
data-x="MathML mtext">mtext</code>) are descendants of HTML elements, they may contain
<span>phrasing content</span> elements from the <span>HTML namespace</span>.</p>
<!-- this hooks into https://w3c.github.io/mathml-core/#html-and-svg -->
<div w-nodev>
<!-- apparently we get to define error handling, so: -->
<p>User agents must handle text other than <span>inter-element whitespace</span> found in MathML
elements whose content models do not allow straight text by pretending for the purposes of MathML
content models, layout, and rendering that the text is actually wrapped in a <span>MathML
<code>mtext</code></span> element. (Such text is not, however, conforming.)</p>
<p>User agents must act as if any MathML element whose contents does not match the element's
content model was replaced, for the purposes of MathML layout and rendering, by a <span>MathML
<code>merror</code></span> element containing some appropriate error message.</p>
</div>
<p>The semantics of MathML elements are defined by <cite>MathML</cite> and <span>other applicable
specifications</span>. <ref>MATHML</ref></p>
<div class="example">
<p>Here is an example of the use of MathML in an HTML document:</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<head>
<title>The quadratic formula</title>
</head>
<body>
<h1>The quadratic formula</h1>
<p>
<math>
<mi>x</mi>
<mo>=</mo>
<mfrac>
<mrow>
<mo form="prefix">−</mo> <mi>b</mi>
<mo>±</mo>
<msqrt>
<msup> <mi>b</mi> <mn>2</mn> </msup>
<mo>−</mo>
<mn>4</mn> <mo>⁢</mo> <mi>a</mi> <mo>⁢</mo> <mi>c</mi>
</msqrt>
</mrow>
<mrow>
<mn>2</mn> <mo>⁢</mo> <mi>a</mi>
</mrow>
</mfrac>
</math>
</p>
</body>
</html></code></pre>
</div>
<h4 id="svg-0">SVG</h4>
<p>The <span>SVG <code>svg</code></span> element falls into the <span>embedded content</span>,
<span>phrasing content</span>, <span>flow content</span>, and <span>palpable content</span>
categories for the purposes of the content models in this specification.</p>
<p>When the <span>SVG <code>foreignObject</code></span> element contains elements from the
<span>HTML namespace</span>, such elements must all be <span>flow content</span>.</p>
<p>The content model for the <span>SVG <code>title</code></span> element inside <span>HTML
documents</span> is <span>phrasing content</span>. (This further constrains the requirements given
in <cite>SVG 2</cite>.)</p>
<p>The semantics of SVG elements are defined by <cite>SVG 2</cite> and <span>other applicable
specifications</span>. <ref>SVG</ref></p>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>doc</var> = <var>iframe</var>.<span subdfn data-x="dom-media-getSVGDocument">getSVGDocument</span>()</code></dt>
<dt><code data-x=""><var>doc</var> = <var>embed</var>.<span data-x="dom-media-getSVGDocument">getSVGDocument</span>()</code></dt>
<dt><code data-x=""><var>doc</var> = <var>object</var>.<span data-x="dom-media-getSVGDocument">getSVGDocument</span>()</code></dt>
<dd><p>Returns the <code>Document</code> object, in the case of <code>iframe</code>,
<code>embed</code>, or <code>object</code> elements being used to embed SVG.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLIFrameElement,HTMLEmbedElement,HTMLObjectElement"><code
data-x="dom-media-getSVGDocument">getSVGDocument()</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span>content document</span>.</p></li>
<li><p>If <var>document</var> is non-null and was created by the <span data-x="navigate-xml">page
load processing model for XML files</span> section because the <span data-x="Content-Type
sniffing">computed type of the resource</span> in the <span>navigate</span> algorithm was
<code>image/svg+xml</code>, then return <var>document</var>.</p></li>
<!-- Ideally this would check a property of the document. -->
<li><p>Return null.</p></li>
</ol>
</div>
<h4><dfn>Dimension attributes</dfn></h4>
<p><span w-nodev><strong>Author requirements</strong>:</span> The <dfn element-attr
for="img,iframe,embed,object,source,video"><code data-x="attr-dim-width">width</code></dfn> and
<dfn element-attr for="img,iframe,embed,object,source,video"><code
data-x="attr-dim-height">height</code></dfn> attributes on <code>img</code>, <code>iframe</code>,
<code>embed</code>, <code>object</code>, <code>video</code>, <code>source</code> when the parent
is a <code>picture</code> element and, when their <code data-x="attr-input-type">type</code>
attribute is in the <span data-x="attr-input-type-image">Image Button</span> state,
<code>input</code> elements may be specified to give the dimensions of the visual content of the
element (the width and height respectively, relative to the nominal direction of the output
medium), in <span data-x="'px'">CSS pixels</span>. The attributes, if specified, must have values
that are <span data-x="valid non-negative integer">valid non-negative integers</span>.</p>
<p>The specified dimensions given may differ from the dimensions specified in the resource itself,
since the resource may have a resolution that differs from the CSS pixel resolution. (On screens,
<span data-x="'px'">CSS pixels</span> have a resolution of 96ppi, but in general the CSS pixel
resolution depends on the reading distance.) If both attributes are specified, then one of the
following statements must be true:</p>
<ul>
<li><var>specified width</var> - 0.5 ≤
<var>specified height</var> * <var>target ratio</var> ≤
<var>specified width</var> + 0.5</li>
<li><var>specified height</var> - 0.5 ≤
<var>specified width</var> / <var>target ratio</var> ≤
<var>specified height</var> + 0.5</li>
<li><var>specified height</var> = <var>specified width</var> = 0</li>
</ul>
<p>The <var>target ratio</var> is the ratio of the <span>natural width</span> to the
<span>natural height</span> in the resource. The <var>specified width</var> and <var>specified
height</var> are the values of the <code data-x="attr-dim-width">width</code> and <code
data-x="attr-dim-height">height</code> attributes respectively.</p>
<p>The two attributes must be omitted if the resource in question does not have both a
<span>natural width</span> and a <span>natural height</span>.</p>
<p>If the two attributes are both 0, it indicates that the element is not intended for the user
(e.g. it might be a part of a service to count page views).</p>
<p class="note">The dimension attributes are not intended to be used to stretch the image.</p>
<div w-nodev>
<p><strong>User agent requirements</strong>: User agents are expected to use these attributes <a
href="#dimRendering">as hints for the rendering</a>.</p>
<p>The <dfn attribute
for="HTMLIFrameElement,HTMLEmbedElement,HTMLObjectElement,HTMLSourceElement,HTMLVideoElement"><code
data-x="dom-dim-width">width</code></dfn> and <dfn attribute
for="HTMLIFrameElement,HTMLEmbedElement,HTMLObjectElement,HTMLSourceElement,HTMLVideoElement"><code
data-x="dom-dim-height">height</code></dfn> IDL attributes on the <code>iframe</code>,
<code>embed</code>, <code>object</code>, <code>source</code>, and <code>video</code> elements must
<span>reflect</span> the respective content attributes of the same name.</p>
<p class="note">For <code>iframe</code>, <code>embed</code> and <code>object</code> the IDL
attributes are <code data-x="idl-DOMString">DOMString</code>; for <code>video</code> and
<code>source</code> the IDL attributes are <code data-x="idl-unsigned-long">unsigned
long</code>.</p>
<p class="note">The corresponding IDL attributes for <code data-x="dom-img-height">img</code> and
<code data-x="dom-input-height">input</code> elements are defined in those respective elements'
sections, as they are slightly more specific to those elements' other behaviors.</p>
</div>
<h3 split-filename="tables" id="tables">Tabular data</h3>
<h4>The <dfn element><code>table</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>In this order: optionally a <code>caption</code> element, followed by zero or more
<code>colgroup</code> elements, followed optionally by a <code>thead</code> element, followed by
either zero or more <code>tbody</code> elements or one or more <code>tr</code> elements, followed
optionally by a <code>tfoot</code> element, optionally intermixed with one or more
<span>script-supporting elements</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-table">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-table">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute <span>HTMLTableCaptionElement</span>? <span data-x="dom-table-caption">caption</span>;
<span>HTMLTableCaptionElement</span> <span data-x="dom-table-createCaption">createCaption</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-table-deleteCaption">deleteCaption</span>();
[<span>CEReactions</span>] attribute <span>HTMLTableSectionElement</span>? <span data-x="dom-table-tHead">tHead</span>;
<span>HTMLTableSectionElement</span> <span data-x="dom-table-createTHead">createTHead</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-table-deleteTHead">deleteTHead</span>();
[<span>CEReactions</span>] attribute <span>HTMLTableSectionElement</span>? <span data-x="dom-table-tFoot">tFoot</span>;
<span>HTMLTableSectionElement</span> <span data-x="dom-table-createTFoot">createTFoot</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-table-deleteTFoot">deleteTFoot</span>();
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-table-tBodies">tBodies</span>;
<span>HTMLTableSectionElement</span> <span data-x="dom-table-createTBody">createTBody</span>();
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-table-rows">rows</span>;
<span>HTMLTableRowElement</span> <span data-x="dom-table-insertRow">insertRow</span>(optional long index = -1);
[<span>CEReactions</span>] undefined <span data-x="dom-table-deleteRow">deleteRow</span>(long index);
// <a href="#HTMLTableElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTableElement</code>.</dd>
</dl>
<p>The <code>table</code> element <span>represents</span> data with more than one dimension, in
the form of a <span data-x="concept-table">table</span>.</p>
<p><span w-nodev>The <code>table</code> element takes part in the <span>table
model</span>.</span> Tables have rows, columns, and cells given by their descendants. The rows and
columns form a grid; a table's cells must completely cover that grid without overlap.</p>
<div w-nodev>
<p class="note">Precise rules for determining whether this conformance requirement is met are
described in the description of the <span>table model</span>.</p>
</div>
<p>Authors are encouraged to provide information describing how to interpret complex tables.
Guidance on how to <a href="#table-descriptions-techniques">provide such information</a> is given
below.</p>
<p>Tables must not be used as layout aids. Historically, some web authors have misused tables in
HTML as a way to control their page layout. This usage is non-conforming, because tools attempting
to extract tabular data from such documents would obtain very confusing results. In particular,
users of accessibility tools like screen readers are likely to find it very difficult to navigate
pages with tables used for layout.</p>
<p class="note">There are a variety of alternatives to using HTML tables for layout, such as CSS
grid layout, CSS flexible box layout ("flexbox"), CSS multi-column layout, CSS positioning, and
the CSS table model. <ref>CSS</ref></p>
<div w-nodev>
<hr>
<p>Tables can be complicated to understand and navigate. To help users with this, user agents
should clearly delineate cells in a table from each other, unless the user agent has classified
the table as a (non-conforming) layout table.</p>
</div>
<p class="note">Authors <span w-nodev>and implementers</span> are encouraged to consider
using some of the <a href="#table-layout-techniques">table design techniques</a> described below
to make tables easier to navigate for users.</p>
<div w-nodev>
<p>User agents, especially those that do table analysis on arbitrary content, are encouraged to
find heuristics to determine which tables actually contain data and which are merely being used
for layout. This specification does not define a precise heuristic, but the following are
suggested as possible indicators:</p>
<table>
<thead>
<tr>
<th>Feature
<th>Indication
<tbody>
<tr>
<td>The use of the <code data-x="attr-aria-role">role</code> attribute with the value <code
data-x="attr-aria-role-presentation">presentation</code>
<td>Probably a layout table
<tr>
<td>The use of the non-conforming <code data-x="attr-table-border">border</code> attribute with the non-conforming value 0
<td>Probably a layout table
<tr>
<td>The use of the non-conforming <code data-x="attr-table-cellspacing">cellspacing</code> and
<code data-x="attr-table-cellpadding">cellpadding</code> attributes with the value 0
<td>Probably a layout table
<tbody>
<tr>
<td>The use of <code>caption</code>, <code>thead</code>, or <code>th</code> elements
<td>Probably a non-layout table
<tr>
<td>The use of the <code data-x="attr-tdth-headers">headers</code> and <code data-x="attr-th-scope">scope</code> attributes
<td>Probably a non-layout table
<tr>
<td>The use of the non-conforming <code data-x="attr-table-border">border</code> attribute with a value other than 0
<td>Probably a non-layout table
<tr>
<td>Explicit visible borders set using CSS
<td>Probably a non-layout table
<tbody>
<tr>
<td>The use of the <code data-x="attr-table-summary">summary</code> attribute
<td>Not a good indicator (both layout and non-layout tables have historically been given this attribute)
</table>
<p class="note">It is quite possible that the above suggestions are wrong. Implementers are urged
to provide feedback elaborating on their experiences with trying to create a layout table
detection heuristic.</p>
<p>If a <code>table</code> element has a (non-conforming) <code
data-x="attr-table-summary">summary</code> attribute, and the user agent has not classified the
table as a layout table, the user agent may report the contents of that attribute to the user.</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-caption">caption</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the table's <code>caption</code> element.</p>
<p>Can be set, to replace the <code>caption</code> element.</p>
</dd>
<dt><code data-x=""><var>caption</var> = <var>table</var>.<span subdfn data-x="dom-table-createCaption">createCaption</span>()</code></dt>
<dd><p>Ensures the table has a <code>caption</code> element, and returns it.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-deleteCaption">deleteCaption</span>()</code></dt>
<dd><p>Ensures the table does not have a <code>caption</code> element.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-tHead">tHead</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the table's <code>thead</code> element.</p>
<p>Can be set, to replace the <code>thead</code> element. If the new value is not a
<code>thead</code> element, throws a <span>"<code>HierarchyRequestError</code>"</span>
<code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>thead</var> = <var>table</var>.<span subdfn data-x="dom-table-createTHead">createTHead</span>()</code></dt>
<dd><p>Ensures the table has a <code>thead</code> element, and returns it.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-deleteTHead">deleteTHead</span>()</code></dt>
<dd><p>Ensures the table does not have a <code>thead</code> element.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-tFoot">tFoot</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the table's <code>tfoot</code> element.</p>
<p>Can be set, to replace the <code>tfoot</code> element. If the new value is not a
<code>tfoot</code> element, throws a <span>"<code>HierarchyRequestError</code>"</span>
<code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>tfoot</var> = <var>table</var>.<span subdfn data-x="dom-table-createTFoot">createTFoot</span>()</code></dt>
<dd><p>Ensures the table has a <code>tfoot</code> element, and returns it.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-deleteTFoot">deleteTFoot</span>()</code></dt>
<dd><p>Ensures the table does not have a <code>tfoot</code> element.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-tBodies">tBodies</span></code></dt>
<dd><p>Returns an <code>HTMLCollection</code> of the <code>tbody</code> elements of the
table.</p></dd>
<dt><code data-x=""><var>tbody</var> = <var>table</var>.<span subdfn data-x="dom-table-createTBody">createTBody</span>()</code></dt>
<dd><p>Creates a <code>tbody</code> element, inserts it into the table, and returns it.</p></dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-rows">rows</span></code></dt>
<dd><p>Returns an <code>HTMLCollection</code> of the <code>tr</code> elements of the
table.</p></dd>
<dt><code data-x=""><var>tr</var> = <var>table</var>.<span subdfn data-x="dom-table-insertRow">insertRow</span>([ <var>index</var> ])</code></dt>
<dd>
<p>Creates a <code>tr</code> element, along with a <code>tbody</code> if required, inserts them
into the table at the position given by the argument, and returns the <code>tr</code>.</p>
<p>The position is relative to the rows in the table. The index −1, which is the default
if the argument is omitted, is equivalent to inserting at the end of the table.</p>
<p>If the given position is less than −1 or greater than the number of rows, throws an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>table</var>.<span subdfn data-x="dom-table-deleteRow">deleteRow</span>(<var>index</var>)</code></dt>
<dd>
<p>Removes the <code>tr</code> element with the given position in the table.</p>
<p>The position is relative to the rows in the table. The index −1 is equivalent to
deleting the last row of the table.</p>
<p>If the given position is less than −1 or greater than the index of the last row, or if
there are no rows, throws an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>In all of the following attribute and method definitions, when an element is to be
<dfn>table-created</dfn>, that means to <span>create an element</span> given the
<code>table</code> element's <span>node document</span>, the given local name, and the <span>HTML
namespace</span>.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-caption">caption</code></dfn>
IDL attribute must return, on getting, the first <code>caption</code> element child of the
<code>table</code> element, if any, or null otherwise. On setting, the first <code>caption</code>
element child of the <code>table</code> element, if any, must be removed, and the new value, if
not null, must be inserted as the first node of the <code>table</code> element.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-createCaption">createCaption()</code></dfn> method must return the first
<code>caption</code> element child of the <code>table</code> element, if any; otherwise a new
<code>caption</code> element must be <span>table-created</span>, inserted as the first node of the
<code>table</code> element, and then returned.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-deleteCaption">deleteCaption()</code></dfn> method must remove the first
<code>caption</code> element child of the <code>table</code> element, if any.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-tHead">tHead</code></dfn> IDL
attribute must return, on getting, the first <code>thead</code> element child of the
<code>table</code> element, if any, or null otherwise. On setting, if the new value is null or a
<code>thead</code> element, the first <code>thead</code> element child of the <code>table</code>
element, if any, must be removed, and the new value, if not null, must be inserted immediately
before the first element in the <code>table</code> element that is neither a <code>caption</code>
element nor a <code>colgroup</code> element, if any, or at the end of the table if there are no
such elements. If the new value is neither null nor a <code>thead</code> element, then a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code> must be thrown
instead.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-createTHead">createTHead()</code></dfn> method must return the first
<code>thead</code> element child of the <code>table</code> element, if any; otherwise a new
<code>thead</code> element must be <span>table-created</span> and inserted immediately before the
first element in the <code>table</code> element that is neither a <code>caption</code> element nor
a <code>colgroup</code> element, if any, or at the end of the table if there are no such elements,
and then that new element must be returned.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-deleteTHead">deleteTHead()</code></dfn> method must remove the first
<code>thead</code> element child of the <code>table</code> element, if any.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-tFoot">tFoot</code></dfn> IDL
attribute must return, on getting, the first <code>tfoot</code> element child of the
<code>table</code> element, if any, or null otherwise. On setting, if the new value is null or a
<code>tfoot</code> element, the first <code>tfoot</code> element child of the <code>table</code>
element, if any, must be removed, and the new value, if not null, must be inserted at the end of
the table. If the new value is neither null nor a <code>tfoot</code> element, then a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code> must be thrown
instead.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-createTFoot">createTFoot()</code></dfn> method must return the first
<code>tfoot</code> element child of the <code>table</code> element, if any; otherwise a new
<code>tfoot</code> element must be <span>table-created</span> and inserted at the end of the
table, and then that new element must be returned.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-deleteTFoot">deleteTFoot()</code></dfn> method must remove the first
<code>tfoot</code> element child of the <code>table</code> element, if any.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-tBodies">tBodies</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>table</code> node, whose
filter matches only <code>tbody</code> elements that are children of the <code>table</code>
element.</p>
<p>The <dfn method for="HTMLTableElement"><code
data-x="dom-table-createTBody">createTBody()</code></dfn> method must <span
data-x="table-created">table-create</span> a new <code>tbody</code> element, insert it immediately
after the last <code>tbody</code> element child in the <code>table</code> element, if any, or at
the end of the <code>table</code> element if the <code>table</code> element has no
<code>tbody</code> element children, and then must return the new <code>tbody</code> element.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-rows">rows</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>table</code> node, whose
filter matches only <code>tr</code> elements that are either children of the <code>table</code>
element, or children of <code>thead</code>, <code>tbody</code>, or <code>tfoot</code> elements
that are themselves children of the <code>table</code> element. The elements in the collection
must be ordered such that those elements whose parent is a <code>thead</code> are included first,
in <span>tree order</span>, followed by those elements whose parent is either a <code>table</code>
or <code>tbody</code> element, again in <span>tree order</span>, followed finally by those
elements whose parent is a <code>tfoot</code> element, still in <span>tree order</span>.</p>
<p>The behavior of the <dfn method for="HTMLTableElement"><code
data-x="dom-table-insertRow">insertRow(<var>index</var>)</code></dfn> method depends on the state
of the table. When it is called, the method must act as required by the first item in the
following list of conditions that describes the state of the table and the <var>index</var>
argument:</p>
<dl class="switch">
<dt>If <var>index</var> is less than −1 or greater than the number of elements
in <code data-x="dom-table-rows">rows</code> collection:</dt>
<dd>The method must throw an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</dd>
<dt>If the <code data-x="dom-table-rows">rows</code> collection has zero elements in it, and the
<code>table</code> has no <code>tbody</code> elements in it:</dt>
<dd>The method must <span data-x="table-created">table-create</span> a <code>tbody</code>
element, then <span data-x="table-created">table-create</span> a <code>tr</code> element, then
append the <code>tr</code> element to the <code>tbody</code> element, then append the
<code>tbody</code> element to the <code>table</code> element, and finally return the
<code>tr</code> element.</dd>
<dt>If the <code data-x="dom-table-rows">rows</code> collection has zero elements in it:</dt>
<dd>The method must <span data-x="table-created">table-create</span> a <code>tr</code> element,
append it to the last <code>tbody</code> element in the table, and return the <code>tr</code>
element.</dd>
<dt>If <var>index</var> is −1 or equal to the number of items in <code
data-x="dom-table-rows">rows</code> collection:</dt>
<dd>The method must <span data-x="table-created">table-create</span> a <code>tr</code> element,
and append it to the parent of the last <code>tr</code> element in the <code
data-x="dom-table-rows">rows</code> collection. Then, the newly created <code>tr</code> element
must be returned.</dd>
<dt>Otherwise:</dt>
<dd>The method must <span data-x="table-created">table-create</span> a <code>tr</code> element,
insert it immediately before the <var>index</var>th <code>tr</code> element in the <code
data-x="dom-table-rows">rows</code> collection, in the same parent, and finally must return the
newly created <code>tr</code> element.</dd>
</dl>
<p>When the <dfn method for="HTMLTableElement"><code
data-x="dom-table-deleteRow">deleteRow(<var>index</var>)</code></dfn> method is called, the user
agent must run the following steps:</p>
<ol>
<li><p>If <var>index</var> is less than −1 or greater than or equal to the number of
elements in the <code data-x="dom-table-rows">rows</code> collection, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>index</var> is −1, then <span data-x="concept-node-remove">remove</span>
the last element in the <code data-x="dom-table-rows">rows</code> collection from its parent, or
do nothing if the <code data-x="dom-table-rows">rows</code> collection is empty.</p></li>
<li><p>Otherwise, <span data-x="concept-node-remove">remove</span> the <var>index</var>th element
in the <code data-x="dom-table-rows">rows</code> collection from its parent.</p></li>
</ol>
</div>
<div class="example">
<p>Here is an example of a table being used to mark up a Sudoku puzzle. Observe the lack of
headers, which are not necessary in such a table.</p>
<pre><code class="html"><style>
#sudoku { border-collapse: collapse; border: solid thick; }
#sudoku colgroup, table#sudoku tbody { border: solid medium; }
#sudoku td { border: solid thin; height: 1.4em; width: 1.4em; text-align: center; padding: 0; }
</style>
<h1>Today's Sudoku</h1>
<table id="sudoku">
<colgroup><col><col><col>
<colgroup><col><col><col>
<colgroup><col><col><col>
<tbody>
<tr> <td> 1 <td> <td> 3 <td> 6 <td> <td> 4 <td> 7 <td> <td> 9
<tr> <td> <td> 2 <td> <td> <td> 9 <td> <td> <td> 1 <td>
<tr> <td> 7 <td> <td> <td> <td> <td> <td> <td> <td> 6
<tbody>
<tr> <td> 2 <td> <td> 4 <td> <td> 3 <td> <td> 9 <td> <td> 8
<tr> <td> <td> <td> <td> <td> <td> <td> <td> <td>
<tr> <td> 5 <td> <td> <td> 9 <td> <td> 7 <td> <td> <td> 1
<tbody>
<tr> <td> 6 <td> <td> <td> <td> 5 <td> <td> <td> <td> 2
<tr> <td> <td> <td> <td> <td> 7 <td> <td> <td> <td>
<tr> <td> 9 <td> <td> <td> 8 <td> <td> 2 <td> <td> <td> 5
</table></code></pre>
</div>
<h5 id="table-descriptions-techniques">Techniques for describing tables</h5>
<p id="table-descriptions">For tables that consist of more than just a grid of cells with headers
in the first row and headers in the first column, and for any table in general where the reader
might have difficulty understanding the content, authors should include explanatory information
introducing the table. This information is useful for all users, but is especially useful for
users who cannot see the table, e.g. users of screen readers.</p>
<p>Such explanatory information should introduce the purpose of the table, outline its basic cell
structure, highlight any trends or patterns, and generally teach the user how to use the
table.</p>
<!-- Describing the conclusions of the data in a table is useful to everyone; explaining how to
read the table, if not obvious from the headers alone, is useful to everyone; describing the
structure of the table, if it is easy to grasp visually, might not be useful to everyone, but it
might also not be useful to users who can quickly navigate the table with an accessibility tool.
-->
<p>For instance, the following table:</p>
<table>
<caption>Characteristics with positive and negative sides</caption>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id=r1> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id=r2> Grade
<td> Passing
</table>
<p>...might benefit from a description explaining the way the table is laid out, something like
"Characteristics are given in the second column, with the negative side in the left column and the
positive side in the right column".</p>
<p>There are a variety of ways to include this information, such as:</p>
<dl>
<dt>In prose, surrounding the table</dt>
<dd>
<div class="example"><pre><code class="html"><strong><p>In the following table, characteristics are given in the second
column, with the negative side in the left column and the positive
side in the right column.</p></strong>
<table>
<caption>Characteristics with positive and negative sides</caption>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table></code></pre></div>
</dd>
<dt>In the table's <code>caption</code></dt>
<dd>
<div class="example"><pre><code class="html"><table>
<strong> <caption>
<strong>Characteristics with positive and negative sides.</strong>
<p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p></strong>
</caption>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table></code></pre></div>
</dd>
<dt>In the table's <code>caption</code>, in a <code>details</code> element</dt>
<dd>
<div class="example"><pre><code class="html"><table>
<caption>
<strong>Characteristics with positive and negative sides.</strong>
<strong> <details>
<summary>Help</summary>
<p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p>
</details></strong>
</caption>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table></code></pre></div>
</dd>
<dt>Next to the table, in the same <code>figure</code></dt>
<dd>
<div class="example"><pre><code class="html"><figure>
<figcaption>Characteristics with positive and negative sides</figcaption>
<strong> <p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p></strong>
<table>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table>
</figure></code></pre></div>
</dd>
<dt>Next to the table, in a <code>figure</code>'s <code>figcaption</code></dt>
<dd>
<div class="example"><pre><code class="html"><figure>
<figcaption>
<strong>Characteristics with positive and negative sides</strong>
<strong> <p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p></strong>
</figcaption>
<table>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table>
</figure></code></pre></div>
</dd>
</dl>
<p>Authors may also use other techniques, or combinations of the above techniques, as
appropriate.</p>
<p>The best option, of course, rather than writing a description explaining the way the table is
laid out, is to adjust the table such that no explanation is needed.</p>
<div class="example">
<p>In the case of the table used in the examples above, a simple rearrangement of the table so
that the headers are on the top and left sides removes the need for an explanation as well as
removing the need for the use of <code data-x="attr-tdth-headers">headers</code> attributes:</p>
<pre><code class="html"><table>
<caption>Characteristics with positive and negative sides</caption>
<thead>
<tr>
<th> Characteristic
<th> Negative
<th> Positive
<tbody>
<tr>
<th> Mood
<td> Sad
<td> Happy
<tr>
<th> Grade
<td> Failing
<td> Passing
</table></code></pre>
</div>
<h5 id="table-layout-techniques">Techniques for table design</h5>
<p>Good table design is key to making tables more readable and usable.</p>
<p>In visual media, providing column and row borders and alternating row backgrounds can be very
effective to make complicated tables more readable.</p>
<p>For tables with large volumes of numeric content, using monospaced fonts can help users see
patterns, especially in situations where a user agent does not render the borders. (Unfortunately,
for historical reasons, not rendering borders on tables is a common default.)</p>
<p>In speech media, table cells can be distinguished by reporting the corresponding headers before
reading the cell's contents, and by allowing users to navigate the table in a grid fashion, rather
than serializing the entire contents of the table in source order.</p>
<p>Authors are encouraged to use CSS to achieve these effects.</p>
<div w-nodev>
<p>User agents are encouraged to render tables using these techniques whenever the page does not
use CSS and the table is not classified as a layout table.</p>
</div>
<h4>The <dfn element><code>caption</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the first element child of a <code>table</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no descendant <code>table</code> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-caption">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-caption">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableCaptionElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
// <a href="#HTMLTableCaptionElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTableCaptionElement</code>.</dd>
</dl>
<p>The <code>caption</code> element <span>represents</span> the title of the <code>table</code>
that is its parent, if it has a parent and that is a <code>table</code> element.</p>
<div w-nodev>
<p>The <code>caption</code> element takes part in the <span>table model</span>.</p>
</div>
<p>When a <code>table</code> element is the only content in a <code>figure</code> element other
than the <code>figcaption</code>, the <code>caption</code> element should be omitted in favor of
the <code>figcaption</code>.</p>
<p>A caption can introduce context for a table, making it significantly easier to understand.</p>
<div class="example">
<p>Consider, for instance, the following table:</p>
<table class="dice-example">
<tr> <th> <th> 1 <th> 2 <th> 3 <th> 4 <th> 5 <th> 6
<tr> <th> 1 <td> 2 <td> 3 <td> 4 <td> 5 <td> 6 <td> 7
<tr> <th> 2 <td> 3 <td> 4 <td> 5 <td> 6 <td> 7 <td> 8
<tr> <th> 3 <td> 4 <td> 5 <td> 6 <td> 7 <td> 8 <td> 9
<tr> <th> 4 <td> 5 <td> 6 <td> 7 <td> 8 <td> 9 <td> 10
<tr> <th> 5 <td> 6 <td> 7 <td> 8 <td> 9 <td> 10 <td> 11
<tr> <th> 6 <td> 7 <td> 8 <td> 9 <td> 10 <td> 11 <td> 12
</table>
<p>In the abstract, this table is not clear. However, with a caption giving the table's number
(for <span data-x="referenced">reference</span> in the main prose) and explaining its use, it
makes more sense:</p>
<pre><code class="html"><caption>
<p>Table 1.
<p>This table shows the total score obtained from rolling two
six-sided dice. The first row represents the value of the first die,
the first column the value of the second die. The total is given in
the cell that corresponds to the values of the two dice.
</caption></code></pre>
<p>This provides the user with more context:</p>
<table class="dice-example">
<caption>
<p>Table 1.
<p>This table shows the total score obtained from rolling two
six-sided dice. The first row represents the value of the first
die, the first column the value of the second die. The total is
given in the cell that corresponds to the values of the two dice.
</caption>
<tr> <th> <th> 1 <th> 2 <th> 3 <th> 4 <th> 5 <th> 6
<tr> <th> 1 <td> 2 <td> 3 <td> 4 <td> 5 <td> 6 <td> 7
<tr> <th> 2 <td> 3 <td> 4 <td> 5 <td> 6 <td> 7 <td> 8
<tr> <th> 3 <td> 4 <td> 5 <td> 6 <td> 7 <td> 8 <td> 9
<tr> <th> 4 <td> 5 <td> 6 <td> 7 <td> 8 <td> 9 <td> 10
<tr> <th> 5 <td> 6 <td> 7 <td> 8 <td> 9 <td> 10 <td> 11
<tr> <th> 6 <td> 7 <td> 8 <td> 9 <td> 10 <td> 11 <td> 12
</table>
</div>
<h4>The <dfn element><code>colgroup</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>table</code> element, after any
<code>caption</code> elements and before any <code>thead</code>,
<code>tbody</code>, <code>tfoot</code>, and <code>tr</code>
elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the <code data-x="attr-colgroup-span">span</code> attribute is present: <span data-x="concept-content-nothing">Nothing</span>.</dd>
<dd>If the <code data-x="attr-colgroup-span">span</code> attribute is absent: Zero or more <code>col</code> and <code>template</code> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-colgroup-span">span</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-colgroup">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-colgroup">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableColElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-colgroup-span">span</span>;
// <a href="#HTMLTableColElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTableColElement</code>.</dd>
</dl>
<p>The <code>colgroup</code> element <span>represents</span> a <span
data-x="concept-column-group">group</span> of one or more <span
data-x="concept-column">columns</span> in the <code>table</code> that is its parent, if it has a
parent and that is a <code>table</code> element.</p>
<p>If the <code>colgroup</code> element contains no <code>col</code> elements, then the element
may have a <dfn element-attr for="colgroup"><code data-x="attr-colgroup-span">span</code></dfn>
content attribute specified, whose value must be a <span>valid non-negative integer</span> greater
than zero and less than or equal to 1000.</p>
<div w-nodev>
<p>The <code>colgroup</code> element and its <code data-x="attr-colgroup-span">span</code>
attribute take part in the <span>table model</span>.</p>
<p>The <dfn attribute for="HTMLTableColElement"><code data-x="dom-colgroup-span">span</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name. It is
<span>clamped to the range</span> [1, 1000], and its <span>default value</span> is 1.</p>
</div>
<h4>The <dfn element><code>col</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>colgroup</code> element that doesn't have
a <code data-x="attr-col-span">span</code> attribute.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-col-span">span</code></dd>
<!-- v2: char, to specify the decimal character used in numeric data cells in the column (not header cells) -->
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-col">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-col">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLTableColElement</code>, as defined for <code>colgroup</code> elements.</dd>
</dl>
<p>If a <code>col</code> element has a parent and that is a <code>colgroup</code> element that
itself has a parent that is a <code>table</code> element, then the <code>col</code> element
<span>represents</span> one or more <span data-x="concept-column">columns</span> in the <span
data-x="concept-column-group">column group</span> represented by that <code>colgroup</code>.</p>
<p>The element may have a <dfn element-attr for="col"><code
data-x="attr-col-span">span</code></dfn> content attribute specified, whose value must be a
<span>valid non-negative integer</span> greater than zero and less than or equal to 1000.</p>
<div w-nodev>
<p>The <code>col</code> element and its <code data-x="attr-col-span">span</code> attribute take
part in the <span>table model</span>.</p>
</div>
<h4>The <dfn element><code>tbody</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>table</code> element, after any
<code>caption</code>, <code>colgroup</code>, and
<code>thead</code> elements, but only if there are no
<code>tr</code> elements that are children of the
<code>table</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>tr</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-tbody">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-tbody">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableSectionElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-tbody-rows">rows</span>;
<span>HTMLTableRowElement</span> <span data-x="dom-tbody-insertRow">insertRow</span>(optional long index = -1);
[<span>CEReactions</span>] undefined <span data-x="dom-tbody-deleteRow">deleteRow</span>(long index);
// <a href="#HTMLTableSectionElement-partial">also has obsolete members</a>
};</code></pre>
<p><span w-dev>Uses <code>HTMLTableSectionElement</code>. </span>The
<code>HTMLTableSectionElement</code> interface is also used for <code>thead</code> and
<code>tfoot</code> elements.</p>
</dd>
</dl>
<p>The <code>tbody</code> element <span>represents</span> a <span
data-x="concept-row-group">block</span> of <span data-x="concept-row">rows</span> that consist of a
body of data for the parent <code>table</code> element, if the <code>tbody</code> element has a
parent and it is a <code>table</code>.</p>
<div w-nodev>
<p>The <code>tbody</code> element takes part in the <span>table model</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>tbody</var>.<span subdfn data-x="dom-tbody-rows">rows</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>tr</code> elements of the table
section.</p>
</dd>
<dt><code data-x=""><var>tr</var> = <var>tbody</var>.<span subdfn data-x="dom-tbody-insertRow">insertRow</span>([ <var>index</var> ])</code></dt>
<dd>
<p>Creates a <code>tr</code> element, inserts it into the table section at the position given by
the argument, and returns the <code>tr</code>.</p>
<p>The position is relative to the rows in the table section. The index −1, which is the
default if the argument is omitted, is equivalent to inserting at the end of the table
section.</p>
<p>If the given position is less than −1 or greater than the number of rows, throws an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>tbody</var>.<span subdfn data-x="dom-tbody-deleteRow">deleteRow</span>(<var>index</var>)</code></dt>
<dd>
<p>Removes the <code>tr</code> element with the given position in the table section.</p>
<p>The position is relative to the rows in the table section. The index −1 is equivalent
to deleting the last row of the table section.</p>
<p>If the given position is less than −1 or greater than the index of the last row, or if
there are no rows, throws an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLTableSectionElement"><code
data-x="dom-tbody-rows">rows</code></dfn> attribute must return an <code>HTMLCollection</code>
rooted at this element, whose filter matches only <code>tr</code> elements that are children of
this element.</p>
<p>The <dfn method for="HTMLTableSectionElement"><code
data-x="dom-tbody-insertRow">insertRow(<var>index</var>)</code></dfn> method must act as
follows:</p>
<ol>
<li><p>If <var>index</var> is less than −1 or greater than the number of elements in the
<code data-x="dom-tbody-rows">rows</code> collection, throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>table row</var> be the result of <span data-x="create an element">creating an
element</span> given this element's <span>node document</span>, "<code data-x="">tr</code>", and
the <span>HTML namespace</span>.</p></li>
<li><p>If <var>index</var> is −1 or equal to the number of items in the <code
data-x="dom-tbody-rows">rows</code> collection, then <span
data-x="concept-node-append">append</span> <var>table row</var> to this element.</p></li>
<li><p>Otherwise, <span data-x="concept-node-insert">insert</span> <var>table row</var> as a
child of this element, immediately before the <var>index</var>th <code>tr</code> element in the
<code data-x="dom-tbody-rows">rows</code> collection.</p></li>
<li><p>Return <var>table row</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLTableSectionElement"><code
data-x="dom-tbody-deleteRow">deleteRow(<var>index</var>)</code></dfn> method must, when invoked,
act as follows:
<ol>
<li><p>If <var>index</var> is less than −1 or greater than or equal to the number of
elements in the <code data-x="dom-tbody-rows">rows</code> collection, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>index</var> is −1, then <span data-x="concept-node-remove">remove</span>
the last element in the <code data-x="dom-tbody-rows">rows</code> collection from this
element, or do nothing if the <code data-x="dom-tbody-rows">rows</code> collection is
empty.</p></li>
<li><p>Otherwise, <span data-x="concept-node-remove">remove</span> the <var>index</var>th element
in the <code data-x="dom-tbody-rows">rows</code> collection from this element.</p></li>
</ol>
</div>
<h4>The <dfn element><code>thead</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>table</code> element, after any
<code>caption</code>, and <code>colgroup</code>
elements and before any <code>tbody</code>, <code>tfoot</code>, and
<code>tr</code> elements, but only if there are no other
<code>thead</code> elements that are children of the
<code>table</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>tr</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-thead">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-thead">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLTableSectionElement</code>, as defined for <code>tbody</code> elements.</dd>
</dl>
<p>The <code>thead</code> element <span>represents</span> the <span
data-x="concept-row-group">block</span> of <span data-x="concept-row">rows</span> that consist of
the column labels (headers) and any ancillary non-header cells for the parent <code>table</code>
element, if the <code>thead</code> element has a parent and it is a <code>table</code>.</p>
<div w-nodev>
<p>The <code>thead</code> element takes part in the <span>table model</span>.</p>
</div>
<div class="example">
<p>This example shows a <code>thead</code> element being used. Notice the use of both
<code>th</code> and <code>td</code> elements in the <code>thead</code> element: the first row is
the headers, and the second row is an explanation of how to fill in the table.</p>
<pre><code class="html"><table>
<caption> School auction sign-up sheet </caption>
<strong> <thead>
<tr>
<th><label for=e1>Name</label>
<th><label for=e2>Product</label>
<th><label for=e3>Picture</label>
<th><label for=e4>Price</label>
<tr>
<td>Your name here
<td>What are you selling?
<td>Link to a picture
<td>Your reserve price
</strong> <tbody>
<tr>
<td>Ms Danus
<td>Doughnuts
<td><img src="https://example.com/mydoughnuts.png" title="Doughnuts from Ms Danus">
<td>$45
<tr>
<td><input id=e1 type=text name=who required form=f>
<td><input id=e2 type=text name=what required form=f>
<td><input id=e3 type=url name=pic form=f>
<td><input id=e4 type=number step=0.01 min=0 value=0 required form=f>
</table>
<form id=f action="/auction.cgi">
<input type=button name=add value="Submit">
</form></code></pre>
</div>
<h4>The <dfn element><code>tfoot</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>table</code> element, after any
<code>caption</code>, <code>colgroup</code>, <code>thead</code>,
<code>tbody</code>, and <code>tr</code> elements, but only if there
are no other <code>tfoot</code> elements that are children of the
<code>table</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>tr</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-tfoot">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-tfoot">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLTableSectionElement</code>, as defined for <code>tbody</code> elements.</dd>
</dl>
<p>The <code>tfoot</code> element <span>represents</span> the <span
data-x="concept-row-group">block</span> of <span data-x="concept-row">rows</span> that consist of
the column summaries (footers) for the parent <code>table</code> element, if the
<code>tfoot</code> element has a parent and it is a <code>table</code>.</p>
<div w-nodev>
<p>The <code>tfoot</code> element takes part in the <span>table
model</span>.</p>
</div>
<h4>The <dfn element><code>tr</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>thead</code> element.</dd>
<dd>As a child of a <code>tbody</code> element.</dd>
<dd>As a child of a <code>tfoot</code> element.</dd>
<dd>As a child of a <code>table</code> element, after any
<code>caption</code>, <code>colgroup</code>, and <code>thead</code>
elements, but only if there are no <code>tbody</code> elements that
are children of the <code>table</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>td</code>, <code>th</code>, and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-tr">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-tr">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableRowElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
readonly attribute long <span data-x="dom-tr-rowIndex">rowIndex</span>;
readonly attribute long <span data-x="dom-tr-sectionRowIndex">sectionRowIndex</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-tr-cells">cells</span>;
<span>HTMLTableCellElement</span> <span data-x="dom-tr-insertCell">insertCell</span>(optional long index = -1);
[<span>CEReactions</span>] undefined <span data-x="dom-tr-deleteCell">deleteCell</span>(long index);
// <a href="#HTMLTableRowElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTableRowElement</code>.</dd>
</dl>
<p>The <code>tr</code> element <span>represents</span> a <span data-x="concept-row">row</span> of
<span data-x="concept-cell">cells</span> in a <span data-x="concept-table">table</span>.</p>
<div w-nodev>
<p>The <code>tr</code> element takes part in the <span>table model</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>tr</var>.<span subdfn data-x="dom-tr-rowIndex">rowIndex</span></code></dt>
<dd>
<p>Returns the position of the row in the table's <code data-x="dom-table-rows">rows</code>
list.</p>
<p>Returns −1 if the element isn't in a table.</p>
</dd>
<dt><code data-x=""><var>tr</var>.<span subdfn data-x="dom-tr-sectionRowIndex">sectionRowIndex</span></code></dt>
<dd>
<p>Returns the position of the row in the table section's <code
data-x="dom-tbody-rows">rows</code> list.</p>
<p>Returns −1 if the element isn't in a table section.</p>
</dd>
<dt><code data-x=""><var>tr</var>.<span subdfn data-x="dom-tr-cells">cells</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>td</code> and <code>th</code> elements of
the row.</p>
</dd>
<dt><code data-x=""><var>cell</var> = <var>tr</var>.<span subdfn data-x="dom-tr-insertCell">insertCell</span>([ <var>index</var> ])</code></dt>
<dd>
<p>Creates a <code>td</code> element, inserts it into the table row at the position given by the
argument, and returns the <code>td</code>.</p>
<p>The position is relative to the cells in the row. The index −1, which is the default
if the argument is omitted, is equivalent to inserting at the end of the row.</p>
<p>If the given position is less than −1 or greater than the number of cells, throws an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>tr</var>.<span subdfn data-x="dom-tr-deleteCell">deleteCell</span>(<var>index</var>)</code></dt>
<dd>
<p>Removes the <code>td</code> or <code>th</code> element with the given position in the
row.</p>
<p>The position is relative to the cells in the row. The index −1 is equivalent to
deleting the last cell of the row.</p>
<p>If the given position is less than −1 or greater than the index of the last cell, or
if there are no cells, throws an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLTableRowElement"><code
data-x="dom-tr-rowIndex">rowIndex</code></dfn> attribute must, if this element has a parent
<code>table</code> element, or a parent <code>tbody</code>, <code>thead</code>, or
<code>tfoot</code> element and a <em>grandparent</em> <code>table</code> element, return the index
of this <code>tr</code> element in that <code>table</code> element's <code
data-x="dom-table-rows">rows</code> collection. If there is no such <code>table</code> element,
then the attribute must return −1.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code
data-x="dom-tr-sectionRowIndex">sectionRowIndex</code></dfn> attribute must, if this element has a
parent <code>table</code>, <code>tbody</code>, <code>thead</code>, or <code>tfoot</code> element,
return the index of the <code>tr</code> element in the parent element's <code
data-x="">rows</code> collection (for tables, that's <code>HTMLTableElement</code>'s <code
data-x="dom-table-rows">rows</code> collection; for table sections, that's
<code>HTMLTableSectionElement</code>'s <code data-x="dom-tbody-rows">rows</code>
collection). If there is no such parent element, then the attribute must return −1.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-cells">cells</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at this <code>tr</code> element, whose
filter matches only <code>td</code> and <code>th</code> elements that are children of the
<code>tr</code> element.</p>
<p>The <dfn method for="HTMLTableRowElement"><code
data-x="dom-tr-insertCell">insertCell(<var>index</var>)</code></dfn> method must act as
follows:</p>
<ol>
<li><p>If <var>index</var> is less than −1 or greater than the number of elements in
the <code data-x="dom-tr-cells">cells</code> collection, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>table cell</var> be the result of <span data-x="create an element">creating an
element</span> given this <code>tr</code> element's <span>node document</span>, "<code
data-x="">td</code>", and the <span>HTML namespace</span>.</p></li>
<li><p>If <var>index</var> is equal to −1 or equal to the number of items in <code
data-x="dom-tr-cells">cells</code> collection, then <span
data-x="concept-node-append">append</span> <var>table cell</var> to this <code>tr</code>
element.</p></li>
<li><p>Otherwise, <span data-x="concept-node-insert">insert</span> <var>table cell</var> as a
child of this <code>tr</code> element, immediately before the <var>index</var>th <code>td</code>
or <code>th</code> element in the <code data-x="dom-tr-cells">cells</code> collection.</p></li>
<li><p>Return <var>table cell</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLTableRowElement"><code
data-x="dom-tr-deleteCell">deleteCell(<var>index</var>)</code></dfn> method must act as
follows:</p>
<ol>
<li><p>If <var>index</var> is less than −1 or greater than or equal to the number of
elements in the <code data-x="dom-tr-cells">cells</code> collection, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>index</var> is −1, then <span data-x="concept-node-remove">remove</span>
the last element in the <code data-x="dom-tr-cells">cells</code> collection from its
parent, or do nothing if the <code data-x="dom-tr-cells">cells</code> collection is
empty.</p></li>
<li><p>Otherwise, <span data-x="concept-node-remove">remove</span> the <var>index</var>th element
in the <code data-x="dom-tr-cells">cells</code> collection from its parent.</p></li>
</ol>
</div>
<h4>The <dfn element><code>td</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>tr</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-tdth-colspan">colspan</code></dd>
<dd><code data-x="attr-tdth-rowspan">rowspan</code></dd>
<dd><code data-x="attr-tdth-headers">headers</code></dd>
<!-- v2 char, to specify the decimal character used in numeric cells -->
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-td">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-td">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTableCellElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-tdth-colSpan">colSpan</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-tdth-rowSpan">rowSpan</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-headers">headers</span>;
readonly attribute long <span data-x="dom-tdth-cellIndex">cellIndex</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-th-scope">scope</span>; // only conforming for th elements
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-th-abbr">abbr</span>; // only conforming for th elements
// <a href="#HTMLTableCellElement-partial">also has obsolete members</a>
};</code></pre>
<p><span w-dev>Uses <code>HTMLTableCellElement</code>. </span>The
<code>HTMLTableCellElement</code> interface is also used for <code>th</code> elements.</p>
</dd>
</dl>
<p>The <code>td</code> element <span>represents</span> a data <span
data-x="concept-cell">cell</span> in a table.</p>
<div w-nodev>
<p>The <code>td</code> element and its <code data-x="attr-tdth-colspan">colspan</code>, <code
data-x="attr-tdth-rowspan">rowspan</code>, and <code data-x="attr-tdth-headers">headers</code>
attributes take part in the <span>table model</span>.</p>
<p>User agents, especially in non-visual environments or where displaying the table as a 2D grid
is impractical, may give the user context for the cell when rendering the contents of a cell; for
instance, giving its position in the <span>table model</span>, or listing the cell's header cells
(as determined by the <span>algorithm for assigning header cells</span>). When a cell's header
cells are being listed, user agents may use the value of <code data-x="attr-th-abbr">abbr</code>
attributes on those header cells, if any, instead of the contents of the header cells
themselves.</p>
</div>
<div class="example">
<p>In this example, we see a snippet of a web application consisting of a grid of editable cells
(essentially a simple spreadsheet). One of the cells has been configured to show the sum of the
cells above it. Three have been marked as headings, which use <code>th</code> elements instead of
<code>td</code> elements. A script would attach event handlers to these elements to maintain the
total.</p>
<pre><code class="html"><table>
<tr>
<th><input value="Name">
<th><input value="Paid ($)">
<tr>
<td><input value="Jeff">
<td><input value="14">
<tr>
<td><input value="Britta">
<td><input value="9">
<tr>
<td><input value="Abed">
<td><input value="25">
<tr>
<td><input value="Shirley">
<td><input value="2">
<tr>
<td><input value="Annie">
<td><input value="5">
<tr>
<td><input value="Troy">
<td><input value="5">
<tr>
<td><input value="Pierce">
<td><input value="1000">
<tr>
<th><input value="Total">
<td><output value="1060">
</table></code></pre>
</div>
<h4>The <dfn element><code>th</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>tr</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>header</code>, <code>footer</code>,
<span>sectioning content</span>, or <span>heading content</span> descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-tdth-colspan">colspan</code></dd>
<dd><code data-x="attr-tdth-rowspan">rowspan</code></dd>
<dd><code data-x="attr-tdth-headers">headers</code></dd>
<dd><code data-x="attr-th-scope">scope</code></dd>
<dd><code data-x="attr-th-abbr">abbr</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-th">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-th">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLTableCellElement</code>, as defined for <code>td</code> elements.</dd>
</dl>
<p>The <code>th</code> element <span>represents</span> a header <span
data-x="concept-cell">cell</span> in a table.</p>
<p>The <code>th</code> element may have a <dfn element-attr for="th"><code
data-x="attr-th-scope">scope</code></dfn> content attribute specified.</p>
<p>The <code data-x="attr-th-scope">scope</code> attribute is an <span>enumerated attribute</span>
with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
</thead>
<tbody>
<tr>
<td><dfn attr-value for="th/scope"><code data-x="attr-th-scope-row">row</code></dfn>
<td><dfn data-x="attr-th-scope-row-state">row</dfn>
<td>The header cell applies to some of the subsequent cells in the same row(s).
<tr>
<td><dfn attr-value for="th/scope"><code data-x="attr-th-scope-col">col</code></dfn>
<td><dfn data-x="attr-th-scope-column-state">column</dfn>
<td>The header cell applies to some of the subsequent cells in the same column(s).
<tr>
<td><dfn attr-value for="th/scope"><code data-x="attr-th-scope-rowgroup">rowgroup</code></dfn>
<td><dfn data-x="attr-th-scope-rowgroup-state">row group</dfn>
<td>The header cell applies to all the remaining cells in the row group.
<tr>
<td><dfn attr-value for="th/scope"><code data-x="attr-th-scope-colgroup">colgroup</code></dfn>
<td><dfn data-x="attr-th-scope-colgroup-state">column group</dfn>
<td>The header cell applies to all the remaining cells in the column group.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-th-scope-auto-state">auto</dfn> state. (In this state the header cell applies to a
set of cells selected based on context.)</p>
<p>A <code>th</code> element's <code data-x="attr-th-scope">scope</code> attribute must not be in
the <span data-x="attr-th-scope-rowgroup-state">row group</span> state if the element is not anchored in
a <span data-x="concept-row-group">row group</span>, nor in the <span
data-x="attr-th-scope-colgroup-state">column group</span> state if the element is not anchored in a
<span data-x="concept-column-group">column group</span>.
<p>The <code>th</code> element may have an <dfn element-attr for="th"><code
data-x="attr-th-abbr">abbr</code></dfn> content attribute specified. Its value must be an
alternative label for the header cell, to be used when referencing the cell in other contexts
(e.g. when describing the header cells that apply to a data cell). It is typically an abbreviated
form of the full header cell, but can also be an expansion, or merely a different phrasing.</p>
<div w-nodev>
<p>The <code>th</code> element and its <code data-x="attr-tdth-colspan">colspan</code>, <code
data-x="attr-tdth-rowspan">rowspan</code>, <code data-x="attr-tdth-headers">headers</code>, and
<code data-x="attr-th-scope">scope</code> attributes take part in the <span>table model</span>.</p>
</div>
<div class="example">
<p>The following example shows how the <code data-x="attr-th-scope">scope</code> attribute's <code
data-x="attr-th-scope-rowgroup">rowgroup</code> value affects which data cells a header cell
applies to.</p>
<p>Here is a markup fragment showing a table:</p>
<pre><code class="html"><table>
<thead>
<tr> <th> ID <th> Measurement <th> Average <th> Maximum
<tbody>
<tr> <td> <th scope=rowgroup> Cats <td> <td>
<tr> <td> 93 <th> Legs <td> 3.5 <td> 4
<tr> <td> 10 <th> Tails <td> 1 <td> 1
<tbody>
<tr> <td> <th scope=rowgroup> English speakers <td> <td>
<tr> <td> 32 <th> Legs <td> 2.67 <td> 4
<tr> <td> 35 <th> Tails <td> 0.33 <td> 1
</table></code></pre>
<p>This would result in the following table:</p>
<table>
<thead>
<tr> <th> ID <th> Measurement <th> Average <th> Maximum
<tbody>
<tr> <td> <th scope=rowgroup> Cats <td> <td>
<tr> <td> 93 <th> Legs <td> 3.5 <td> 4
<tr> <td> 10 <th> Tails <td> 1 <td> 1
<tbody>
<tr> <td> <th scope=rowgroup> English speakers <td> <td>
<tr> <td> 32 <th> Legs <td> 2.67 <td> 4
<tr> <td> 35 <th> Tails <td> 0.33 <td> 1
</table>
<p>The headers in the first row all apply directly down to the rows in their column.</p>
<p>The headers with a <code data-x="attr-th-scope">scope</code> attribute in the <span
data-x="attr-th-scope-rowgroup-state">rowgroup</span> state apply to all the cells in their row
group other than the cells in the first column.</p>
<p>The remaining headers apply just to the cells to the right of them.</p>
<!-- image source: https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=151 -->
<img src="/images/table-scope-diagram.png" width="459" height="256" alt=""><!-- (alt is empty because the diagram is completely described by the previous paragraphs) -->
</div>
<h4>Attributes common to <code>td</code> and <code>th</code> elements</h4>
<p>The <code>td</code> and <code>th</code> elements may have a <dfn element-attr for="td,th"><code
data-x="attr-tdth-colspan">colspan</code></dfn> content attribute specified, whose value must be a
<span>valid non-negative integer</span> greater than zero and less than or equal to 1000.</p>
<p>The <code>td</code> and <code>th</code> elements may also have a <dfn element-attr
for="td,th"><code data-x="attr-tdth-rowspan">rowspan</code></dfn> content attribute specified,
whose value must be a <span>valid non-negative integer</span> less than or equal to 65534. For
this attribute, the value zero means that the cell is to span all the remaining rows in the row
group.</p> <!-- only in no-quirks and limited-quirks mode though, for back compat! -->
<p>These attributes give the number of columns and rows respectively that the cell is to span.
These attributes must not be used to overlap cells<span w-nodev>, as described in the
description of the <span>table model</span></span>.</p> <!-- conformance criteria for determining
when this is violated are given in the processing model -->
<hr>
<p>The <code>td</code> and <code>th</code> element may have a <dfn element-attr for="td,th"><code
data-x="attr-tdth-headers">headers</code></dfn> content attribute specified. The <code
data-x="attr-tdth-headers">headers</code> attribute, if specified, must contain a string
consisting of an <span>unordered set of unique space-separated tokens</span>, none of which are
<span>identical to</span> another token and each of which must have the value of an <span
data-x="concept-id">ID</span> of a <code>th</code> element taking part in the same <span
data-x="concept-table">table</span> as the <code>td</code> or <code>th</code> element<span
w-nodev> (as defined by the <span>table model</span>)</span>.</p>
<p>A <code>th</code> element with <span data-x="concept-id">ID</span> <var>id</var> is
said to be <i>directly targeted</i> by all <code>td</code> and <code>th</code> elements in the
same <span data-x="concept-table">table</span> that have <code
data-x="attr-tdth-headers">headers</code> attributes whose values include as one of their tokens
the <span data-x="concept-id">ID</span> <var>id</var>. A <code>th</code> element <var>A</var> is said to be <i>targeted</i> by a <code>th</code> or <code>td</code> element
<var>B</var> if either <var>A</var> is <i>directly targeted</i> by <var>B</var> or if there exists an element <var>C</var> that is itself
<i>targeted</i> by the element <var>B</var> and <var>A</var> is <i>directly
targeted</i> by <var>C</var>.</p>
<p>A <code>th</code> element must not be <i>targeted</i> by itself.</p>
<div w-nodev>
<p>The <code data-x="attr-tdth-colspan">colspan</code>, <code
data-x="attr-tdth-rowspan">rowspan</code>, and <code data-x="attr-tdth-headers">headers</code>
attributes take part in the <span>table model</span>.</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>cell</var>.<span subdfn data-x="dom-tdth-cellIndex">cellIndex</span></code></dt>
<dd>
<p>Returns the position of the cell in the row's <code data-x="dom-tr-cells">cells</code> list.
This does not necessarily correspond to the <var>x</var>-position of the cell in the table,
since earlier cells might cover multiple rows or columns.</p>
<p>Returns −1 if the element isn't in a row.</p>
</dd>
</dl>
<div w-nodev>
<!--
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1699
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1700
-->
<!-- For colSpan/rowSpan rationale: https://github.com/whatwg/html/issues/1198 -->
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-colSpan">colSpan</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-tdth-colspan">colspan</code> content attribute. It is <span>clamped to the
range</span> [1, 1000], and its <span>default value</span> is 1.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-rowSpan">rowSpan</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-tdth-rowspan">rowspan</code> content attribute. It is <span>clamped to the
range</span> [0, 65534], and its <span>default value</span> is 1.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-headers">headers</code></dfn> IDL attribute must <span>reflect</span> the content
attribute of the same name.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-cellIndex">cellIndex</code></dfn> IDL attribute must, if the element has a parent
<code>tr</code> element, return the index of the cell's element in the parent element's <code
data-x="dom-tr-cells">cells</code> collection. If there is no such parent element, then the
attribute must return −1.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code data-x="dom-th-scope">scope</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name, <span>limited to
only known values</span>.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code data-x="dom-th-abbr">abbr</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>
</div>
<div w-nodev>
<h4 id="table-processing-model"><span id="processing-model-2"></span>Processing model</h4>
<p>The various table elements and their content attributes together define the <dfn>table
model</dfn>.</p>
<p>A <dfn data-x="concept-table">table</dfn> consists of cells aligned on a two-dimensional grid of
<dfn data-x="concept-slots">slots</dfn> with coordinates (<var>x</var>, <var>y</var>). The grid is finite, and is either empty or has one or more slots. If the grid
has one or more slots, then the <var>x</var> coordinates are always in the range <span
data-x="">0 ≤ <var>x</var> < <var>x<sub>width</sub></var></span>, and the <var>y</var> coordinates are always in the
range <span data-x="">0 ≤ <var>y</var> < <var>y<sub>height</sub></var></span>. If one or both of <var>x<sub>width</sub></var> and <var>y<sub>height</sub></var> are zero, then the
table is empty (has no slots). Tables correspond to <code>table</code> elements.</p>
<p>A <dfn data-x="concept-cell">cell</dfn> is a set of slots anchored at a slot (<var>cell<sub>x</sub></var>, <var>cell<sub>y</sub></var>), and with
a particular <var>width</var> and <var>height</var> such that the cell covers
all the slots with coordinates (<var>x</var>, <var>y</var>) where <span
data-x=""><var>cell<sub>x</sub></var> ≤ <var>x</var> < <var>cell<sub>x</sub></var>+<var>width</var></span> and <var>cell<sub>y</sub></var> ≤ <var>y</var> < <var>cell<sub>y</sub></var>+<var>height</var>. Cells can either be <em>data cells</em>
or <em>header cells</em>. Data cells correspond to <code>td</code> elements, and header cells
correspond to <code>th</code> elements. Cells of both types can have zero or more associated
header cells.</p>
<p>It is possible, in certain error cases, for two cells to occupy the same slot.</p>
<p>A <dfn data-x="concept-row">row</dfn> is a complete set of slots from <var>x</var>=0 to <var>x</var>=<var>x<sub>width</sub></var>-1, for a particular value of <var>y</var>. Rows usually
correspond to <code>tr</code> elements, though a <span data-x="concept-row-group">row group</span>
can have some implied <span data-x="concept-row">rows</span> at the end in some cases involving
<span data-x="concept-cell">cells</span> spanning multiple rows.</p>
<p>A <dfn data-x="concept-column">column</dfn> is a complete set of slots from <var>y</var>=0 to <var>y</var>=<var>y<sub>height</sub></var>-1, for a particular value of <var>x</var>. Columns can
correspond to <code>col</code> elements. In the absence of <code>col</code> elements, columns are
implied.</p>
<p>A <dfn data-x="concept-row-group">row group</dfn> is a set of <span
data-x="concept-row">rows</span> anchored at a slot (0, <var>group<sub>y</sub></var>) with a particular <var>height</var> such that the row group
covers all the slots with coordinates (<var>x</var>, <var>y</var>) where <span
data-x="">0 ≤ <var>x</var> < <var>x<sub>width</sub></var></span> and <var>group<sub>y</sub></var> ≤ <var>y</var> < <var>group<sub>y</sub></var>+<var>height</var>. Row groups correspond to
<code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements. Not every row is
necessarily in a row group.</p>
<p>A <dfn data-x="concept-column-group">column group</dfn> is a set of <span
data-x="concept-column">columns</span> anchored at a slot (<var>group<sub>x</sub></var>, 0) with a particular <var>width</var> such that the column group
covers all the slots with coordinates (<var>x</var>, <var>y</var>) where <span
data-x=""><var>group<sub>x</sub></var> ≤ <var>x</var> < <var>group<sub>x</sub></var>+<var>width</var></span> and <span data-x="">0 ≤ <var>y</var> < <var>y<sub>height</sub></var></span>. Column
groups correspond to <code>colgroup</code> elements. Not every column is necessarily in a column
group.</p>
<p><span data-x="concept-row-group">Row groups</span> cannot overlap each other. Similarly, <span
data-x="concept-column-group">column groups</span> cannot overlap each other.</p>
<p>A <span data-x="concept-cell">cell</span> cannot cover slots that are from two or more <span
data-x="concept-row-group">row groups</span>. It is, however, possible for a cell to be in multiple
<span data-x="concept-column-group">column groups</span>. All the slots that form part of one cell
are part of zero or one <span data-x="concept-row-group">row groups</span> and zero or more <span
data-x="concept-column-group">column groups</span>.</p>
<p>In addition to <span data-x="concept-cell">cells</span>, <span
data-x="concept-column">columns</span>, <span data-x="concept-row">rows</span>, <span
data-x="concept-row-group">row groups</span>, and <span data-x="concept-column-group">column
groups</span>, <span data-x="concept-table">tables</span> can have a <code>caption</code> element
associated with them. This gives the table a heading, or legend.</p>
<p>A <dfn>table model error</dfn> is an error with the data represented by <code>table</code>
elements and their descendants. Documents must not have table model errors.</p>
<h5>Forming a table</h5>
<p>To determine which elements correspond to which slots in a <span
data-x="concept-table">table</span> associated with a <code>table</code> element, to determine the
dimensions of the table (<var>x<sub>width</sub></var> and <var>y<sub>height</sub></var>), and to determine if there are any <span data-x="table model
error">table model errors</span>, user agents must use the following algorithm:</p>
<ol>
<li>
<p>Let <var>x<sub>width</sub></var> be zero.</p>
</li>
<li>
<p>Let <var>y<sub>height</sub></var> be zero.</p>
</li>
<li>
<p>Let <var>pending <code>tfoot</code> elements</var> be a list of <code>tfoot</code>
elements, initially empty.</p>
</li>
<li>
<p>Let <var>the table</var> be the <span data-x="concept-table">table</span> represented
by the <code>table</code> element. The <var>x<sub>width</sub></var> and <var>y<sub>height</sub></var> variables give <var>the table</var>'s
dimensions. <var>The table</var> is initially empty.</p>
</li>
<li>
<!-- this step is here just so that we can be sure to have a first element in the next step, so
that we can set up the "advance" exception-handling thingy below; otherwise it'd be more
complicated. it's not a perf optimization per se. -->
<p>If the <code>table</code> element has no children elements, then return <var>the
table</var> (which will be empty).</p>
</li>
<li>
<p>Associate the first <code>caption</code> element child of the <code>table</code> element with
<var>the table</var>. If there are no such children, then it has no associated
<code>caption</code> element.</p>
</li>
<li>
<p>Let the <var>current element</var> be the first element child of the
<code>table</code> element.</p>
<p>If a step in this algorithm ever requires the <var>current element</var> to be <dfn
data-x="concept-table-advance">advanced to the next child of the <code>table</code></dfn> when
there is no such next child, then the user agent must jump to the step labeled <i>end</i>, near
the end of this algorithm.</p>
</li>
<li>
<p>While the <var>current element</var> is not one of the following elements, <span
data-x="concept-table-advance">advance</span> the <var>current element</var> to the next
child of the <code>table</code>:</p>
<ul class="brief">
<li><code>colgroup</code></li>
<li><code>thead</code></li>
<li><code>tbody</code></li>
<li><code>tfoot</code></li>
<li><code>tr</code></li>
</ul>
</li>
<li>
<p>If the <var>current element</var> is a <code>colgroup</code>, follow these
substeps:</p>
<ol>
<li>
<p><i>Column groups</i>: Process the <var>current element</var> according to the
appropriate case below:</p>
<dl class="switch">
<dt>If the <var>current element</var> has any <code>col</code> element children</dt>
<dd>
<p>Follow these steps:</p>
<ol>
<li>
<p>Let <var>x<sub>start</sub></var> have the value of <span
data-x=""><var>x<sub>width</sub></var></span>.</p>
</li>
<li>
<p>Let the <var>current column</var> be the first <code>col</code> element child
of the <code>colgroup</code> element.</p>
</li>
<li>
<p><i>Columns</i>: If the <var>current column</var> <code>col</code> element has
a <code data-x="attr-col-span">span</code> attribute, then parse its value using the
<span>rules for parsing non-negative integers</span>.</p>
<p>If the result of parsing the value is not an error or zero, then let <var>span</var> be that value.</p>
<p>Otherwise, if the <code>col</code> element has no <code
data-x="attr-col-span">span</code> attribute, or if trying to parse the attribute's value
resulted in an error or zero, then let <var>span</var> be 1.</p>
<p>If <var>span</var> is greater than 1000, let it be 1000 instead.</p>
</li>
<li>
<p>Increase <var>x<sub>width</sub></var> by <var>span</var>.</p>
</li>
<li>
<p>Let the last <var>span</var> <span data-x="concept-column">columns</span> in
<var>the table</var> correspond to the <var>current column</var>
<code>col</code> element.</p>
</li>
<li>
<p>If <var>current column</var> is not the last <code>col</code> element child of
the <code>colgroup</code> element, then let the <var>current column</var> be the
next <code>col</code> element child of the <code>colgroup</code> element, and return to
the step labeled <i>columns</i>.</p>
</li>
<li>
<p>Let all the last <span data-x="concept-column">columns</span> in <var>the
table</var> from <span data-x="">x=<var>x<sub>start</sub></var></span> to
<span data-x="">x=<var>x<sub>width</sub></var>-1</span> form a new <span
data-x="concept-column-group">column group</span>, anchored at the slot (<var>x<sub>start</sub></var>, 0), with width <var>x<sub>width</sub></var>-<var>x<sub>start</sub></var>, corresponding to the <code>colgroup</code> element.</p>
</li>
</ol>
</dd>
<dt>If the <var>current element</var> has no <code>col</code> element children</dt>
<dd>
<ol>
<li>
<p>If the <code>colgroup</code> element has a <code data-x="attr-colgroup-span">span</code>
attribute, then parse its value using the <span>rules for parsing non-negative
integers</span>.</p>
<p>If the result of parsing the value is not an error or zero, then let <var>span</var> be that value.</p>
<p>Otherwise, if the <code>colgroup</code> element has no <code
data-x="attr-colgroup-span">span</code> attribute, or if trying to parse the attribute's
value resulted in an error or zero, then let <var>span</var> be 1.</p>
<p>If <var>span</var> is greater than 1000, let it be 1000 instead.</p>
</li>
<li>
<p>Increase <var>x<sub>width</sub></var> by <var>span</var>.</p>
</li>
<li>
<p>Let the last <var>span</var> <span data-x="concept-column">columns</span> in
<var>the table</var> form a new <span data-x="concept-column-group">column
group</span>, anchored at the slot (<var>x<sub>width</sub></var>-<var>span</var>, 0), with width <var>span</var>, corresponding to the <code>colgroup</code> element.</p>
</li>
</ol>
</dd>
</dl>
</li>
<li>
<p><span data-x="concept-table-advance">Advance</span> the <var>current element</var>
to the next child of the <code>table</code>.</p>
</li>
<li>
<p>While the <var>current element</var> is not one of the following elements, <span
data-x="concept-table-advance">advance</span> the <var>current element</var> to the
next child of the <code>table</code>:</p>
<ul class="brief">
<li><code>colgroup</code></li>
<li><code>thead</code></li>
<li><code>tbody</code></li>
<li><code>tfoot</code></li>
<li><code>tr</code></li>
</ul>
</li>
<li>
<p>If the <var>current element</var> is a <code>colgroup</code> element, jump to the
step labeled <i>column groups</i> above.</p>
</li>
</ol>
</li>
<li>
<p>Let <var>y<sub>current</sub></var> be zero.</p>
</li>
<li>
<p>Let the <var>list of downward-growing cells</var> be an empty list.</p>
</li>
<li>
<p><i>Rows</i>: While the <var>current element</var> is not one of the following
elements, <span data-x="concept-table-advance">advance</span> the <var>current
element</var> to the next child of the <code>table</code>:</p>
<ul class="brief">
<li><code>thead</code></li>
<li><code>tbody</code></li>
<li><code>tfoot</code></li>
<li><code>tr</code></li>
</ul>
</li>
<li>
<p>If the <var>current element</var> is a <code>tr</code>, then run the <span>algorithm
for processing rows</span>, <span data-x="concept-table-advance">advance</span> the <var>current element</var> to the next child of the <code>table</code>, and return to the
step labeled <i>rows</i>.</p>
</li>
<li>
<p>Run the <span>algorithm for ending a row group</span>.</p>
</li>
<li>
<p>If the <var>current element</var> is a <code>tfoot</code>, then add that element to
the list of <var>pending <code>tfoot</code> elements</var>, <span
data-x="concept-table-advance">advance</span> the <var>current element</var> to the next
child of the <code>table</code>, and return to the step labeled <i>rows</i>.</p>
</li>
<li>
<p>The <var>current element</var> is either a <code>thead</code> or a
<code>tbody</code>.</p>
<p>Run the <span>algorithm for processing row groups</span>.</p>
</li>
<li>
<p><span data-x="concept-table-advance">Advance</span> the <var>current element</var> to
the next child of the <code>table</code>.</p>
</li>
<li>
<p>Return to the step labeled <i>rows</i>.</p>
</li>
<li>
<p><i>End</i>: For each <code>tfoot</code> element in the list of <var>pending
<code>tfoot</code> elements</var>, in <span>tree order</span>, run the <span>algorithm for processing row
groups</span>.</p>
</li>
<li>
<p>If there exists a <span data-x="concept-row">row</span> or <span
data-x="concept-column">column</span> in <var>the table</var> containing only <span
data-x="concept-slots">slots</span> that do not have a <span data-x="concept-cell">cell</span>
anchored to them, then this is a <span>table model error</span>.</p>
</li>
<li>
<p>Return <var>the table</var>.</p>
</li>
</ol>
<p>The <dfn>algorithm for processing row groups</dfn>, which is invoked by the set of steps above
for processing <code>thead</code>, <code>tbody</code>, and <code>tfoot</code> elements, is:</p>
<ol>
<li>
<p>Let <var>y<sub>start</sub></var> have the value of <var>y<sub>height</sub></var>.</p>
</li>
<li>
<p>For each <code>tr</code> element that is a child of the element being processed, in tree
order, run the <span>algorithm for processing rows</span>.</p>
</li>
<li>
<!-- if we added any rows, make them part of a row group -->
<p>If <var>y<sub>height</sub></var> > <var>y<sub>start</sub></var>, then let all the last <span
data-x="concept-row">rows</span> in <var>the table</var> from <span data-x="">y=<var>y<sub>start</sub></var></span> to <span data-x="">y=<var>y<sub>height</sub></var>-1</span> form a new <span data-x="concept-row-group">row
group</span>, anchored at the slot with coordinate (0, <var>y<sub>start</sub></var>), with height <var>y<sub>height</sub></var>-<var>y<sub>start</sub></var>, corresponding
to the element being processed.</p>
</li>
<li>
<p>Run the <span>algorithm for ending a row group</span>.</p>
</li>
</ol>
<p>The <dfn>algorithm for ending a row group</dfn>, which is invoked by the set of steps above
when starting and ending a block of rows, is:</p>
<ol>
<li>
<p>While <var>y<sub>current</sub></var> is less than <var>y<sub>height</sub></var>, follow these steps:</p>
<ol>
<li>
<p>Run the <span>algorithm for growing downward-growing cells</span>.</p>
</li>
<li>
<p>Increase <var>y<sub>current</sub></var> by 1.</p>
</li>
</ol>
</li>
<li>
<p>Empty the <var>list of downward-growing cells</var>.</p>
</li>
</ol>
<p>The <dfn>algorithm for processing rows</dfn>, which is invoked by the set of steps above for
processing <code>tr</code> elements, is:</p>
<ol>
<li>
<p>If <var>y<sub>height</sub></var> is equal to <var>y<sub>current</sub></var>, then increase <var>y<sub>height</sub></var> by
1. (<var>y<sub>current</sub></var> is never <em>greater</em> than <var>y<sub>height</sub></var>.)</p>
</li>
<li>
<p>Let <var>x<sub>current</sub></var> be 0.</p>
</li>
<li>
<p>Run the <span>algorithm for growing downward-growing cells</span>.</p>
</li>
<li>
<p>If the <code>tr</code> element being processed has no <code>td</code> or <code>th</code>
element children, then increase <var>y<sub>current</sub></var> by 1, abort
this set of steps, and return to the algorithm above.</p>
</li>
<li>
<p>Let <var>current cell</var> be the first <code>td</code> or <code>th</code> element child
in the <code>tr</code> element being processed.</p>
</li>
<li>
<p><i>Cells</i>: While <var>x<sub>current</sub></var> is less than <var>x<sub>width</sub></var> and the slot with coordinate (<var>x<sub>current</sub></var>, <var>y<sub>current</sub></var>) already has a
cell assigned to it, increase <var>x<sub>current</sub></var> by 1.</p>
</li>
<li>
<p>If <var>x<sub>current</sub></var> is equal to <var>x<sub>width</sub></var>, increase <var>x<sub>width</sub></var> by 1. (<var>x<sub>current</sub></var> is never <em>greater</em> than <var>x<sub>width</sub></var>.)</p>
</li>
<li>
<p>If the <var>current cell</var> has a <code data-x="attr-tdth-colspan">colspan</code>
attribute, then <span data-x="rules for parsing non-negative integers">parse that attribute's
value</span>, and let <var>colspan</var> be the result.</p>
<p>If parsing that value failed, or returned zero, or if the attribute is absent, then let <var>colspan</var> be 1, instead.</p>
<p>If <var>colspan</var> is greater than 1000, let it be 1000 instead.</p>
</li>
<li>
<p>If the <var>current cell</var> has a <code data-x="attr-tdth-rowspan">rowspan</code>
attribute, then <span data-x="rules for parsing non-negative integers">parse that attribute's
value</span>, and let <var>rowspan</var> be the result.</p>
<p>If parsing that value failed or if the attribute is absent, then let <var>rowspan</var> be 1, instead.</p>
<p>If <var>rowspan</var> is greater than 65534, let it be 65534 instead.</p>
</li>
<li>
<p>If <var>rowspan</var> is zero and the <code>table</code> element's
<span>node document</span> is not set to <span>quirks mode</span>, then let <var>cell grows
downward</var> be true, and set <var>rowspan</var> to 1. Otherwise, let <var>cell grows downward</var> be false.</p>
</li>
<li>
<p>If <var>x<sub>width</sub></var> < <var>x<sub>current</sub></var>+<var>colspan</var>, then let <var>x<sub>width</sub></var> be <var>x<sub>current</sub></var>+<var>colspan</var>.</p>
</li>
<li>
<p>If <var>y<sub>height</sub></var> < <var>y<sub>current</sub></var>+<var>rowspan</var>, then let <var>y<sub>height</sub></var> be <var>y<sub>current</sub></var>+<var>rowspan</var>.</p>
</li>
<li>
<p>Let the slots with coordinates (<var>x</var>, <var>y</var>) such that <span
data-x=""><var>x<sub>current</sub></var> ≤ <var>x</var> < <var>x<sub>current</sub></var>+<var>colspan</var></span> and <var>y<sub>current</sub></var> ≤ <var>y</var> < <var>y<sub>current</sub></var>+<var>rowspan</var> be covered by a
new <span data-x="concept-cell">cell</span> <var>c</var>, anchored at (<var>x<sub>current</sub></var>, <var>y<sub>current</sub></var>),
which has width <var>colspan</var> and height <var>rowspan</var>,
corresponding to the <var>current cell</var> element.</p>
<p>If the <var>current cell</var> element is a <code>th</code> element, let this new
cell <var>c</var> be a header cell; otherwise, let it be a data cell.</p>
<p>To establish which header cells apply to the <var>current cell</var> element, use
the <span>algorithm for assigning header cells</span> described in the next section.</p>
<p>If any of the slots involved already had a <span data-x="concept-cell">cell</span> covering
them, then this is a <span>table model error</span>. Those slots now have two cells
overlapping.</p>
</li>
<li>
<p>If <var>cell grows downward</var> is true, then add the tuple {<var>c</var>, <var>x<sub>current</sub></var>, <var>colspan</var>}
to the <var>list of downward-growing cells</var>.</p>
</li>
<li>
<p>Increase <var>x<sub>current</sub></var> by <var>colspan</var>.</p>
</li>
<li>
<p>If <var>current cell</var> is the last <code>td</code> or <code>th</code> element child in
the <code>tr</code> element being processed, then increase <var>y<sub>current</sub></var> by 1, abort this set of steps, and return to the algorithm
above.</p>
</li>
<li>
<p>Let <var>current cell</var> be the next <code>td</code> or <code>th</code> element child
in the <code>tr</code> element being processed.</p>
</li>
<li>
<p>Return to the step labeled <i>cells</i>.</p>
</li>
</ol>
<p>When the algorithms above require the user agent to run the <dfn>algorithm for growing
downward-growing cells</dfn>, the user agent must, for each {<var>cell</var>, <var>cell<sub>x</sub></var>, <var>width</var>} tuple in the <var>list of downward-growing cells</var>, if any, extend the <span
data-x="concept-cell">cell</span> <var>cell</var> so that it also covers the slots with
coordinates (<var>x</var>, <var>y<sub>current</sub></var>), where <span
data-x=""><var>cell<sub>x</sub></var> ≤ <var>x</var> < <var>cell<sub>x</sub></var>+<var>width</var></span>.</p>
<h5 id="header-and-data-cell-semantics">Forming relationships between data cells and header cells</h5>
<p>Each cell can be assigned zero or more header cells. The <dfn>algorithm for assigning header
cells</dfn> to a cell <var>principal cell</var> is as follows.</p>
<ol>
<!-- INITIALIZATION -->
<li>
<p>Let <var>header list</var> be an empty list of cells.</p>
</li>
<li>
<p>Let (<var>principal<sub>x</sub></var>, <var>principal<sub>y</sub></var>) be the coordinate of the slot to which the <var>principal
cell</var> is anchored.</p>
</li>
<li>
<dl class="switch">
<dt>If the <var>principal cell</var> has a <code
data-x="attr-tdth-headers">headers</code> attribute specified</dt>
<dd>
<!-- HEADERS="" -->
<ol>
<li>
<p>Take the value of the <var>principal cell</var>'s <code
data-x="attr-tdth-headers">headers</code> attribute and <span data-x="split a string on
ASCII whitespace">split it on ASCII whitespace</span>, letting <var>id list</var> be the
list of tokens obtained.</p>
</li>
<li>
<!-- support headers="" on <td> element for legacy compat -->
<!-- note that it's not conforming though -->
<p>For each token in the <var>id list</var>, if the
first element in the <code>Document</code> with an <span data-x="concept-id">ID</span> equal to
the token is a cell in the same <span
data-x="concept-table">table</span>, and that cell is not the
<var>principal cell</var>, then add that cell to <var>header list</var>.</p>
</li>
</ol>
</dd>
<dt>If <var>principal cell</var> does not have a <code
data-x="attr-tdth-headers">headers</code> attribute specified</dt>
<dd>
<ol>
<li>
<p>Let <var>principal<sub>width</sub></var> be the width of the <var>principal cell</var>.</p>
</li>
<li>
<p>Let <var>principal<sub>height</sub></var> be the height of the <var>principal cell</var>.</p>
</li>
<!-- HORIZONTAL -->
<li>
<p>For each value of <var>y</var> from <var>principal<sub>y</sub></var> to <var>principal<sub>y</sub></var>+<var>principal<sub>height</sub></var>-1, run
the <span>internal algorithm for scanning and assigning header cells</span>, with the <var>principal cell</var>, the <var>header list</var>, the initial coordinate
(<var>principal<sub>x</sub></var>, <var>y</var>), and the
increments <span data-x="">Δ<var>x</var>=−1</span> and <span
data-x="">Δ<var>y</var>=0</span>.</p>
</li>
<!-- VERTICAL -->
<li>
<p>For each value of <var>x</var> from <var>principal<sub>x</sub></var> to <var>principal<sub>x</sub></var>+<var>principal<sub>width</sub></var>-1, run
the <span>internal algorithm for scanning and assigning header cells</span>, with the <var>principal cell</var>, the <var>header list</var>, the initial coordinate
(<var>x</var>, <var>principal<sub>y</sub></var>), and the
increments <span data-x="">Δ<var>x</var>=0</span> and <span
data-x="">Δ<var>y</var>=−1</span>.</p>
</li>
<!-- ROW GROUP HEADERS -->
<li>
<p>If the <var>principal cell</var> is anchored in a <span
data-x="concept-row-group">row group</span>, then add all header cells that are <span
data-x="row group header">row group headers</span> and are anchored in the same row group
with an <var>x</var>-coordinate less than or equal to <var>principal<sub>x</sub></var>+<var>principal<sub>width</sub></var>-1 and a <var>y</var>-coordinate less than or
equal to <var>principal<sub>y</sub></var>+<var>principal<sub>height</sub></var>-1 to <var>header
list</var>.</p>
<!-- this might introduce principal accidentally; fixed below -->
</li>
<!-- COLUMN GROUP HEADERS -->
<li>
<p>If the <var>principal cell</var> is anchored in a <span
data-x="concept-column-group">column group</span>, then add all header cells that are <span
data-x="column group header">column group headers</span> and are anchored in the same column
group with an <var>x</var>-coordinate less than or equal to <var>principal<sub>x</sub></var>+<var>principal<sub>width</sub></var>-1 and a <var>y</var>-coordinate less than or
equal to <var>principal<sub>y</sub></var>+<var>principal<sub>height</sub></var>-1 to <var>header
list</var>.</p>
<!-- this might introduce principal accidentally; fixed below -->
</li>
</ol>
</dd>
</dl>
</li>
<!--CLEANING UP-->
<li>
<p>Remove all the <span data-x="empty cell">empty cells</span> from the <var>header
list</var>.</p>
</li>
<li>
<p>Remove any duplicates from the <var>header list</var>.</p>
</li>
<li>
<p>Remove <var>principal cell</var> from the <var>header list</var> if it is
there.</p> <!-- see "might introduce principal accidentally" above -->
</li>
<li>
<p>Assign the headers in the <var>header list</var> to the <var>principal
cell</var>.</p>
</li>
</ol>
<p>The <dfn>internal algorithm for scanning and assigning header cells</dfn>, given a <var>principal cell</var>, a <var>header list</var>, an initial coordinate (<var>initial<sub>x</sub></var>, <var>initial<sub>y</sub></var>),
and Δ<var>x</var> and Δ<var>y</var> increments, is as follows:</p>
<ol>
<li>
<p>Let <var>x</var> equal <var>initial<sub>x</sub></var>.</p>
</li>
<li>
<p>Let <var>y</var> equal <var>initial<sub>y</sub></var>.</p>
</li>
<li>
<p>Let <var>opaque headers</var> be an empty list of cells.</p>
</li>
<li>
<dl class="switch">
<dt>If <var>principal cell</var> is a header cell</dt>
<dd><p>Let <var>in header block</var> be true, and let <var>headers from
current header block</var> be a list of cells containing just the <var>principal
cell</var>.</p></dd>
<dt>Otherwise</dt>
<dd><p>Let <var>in header block</var> be false and let <var>headers from
current header block</var> be an empty list of cells.</p>
</dl>
</li>
<li>
<p><i>Loop</i>: Increment <var>x</var> by Δ<var>x</var>; increment <var>y</var> by Δ<var>y</var>.</p>
<p class="note">For each invocation of this algorithm, one of Δ<var>x</var> and
Δ<var>y</var> will be −1, and the other will be 0.</p>
</li>
<li>
<p>If either <var>x</var> or <var>y</var> are less than 0, then abort this
internal algorithm.</p>
</li>
<li>
<p>If there is no cell covering slot (<var>x</var>, <var>y</var>), or if there
is more than one cell covering slot (<var>x</var>, <var>y</var>), return to
the substep labeled <i>loop</i>.</p>
</li>
<li>
<p>Let <var>current cell</var> be the cell covering slot (<var>x</var>, <var>y</var>).</p>
</li>
<li>
<dl class="switch">
<dt>If <var>current cell</var> is a header cell</dt>
<dd>
<ol>
<li><p>Set <var>in header block</var> to true.</p></li>
<li><p>Add <var>current cell</var> to <var>headers from current header
block</var>.</p></li>
<li><p>Let <var>blocked</var> be false.</p></li>
<li>
<dl class="switch">
<dt>If Δ<var>x</var> is 0</dt>
<dd>
<p>If there are any cells in the <var>opaque headers</var> list anchored with the
same <var>x</var>-coordinate as the <var>current cell</var>, and with
the same width as <var>current cell</var>, then let <var>blocked</var>
be true.</p>
<p>If the <var>current cell</var> is not a <span>column header</span>, then let
<var>blocked</var> be true.</p>
</dd>
<dt>If Δ<var>y</var> is 0</dt>
<dd>
<p>If there are any cells in the <var>opaque headers</var> list anchored with the
same <var>y</var>-coordinate as the <var>current cell</var>, and with
the same height as <var>current cell</var>, then let <var>blocked</var>
be true.</p>
<p>If the <var>current cell</var> is not a <span>row header</span>, then let <var>blocked</var> be true.</p>
</dd>
</dl>
</li>
<li><p>If <var>blocked</var> is false, then add the <var>current cell</var>
to the <var>header list</var>.</p></li>
</ol>
</dd>
<dt>If <var>current cell</var> is a data cell and <var>in header block</var> is true</dt>
<dd><p>Set <var>in header block</var> to false. Add all the cells in <var>headers from current header block</var> to the <var>opaque headers</var>
list, and empty the <var>headers from current header block</var> list.</p>
</dl>
</li>
<li>
<p>Return to the step labeled <i>loop</i>.</p>
</li>
</ol>
<p>A header cell anchored at the slot with coordinate (<var>x</var>, <var>y</var>) with width
<var>width</var> and height <var>height</var> is said to be a <dfn>column header</dfn> if any of
the following are true:</p>
<ul>
<li><p>the cell's <code data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-column-state">column</span> state; or</p></li>
<li><p>the cell's <code data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-auto-state">auto</span> state, and there are no data cells in any of the
cells covering slots with <var>y</var>-coordinates <var>y</var> .. <span
data-x=""><var>y</var>+<var>height</var>-1</span>.</p></li>
</ul>
<p>A header cell anchored at the slot with coordinate (<var>x</var>, <var>y</var>) with width
<var>width</var> and height <var>height</var> is said to be a <dfn>row header</dfn> if any of the
following are true:</p>
<ul>
<li><p>the cell's <code data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-row-state">row</span> state; or</p></li>
<li><p>the cell's <code data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-auto-state">auto</span> state, the cell is not a <span>column
header</span>, and there are no data cells in any of the cells covering slots with
<var>x</var>-coordinates <var>x</var> .. <var>x</var>+<var>width</var>-1.</p></li>
</ul>
<p>A header cell is said to be a <dfn>column group header</dfn> if its <code
data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-colgroup-state">column group</span> state.</p>
<p>A header cell is said to be a <dfn>row group header</dfn> if its <code
data-x="attr-th-scope">scope</code> attribute is in the <span
data-x="attr-th-scope-rowgroup-state">row group</span> state.</p>
<p>A cell is said to be an <dfn>empty cell</dfn> if it contains no elements and its <span>child
text content</span>, if any, consists only of <span>ASCII whitespace</span>.</p>
</div>
<h4 id="table-examples">Examples</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The following shows how one might mark up the bottom part of table 45 of the <cite>Smithsonian
physical tables, Volume 71</cite>:</p>
<!-- Smithsonian physical tables, Volume 71: By Smithsonian Institution, Frederick Eugene Fowle; page 76 -->
<!-- from the reprint of the seventh revised edition; publication 2539, published 1921 -->
<pre><code class="html"><table>
<caption>Specification values: <b>Steel</b>, <b>Castings</b>,
Ann. A.S.T.M. A27-16, Class B;* P max. 0.06; S max. 0.05.</caption>
<thead>
<tr>
<th rowspan=2>Grade.</th>
<th rowspan=2>Yield Point.</th>
<th colspan=2>Ultimate tensile strength</th>
<th rowspan=2>Per cent elong. 50.8&nbsp;mm or 2&nbsp;in.</th>
<th rowspan=2>Per cent reduct. area.</th>
</tr>
<tr>
<th>kg/mm<sup>2</sup></th>
<th>lb/in<sup>2</sup></th>
</tr>
</thead>
<tbody>
<tr>
<td>Hard</td>
<td>0.45 ultimate</td>
<td>56.2</td>
<td>80,000</td>
<td>15</td>
<td>20</td>
</tr>
<tr>
<td>Medium</td>
<td>0.45 ultimate</td>
<td>49.2</td>
<td>70,000</td>
<td>18</td>
<td>25</td>
</tr>
<tr>
<td>Soft</td>
<td>0.45 ultimate</td>
<td>42.2</td>
<td>60,000</td>
<td>22</td>
<td>30</td>
</tr>
</tbody>
</table></code></pre>
<p>This table could look like this:</p>
<table id="table-example-1">
<caption>Specification values: <b>Steel</b>, <b>Castings</b>,
Ann. A.S.T.M. A27-16, Class B;* P max. 0.06; S max. 0.05.</caption>
<thead>
<tr>
<th rowspan=2>Grade.</th>
<th rowspan=2>Yield Point.</th>
<th colspan=2>Ultimate tensile strength</th>
<th rowspan=2>Per cent elong. 50.8 mm or 2 in.</th>
<th rowspan=2>Per cent reduct. area.</th>
</tr>
<tr>
<th>kg/mm<sup>2</sup></th>
<th>lb/in<sup>2</sup></th>
</tr>
</thead>
<tbody>
<tr>
<td>Hard</td>
<td>0.45 ultimate</td>
<td>56.2</td>
<td>80,000</td>
<td>15</td>
<td>20</td>
</tr>
<tr>
<td>Medium</td>
<td>0.45 ultimate</td>
<td>49.2</td>
<td>70,000</td>
<td>18</td>
<td>25</td>
</tr>
<tr>
<td>Soft</td>
<td>0.45 ultimate</td>
<td>42.2</td>
<td>60,000</td>
<td>22</td>
<td>30</td>
</tr>
</tbody>
</table>
<hr>
<p>The following shows how one might mark up the gross margin table on page 46 of Apple, Inc's
10-K filing for fiscal year 2008:</p>
<pre><code class="html"><table>
<thead>
<tr>
<th>
<th>2008
<th>2007
<th>2006
<tbody>
<tr>
<th>Net sales
<td>$ 32,479
<td>$ 24,006
<td>$ 19,315
<tr>
<th>Cost of sales
<td> 21,334
<td> 15,852
<td> 13,717
<tbody>
<tr>
<th>Gross margin
<td>$ 11,145
<td>$ 8,154
<td>$ 5,598
<tfoot>
<tr>
<th>Gross margin percentage
<td>34.3%
<td>34.0%
<td>29.0%
</table></code></pre>
<p>This table could look like this:</p>
<table class="apple-table-examples e1">
<thead>
<tr>
<th>
<th>2008
<th>2007
<th>2006
<tbody>
<tr>
<th>Net sales
<td>$ 32,479
<td>$ 24,006
<td>$ 19,315
<tr>
<th>Cost of sales
<td> 21,334
<td> 15,852
<td> 13,717
<tbody>
<tr>
<th>Gross margin
<td>$ 11,145
<td>$ 8,154
<td>$ 5,598
<tfoot>
<tr>
<th>Gross margin percentage
<td>34.3%
<td>34.0%
<td>29.0%
</table>
<hr>
<p>The following shows how one might mark up the operating expenses table from lower on the same
page of that document:</p>
<pre><code class="html"><table>
<colgroup> <col>
<colgroup> <col> <col> <col>
<thead>
<tr> <th> <th>2008 <th>2007 <th>2006
<tbody>
<tr> <th scope=rowgroup> Research and development
<td> $ 1,109 <td> $ 782 <td> $ 712
<tr> <th scope=row> Percentage of net sales
<td> 3.4% <td> 3.3% <td> 3.7%
<tbody>
<tr> <th scope=rowgroup> Selling, general, and administrative
<td> $ 3,761 <td> $ 2,963 <td> $ 2,433
<tr> <th scope=row> Percentage of net sales
<td> 11.6% <td> 12.3% <td> 12.6%
</table></code></pre>
<p>This table could look like this:</p>
<table class="apple-table-examples e2">
<thead>
<tr> <th> <th>2008 <th>2007 <th>2006
<tbody>
<tr> <th scope=rowgroup> Research and development
<td> $ 1,109 <td> $ 782 <td> $ 712
<tr> <th scope=row> Percentage of net sales
<td> 3.4% <td> 3.3% <td> 3.7%
<tbody>
<tr> <th scope=rowgroup> Selling, general, and administrative
<td> $ 3,761 <td> $ 2,963 <td> $ 2,433
<tr> <th scope=row> Percentage of net sales
<td> 11.6% <td> 12.3% <td> 12.6%
</table>
<h3 split-filename="forms" id="forms">Forms</h3>
<h4>Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>A form is a component of a web page that has form controls, such as text, buttons, checkboxes,
range, or color picker controls. A user can interact with such a form, providing data that can
then be sent to the server for further processing (e.g. returning the results of a search or
calculation). No client-side scripting is needed in many cases, though an API is available so that
scripts can augment the user experience or use forms for purposes other than submitting data to a
server.</p>
<p>Writing a form consists of several steps, which can be performed in any order: writing the user
interface, implementing the server-side processing, and configuring the user interface to
communicate with the server.</p>
<h5>Writing a form's user interface</h5>
<!-- NON-NORMATIVE SECTION -->
<p>For the purposes of this brief introduction, we will create a pizza ordering form.</p>
<p>Any form starts with a <code>form</code> element, inside which are placed the controls. Most
controls are represented by the <code>input</code> element, which by default provides a text
control. To label a control, the <code>label</code> element is used; the label text and the
control itself go inside the <code>label</code> element. Each part of a form is considered a
<span>paragraph</span>, and is typically separated from other parts using <code>p</code> elements.
Putting this together, here is how one might ask for the customer's name:</p>
<pre><code class="html"><strong><form>
<p><label>Customer name: <input></label></p>
</form></strong></code></pre>
<p>To let the user select the size of the pizza, we can use a set of radio buttons. Radio buttons
also use the <code>input</code> element, this time with a <code
data-x="attr-input-type">type</code> attribute with the value <code
data-x="attr-input-type-radio">radio</code>. To make the radio buttons work as a group, they are
given a common name using the <code data-x="attr-fe-name">name</code> attribute. To group a batch
of controls together, such as, in this case, the radio buttons, one can use the
<code>fieldset</code> element. The title of such a group of controls is given by the first element
in the <code>fieldset</code>, which has to be a <code>legend</code> element.</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<strong> <fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset></strong>
</form></code></pre>
<p class="note">Changes from the previous step are highlighted.</p>
<p>To pick toppings, we can use checkboxes. These use the <code>input</code> element with a <code
data-x="attr-input-type">type</code> attribute with the value <code
data-x="attr-input-type-checkbox">checkbox</code>:</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset>
<strong> <fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox> Bacon </label></p>
<p><label> <input type=checkbox> Extra Cheese </label></p>
<p><label> <input type=checkbox> Onion </label></p>
<p><label> <input type=checkbox> Mushroom </label></p>
</fieldset></strong>
</form></code></pre>
<p>The pizzeria for which this form is being written is always making mistakes, so it needs a way
to contact the customer. For this purpose, we can use form controls specifically for telephone
numbers (<code>input</code> elements with their <code data-x="attr-input-type">type</code>
attribute set to <code data-x="attr-input-type-tel">tel</code>) and email addresses
(<code>input</code> elements with their <code data-x="attr-input-type">type</code> attribute set
to <code data-x="attr-input-type-email">email</code>):</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<strong> <p><label>Telephone: <input type=tel></label></p>
<p><label>Email address: <input type=email></label></p></strong>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox> Bacon </label></p>
<p><label> <input type=checkbox> Extra Cheese </label></p>
<p><label> <input type=checkbox> Onion </label></p>
<p><label> <input type=checkbox> Mushroom </label></p>
</fieldset>
</form></code></pre>
<p>We can use an <code>input</code> element with its <code data-x="attr-input-type">type</code>
attribute set to <code data-x="attr-input-type-time">time</code> to ask for a delivery time. Many
of these form controls have attributes to control exactly what values can be specified; in this
case, three attributes of particular interest are <code data-x="attr-input-min">min</code>, <code
data-x="attr-input-max">max</code>, and <code data-x="attr-input-step">step</code>. These set the
minimum time, the maximum time, and the interval between allowed values (in seconds). This
pizzeria only delivers between 11am and 9pm, and doesn't promise anything better than 15 minute
increments, which we can mark up as follows:</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<p><label>Telephone: <input type=tel></label></p>
<p><label>Email address: <input type=email></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox> Bacon </label></p>
<p><label> <input type=checkbox> Extra Cheese </label></p>
<p><label> <input type=checkbox> Onion </label></p>
<p><label> <input type=checkbox> Mushroom </label></p>
</fieldset>
<strong> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p></strong>
</form></code></pre>
<p>The <code>textarea</code> element can be used to provide a multiline text control. In this
instance, we are going to use it to provide a space for the customer to give delivery
instructions:</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<p><label>Telephone: <input type=tel></label></p>
<p><label>Email address: <input type=email></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox> Bacon </label></p>
<p><label> <input type=checkbox> Extra Cheese </label></p>
<p><label> <input type=checkbox> Onion </label></p>
<p><label> <input type=checkbox> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p>
<strong> <p><label>Delivery instructions: <textarea></textarea></label></p></strong>
</form></code></pre>
<p>Finally, to make the form submittable we use the <code>button</code> element:</p>
<pre><code class="html"><form>
<p><label>Customer name: <input></label></p>
<p><label>Telephone: <input type=tel></label></p>
<p><label>Email address: <input type=email></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size> Small </label></p>
<p><label> <input type=radio name=size> Medium </label></p>
<p><label> <input type=radio name=size> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox> Bacon </label></p>
<p><label> <input type=checkbox> Extra Cheese </label></p>
<p><label> <input type=checkbox> Onion </label></p>
<p><label> <input type=checkbox> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p>
<p><label>Delivery instructions: <textarea></textarea></label></p>
<strong> <p><button>Submit order</button></p></strong>
</form></code></pre>
<h5>Implementing the server-side processing for a form</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The exact details for writing a server-side processor are out of scope for this specification.
For the purposes of this introduction, we will assume that the script at <code
data-x="">https://pizza.example.com/order.cgi</code> is configured to accept submissions using the
<code data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code> format,
expecting the following parameters sent in an HTTP POST body:</p>
<dl>
<dt><code data-x="">custname</code></dt>
<dd>Customer's name</dd>
<dt><code data-x="">custtel</code></dt>
<dd>Customer's telephone number</dd>
<dt><code data-x="">custemail</code></dt>
<dd>Customer's email address</dd>
<dt><code data-x="">size</code></dt>
<dd>The pizza size, either <code data-x="">small</code>, <code data-x="">medium</code>, or <code data-x="">large</code></dd>
<dt><code data-x="">topping</code></dt>
<dd>A topping, specified once for each selected topping, with the allowed values being <code data-x="">bacon</code>, <code data-x="">cheese</code>, <code data-x="">onion</code>, and <code data-x="">mushroom</code></dd>
<dt><code data-x="">delivery</code></dt>
<dd>The requested delivery time</dd>
<dt><code data-x="">comments</code></dt>
<dd>The delivery instructions</dd>
</dl>
<h5>Configuring a form to communicate with a server</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Form submissions are exposed to servers in a variety of ways, most commonly as HTTP GET or POST
requests. To specify the exact method used, the <code data-x="attr-fs-method">method</code>
attribute is specified on the <code>form</code> element. This doesn't specify how the form data is
encoded, though; to specify that, you use the <code data-x="attr-fs-enctype">enctype</code>
attribute. You also have to specify the <span>URL</span> of the service that will handle the
submitted data, using the <code data-x="attr-fs-action">action</code> attribute.</p>
<p>For each form control you want submitted, you then have to give a name that will be used to
refer to the data in the submission. We already specified the name for the group of radio buttons;
the same attribute (<code data-x="attr-fe-name">name</code>) also specifies the submission name.
Radio buttons can be distinguished from each other in the submission by giving them different
values, using the <code data-x="attr-input-value">value</code> attribute.</p>
<p>Multiple controls can have the same name; for example, here we give all the checkboxes the same
name, and the server distinguishes which checkbox was checked by seeing which values are submitted
with that name — like the radio buttons, they are also given unique values with the <code
data-x="attr-input-value">value</code> attribute.</p>
<p>Given the settings in the previous section, this all becomes:</p>
<pre><code class="html"><form<strong> method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi"</strong>>
<p><label>Customer name: <input<strong> name="custname"</strong>></label></p>
<p><label>Telephone: <input type=tel<strong> name="custtel"</strong>></label></p>
<p><label>Email address: <input type=email<strong> name="custemail"</strong>></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size<strong> value="small"</strong>> Small </label></p>
<p><label> <input type=radio name=size<strong> value="medium"</strong>> Medium </label></p>
<p><label> <input type=radio name=size<strong> value="large"</strong>> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox<strong> name="topping" value="bacon"</strong>> Bacon </label></p>
<p><label> <input type=checkbox<strong> name="topping" value="cheese"</strong>> Extra Cheese </label></p>
<p><label> <input type=checkbox<strong> name="topping" value="onion"</strong>> Onion </label></p>
<p><label> <input type=checkbox<strong> name="topping" value="mushroom"</strong>> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"<strong> name="delivery"</strong>></label></p>
<p><label>Delivery instructions: <textarea<strong> name="comments"</strong>></textarea></label></p>
<p><button>Submit order</button></p>
</form></code></pre>
<p class="note">There is no particular significance to the way some of the attributes have their
values quoted and others don't. The HTML syntax allows a variety of equally valid ways to specify
attributes, as discussed <span data-x="syntax-attributes">in the syntax section</span>.</p>
<p>For example, if the customer entered "Denise Lawrence" as their name, "555-321-8642" as their
telephone number, did not specify an email address, asked for a medium-sized pizza, selected the
Extra Cheese and Mushroom toppings, entered a delivery time of 7pm, and left the delivery
instructions text control blank, the user agent would submit the following to the online web
service:</p>
<pre><code class="html">custname=Denise+Lawrence&custtel=555-321-8642&custemail=&size=medium&topping=cheese&topping=mushroom&delivery=19%3A00&comments=</code></pre>
<h5>Client-side form validation</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Forms can be annotated in such a way that the user agent will check the user's input before the
form is submitted. The server still has to verify the input is valid (since hostile users can
easily bypass the form validation), but it allows the user to avoid the wait incurred by having
the server be the sole checker of the user's input.</p>
<p>The simplest annotation is the <code data-x="attr-input-required">required</code> attribute,
which can be specified on <code>input</code> elements to indicate that the form is not to be
submitted until a value is given. By adding this attribute to the customer name, pizza size, and
delivery time fields, we allow the user agent to notify the user when the user submits the form
without filling in those fields:</p>
<pre><code class="html"><form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname"<strong> required</strong>></label></p>
<p><label>Telephone: <input type=tel name="custtel"></label></p>
<p><label>Email address: <input type=email name="custemail"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size<strong> required</strong> value="small"> Small </label></p>
<p><label> <input type=radio name=size<strong> required</strong> value="medium"> Medium </label></p>
<p><label> <input type=radio name=size<strong> required</strong> value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery"<strong> required</strong>></label></p>
<p><label>Delivery instructions: <textarea name="comments"></textarea></label></p>
<p><button>Submit order</button></p>
</form></code></pre>
<p>It is also possible to limit the length of the input, using the <code
data-x="attr-fe-maxlength">maxlength</code> attribute. By adding this to the <code>textarea</code>
element, we can limit users to 1000 characters, preventing them from writing huge essays to the
busy delivery drivers instead of staying focused and to the point:</p>
<pre><code class="html"><form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname" required></label></p>
<p><label>Telephone: <input type=tel name="custtel"></label></p>
<p><label>Email address: <input type=email name="custemail"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size required value="small"> Small </label></p>
<p><label> <input type=radio name=size required value="medium"> Medium </label></p>
<p><label> <input type=radio name=size required value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p>
<p><label>Delivery instructions: <textarea name="comments"<strong> maxlength=1000</strong>></textarea></label></p>
<p><button>Submit order</button></p>
</form></code></pre>
<p class="note">When a form is submitted, <code data-x="event-invalid">invalid</code> events are
fired at each form control that is invalid. This can be useful for displaying a summary of the
problems with the form, since typically the browser itself will only report one problem at a
time.</p>
<h5>Enabling client-side automatic filling of form controls</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Some browsers attempt to aid the user by automatically filling form controls rather than having
the user reenter their information each time. For example, a field asking for the user's telephone
number can be automatically filled with the user's phone number.</p>
<p>To help the user agent with this, the <code data-x="attr-fe-autocomplete">autocomplete</code>
attribute can be used to describe the field's purpose. In the case of this form, we have three
fields that can be usefully annotated in this way: the information about who the pizza is to be
delivered to. Adding this information looks like this:</p>
<pre><code class="html"><form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname" required <strong>autocomplete="shipping name"</strong>></label></p>
<p><label>Telephone: <input type=tel name="custtel" <strong>autocomplete="shipping tel"</strong>></label></p>
<p><label>Email address: <input type=email name="custemail" <strong>autocomplete="shipping email"</strong>></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size required value="small"> Small </label></p>
<p><label> <input type=radio name=size required value="medium"> Medium </label></p>
<p><label> <input type=radio name=size required value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p>
<p><label>Delivery instructions: <textarea name="comments" maxlength=1000></textarea></label></p>
<p><button>Submit order</button></p>
</form></code></pre>
<h5>Improving the user experience on mobile devices</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Some devices, in particular those with virtual keyboards can provide the user with multiple
input modalities. For example, when typing in a credit card number the user may wish to only see
keys for digits 0-9, while when typing in their name they may wish to see a form field that by
default capitalizes each word.</p>
<p>Using the <code data-x="attr-inputmode">inputmode</code> attribute we can select appropriate
input modalities:</p>
<pre><code class="html"><form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname" required autocomplete="shipping name"></label></p>
<p><label>Telephone: <input type=tel name="custtel" autocomplete="shipping tel"></label></p>
<p><label>Buzzer code: <input name="custbuzz" <strong>inputmode="numeric"</strong>></label></p>
<p><label>Email address: <input type=email name="custemail" autocomplete="shipping email"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size required value="small"> Small </label></p>
<p><label> <input type=radio name=size required value="medium"> Medium </label></p>
<p><label> <input type=radio name=size required value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p>
<p><label>Delivery instructions: <textarea name="comments" maxlength=1000></textarea></label></p>
<p><button>Submit order</button></p>
</form></code></pre>
<h5>The difference between the field type, the autofill field name, and the input modality</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The <code data-x="attr-input-type">type</code>, <code
data-x="attr-fe-autocomplete">autocomplete</code>, and <code
data-x="attr-inputmode">inputmode</code> attributes can seem confusingly similar. For instance,
in all three cases, the string "<code data-x="">email</code>" is a valid value. This section
attempts to illustrate the difference between the three attributes and provides advice suggesting
how to use them.</p>
<p>The <code data-x="attr-input-type">type</code> attribute on <code>input</code> elements decides
what kind of control the user agent will use to expose the field. Choosing between different
values of this attribute is the same choice as choosing whether to use an <code>input</code>
element, a <code>textarea</code> element, a <code>select</code> element, etc.</p>
<p>The <code data-x="attr-fe-autocomplete">autocomplete</code> attribute, in contrast, describes
what the value that the user will enter actually represents. Choosing between different values of
this attribute is the same choice as choosing what the label for the element will be.</p>
<p>First, consider telephone numbers. If a page is asking for a telephone number from the user,
the right form control to use is <code data-x="attr-input-type-tel"><input type=tel></code>.
However, which <code data-x="attr-fe-autocomplete">autocomplete</code> value to use depends on
which phone number the page is asking for, whether they expect a telephone number in the
international format or just the local format, and so forth.</p>
<p>For example, a page that forms part of a checkout process on an e-commerce site for a customer
buying a gift to be shipped to a friend might need both the buyer's telephone number (in case of
payment issues) and the friend's telephone number (in case of delivery issues). If the site
expects international phone numbers (with the country code prefix), this could thus look like
this:</p>
<pre><code class="html"><p><label>Your phone number: <input type=tel name=custtel autocomplete="billing tel"></label>
<p><label>Recipient's phone number: <input type=tel name=shiptel autocomplete="shipping tel"></label>
<p>Please enter complete phone numbers including the country code prefix, as in "+1 555 123 4567".</code></pre>
<p>But if the site only supports British customers and recipients, it might instead look like this
(notice the use of <code data-x="attr-fe-autocomplete-tel-national">tel-national</code> rather than
<code data-x="attr-fe-autocomplete-tel">tel</code>):</p>
<pre><code class="html"><p><label>Your phone number: <input type=tel name=custtel autocomplete="billing tel-national"></label>
<p><label>Recipient's phone number: <input type=tel name=shiptel autocomplete="shipping tel-national"></label>
<p>Please enter complete UK phone numbers, as in "(01632) 960 123".</code></pre>
<p>Now, consider a person's preferred languages. The right <code
data-x="attr-fe-autocomplete">autocomplete</code> value is <code
data-x="attr-fe-autocomplete-language">language</code>. However, there could be a number of
different form controls used for the purpose: a text control (<code
data-x="attr-input-type-text"><input type=text></code>), a drop-down list (<code
data-x="select"><select></code>), radio buttons (<code data-x="attr-input-type-radio"><input
type=radio></code>), etc. It only depends on what kind of interface is desired.</p>
<p>Finally, consider names. If a page just wants one name from the user, then the relevant control
is <code data-x="attr-input-type-text"><input type=text></code>. If the page is asking for the
user's full name, then the relevant <code data-x="attr-fe-autocomplete">autocomplete</code> value
is <code data-x="attr-fe-autocomplete-name">name</code>.
<pre><code class="html"><p><label>Japanese name: <input name="j" type="text" autocomplete="section-jp name"></label>
<label>Romanized name: <input name="e" type="text" autocomplete="section-en name"></label></code></pre>
<p>In this example, the "<code data-x="attr-fe-autocomplete-section">section-*</code>" keywords in
the <code data-x="attr-fe-autocomplete">autocomplete</code> attributes' values tell the user agent
that the two fields expect <em>different</em> names. Without them, the user agent could
automatically fill the second field with the value given in the first field when the user gave a
value to the first field.</p>
<p class="note">The "<code data-x="">-jp</code>" and "<code data-x="">-en</code>" parts of the
keywords are opaque to the user agent; the user agent cannot guess, from those, that the two names
are expected to be in Japanese and English respectively.</p>
<p>Separate from the choices regarding <code data-x="attr-input-type">type</code> and <code
data-x="attr-fe-autocomplete">autocomplete</code>, the <code
data-x="attr-inputmode">inputmode</code> attribute decides what kind of input modality (e.g.,
virtual keyboard) to use, when the control is a text control.</p>
<p>Consider credit card numbers. The appropriate input type is <em>not</em> <code
data-x="attr-input-type-number"><input type=number></code>, <a
href="#when-number-is-not-appropriate">as explained below</a>; it is instead <code
data-x="attr-input-type-text"><input type=text></code>. To encourage the user agent to use a
numeric input modality anyway (e.g., a virtual keyboard displaying only digits), the page would
use</p>
<pre><code class="html"><p><label>Credit card number:
<input name="cc" type="text" inputmode="numeric" pattern="[0-9]{8,19}" autocomplete="cc-number">
</label></p></code></pre>
<h5 id="input-author-notes">Date, time, and number formats</h5>
<!-- ID referenced from other parts of the spec -->
<!-- NON-NORMATIVE SECTION -->
<p>In this pizza delivery example, the times are specified in the format "HH:MM": two digits for
the hour, in 24-hour format, and two digits for the time. (Seconds could also be specified, though
they are not necessary in this example.)</p>
<p>In some locales, however, times are often expressed differently when presented to users. For
example, in the United States, it is still common to use the 12-hour clock with an am/pm
indicator, as in "2pm". In France, it is common to separate the hours from the minutes using an
"h" character, as in "14h00".</p>
<p>Similar issues exist with dates, with the added complication that even the order of the
components is not always consistent — for example, in Cyprus the first of February 2003
would typically be written "1/2/03", while that same date in Japan would typically be written as
"2003年02月01日" — and even with numbers, where locales differ, for
example, in what punctuation is used as the decimal separator and the thousands separator.</p>
<p>It is therefore important to distinguish the time, date, and number formats used in HTML and in
form submissions, which are always the formats defined in this specification (and based on the
well-established ISO 8601 standard for computer-readable date and time formats), from the time,
date, and number formats presented to the user by the browser and accepted as input from the user
by the browser.</p>
<p>The format used "on the wire", i.e., in HTML markup and in form submissions, is intended to be
computer-readable and consistent irrespective of the user's locale. Dates, for instance, are
always written in the format "YYYY-MM-DD", as in "2003-02-01". While some users might see this
format, others might see it as "01.02.2003" or "February 1, 2003".</p>
<p>The time, date, or number given by the page in the wire format is then translated to the user's
preferred presentation (based on user preferences or on the locale of the page itself), before
being displayed to the user. Similarly, after the user inputs a time, date, or number using their
preferred format, the user agent converts it back to the wire format before putting it in the DOM
or submitting it.</p>
<p>This allows scripts in pages and on servers to process times, dates, and numbers in a
consistent manner without needing to support dozens of different formats, while still supporting
the users' needs.</p>
<div w-nodev>
<p class="note">See also the <a
href="#input-impl-notes">implementation notes</a> regarding
localization of form controls.</p>
</div>
<h4>Categories</h4>
<p>Mostly for historical reasons, elements in this section fall into several overlapping (but
subtly different) categories in addition to the usual ones like <span>flow content</span>,
<span>phrasing content</span>, and <span>interactive content</span>.</p>
<p>A number of the elements are <dfn data-x="form-associated element">form-associated
elements</dfn>, which means they can have a <span>form owner</span>.
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>button</code></li>
<li><code>fieldset</code></li>
<li><code>input</code></li>
<li><code>object</code></li>
<li><code>output</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><code>img</code></li>
<li><span data-x="form-associated custom element">form-associated custom elements</span></li>
</ul>
<p>The <span data-x="form-associated element">form-associated elements</span> fall into several
subcategories:</p>
<dl>
<dt><dfn data-x="category-listed">Listed elements</dfn></dt>
<dd>
<p>Denotes elements that are listed in the <code
data-x="dom-form-elements"><var>form</var>.elements</code> and <code
data-x="dom-fieldset-elements"><var>fieldset</var>.elements</code> APIs. These elements also
have a <code data-x="attr-fae-form">form</code> content attribute, and a matching <code
data-x="dom-fae-form">form</code> IDL attribute, that allow authors to specify an explicit
<span>form owner</span>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>button</code></li>
<li><code>fieldset</code></li>
<li><code>input</code></li>
<li><code>object</code></li>
<li><code>output</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><span data-x="form-associated custom element">form-associated custom elements</span></li>
</ul>
</dd>
<dt><dfn data-x="category-submit">Submittable elements</dfn></dt>
<dd>
<p>Denotes elements that can be used for <span>constructing the entry list</span> when a
<code>form</code> element is <span data-x="concept-form-submit">submitted</span>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>button</code></li>
<li><code>input</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><span data-x="form-associated custom element">form-associated custom elements</span></li>
</ul>
<p>Some <span data-x="category-submit">submittable elements</span> can be, depending on their
attributes, <dfn data-x="concept-button">buttons</dfn>. The prose below defines when an element
is a button. Some buttons are specifically <dfn export data-lt="submit button"
data-x="concept-submit-button">submit buttons</dfn>.</p>
</dd>
<dt><dfn data-x="category-reset">Resettable elements</dfn></dt>
<dd>
<p>Denotes elements that can be affected when a <code>form</code> element is <span
data-x="concept-form-reset">reset</span>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>input</code></li>
<li><code>output</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><span data-x="form-associated custom element">form-associated custom elements</span></li>
</ul>
</dd>
<dt><dfn id="category-autocapitalize"
data-x="category-autocapitalize-and-autocorrect">Autocapitalize-and-autocorrect-inheriting
elements</dfn></dt>
<dd>
<p>Denotes elements that inherit the <code data-x="attr-autocapitalize">autocapitalize</code>
and <code data-x="attr-autocorrect">autocorrect</code> attributes from their <span>form
owner</span>.</p>
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>button</code></li>
<li><code>fieldset</code></li>
<li><code>input</code></li>
<li><code>output</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
</ul>
</dd>
</dl>
<p>Some elements, not all of them <span data-x="form-associated element">form-associated</span>,
are categorized as <dfn data-x="category-label">labelable elements</dfn>. These are elements that
can be associated with a <code>label</code> element.
<!-- when updating this also update the category index -->
<ul class="brief category-list">
<li><code>button</code></li>
<li><code>input</code> (if the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state)</li>
<li><code>meter</code></li>
<li><code>output</code></li>
<li><code>progress</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
<li><span data-x="form-associated custom element">form-associated custom elements</span></li>
</ul>
<h4>The <dfn element><code>form</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>form</code> element descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-form-accept-charset">accept-charset</code></dd>
<dd><code data-x="attr-fs-action">action</code></dd>
<dd><code data-x="attr-form-autocomplete">autocomplete</code></dd>
<dd><code data-x="attr-fs-enctype">enctype</code></dd>
<dd><code data-x="attr-fs-method">method</code></dd>
<dd><code data-x="attr-form-name">name</code></dd>
<dd><code data-x="attr-fs-novalidate">novalidate</code></dd>
<dd><code data-x="attr-fs-target">target</code></dd>
<dd><code data-x="attr-form-rel">rel</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-form">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-form">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window,
<span>LegacyOverrideBuiltIns</span>,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface>HTMLFormElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-form-acceptCharset">acceptCharset</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-fs-action">action</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-form-autocomplete">autocomplete</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-enctype">enctype</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-encoding">encoding</span>;<!-- historical artefact -->
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-method">method</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-form-name">name</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fs-noValidate">noValidate</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-target">target</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-form-rel">rel</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-form-relList">relList</span>;
[SameObject] readonly attribute <span>HTMLFormControlsCollection</span> <span data-x="dom-form-elements">elements</span>;
readonly attribute unsigned long <span data-x="dom-form-length">length</span>;
<a href="#dom-form-item">getter</a> <span>Element</span> (unsigned long index);
<a href="#dom-form-nameditem">getter</a> (<span>RadioNodeList</span> or <span>Element</span>) (DOMString name);
undefined <span data-x="dom-form-submit">submit</span>();
undefined <span data-x="dom-form-requestSubmit">requestSubmit</span>(optional <span>HTMLElement</span>? submitter = null);
[<span>CEReactions</span>] undefined <span data-x="dom-form-reset">reset</span>();
boolean <span data-x="dom-form-checkValidity">checkValidity</span>();
boolean <span data-x="dom-form-reportValidity">reportValidity</span>();
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLFormElement</code>.</dd>
</dl>
<p>The <code>form</code> element <span>represents</span> a <span>hyperlink</span> that can be
manipulated through a collection of <span data-x="form-associated element">form-associated
elements</span>, some of which can represent editable values that can be submitted to a server for
processing.</p>
<p>The <dfn element-attr for="form"><code
data-x="attr-form-accept-charset">accept-charset</code></dfn> attribute gives the character
encodings that are to be used for the submission. If specified, the value must be an <span>ASCII
case-insensitive</span> match for "<code data-x="">UTF-8</code>". <ref>ENCODING</ref></p>
<p>The <dfn element-attr for="form"><code data-x="attr-form-name">name</code></dfn> attribute
represents the <code>form</code>'s name within the <code data-x="dom-document-forms">forms</code>
collection. The value must not be the empty string, and the value must be unique amongst the
<code>form</code> elements in the <code data-x="dom-document-forms">forms</code> collection that
it is in, if any.</p>
<p>The <dfn element-attr for="form"><code
data-x="attr-form-autocomplete">autocomplete</code></dfn> attribute is an <span>enumerated
attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="form/autocomplete"><code data-x="attr-form-autocomplete-on">on</code></dfn>
<td><dfn data-x="attr-form-autocomplete-on-state">on</dfn>
<td>Form controls will have their <span>autofill field name</span> set to "<code
data-x="attr-fe-autocomplete-on">on</code>" by default.
<tr>
<td><dfn attr-value for="form/autocomplete"><code data-x="attr-form-autocomplete-off">off</code></dfn>
<td><dfn data-x="attr-form-autocomplete-off-state">off</dfn>
<td>Form controls will have their <span>autofill field name</span> set to "<code
data-x="attr-fe-autocomplete-off">off</code>" by default.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-form-autocomplete-on-state">on</span> state.</p>
<p>The <code data-x="attr-fs-action">action</code>, <code data-x="attr-fs-enctype">enctype</code>,
<code data-x="attr-fs-method">method</code>, <code data-x="attr-fs-novalidate">novalidate</code>,
and <code data-x="attr-fs-target">target</code> attributes are <span>attributes for form
submission</span>.</p>
<p>The <dfn element-attr for="form"><code data-x="attr-form-rel">rel</code></dfn> attribute on
<code>form</code> elements controls what kinds of links the elements create. The attribute's value
must be a <span>unordered set of unique space-separated tokens</span>. The <a
href="#linkTypes">allowed keywords and their meanings</a> are defined in an earlier section.</p>
<p><code data-x="attr-form-rel">rel</code>'s <span data-x="concept-supported-tokens">supported
tokens</span> are the keywords defined in <a href="#linkTypes">HTML link types</a> which are
allowed on <code>form</code> elements, impact the processing model, and are supported by the user
agent. The possible <span data-x="concept-supported-tokens">supported tokens</span> are <code
data-x="rel-noreferrer">noreferrer</code>, <code data-x="rel-noopener">noopener</code>, and <code
data-x="rel-opener">opener</code>. <code data-x="attr-form-rel">rel</code>'s <span
data-x="concept-supported-tokens">supported tokens</span> must only include the tokens from this
list that the user agent implements the processing model for.</p>
<dl class="domintro">
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-elements">elements</span></code></dt>
<dd>
<p>Returns an <code>HTMLFormControlsCollection</code> of the form controls in the form
(excluding image buttons for historical reasons).</p>
</dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-length">length</span></code></dt>
<dd>
<p>Returns the number of form controls in the form (excluding image buttons for historical
reasons).</p>
</dd>
<dt><code data-x=""><var>form</var>[<var>index</var>]</code></dt>
<dd>
<p>Returns the <var>index</var>th element in the form (excluding image buttons for historical
reasons).</p>
</dd>
<dt><code data-x=""><var>form</var>[<var>name</var>]</code></dt>
<dd>
<p>Returns the form control (or, if there are several, a <code>RadioNodeList</code> of the form
controls) in the form with the given <span data-x="concept-id">ID</span> or <code
data-x="attr-fe-name">name</code> (excluding image buttons for historical reasons); or, if there
are none, returns the <code>img</code> element with the given ID.</p>
<p>Once an element has been referenced using a particular name, that name will continue being
available as a way to reference that element in this method, even if the element's actual <span
data-x="concept-id">ID</span> or <code data-x="attr-fe-name">name</code> changes, for as long as
the element remains in the <span>tree</span>.</p>
<p>If there are multiple matching items, then a <code>RadioNodeList</code> object containing all
those elements is returned.</p>
</dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-submit">submit</span>()</code></dt>
<dd>
<p>Submits the form, bypassing <span data-x="interactively validate the constraints">interactive
constraint validation</span> and without firing a <code data-x="event-submit">submit</code>
event.</p>
</dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-requestSubmit">requestSubmit</span>([ <var>submitter</var> ])</code></dt>
<dd>
<p>Requests to submit the form. Unlike <code data-x="dom-form-submit">submit()</code>, this
method includes <span data-x="interactively validate the constraints">interactive constraint
validation</span> and firing a <code data-x="event-submit">submit</code> event, either of which
can cancel submission.</p>
<p>The <var>submitter</var> argument can be used to point to a specific <span
data-x="concept-submit-button">submit button</span>, whose <code
data-x="attr-fs-formaction">formaction</code>, <code
data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code> attributes can impact submission. Additionally,
the submitter will be included when <span>constructing the entry list</span> for submission;
normally, buttons are excluded.</p>
</dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-reset">reset</span>()</code></dt>
<dd><p>Resets the form.</p></dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-checkValidity">checkValidity</span>()</code></dt>
<dd><p>Returns true if the form's controls are all valid; otherwise, returns false.</p></dd>
<dt><code data-x=""><var>form</var>.<span subdfn data-x="dom-form-reportValidity">reportValidity</span>()</code></dt>
<dd>
<p>Returns true if the form's controls are all valid; otherwise, returns false and informs the
user.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLFormElement"><code
data-x="dom-form-autocomplete">autocomplete</code></dfn> IDL attribute must <span>reflect</span>
the content attribute of the same name, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLFormElement"><code data-x="dom-form-name">name</code></dfn> and
<dfn attribute for="HTMLFormElement"><code data-x="dom-form-rel">rel</code></dfn> IDL attributes
must <span>reflect</span> the content attribute of the same name.</p>
<p>The <dfn attribute for="HTMLFormElement"><code
data-x="dom-form-acceptCharset">acceptCharset</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-form-accept-charset">accept-charset</code> content attribute.</p>
<p>The <dfn attribute for="HTMLFormElement"><code data-x="dom-form-relList">relList</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-form-rel">rel</code> content
attribute.</p>
<hr>
<p>The <dfn attribute for="HTMLFormElement"><code data-x="dom-form-elements">elements</code></dfn>
IDL attribute must return an <code>HTMLFormControlsCollection</code> rooted at the
<code>form</code> element's <span>root</span>, whose filter matches <span
data-x="category-listed">listed elements</span> whose <span>form owner</span> is the
<code>form</code> element, with the exception of <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-image">Image Button</span> state, which must, for historical reasons, be
excluded from this particular collection.</p>
<p>The <dfn attribute for="HTMLFormElement"><code data-x="dom-form-length">length</code></dfn> IDL
attribute must return the number of nodes <span data-x="represented by the
collection">represented</span> by the <code data-x="dom-form-elements">elements</code>
collection.</p>
<p>The <span>supported property indices</span> at any instant are the indices supported by the
object returned by the <code data-x="dom-form-elements">elements</code> attribute at that
instant.</p>
<p id="dom-form-item">To <span>determine the value of an indexed property</span> for a
<code>form</code> element, the user agent must return the value returned by the <code
data-x="dom-HTMLCollection-item">item</code> method on the <code
data-x="dom-form-elements">elements</code> collection, when invoked with the given index as its
argument.</p>
<hr>
<p>Each <code>form</code> element has a mapping of names to elements called the <dfn>past names
map</dfn>. It is used to persist names of controls even when they change names.</p>
<p>The <span>supported property names</span> consist of the names obtained from the following
algorithm, in the order obtained from this algorithm:</p>
<ol>
<li><p>Let <var>sourced names</var> be an initially empty ordered list of tuples
consisting of a string, an element, a source, where the source is either <i>id</i>, <i>name</i>,
or <i>past</i>, and, if the source is <i>past</i>, an age.</p></li>
<li>
<p>For each <span data-x="category-listed">listed element</span> <var>candidate</var>
whose <span>form owner</span> is the <code>form</code> element, with the exception of any
<code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in the
<span data-x="attr-input-type-image">Image Button</span> state:</p>
<ol>
<li><p>If <var>candidate</var> has an <code data-x="attr-id">id</code> attribute, add
an entry to <var>sourced names</var> with that <code data-x="attr-id">id</code>
attribute's value as the string, <var>candidate</var> as the element, and <i>id</i> as
the source.</p></li>
<li><p>If <var>candidate</var> has a <code data-x="attr-fe-name">name</code> attribute,
add an entry to <var>sourced names</var> with that <code
data-x="attr-fe-name">name</code> attribute's value as the string, <var>candidate</var>
as the element, and <i>name</i> as the source.</p></li>
</ol>
</li>
<li>
<p>For each <code>img</code> element <var>candidate</var> whose <span>form owner</span> is the
<code>form</code> element:</p>
<ol><!-- this is the same as the above list, except 'name' xrefs to something different -->
<li><p>If <var>candidate</var> has an <code data-x="attr-id">id</code> attribute, add
an entry to <var>sourced names</var> with that <code data-x="attr-id">id</code>
attribute's value as the string, <var>candidate</var> as the element, and <i>id</i> as
the source.</p></li>
<li><p>If <var>candidate</var> has a <code data-x="attr-img-name">name</code> attribute,
add an entry to <var>sourced names</var> with that <code
data-x="attr-img-name">name</code> attribute's value as the string, <var>candidate</var>
as the element, and <i>name</i> as the source.</p></li>
</ol>
</li>
<li>
<p>For each entry <var>past entry</var> in the <span>past names map</span>, add an entry
to <var>sourced names</var> with the <var>past entry</var>'s name as the
string, <var>past entry</var>'s element as the element, <i>past</i> as the source, and
the length of time <var>past entry</var> has been in the <span>past names map</span> as
the age.</p>
</li>
<li><p>Sort <var>sourced names</var> by <span>tree order</span> of the element entry of
each tuple, sorting entries with the same element by putting entries whose source is <i>id</i>
first, then entries whose source is <i>name</i>, and finally entries whose source is <i>past</i>,
and sorting entries with the same element and source by their age, oldest first.</p></li>
<li><p>Remove any entries in <var>sourced names</var> that have the empty string as
their name.</p></li>
<li><p>Remove any entries in <var>sourced names</var> that have the same name as an
earlier entry in the map.</p></li>
<li><p>Return the list of names from <var>sourced names</var>, maintaining their
relative order.</p></li>
</ol>
<p id="dom-form-nameditem">To <span>determine the value of a named property</span> <var>name</var>
for a <code>form</code> element, the user agent must run the following steps:</p>
<ol>
<li><p>Let <var>candidates</var> be a <span>live</span> <code>RadioNodeList</code> object
containing all the <span data-x="category-listed">listed elements</span>, whose <span>form
owner</span> is the <code>form</code> element, that have either an <code
data-x="attr-id">id</code> attribute or a <code data-x="attr-fe-name">name</code> attribute equal
to <var>name</var>, with the exception of <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-image">Image Button</span> state, in <span>tree order</span>.</p></li>
<!-- we return RadioNodeList here for consistency -->
<li><p>If <var>candidates</var> is empty, let <var>candidates</var> be a <span>live</span>
<code>RadioNodeList</code> object containing all the <code>img</code> elements, whose <span>form
owner</span> is the <code>form</code> element, that have either an <code
data-x="attr-id">id</code> attribute or a <code data-x="attr-img-name">name</code> attribute
equal to <var>name</var>, in <span>tree order</span>.</p></li>
<li><p>If <var>candidates</var> is empty, <var>name</var> is the name of one of
the entries in the <code>form</code> element's <span>past names map</span>: return the object
associated with <var>name</var> in that map.</p></li>
<li><p>If <var>candidates</var> contains more than one node, return <var>candidates</var>.</p></li>
<li><p>Otherwise, <var>candidates</var> contains exactly one node. Add a mapping from
<var>name</var> to the node in <var>candidates</var> in the <code>form</code>
element's <span>past names map</span>, replacing the previous entry with the same name, if
any.</p></li>
<li><p>Return the node in <var>candidates</var>.</p></li>
</ol>
<p>If an element listed in a <code>form</code> element's <span>past names map</span> changes
<span>form owner</span>, then its entries must be removed from that map.</p>
<!--
This ridiculous setup is intended to do as much of the right thing while still supporting code
written to work in IE7. IE versions prior to IE8 do not update the names on the <form> element
collection to match new names when elements are renamed, and there are enough pages that rename
elements and then access them by their old name that we have to support this.
But we still want to expose them using the new names, so as far as possible we pretend the
legacy names aren't there except if there's no other element actually named that way.
Removing the element did remove the legacy name in IE7:
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E...%3Cform%20action%3D%22%2F%22%3E%3Cinput%20name%3Dsubmit%3E%3C%2Fform%3E%0A%3Cscript%3E%0A%20w(document.forms%5B0%5D.submit)%3B%0A%20w(document.forms%5B0%5D.removeChild(document.getElementsByTagName('input')%5B0%5D))%3B%0A%20w(document.forms%5B0%5D.length)%3B%0A%20try%20%7B%20document.forms%5B0%5D.submit()%3B%20%7D%20catch%20(e)%20%20%7B%20w(e.message)%20%7D%0A%3C%2Fscript%3E
There's no interop on what happens when the name was originally a duplicate name, so we don't
persist such accesses - at the time of writing, Safari returned the first element, Firefox
returned null (as we do), and IE7 returned the original collection:
https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E...%3Cform%20action%3D%22%2F%22%3E%3Cinput%20name%3Da%20id%3Dfirst%3E%3Cinput%20name%3Da%20id%3Dsecond%3E%3C%2Fform%3E%0A%3Cscript%3E%0A%20w%28document.forms[0].a%29%3B%0A%20document.getElementsByTagName%28%27input%27%29[0].name%20%3D%20%27b%27%3B%0A%20document.getElementsByTagName%28%27input%27%29[1].name%20%3D%20%27b%27%3B%0A%20w%28document.forms[0].length%29%3B%0A%20w%28document.forms[0].a.id%29%3B%0A%3C%2Fscript%3E
In addition, the <img> fallback nonsense is similarly here for legacy reasons. As is the
exclusion of <input type=image>.
Also, check these out:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1220
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2388
-->
<hr>
<p>The <dfn method for="HTMLFormElement"><code data-x="dom-form-submit">submit()</code></dfn>
method steps are to <span data-x="concept-form-submit">submit</span> <span>this</span> from
<span>this</span>, with <i data-x="submit-subbmitted-from-method">submitted from <code
data-x="dom-form-submit">submit()</code> method</i> set to true.</p>
<p>The <dfn method for="HTMLFormElement"><code
data-x="dom-form-requestSubmit">requestSubmit(<var>submitter</var>)</code></dfn> method, when
invoked, must run the following steps:</p>
<ol>
<li>
<p>If <var>submitter</var> is not null, then:</p>
<ol>
<li><p>If <var>submitter</var> is not a <span data-x="concept-submit-button">submit
button</span>, then throw a <code>TypeError</code>.</p></li>
<li><p>If <var>submitter</var>'s <span>form owner</span> is not this <code>form</code> element,
then throw a <span>"<code>NotFoundError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>submitter</var> to this <code>form</code> element.</p></li>
<li><p><span data-x="concept-form-submit">Submit</span> this <code>form</code> element, from
<var>submitter</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLFormElement"><code data-x="dom-form-reset">reset()</code></dfn>
method, when invoked, must run the following steps:</p>
<ol>
<li><p>If the <code>form</code> element is marked as <i data-x="locked for reset">locked for reset</i>, then return.</p></li>
<li><p>Mark the <code>form</code> element as <dfn>locked for reset</dfn>.</p></li>
<li><p><span data-x="concept-form-reset">Reset</span> the <code>form</code> element.</p></li>
<li><p>Unmark the <code>form</code> element as <i data-x="locked for reset">locked for reset</i>.</p></li>
</ol>
<p>If the <dfn method for="HTMLFormElement"><code
data-x="dom-form-checkValidity">checkValidity()</code></dfn> method is invoked, the user agent
must <span>statically validate the constraints</span> of the <code>form</code> element, and return
true if the constraint validation return a <i>positive</i> result, and false if it returned a
<i>negative</i> result.</p>
<p>If the <dfn method for="HTMLFormElement"><code
data-x="dom-form-reportValidity">reportValidity()</code></dfn> method is invoked, the user agent
must <span>interactively validate the constraints</span> of the <code>form</code> element, and
return true if the constraint validation return a <i>positive</i> result, and false if it returned
a <i>negative</i> result.</p>
</div>
<div class="example">
<p>This example shows two search forms:</p>
<pre><code class="html"><form action="https://www.google.com/search" method="get">
<label>Google: <input type="search" name="q"></label> <input type="submit" value="Search...">
</form>
<form action="https://www.bing.com/search" method="get">
<label>Bing: <input type="search" name="q"></label> <input type="submit" value="Search...">
</form></code></pre>
</div>
<h4>The <dfn element><code>label</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, but with no descendant <span data-x="category-label">labelable elements</span> unless it is the element's <span>labeled control</span>, and no descendant <code>label</code> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-label-for">for</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-label">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-label">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLLabelElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-label-form">form</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-label-htmlFor">htmlFor</span>;
readonly attribute <span>HTMLElement</span>? <span data-x="dom-label-control">control</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLLabelElement</code>.</dd>
</dl>
<p>The <code>label</code> element <span>represents</span> a caption in a user interface. The
caption can be associated with a specific form control<span w-nodev>, known as the
<code>label</code> element's <dfn>labeled control</dfn></span>, either using the <code
data-x="attr-label-for">for</code> attribute, or by putting the form control inside the
<code>label</code> element itself.</p>
<div w-nodev>
<p>Except where otherwise specified by the following rules, a <code>label</code> element has no
<span>labeled control</span>.</p>
</div>
<p>The <dfn element-attr for="label"><code data-x="attr-label-for">for</code></dfn> attribute may
be specified to indicate a form control with which the caption is to be associated. If the
attribute is specified, the attribute's value must be the <span data-x="concept-id">ID</span> of a
<span data-x="category-label">labelable element</span> in the same <span>tree</span> as the
<code>label</code> element. <span w-nodev>If the attribute is specified and there is an element in
the <span>tree</span> whose <span data-x="concept-id">ID</span> is equal to the value of the <code
data-x="attr-label-for">for</code> attribute, and the first such element in <span>tree
order</span> is a <span data-x="category-label">labelable element</span>, then that element is the
<code>label</code> element's <span>labeled control</span>.</span></p>
<div w-nodev>
<p>If the <code data-x="attr-label-for">for</code> attribute is not specified, but the
<code>label</code> element has a <span data-x="category-label">labelable element</span> descendant,
then the first such descendant in <span>tree order</span> is the <code>label</code> element's
<span>labeled control</span>.</p>
<p>The <code>label</code> element's exact default presentation and behavior, in particular what
its <span>activation behavior</span> might be, if anything, should match the platform's label
behavior. The <span>activation behavior</span> of a <code>label</code> element for events targeted
at <span>interactive content</span> descendants of a <code>label</code> element, and any
descendants of those <span>interactive content</span> descendants, must be to do nothing.</p>
<p class="note"><span data-x="form-associated custom element">Form-associated custom
elements</span> are <span data-x="category-label">labelable elements</span>, so for user agents
where the <code>label</code> element's <span>activation behavior</span> impacts the <span>labeled
control</span>, both built-in and custom elements will be impacted.</p>
<!-- activation behavior need not be dependent on whether the
labeled control is being rendered:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=371
-->
<div class="example">
<p>For example, on platforms where clicking a label activates the form control, clicking the
<code>label</code> in the following snippet could trigger the user agent to <span>fire a <code
data-x="event-click">click</code> event</span> at the <code>input</code> element, as if the
element itself had been triggered by the user:</p>
<pre><code class="html"><label><input type=checkbox name=lost> Lost</label></code></pre>
<p>Similarly, assuming <code data-x="">my-checkbox</code> was declared as a
<span>form-associated custom element</span> (like in <a href="#custom-elements-face-example">this
example</a>), then the code</p>
<pre><code class="html"><label><my-checkbox name=lost></my-checkbox> Lost</label></code></pre>
<p>would have the same behavior, <span data-x="fire a click event">firing a <code
data-x="event-click">click</code> event</span> at the <code data-x="">my-checkbox</code>
element.</p>
<p>On other platforms, the behavior in both cases might be just to focus the control, or to do
nothing.</p>
</div>
</div>
<div class="example">
<p>The following example shows three form controls each with a label, two of which have small
text showing the right format for users to use.</p>
<pre><code class="html"><p><label>Full name: <input name=fn> <small>Format: First Last</small></label></p>
<p><label>Age: <input name=age type=number min=0></label></p>
<p><label>Post code: <input name=pc> <small>Format: AB12 3CD</small></label></p></code></pre>
</div>
<dl class="domintro">
<dt><code data-x=""><var>label</var>.<span subdfn data-x="dom-label-control">control</span></code></dt>
<dd><p>Returns the form control that is associated with this element.</p></dd>
<dt><code data-x=""><var>label</var>.<span subdfn data-x="dom-label-form">form</span></code></dt>
<dd>
<p>Returns the <span>form owner</span> of the form control that is associated with this
element.</p>
<p>Returns null if there isn't one.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLLabelElement"><code data-x="dom-label-htmlFor">htmlFor</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-label-for">for</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLLabelElement"><code data-x="dom-label-control">control</code></dfn>
IDL attribute must return the <code>label</code> element's <span>labeled control</span>, if any,
or null if there isn't one.</p>
<p>The <dfn attribute for="HTMLLabelElement"><code data-x="dom-label-form">form</code></dfn> IDL
attribute must run the following steps:</p>
<ol>
<li><p>If the <code>label</code> element has no <span>labeled control</span>, then return
null.</p></li>
<li><p>If the <code>label</code> element's <span>labeled control</span> is not a
<span>form-associated element</span>, then return null.</p></li>
<li><p>Return the <code>label</code> element's <span>labeled control</span>'s <span>form
owner</span> (which can still be null).</p></li>
</ol>
</div>
<p class="note">The <code data-x="dom-label-form">form</code> IDL attribute on the
<code>label</code> element is different from the <code data-x="attr-fae-form">form</code> IDL
attribute on <span data-x="category-listed">listed</span> <span data-x="form-associated
element">form-associated elements</span>, and the <code>label</code> element does not have a <code
data-x="attr-fae-form">form</code> content attribute.</p>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>control</var>.<span subdfn data-x="dom-lfe-labels">labels</span></code></dt>
<dd>
<p>Returns a <code>NodeList</code> of all the <code>label</code> elements that the form control
is associated with.</p>
</dd>
</dl>
<div w-nodev>
<p><span data-x="category-label">Labelable elements</span> and all <code>input</code> elements
have a <span>live</span> <code>NodeList</code> object associated with them that represents the
list of <code>label</code> elements, in <span>tree order</span>, whose <span>labeled
control</span> is the element in question. The <dfn attribute
for="HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLProgressElement,HTMLMeterElement"><code
data-x="dom-lfe-labels">labels</code></dfn> IDL attribute of <span
data-x="category-label">labelable elements</span> that are not <span data-x="form-associated
custom element">form-associated custom elements</span>, and the <code
data-x="dom-lfe-labels">labels</code> IDL attribute of <code>input</code> elements, on getting,
must return that <code>NodeList</code> object, and that same value must always be returned, unless
this element is an <code>input</code> element whose <code data-x="attr-input-type">type</code>
attribute is in the <span data-x="attr-input-type-hidden">Hidden</span> state, in which case it
must instead return null.</p>
<p><span data-x="form-associated custom element">Form-associated custom elements</span> don't have
a <code data-x="dom-lfe-labels">labels</code> IDL attribute. Instead, their
<code>ElementInternals</code> object has a <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-labels">labels</code></dfn> IDL attribute. On getting, it must throw
a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code> if the <span
data-x="internals-target">target element</span> is not a <span>form-associated custom
element</span>. Otherwise, it must return that <code>NodeList</code> object, and that same value
must always be returned.</p>
<div class="example">
<p>This (non-conforming) example shows what happens to the <code>NodeList</code> and what <code
data-x="dom-lfe-labels">labels</code> returns when an <code>input</code> element has its <code
data-x="attr-input-type">type</code> attribute changed.</p>
<pre><code class="html"><!doctype html>
<p><label><input></label></p>
<script>
const input = document.querySelector('input');
const labels = input.labels;
console.assert(labels.length === 1);
input.type = 'hidden';
console.assert(labels.length === 0); // the input is no longer the label's <span>labeled control</span>
console.assert(input.labels === null);
input.type = 'checkbox';
console.assert(labels.length === 1); // the input is once again the label's <span>labeled control</span>
console.assert(input.labels === labels); // same value as returned originally
</script></code></pre>
</div>
</div>
<h4 split-filename="input">The <dfn element><code>input</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd>If the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state: <span>Interactive content</span>.</dd>
<dd>If the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state: <span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-submit">submittable</span>, <span data-x="category-reset">resettable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd>If the <code data-x="attr-input-type">type</code> attribute is in the <span data-x="attr-input-type-hidden">Hidden</span> state: <span data-x="category-listed">Listed</span>, <span data-x="category-submit">submittable</span>, <span data-x="category-reset">resettable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd>If the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state: <span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-input-accept">accept</code></dd>
<dd><code data-x="attr-input-alpha">alpha</code></dd>
<dd><code data-x="attr-input-alt">alt</code></dd>
<dd><code data-x="attr-fe-autocomplete">autocomplete</code></dd>
<dd><code data-x="attr-input-checked">checked</code></dd>
<dd><code data-x="attr-input-colorspace">colorspace</code></dd>
<dd><code data-x="attr-fe-dirname">dirname</code></dd>
<dd><code data-x="attr-fe-disabled">disabled</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-fs-formaction">formaction</code></dd>
<dd><code data-x="attr-fs-formenctype">formenctype</code></dd>
<dd><code data-x="attr-fs-formmethod">formmethod</code></dd>
<dd><code data-x="attr-fs-formnovalidate">formnovalidate</code></dd>
<dd><code data-x="attr-fs-formtarget">formtarget</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dd><code data-x="attr-input-list">list</code></dd>
<dd><code data-x="attr-input-max">max</code></dd>
<dd><code data-x="attr-input-maxlength">maxlength</code></dd>
<dd><code data-x="attr-input-min">min</code></dd>
<dd><code data-x="attr-input-minlength">minlength</code></dd>
<dd><code data-x="attr-input-multiple">multiple</code></dd>
<dd><code data-x="attr-fe-name">name</code></dd>
<dd><code data-x="attr-input-pattern">pattern</code></dd>
<dd><code data-x="attr-input-placeholder">placeholder</code></dd>
<dd><code data-x="attr-popovertarget">popovertarget</code></dd>
<dd><code data-x="attr-popovertargetaction">popovertargetaction</code></dd>
<dd><code data-x="attr-input-readonly">readonly</code></dd>
<dd><code data-x="attr-input-required">required</code></dd>
<dd><code data-x="attr-input-size">size</code></dd>
<dd><code data-x="attr-input-src">src</code></dd>
<dd><code data-x="attr-input-step">step</code></dd>
<dd><code data-x="attr-input-type">type</code></dd>
<dd><code data-x="attr-input-value">value</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd>Also, the <code data-x="attr-input-title">title</code> attribute <span data-x="attr-input-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-hidden">Hidden</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-hidden">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-hidden">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-text">Text</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-text">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-text">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-search">Search</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-search">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-search">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-tel">Telephone</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-tel">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-tel">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-url">URL</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-url">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-url">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-email">Email</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-email">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-email">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-password">Password</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-password">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-password">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-date">Date</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-date">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-date">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-month">Month</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-month">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-month">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-week">Week</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-week">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-week">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-time">Time</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-time">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-time">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-datetime-local">Local Date and Time</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-datetime-local">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-datetime-local">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-number">Number</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-number">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-number">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-range">Range</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-range">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-range">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-color">Color</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-color">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-color">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-checkbox">Checkbox</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-checkbox">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-checkbox">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-radio">Radio Button</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-radio">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-radio">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-file">File Upload</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-file">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-file">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-submit">Submit Button</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-submit">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-submit">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-image">Image Button</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-image">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-image">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-reset">Reset Button</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-reset">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-reset">for implementers</a>.</dd>
<dd><code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-button">Button</span> state: <a
href="https://w3c.github.io/html-aria/#el-input-button">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-input-button">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLInputElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-accept">accept</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-input-alpha">alpha</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-alt">alt</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-autocomplete">autocomplete</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-input-defaultChecked">defaultChecked</span>;
attribute boolean <span data-x="dom-input-checked">checked</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-colorspace">colorSpace</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-dirName">dirName</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fe-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
attribute <span>FileList</span>? <span data-x="dom-input-files">files</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-fs-formAction">formAction</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formEnctype">formEnctype</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formMethod">formMethod</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fs-formNoValidate">formNoValidate</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formTarget">formTarget</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-input-height">height</span>;
attribute boolean <span data-x="dom-input-indeterminate">indeterminate</span>;
readonly attribute <span>HTMLDataListElement</span>? <span data-x="dom-input-list">list</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-max">max</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-input-maxLength">maxLength</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-min">min</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-input-minLength">minLength</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-input-multiple">multiple</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-pattern">pattern</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-placeholder">placeholder</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-input-readOnly">readOnly</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-input-required">required</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-input-size">size</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-input-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-step">step</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-defaultValue">defaultValue</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-input-value">value</span>;
attribute <span data-x="idl-object">object</span>? <span data-x="dom-input-valueAsDate">valueAsDate</span>;
attribute unrestricted double <span data-x="dom-input-valueAsNumber">valueAsNumber</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-input-width">width</span>;
undefined <span data-x="dom-input-stepUp">stepUp</span>(optional long n = 1);
undefined <span data-x="dom-input-stepDown">stepDown</span>(optional long n = 1);
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
readonly attribute <span>NodeList</span>? <span data-x="dom-lfe-labels">labels</span>;
undefined <span data-x="dom-textarea/input-select">select</span>();
attribute unsigned long? <span data-x="dom-textarea/input-selectionStart">selectionStart</span>;
attribute unsigned long? <span data-x="dom-textarea/input-selectionEnd">selectionEnd</span>;
attribute DOMString? <span data-x="dom-textarea/input-selectionDirection">selectionDirection</span>;
undefined <span data-x="dom-textarea/input-setRangeText">setRangeText</span>(DOMString replacement);
undefined <span data-x="dom-textarea/input-setRangeText">setRangeText</span>(DOMString replacement, unsigned long start, unsigned long end, optional <span>SelectionMode</span> selectionMode = "preserve");
undefined <span data-x="dom-textarea/input-setSelectionRange">setSelectionRange</span>(unsigned long start, unsigned long end, optional DOMString direction);
undefined <span data-x="dom-input-showPicker">showPicker</span>();
// <a href="#HTMLInputElement-partial">also has obsolete members</a>
};
<span>HTMLInputElement</span> includes <span>PopoverInvokerElement</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLInputElement</code>.</dd>
</dl>
<p>The <code>input</code> element <span>represents</span> a typed data field, usually with a form
control to allow the user to edit the data.</p>
<p>The <dfn element-attr for="input"><code data-x="attr-input-type">type</code></dfn> attribute
controls the data type (and associated control) of the element. It is an <span>enumerated
attribute</span> with the following keywords and states:</p>
<table id="attr-input-type-keywords">
<thead>
<tr>
<th> Keyword
<th> State
<th> Data type
<th> Control type
<tbody>
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-hidden-keyword">hidden</code></dfn>
<td> <span data-x="attr-input-type-hidden">Hidden</span>
<td> An arbitrary string
<td> n/a
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-text-keyword">text</code></dfn>
<td> <span data-x="attr-input-type-text">Text</span>
<td> Text with no line breaks
<td> A text control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-search-keyword">search</code></dfn>
<td> <span data-x="attr-input-type-search">Search</span>
<td> Text with no line breaks
<td> Search control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-tel-keyword">tel</code></dfn>
<td> <span data-x="attr-input-type-tel">Telephone</span>
<td> Text with no line breaks
<td> A text control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-url-keyword">url</code></dfn>
<td> <span data-x="attr-input-type-url">URL</span>
<td> An absolute URL
<td> A text control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-email-keyword">email</code></dfn>
<td> <span data-x="attr-input-type-email">Email</span>
<td> An email address or list of email addresses
<td> A text control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-password-keyword">password</code></dfn>
<td> <span data-x="attr-input-type-password">Password</span>
<td> Text with no line breaks (sensitive information)
<td> A text control that obscures data entry
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-date-keyword">date</code></dfn>
<td> <span data-x="attr-input-type-date">Date</span>
<td> A date (year, month, day) with no time zone
<td> A date control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-month-keyword">month</code></dfn>
<td> <span data-x="attr-input-type-month">Month</span>
<td> A date consisting of a year and a month with no time zone
<td> A month control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-week-keyword">week</code></dfn>
<td> <span data-x="attr-input-type-week">Week</span>
<td> A date consisting of a week-year number and a week number with no time zone
<td> A week control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-time-keyword">time</code></dfn>
<td> <span data-x="attr-input-type-time">Time</span>
<td> A time (hour, minute, seconds, fractional seconds) with no time zone
<td> A time control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-datetime-local-keyword">datetime-local</code></dfn>
<td> <span data-x="attr-input-type-datetime-local">Local Date and Time</span>
<td> A date and time (year, month, day, hour, minute, second, fraction of a second) with no time zone
<td> A date and time control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-number-keyword">number</code></dfn>
<td> <span data-x="attr-input-type-number">Number</span>
<td> A numerical value
<td> A text control or spinner control
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-range-keyword">range</code></dfn>
<td> <span data-x="attr-input-type-range">Range</span>
<td> A numerical value, with the extra semantic that the exact value is not important
<td> A slider control or similar
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-color-keyword">color</code></dfn>
<td> <span data-x="attr-input-type-color">Color</span>
<td> An sRGB color with 8-bit red, green, and blue components
<td> A color picker
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-checkbox-keyword">checkbox</code></dfn>
<td> <span data-x="attr-input-type-checkbox">Checkbox</span>
<td> A set of zero or more values from a predefined list
<td> A checkbox
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-radio-keyword">radio</code></dfn>
<td> <span data-x="attr-input-type-radio">Radio Button</span>
<td> An enumerated value
<td> A radio button
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-file-keyword">file</code></dfn>
<td> <span data-x="attr-input-type-file">File Upload</span>
<td> Zero or more files each with a <span>MIME type</span> and optionally a filename
<td> A label and a button
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-submit-keyword">submit</code></dfn>
<td> <span data-x="attr-input-type-submit">Submit Button</span>
<td> An enumerated value, with the extra semantic that it must be the last value selected and initiates form submission
<td> A button
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-image-keyword">image</code></dfn>
<td> <span data-x="attr-input-type-image">Image Button</span>
<td> A coordinate, relative to a particular image's size, with the extra semantic that it must
be the last value selected and initiates form submission
<td> Either a clickable image, or a button
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-reset-keyword">reset</code></dfn>
<td> <span data-x="attr-input-type-reset">Reset Button</span>
<td> n/a
<td> A button
<tr>
<td> <dfn attr-value for="input/type"><code data-x="attr-input-type-button-keyword">button</code></dfn>
<td> <span data-x="attr-input-type-button">Button</span>
<td> n/a
<td> A button
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-input-type-text">Text</span> state.</p>
<p>Which of the
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code> content attributes, the
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>,
<code data-x="dom-input-valueAsNumber">valueAsNumber</code>, and
<code data-x="dom-input-list">list</code> IDL attributes, the
<code data-x="dom-textarea/input-select">select()</code> method, the
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, and
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, IDL attributes, the
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code> and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods, the
<code data-x="dom-input-stepUp">stepUp()</code> and
<code data-x="dom-input-stepDown">stepDown()</code> methods, and the
<code data-x="event-input">input</code> and
<code data-x="event-change">change</code> events <dfn data-x="concept-input-apply">apply</dfn> to an
<code>input</code> element depends on the state of its
<code data-x="attr-input-type">type</code> attribute.
The subsections that define each type also clearly define in normative "bookkeeping" sections
which of these feature apply, and which <dfn>do not apply</dfn>, to each type. The behavior of
these features depends on whether they apply or not, as defined in their various sections (q.v.
for <a href="#common-input-element-attributes">content attributes</a>, for <a
href="#common-input-element-apis">APIs</a>, for <a
href="#common-input-element-events">events</a>).</p>
<p>The following table <span w-nodev>is non-normative and</span> summarizes which of those
content attributes, IDL attributes, methods, and events <span
data-x="concept-input-apply">apply</span> to each state:</p>
<table class="applies" id="input-type-attr-summary">
<thead>
<tr>
<th>
<th> <span data-x=""><span data-x="attr-input-type-hidden">Hidden</span></span>
<th> <span data-x=""><span data-x="attr-input-type-text">Text</span>,</span>
<span data-x=""><span data-x="attr-input-type-search">Search</span></span>
<th> <span data-x=""><span data-x="attr-input-type-tel">Telephone</span>,</span>
<span data-x=""><span data-x="attr-input-type-url">URL</span></span>
<th> <span data-x=""><span data-x="attr-input-type-email">Email</span></span>
<th> <span data-x=""><span data-x="attr-input-type-password">Password</span></span>
<th> <span data-x=""><span data-x="attr-input-type-date">Date</span>,</span>
<span data-x=""><span data-x="attr-input-type-month">Month</span>,</span>
<span data-x=""><span data-x="attr-input-type-week">Week</span>,</span>
<span data-x=""><span data-x="attr-input-type-time">Time</span></span>
<th> <span data-x=""><span data-x="attr-input-type-datetime-local">Local Date and Time</span></span>
<th> <span data-x=""><span data-x="attr-input-type-number">Number</span></span>
<th> <span data-x=""><span data-x="attr-input-type-range">Range</span></span>
<th> <span data-x=""><span data-x="attr-input-type-color">Color</span></span>
<th> <span data-x=""><span data-x="attr-input-type-checkbox">Checkbox</span>,</span>
<span data-x=""><span data-x="attr-input-type-radio">Radio Button</span></span>
<th> <span data-x=""><span data-x="attr-input-type-file">File Upload</span></span>
<th> <span data-x=""><span data-x="attr-input-type-submit">Submit Button</span></span>
<th> <span data-x=""><span data-x="attr-input-type-image">Image Button</span></span>
<th> <span data-x=""><span data-x="attr-input-type-reset">Reset Button</span>,</span>
<span data-x=""><span data-x="attr-input-type-button">Button</span></span>
<tbody>
<tr>
<th scope="rowgroup" colspan="16">Content attributes
<tr>
<th> <code data-x="attr-input-accept">accept</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-alpha">alpha</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-alt">alt</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fe-autocomplete">autocomplete</code>
<td class="yes"> Yes <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-checked">checked</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="yes"> Yes <!-- Checkbox -->
<!-- <td class="yes"> Yes Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-colorspace">colorspace</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fe-dirname">dirname</code>
<td class="yes"> Yes <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fs-formaction">formaction</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fs-formenctype">formenctype</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fs-formmethod">formmethod</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fs-formnovalidate">formnovalidate</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-fs-formtarget">formtarget</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-dim-height">height</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-list">list</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-max">max</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-maxlength">maxlength</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-min">min</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-minlength">minlength</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-multiple">multiple</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL --> <!-- if you change this, you can merge this line with the next to save room on the chart -->
<td class="yes"> Yes <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-pattern">pattern</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-placeholder">placeholder</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-popovertarget">popovertarget</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="yes"> Yes <!-- Reset Button -->
<!-- <td class="yes"> Yes Button -->
<tr>
<th> <code data-x="attr-popovertargetaction">popovertargetaction</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="yes"> Yes <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="yes"> Yes <!-- Reset Button -->
<!-- <td class="yes"> Yes Button -->
<tr>
<th> <code data-x="attr-input-readonly">readonly</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-required">required</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="yes"> Yes <!-- Checkbox -->
<!-- <td class="yes"> Yes Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-size">size</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-src">src</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-input-step">step</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="attr-dim-width">width</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="yes"> Yes <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tbody>
<tr>
<th scope="rowgroup" colspan="16">IDL attributes and methods
<tr>
<th> <code data-x="dom-input-checked">checked</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="yes"> Yes <!-- Checkbox -->
<!-- <td class="yes"> Yes Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-input-files">files</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr w-nodev>
<th> <code data-x="dom-input-value">value</code>
<td class="yes"> <span data-x="dom-input-value-default">default</span> <!-- Hidden -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Text -->
<!-- <td class="yes"> <span data-x="dom-input-value-value">value</span> Search -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Telephone, URL -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Email -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Password -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Date -->
<!-- <td class="yes"> <span data-x="dom-input-value-value">value</span> Month -->
<!-- <td class="yes"> <span data-x="dom-input-value-value">value</span> Week -->
<!-- <td class="yes"> <span data-x="dom-input-value-value">value</span> Time -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Local Date and Time -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Number -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Range -->
<td class="yes"> <span data-x="dom-input-value-value">value</span> <!-- Color -->
<td class="yes"> <span data-x="dom-input-value-default-on">default/on</span> <!-- Checkbox -->
<!-- <td class="yes"> <span data-x="dom-input-value-default-on">default/on</span> Radio Button -->
<td class="yes"> <span data-x="dom-input-value-filename">filename</span> <!-- File Upload -->
<td class="yes"> <span data-x="dom-input-value-default">default</span> <!-- Submit Button -->
<td class="yes"> <span data-x="dom-input-value-default">default</span> <!-- Image Button -->
<td class="yes"> <span data-x="dom-input-value-default">default</span> <!-- Reset Button -->
<!-- <td class="yes"> <span data-x="dom-input-value-default">default</span> Button -->
<tr>
<th> <code data-x="dom-input-valueAsDate">valueAsDate</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-input-valueAsNumber">valueAsNumber</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-input-list">list</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-select">select()</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes† <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes† <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes† <!-- Local Date and Time -->
<td class="yes"> Yes† <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="yes"> Yes† <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="yes"> Yes† <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-selectionStart">selectionStart</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-setRangeText">setRangeText()</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="no"> · <!-- Date -->
<!-- <td class="no"> · Month -->
<!-- <td class="no"> · Week -->
<!-- <td class="no"> · Time -->
<td class="no"> · <!-- Local Date and Time -->
<td class="no"> · <!-- Number -->
<td class="no"> · <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-input-stepDown">stepDown()</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <code data-x="dom-input-stepUp">stepUp()</code>
<td class="no"> · <!-- Hidden -->
<td class="no"> · <!-- Text -->
<!-- <td class="no"> · Search -->
<td class="no"> · <!-- Telephone, URL -->
<td class="no"> · <!-- Email -->
<td class="no"> · <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="no"> · <!-- Color -->
<td class="no"> · <!-- Checkbox -->
<!-- <td class="no"> · Radio Button -->
<td class="no"> · <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tbody>
<tr>
<th scope="rowgroup" colspan="16">Events
<tr>
<th> <span data-x=""><code data-x="event-input">input</code> event</span>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="yes"> Yes <!-- Checkbox -->
<!-- <td class="yes"> Yes Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
<tr>
<th> <span data-x=""><code data-x="event-change">change</code> event</span>
<td class="no"> · <!-- Hidden -->
<td class="yes"> Yes <!-- Text -->
<!-- <td class="yes"> Yes Search -->
<td class="yes"> Yes <!-- Telephone, URL -->
<td class="yes"> Yes <!-- Email -->
<td class="yes"> Yes <!-- Password -->
<td class="yes"> Yes <!-- Date -->
<!-- <td class="yes"> Yes Month -->
<!-- <td class="yes"> Yes Week -->
<!-- <td class="yes"> Yes Time -->
<td class="yes"> Yes <!-- Local Date and Time -->
<td class="yes"> Yes <!-- Number -->
<td class="yes"> Yes <!-- Range -->
<td class="yes"> Yes <!-- Color -->
<td class="yes"> Yes <!-- Checkbox -->
<!-- <td class="yes"> Yes Radio Button -->
<td class="yes"> Yes <!-- File Upload -->
<td class="no"> · <!-- Submit Button -->
<td class="no"> · <!-- Image Button -->
<td class="no"> · <!-- Reset Button -->
<!-- <td class="no"> · Button -->
</table>
<p class="tablenote"><small>† If the control has no selectable text, the <code
data-x="dom-textarea/input-select">select()</code> method results in a no-op, with no
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</small></p>
<div w-nodev>
<p>Some states of the <code data-x="attr-input-type">type</code> attribute define a <dfn>value
sanitization algorithm</dfn>.</p>
<p>Each <code>input</code> element has a <span data-x="concept-fe-value">value</span>, which is
exposed by the <code data-x="dom-input-value">value</code> IDL attribute. Some states define an
<dfn data-x="concept-input-value-string-number">algorithm to convert a string to a number</dfn>,
an <dfn data-x="concept-input-value-number-string">algorithm to convert a number to a
string</dfn>, an <dfn data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</dfn>, and an <dfn data-x="concept-input-value-date-string">algorithm to
convert a <code>Date</code> object to a string</dfn>, which are used by <code
data-x="attr-input-max">max</code>, <code data-x="attr-input-min">min</code>, <code
data-x="attr-input-step">step</code>, <code data-x="dom-input-valueAsDate">valueAsDate</code>,
<code data-x="dom-input-valueAsNumber">valueAsNumber</code>, and <code
data-x="dom-input-stepUp">stepUp()</code>.</p>
<p>An <code>input</code> element's <span data-x="concept-fe-dirty">dirty value flag</span> must be
set to true whenever the user interacts with the control in a way that changes the <span
data-x="concept-fe-value">value</span>. (It is also set to true when the value is programmatically
changed, as described in the definition of the <code data-x="dom-input-value">value</code> IDL
attribute.)</p>
</div>
<p>The <dfn element-attr for="input"><code data-x="attr-input-value">value</code></dfn> content
attribute gives the default <span data-x="concept-fe-value">value</span> of the <code>input</code>
element. <span w-nodev>When the <code data-x="attr-input-value">value</code> content attribute is
added, set, or removed, if the control's <span data-x="concept-fe-dirty">dirty value flag</span>
is false, the user agent must set the <span data-x="concept-fe-value">value</span> of the element
to the value of the <code data-x="attr-input-value">value</code> content attribute, if there is
one, or the empty string otherwise, and then run the current <span>value sanitization
algorithm</span>, if one is defined.</span></p>
<div w-nodev>
<p>Each <code>input</code> element has a <span data-x="concept-fe-checked">checkedness</span>,
which is exposed by the <code data-x="dom-input-checked">checked</code> IDL attribute.</p>
<p>Each <code>input</code> element has a boolean <dfn
data-x="concept-input-checked-dirty-flag">dirty checkedness flag</dfn>. When it is true, the
element is said to have a <dfn data-x="concept-input-checked-dirty"><i>dirty checkedness</i></dfn>.
The <span data-x="concept-input-checked-dirty-flag">dirty checkedness flag</span> must be initially
set to false when the element is created, and must be set to true whenever the user interacts with
the control in a way that changes the <span data-x="concept-fe-checked">checkedness</span>.</p>
</div>
<p>The <dfn element-attr for="input"><code data-x="attr-input-checked">checked</code></dfn>
content attribute is a <span>boolean attribute</span> that gives the default <span
data-x="concept-fe-checked">checkedness</span> of the <code>input</code> element. <span
w-nodev>When the <code data-x="attr-input-checked">checked</code> content attribute is added, if
the control does not have <i data-x="concept-input-checked-dirty">dirty checkedness</i>, the user
agent must set the <span data-x="concept-fe-checked">checkedness</span> of the element to true;
when the <code data-x="attr-input-checked">checked</code> content attribute is removed, if the
control does not have <i data-x="concept-input-checked-dirty">dirty checkedness</i>, the user
agent must set the <span data-x="concept-fe-checked">checkedness</span> of the element to
false.</span></p>
<div w-nodev>
<p>The <span data-x="concept-form-reset-control">reset algorithm</span> for <code>input</code>
elements is to set its <span>user validity</span>,
<span data-x="concept-fe-dirty">dirty value flag</span>, and
<span data-x="concept-input-checked-dirty-flag">dirty checkedness flag</span>
back to false, set the <span data-x="concept-fe-value">value</span> of the element to the value
of the <code data-x="attr-input-value">value</code> content attribute, if there is one, or the
empty string otherwise, set the <span data-x="concept-fe-checked">checkedness</span> of the
element to true if the element has a <code data-x="attr-input-checked">checked</code> content
attribute and false if it does not, empty the list of <span
data-x="concept-input-type-file-selected">selected files</span>, and then invoke the <span>value
sanitization algorithm</span>, if the <code data-x="attr-input-type">type</code> attribute's
current state defines one.</p>
<p>Each <code>input</code> element can be <i data-x="concept-fe-mutable">mutable</i>. Except where
otherwise specified, an <code>input</code> element is always <i
data-x="concept-fe-mutable">mutable</i>. Similarly, except where otherwise specified, the user
agent should not allow the user to modify the element's <span
data-x="concept-fe-value">value</span> or <span data-x="concept-fe-checked">checkedness</span>.</p>
<p>When an <code>input</code> element is <span
data-x="concept-fe-disabled">disabled</span>, it is not <i
data-x="concept-fe-mutable">mutable</i>.</p>
<p class="note">The <code data-x="attr-input-readonly">readonly</code> attribute can also in some
cases (e.g. for the <span data-x="attr-input-type-date">Date</span> state, but not the <span
data-x="attr-input-type-checkbox">Checkbox</span> state) stop an <code>input</code> element from
being <i data-x="concept-fe-mutable">mutable</i>.</p>
<p>The <code>input</code> element can <dfn data-x="input-support-picker">support a picker</dfn>. A
picker is a user interface element that allows the end user to choose a value. Whether an
<code>input</code> element supports a picker depends on the <code
data-x="attr-input-type">type</code> attribute state and <span>implementation-defined</span>
behavior. An <code>input</code> element must support a picker when its <code
data-x="attr-input-type">type</code> attribute is in the <span data-x="attr-input-type-file">File
Upload</span> state.</p>
<div class="note">
<p>As of the time of this writing, typical browser implementations show such picker UI for:</p>
<ul>
<li><p><code>input</code> elements whose <code data-x="attr-input-type">type</code>
attributes are in the <span data-x="attr-input-type-date">Date</span>, <span
data-x="attr-input-type-month">Month</span>, <span data-x="attr-input-type-week">Week</span>,
<span data-x="attr-input-type-time">Time</span>, <span
data-x="attr-input-type-datetime-local">Local Date and Time</span>, and <span
data-x="attr-input-type-color">Color</span> states;</p></li>
<li><p><code>input</code> elements in various states that have a <span
data-x="concept-input-list">suggestions source element</span>;</p></li>
<li><p><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute
is in the <span data-x="attr-input-type-file">File Upload</span> state; and</p></li>
<li><p><code>select</code> elements.</p></li>
</ul>
</div>
<p>The <span data-x="concept-node-clone-ext">cloning steps</span> for <code>input</code> elements
given <var>node</var>, <var>copy</var>, and <var>subtree</var> are to propagate the <span
data-x="concept-fe-value">value</span>, <span data-x="concept-fe-dirty">dirty value flag</span>,
<span data-x="concept-fe-checked">checkedness</span>, and <span
data-x="concept-input-checked-dirty-flag">dirty checkedness flag</span> from <var>node</var> to
<var>copy</var>.</p>
<p>The <span>activation behavior</span> for <code>input</code> elements <var>element</var>, given
<var>event</var>, are these steps:</p>
<ol>
<li><p>If <var>element</var> is not <i data-x="concept-fe-mutable">mutable</i>, and
<var>element</var>'s <span data-x="attr-input-type">type</span> attribute is neither in the <span
data-x="attr-input-type-checkbox">Checkbox</span> nor in the <span
data-x="attr-input-type-radio">Radio</span> state, then return.</p></li>
<li><p>Run <var>element</var>'s <dfn>input activation behavior</dfn>, if any, and do nothing
otherwise.</p></li>
<li><p>If <var>element</var> has a <span>form owner</span> and <var>element</var>'s <span
data-x="attr-input-type">type</span> attribute is not in the <span
data-x="attr-input-type-button">Button</span> state, then return.</p></li>
<li><p>Run the <span>popover target attribute activation behavior</span> given <var>element</var>
and <var>event</var>'s <span data-x="concept-event-target">target</span>.</p></li>
</ol>
<p class="note">Recall that an element's <span>activation behavior</span> runs for both
user-initiated activations and for synthetic activations (e.g., via <code
data-x="">el.click()</code>). User agents might also have behaviors for a given control — not
specified here — that are triggered only by true user-initiated activations. A common choice is to
<span>show the picker, if applicable</span>, for the control. In contrast, the <span>input
activation behavior</span> only shows pickers for the special historical cases of the <span
data-x="attr-input-type-file">File Upload</span> and <span
data-x="attr-input-type-color">Color</span> states.</p>
<p>The <span>legacy-pre-activation behavior</span> for <code>input</code> elements are these
steps:</p>
<ol>
<li><p>If this element's <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-checkbox">Checkbox state</span>, then set this element's <span
data-x="concept-fe-checked">checkedness</span> to its opposite value (i.e. true if it is false,
false if it is true) and set this element's <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute to false.</p></li>
<li><p>If this element's <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button state</span>, then get a reference to the element in
this element's <span>radio button group</span> that has its <span
data-x="concept-fe-checked">checkedness</span> set to true, if any, and then set this element's
<span data-x="concept-fe-checked">checkedness</span> to true.</p></li>
</ol>
<p>The <span>legacy-canceled-activation behavior</span> for <code>input</code> elements are these
steps:</p>
<ol>
<li><p>If the element's <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-checkbox">Checkbox state</span>, then set the element's <span
data-x="concept-fe-checked">checkedness</span> and the element's <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute back to the values they had
before the <span>legacy-pre-activation behavior</span> was run.</p></li>
<li><p>If this element's <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button state</span>, then if the element to which a
reference was obtained in the <span>legacy-pre-activation behavior</span>, if any, is still in
what is now this element's <span>radio button group</span>, if it still has one, and if so,
setting that element's <span data-x="concept-fe-checked">checkedness</span> to true; or else, if
there was no such element, or that element is no longer in this element's <span>radio button
group</span>, or if this element no longer has a <span>radio button group</span>, setting this
element's <span data-x="concept-fe-checked">checkedness</span> to false.
</ol>
<!--
http://software.hixie.ch/utilities/js/live-dom-viewer/?saved=3094
http://software.hixie.ch/utilities/js/live-dom-viewer/?saved=3095
http://software.hixie.ch/utilities/js/live-dom-viewer/?saved=3096
-->
<hr>
<p>When an <code>input</code> element is first created, the element's rendering and behavior must
be set to the rendering and behavior defined for the <code data-x="attr-input-type">type</code>
attribute's state, and the <span>value sanitization algorithm</span>, if one is defined for the
<code data-x="attr-input-type">type</code> attribute's state, must be invoked.</p>
</div>
<div id="input-type-change" w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute
changes state, the user agent must run the following steps:</p>
<ol>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=602 -->
<li><p>If the previous state of the element's <code data-x="attr-input-type">type</code> attribute
put the <code data-x="dom-input-value">value</code> IDL attribute in the <i
data-x="dom-input-value-value">value</i> mode, and the element's <span
data-x="concept-fe-value">value</span> is not the empty string, and the new state of the element's
<code data-x="attr-input-type">type</code> attribute puts the <code
data-x="dom-input-value">value</code> IDL attribute in either the <i
data-x="dom-input-value-default">default</i> mode or the <i
data-x="dom-input-value-default-on">default/on</i> mode, then set the element's <code
data-x="attr-input-value">value</code> content attribute to the element's <span
data-x="concept-fe-value">value</span>.</p></li>
<li><p>Otherwise, if the previous state of the element's <code
data-x="attr-input-type">type</code> attribute put the <code data-x="dom-input-value">value</code>
IDL attribute in any mode other than the <i data-x="dom-input-value-value">value</i> mode, and the
new state of the element's <code data-x="attr-input-type">type</code> attribute puts the <code
data-x="dom-input-value">value</code> IDL attribute in the <i
data-x="dom-input-value-value">value</i> mode, then set the <span
data-x="concept-fe-value">value</span> of the element to the value of the <code
data-x="attr-input-value">value</code> content attribute, if there is one, or the empty string
otherwise, and then set the control's <span data-x="concept-fe-dirty">dirty value flag</span> to
false.</p></li>
<!-- This step is present for the sake of clarity and safety so that the previous internal value
can't be accidentally referenced while we're in the type=file state. This step's effect isn't
(or at least shouldn't be) observable by script, due to the #input-type-change and
#dom-input-value state machines. -->
<li><p>Otherwise, if the previous state of the element's <code
data-x="attr-input-type">type</code> attribute put the <code
data-x="dom-input-value">value</code> IDL attribute in any mode other than the <i
data-x="dom-input-value-filename">filename</i> mode, and the new state of the element's <code
data-x="attr-input-type">type</code> attribute puts the <code
data-x="dom-input-value">value</code> IDL attribute in the <i
data-x="dom-input-value-filename">filename</i> mode, then set the <span
data-x="concept-fe-value">value</span> of the element to the empty string.</p></li>
<li><p>Update the element's rendering and behavior to the new state's.</p></li>
<li><p><dfn>Signal a type change</dfn> for the element. (The <span
data-x="attr-input-type-radio">Radio Button</span> state uses this, in particular.)</p></li>
<li><p>Invoke the <span>value sanitization algorithm</span>, if one is defined for the <code
data-x="attr-input-type">type</code> attribute's new state.</p></li>
<li><p>Let <var>previouslySelectable</var> be true if <code
data-x="dom-textarea/input-setRangeText">setRangeText()</code> previously <span
data-x="concept-input-apply">applied</span> to the element, and false otherwise.</p></li>
<li><p>Let <var>nowSelectable</var> be true if <code
data-x="dom-textarea/input-setRangeText">setRangeText()</code> now <span
data-x="concept-input-apply">applies</span> to the element, and false otherwise.</p></li>
<li><p>If <var>previouslySelectable</var> is false and <var>nowSelectable</var> is true, set the
element's <span data-x="concept-textarea/input-cursor">text entry cursor position</span> to the
beginning of the text control, and <span data-x="set the selection direction">set its selection
direction</span> to "<code data-x="">none</code>".</p></li>
</ol>
</div>
<hr>
<p>
The <code data-x="attr-fe-name">name</code> attribute represents the element's name.
The <code data-x="attr-fe-dirname">dirname</code> attribute controls how the element's <span data-x="the directionality">directionality</span> is submitted.
The <code data-x="attr-fe-disabled">disabled</code> attribute is used to make the control non-interactive and to prevent its value from being submitted.
The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the <code>input</code> element with its <span>form owner</span>.
The <code data-x="attr-fe-autocomplete">autocomplete</code> attribute controls how the user agent provides autofill behavior.
</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-indeterminate">indeterminate</code></dfn> IDL attribute must initially be set to
false. On getting, it must return the last value it was set to. On setting, it must be set to the
new value. It has no effect except for changing the appearance of <span
data-x="attr-input-type-checkbox">checkbox</span> controls.</p>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-accept">accept</code></dfn>,
<dfn attribute for="HTMLInputElement"><code data-x="dom-input-alpha">alpha</code></dfn>, <dfn
attribute for="HTMLInputElement"><code data-x="dom-input-alt">alt</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-max">max</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-min">min</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-multiple">multiple</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-pattern">pattern</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-placeholder">placeholder</code></dfn>, <dfn
attribute for="HTMLInputElement"><code data-x="dom-input-required">required</code></dfn>, <dfn
attribute for="HTMLInputElement"><code data-x="dom-input-size">size</code></dfn>, <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-src">src</code></dfn>, and <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-step">step</code></dfn> IDL attributes must
<span>reflect</span> the respective content attributes of the same name. The <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-dirName">dirName</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-fe-dirname">dirname</code> content attribute. The <dfn
attribute for="HTMLInputElement"><code data-x="dom-input-readOnly">readOnly</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-input-readonly">readonly</code> content
attribute. The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-defaultChecked">defaultChecked</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-input-checked">checked</code> content attribute. The
<dfn attribute for="HTMLInputElement"><code
data-x="dom-input-defaultValue">defaultValue</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-input-value">value</code> content attribute.</p>
<p>The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-colorSpace">colorSpace</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-input-colorspace">colorspace</code> content attribute, <span>limited to only
known values</span>. The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-type">type</code></dfn> IDL attribute must <span>reflect</span> the respective
content attribute of the same name, <span>limited to only known values</span>. The <dfn attribute
for="HTMLInputElement"><code data-x="dom-input-maxLength">maxLength</code></dfn> IDL attribute
must <span>reflect</span> the <code data-x="attr-input-maxlength">maxlength</code> content
attribute, <span>limited to only non-negative numbers</span>. The <dfn
attribute for="HTMLInputElement"><code data-x="dom-input-minLength">minLength</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-input-minlength">minlength</code>
content attribute, <span>limited to only non-negative numbers</span>.</p>
<p>The IDL attributes <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-width">width</code></dfn> and <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-height">height</code></dfn> must return the rendered width and height of the
image, in <span data-x="'px'">CSS pixels</span>, if an image is <span>being rendered</span>; or
else the <span data-x="natural dimensions">natural width and height</span> of the image, in
<span data-x="'px'">CSS pixels</span>, if an image is <i
data-x="input-img-available">available</i> but not <span>being rendered</span>; or else 0,
if no image is <i data-x="input-img-available">available</i>. When the <code>input</code>
element's <code data-x="attr-input-type">type</code> attribute is not in the <span
data-x="attr-input-type-image">Image Button</span> state, then no image is <i
data-x="input-img-available">available</i>. <ref>CSS</ref></p>
<p>On setting, they must act as if they <span data-x="reflect">reflected</span> the respective
content attributes of the same name.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> IDL attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-lfe-labels">labels</code> IDL
attribute provides a list of the element's <code>label</code>s. The <code
data-x="dom-textarea/input-select">select()</code>, <code
data-x="dom-textarea/input-selectionStart">selectionStart</code>, <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, <code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, <code
data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and <code
data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods and IDL attributes
expose the element's text selection. The <code data-x="dom-fe-disabled">disabled</code>,
<code data-x="dom-fae-form">form</code>, and <code data-x="dom-fe-name">name</code> IDL attributes
are part of the element's forms API.</p>
</div>
<h5>States of the <code data-x="attr-input-type">type</code> attribute</h5>
<h6><dfn element-state for="input" data-x="attr-input-type-hidden">Hidden</dfn> state (<code data-x="">type=hidden</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-hidden">Hidden</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a value that is not intended to be
examined or manipulated by the user.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If an <code>input</code> element's <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-hidden">Hidden</span> state, it is <span>barred from constraint
validation</span>.</p>
</div>
<p>If the <code data-x="attr-fe-name">name</code> attribute is present and has a value that is an
<span>ASCII case-insensitive</span> match for "<code
data-x="attr-fe-name-charset">_charset_</code>", then the element's <code
data-x="attr-input-value">value</code> attribute must be omitted.</p>
<div class="bookkeeping">
<p>The
<code data-x="attr-fe-autocomplete">autocomplete</code> and
<code data-x="attr-fe-dirname">dirname</code>
content attributes <span data-x="concept-input-apply">apply</span> to this element.</p>
<p>The
<code data-x="dom-input-value">value</code>
IDL attribute <span data-x="concept-input-apply">applies</span> to this element and is
in mode <span data-x="dom-input-value-default">default</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code
data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span>do not apply</span>.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-text">Text</dfn> (<code data-x="">type=text</code>) state and <dfn element-state for="input" data-x="attr-input-type-search">Search</dfn> state (<code data-x="">type=search</code>)</h6>
<!-- v2 idea: applying input masks to <input>, e.g. for entering
data with slashes and dashes (ack Greg Kilwein)
-->
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-text">Text</span> state or the <span
data-x="attr-input-type-search">Search</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a one line plain text edit control for
the element's <span data-x="concept-fe-value">value</span>.</p>
<p class="note">The difference between the <span data-x="attr-input-type-text">Text</span> state
and the <span data-x="attr-input-type-search">Search</span> state is primarily stylistic: on
platforms where search controls are distinguished from regular text controls, the <span
data-x="attr-input-type-search">Search</span> state might result in an appearance consistent with
the platform's search controls rather than appearing like a regular text control.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, its <span
data-x="concept-fe-value">value</span> should be editable by the user. User agents must not allow
users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the element's
<span data-x="concept-fe-value">value</span>.</p>
<!-- this next bit is also in the <textarea> section -->
<!-- and something similar is in the session history section -->
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the writing direction of the element, setting it either to a left-to-right writing
direction or a right-to-left writing direction. If the user does so, the user agent must then run
the following steps:</p>
<ol>
<li><p>Set the element's <code data-x="attr-dir">dir</code> attribute to "<code
data-x="attr-dir-ltr">ltr</code>" if the user selected a left-to-right writing direction, and
"<code data-x="attr-dir-rtl">rtl</code>" if the user selected a right-to-left writing
direction.</p></li>
<li><p><span>Queue an element task</span> on the <span>user interaction task source</span> given
the element to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-input">input</code> at the element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
</ol>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: <span>Strip
newlines</span> from the <span data-x="concept-fe-value">value</span>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-size">size</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-tel">Telephone</dfn> state (<code data-x="">type=tel</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-tel">Telephone</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for editing a telephone number
given in the element's <span data-x="concept-fe-value">value</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, its <span
data-x="concept-fe-value">value</span> should be editable by the user. User agents may change the
spacing and, with care, the punctuation of <span data-x="concept-fe-value">values</span> that the
user enters. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE
RETURN (CR) characters into the element's <span data-x="concept-fe-value">value</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: <span>Strip
newlines</span> from the <span data-x="concept-fe-value">value</span>.</p>
</div>
<p class="note">Unlike the <span data-x="attr-input-type-url">URL</span> and <span
data-x="attr-input-type-email">Email</span> types, the <span
data-x="attr-input-type-tel">Telephone</span> type does not enforce a particular syntax. This is
intentional; in practice, telephone number fields tend to be free-form fields, because there are a
wide variety of valid phone numbers. Systems that need to enforce a particular format are
encouraged to use the <code data-x="attr-input-pattern">pattern</code> attribute or the <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> method to hook into the client-side
validation mechanism.</p>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-size">size</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-url">URL</dfn> state (<code data-x="">type=url</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-url">URL</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for editing a single
<span>absolute URL</span> given in the element's <span data-x="concept-fe-value">value</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the URL represented by its <span data-x="concept-fe-value">value</span>. User agents
may allow the user to set the <span data-x="concept-fe-value">value</span> to a string that is not
a <span data-x="valid URL string">valid</span> <span>absolute URL</span>, but may also or instead
automatically escape characters entered by the user so that the <span
data-x="concept-fe-value">value</span> is always a <span data-x="valid URL string">valid</span>
<span>absolute URL</span> (even if that isn't the actual value seen and edited by the user in the
interface). User agents should allow the user to set the <span
data-x="concept-fe-value">value</span> to the empty string. User agents must not allow users to
insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the <span
data-x="concept-fe-value">value</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid URL potentially surrounded by spaces</span> that is also an
<span>absolute URL</span>.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: <span>Strip
newlines</span> from the <span data-x="concept-fe-value">value</span>, then <span>strip leading
and trailing ASCII whitespace</span> from the <span data-x="concept-fe-value">value</span>.</p>
<p><strong>Constraint validation</strong>: While the <span data-x="concept-fe-value">value</span>
of the element is neither the empty string nor a <span data-x="valid URL string">valid</span>
<span>absolute URL</span>, the element is <span>suffering from a type mismatch</span>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-size">size</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<div class="example">
<p>If a document contained the following markup:</p>
<pre><code class="html"><input type="url" name="location" list="urls">
<datalist id="urls">
<option label="MIME: Format of Internet Message Bodies" value="https://www.rfc-editor.org/rfc/rfc2045">
<option label="HTML" value="https://html.spec.whatwg.org/">
<option label="DOM" value="https://dom.spec.whatwg.org/">
<option label="Fullscreen" value="https://fullscreen.spec.whatwg.org/">
<option label="Media Session" value="https://mediasession.spec.whatwg.org/">
<option label="The Single UNIX Specification, Version 3" value="http://www.unix.org/version3/">
</datalist></code></pre>
<p>...and the user had typed "<kbd>spec.w</kbd>", and the user agent had also found that the user
had visited <code data-x="">https://url.spec.whatwg.org/#url-parsing</code> and <code
data-x="">https://streams.spec.whatwg.org/</code> in the recent past, then the rendering might look
like this:</p>
<p><img src="/images/sample-url.svg" width="480" height="150" alt="A text box with an icon on the left followed by the text "spec.w" and a cursor, with a drop down button on the right hand side; with, below, a drop down box containing a list of six URLs on the left, with the first four having grayed out labels on the right; and a scrollbar to the right of the drop down box, indicating further values are available." class="darkmode-aware"></p>
<p>The first four URLs in this sample consist of the four URLs in the author-specified list that
match the text the user has entered, sorted in some <span>implementation-defined</span> manner
(maybe by how frequently the user refers to those URLs). Note how the UA is using the knowledge
that the values are URLs to allow the user to omit the scheme part and perform intelligent
matching on the domain name.</p>
<p>The last two URLs (and probably many more, given the scrollbar's indications of more values
being available) are the matches from the user agent's session history data. This data is not
made available to the page DOM. In this particular case, the UA has no titles to provide for
those values.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-email">Email</dfn> state (<code data-x="">type=email</code>)<span
id="e-mail-state-(type=email)"></span></h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-email">Email</span> state, the rules in this section apply.</p>
</div>
<p>How the <span data-x="attr-input-type-email">Email</span> state operates depends on whether the
<code data-x="attr-input-multiple">multiple</code> attribute is specified or not.</p>
<dl class="switch">
<dt>When the <code data-x="attr-input-multiple">multiple</code> attribute is not specified on the
element</dt>
<dd>
<p>The <code>input</code> element <span>represents</span> a control for editing an email
address given in the element's <span data-x="concept-fe-value">value</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the email address represented by its <span
data-x="concept-fe-value">value</span>. User agents may allow the user to set the <span
data-x="concept-fe-value">value</span> to a string that is not a <span>valid email
address</span>. The user agent should act in a manner consistent with expecting the user to
provide a single email address. User agents should allow the user to set the <span
data-x="concept-fe-value">value</span> to the empty string. User agents must not allow users to
insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the <span
data-x="concept-fe-value">value</span>. User agents may transform the <span
data-x="concept-fe-value">value</span> for display and editing; in particular, user agents should
convert punycode in the domain labels of the <span data-x="concept-fe-value">value</span> to IDN in the display and
vice versa.</p>
<p><strong>Constraint validation</strong>: While the user interface is representing input that
the user agent cannot convert to punycode, the control is <span>suffering from bad
input</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a single <span>valid email address</span>.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: <span>Strip
newlines</span> from the <span data-x="concept-fe-value">value</span>, then <span>strip leading
and trailing ASCII whitespace</span> from the <span data-x="concept-fe-value">value</span>.</p>
<p><strong>Constraint validation</strong>: While the <span data-x="concept-fe-value">value</span>
of the element is neither the empty string nor a single <span>valid email address</span>, the
element is <span>suffering from a type mismatch</span>.</p>
</div>
</dd>
<dt>When the <code data-x="attr-input-multiple">multiple</code> attribute <em>is</em> specified on
the element</dt>
<dd>
<p>The <code>input</code> element <span>represents</span> a control for adding, removing, and
editing the email addresses given in the element's <span
data-x="concept-fe-values">value<em>s</em></span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to add, remove, and edit the email addresses represented by its <span
data-x="concept-fe-values">values</span>. User agents may allow the user to set any
individual value in the list of <span data-x="concept-fe-value">value<em>s</em></span> to a
string that is not a <span>valid email address</span>, but must not allow users to set any
individual value to a string containing U+002C COMMA (,), U+000A LINE FEED (LF), or U+000D
CARRIAGE RETURN (CR) characters. User agents should allow the user to remove all the addresses
in the element's <span data-x="concept-fe-values">values</span>. User agents may
transform the <span data-x="concept-fe-values">values</span> for display and editing; in
particular, user agents should convert punycode in the domain labels of the <span
data-x="concept-fe-value">value</span> to IDN in the display and vice versa.</p>
<p><strong>Constraint validation</strong>: While the user interface describes a situation where
an individual value contains a U+002C COMMA (,) or is representing input that the user agent
cannot convert to punycode, the control is <span>suffering from bad input</span>.</p>
<p>Whenever the user changes the element's <span
data-x="concept-fe-value">value<em>s</em></span>, the user agent must run the following
steps:</p>
<ol>
<li><p>Let <var>latest values</var> be a copy of the element's <span
data-x="concept-fe-value">value<em>s</em></span>.</p></li>
<!-- It's a copy because /values/ might include leading and trailing spaces that we don't
necessarily want to remove from the UI but that we do want to remove before serializing. -->
<li><p><span>Strip leading and trailing ASCII whitespace</span> from each value in <var>latest
values</var>.</p></li>
<li><p>Let the element's <span data-x="concept-fe-value">value</span> be the result of
concatenating all the values in <var>latest values</var>, separating each value from
the next by a single U+002C COMMA character (,), maintaining the list's order.</p></li>
</ol>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified, must have a value
that is a <span>valid email address list</span>.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>:</p>
<ol>
<li><p><span data-x="split a string on commas">Split on commas</span> the element's <span
data-x="concept-fe-value">value</span>, <span>strip leading and trailing ASCII
whitespace</span> from each resulting token, if any, and let the element's <span
data-x="concept-fe-values">values</span> be the (possibly empty) resulting list of
(possibly empty) tokens, maintaining the original order.</p></li>
<li><p>Let the element's <span data-x="concept-fe-value">value</span> be the result of
concatenating the element's <span data-x="concept-fe-values">values</span>, separating
each value from the next by a single U+002C COMMA character (,), maintaining the list's
order.</p></li>
</ol>
<p><strong>Constraint validation</strong>: While the <span data-x="concept-fe-value">value</span>
of the element is not a <span>valid email address list</span>, the element is <span>suffering
from a type mismatch</span>.</p>
</div>
</dd>
</dl>
<p>When the <code data-x="attr-input-multiple">multiple</code> attribute is set or removed, the
user agent must run the <span>value sanitization algorithm</span>.</p>
<p>A <dfn id="valid-e-mail-address">valid email address</dfn> is a string that matches the <code
data-x="">email</code> production of the following ABNF, the character set for which is Unicode.
This ABNF implements the extensions described in RFC 1123. <ref>ABNF</ref> <ref>RFC5322</ref>
<ref>RFC1034</ref> <ref>RFC1123</ref></p>
<pre><code data-x="" class="abnf">email = 1*( atext / "." ) "@" label *( "." label )
label = let-dig [ [ ldh-str ] let-dig ] ; limited to a length of 63 characters by <a href="https://www.rfc-editor.org/rfc/rfc1034#section-3.5">RFC 1034 section 3.5</a>
atext = < as defined in <a href="https://www.rfc-editor.org/rfc/rfc5322#section-3.2.3">RFC 5322 section 3.2.3</a> >
let-dig = < as defined in <a href="https://www.rfc-editor.org/rfc/rfc1034#section-3.5">RFC 1034 section 3.5</a> >
ldh-str = < as defined in <a href="https://www.rfc-editor.org/rfc/rfc1034#section-3.5">RFC 1034 section 3.5</a> ></code></pre>
<!-- Domain syntax based on section 3.5 of [RFC1034] and section 2.1 of [RFC1123] -->
<p class="note">This requirement is a <span>willful violation</span> of RFC 5322, which defines a
syntax for email addresses that is simultaneously too strict (before the "@" character), too
vague (after the "@" character), and too lax (allowing comments, whitespace characters, and quoted
strings in manners unfamiliar to most users) to be of practical use here.</p>
<div class="note">
<p>The following JavaScript- and Perl-compatible regular expression is an implementation of the
above definition.</p>
<pre>/^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/</pre>
<!-- based on: https://blog.gerv.net/2011/05/html5_email_address_regexp/ -->
</div>
<p>A <dfn id="valid-e-mail-address-list">valid email address list</dfn> is a <span>set of
comma-separated tokens</span>, where each token is itself a <span>valid email address</span>.
<span w-nodev>To obtain the list of tokens from a <span>valid email address list</span>, an
implementation must <span data-x="split a string on commas">split the string on
commas</span>.</span></p>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-size">size</code> content attributes;
<code data-x="dom-input-list">list</code> and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code> method.</p>
<!--
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element when
the <code data-x="attr-input-multiple">multiple</code> attribute is
not specified:
.</p>
-->
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-password">Password</dfn> state (<code data-x="">type=password</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state, the rules in this section
apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a one line plain text edit control for
the element's <span data-x="concept-fe-value">value</span>. The user agent should obscure the value
so that people other than the user cannot see it.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, its <span
data-x="concept-fe-value">value</span> should be editable by the user. User agents must not allow
users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the <span
data-x="concept-fe-value">value</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: <span>Strip
newlines</span> from the <span data-x="concept-fe-value">value</span>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-size">size</code> content attributes;
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6 id="date-state-(type=date)"><dfn element-state for="input" data-x="attr-input-type-date">Date</dfn> state (<code data-x="">type=date</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-date">Date</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a specific <span
data-x="concept-date">date</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the <span data-x="concept-date">date</span> represented by its <span
data-x="concept-fe-value">value</span>, as obtained by <span data-x="parse a date string">parsing a
date</span> from it. User agents must not allow the user to set the <span
data-x="concept-fe-value">value</span> to a non-empty string that is not a <span>valid date
string</span>. If the user agent provides a user interface for selecting a <span
data-x="concept-date">date</span>, then the <span data-x="concept-fe-value">value</span> must be set
to a <span>valid date string</span> representing the user's selection. User agents should allow
the user to set the <span data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid date string</span>, the control is <span>suffering from bad
input</span>.</p>
</div>
<p class="note">See the <a href="#input-author-notes">introduction section</a> for a discussion of
the difference between the input format and submission format for date, time, and number form
controls<span w-nodev>, and the <a href="#input-impl-notes">implementation notes</a>
regarding localization of form controls</span>.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid date string</span>.</p> <!-- ok to set out-of-range value, we
never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid date string</span>, then
set it to the empty string instead.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid date string</span>. The <code data-x="attr-input-max">max</code> attribute, if
specified, must have a value that is a <span>valid date string</span>.</p>
<p>The <code data-x="attr-input-step">step</code> attribute is expressed in days. <span
w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is 86,400,000
(which converts the days to milliseconds, as used in the other algorithms).</span> The <span
data-x="concept-input-step-default">default step</span> is 1 day.</p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest <span
data-x="concept-date">date</span> for which the element would not <span data-x="suffering from a
step mismatch">suffer from a step mismatch</span>.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a date string">parsing a date</span> from <var>input</var> results in an
error, then return an error; otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value "<code
data-x="">1970-01-01T00:00:00.0Z</code>") to midnight UTC on the morning of the parsed <span
data-x="concept-date">date</span>, ignoring leap seconds.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid date string</span> that represents the <span data-x="concept-date">date</span> that, in
UTC, is current <var>input</var> milliseconds after midnight UTC on the morning of
1970-01-01 (the time represented by the value "<code data-x="">1970-01-01T00:00:00.0Z</code>").</p>
<p><strong>The <span data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</span>, given a string <var>input</var>, is as follows</strong>:
If <span data-x="parse a date string">parsing a date</span> from <var>input</var> results
in an error, then return an error; otherwise, return <span data-x="create a Date object">a new
<code>Date</code> object</span> representing midnight UTC on the morning of the parsed <span
data-x="concept-date">date</span>.</p>
<p><strong>The <span data-x="concept-input-value-date-string">algorithm to convert a
<code>Date</code> object to a string</span>, given a <code>Date</code> object <var>input</var>, is
as follows</strong>: Return a <span>valid date string</span> that represents the <span
data-x="concept-date">date</span> current at the time represented by <var>input</var> in the UTC
time zone.</p>
</div>
<div class="note" id="only-contemporary-times">
<p>The <span data-x="attr-input-type-date">Date</span> state (and other date- and time-related
states described in subsequent sections) is not intended for the entry of values for which a
precise date and time relative to the contemporary calendar cannot be established. For example,
it would be inappropriate for the entry of times like "one millisecond after the big bang", "the
early part of the Jurassic period", or "a winter around 250 BCE".</p>
<p>For the input of dates before the introduction of the Gregorian calendar, authors are
encouraged to not use the <span data-x="attr-input-type-date">Date</span> state (and the other
date- and time-related states described in subsequent sections), as user agents are not required
to support converting dates and times from earlier periods to the Gregorian calendar, and asking
users to do so manually puts an undue burden on users. (This is complicated by the manner in
which the Gregorian calendar was phased in, which occurred at different times in different
countries, ranging from partway through the 16th century all the way to early in the 20th.)
Instead, authors are encouraged to provide fine-grained input controls using the
<code>select</code> element and <code>input</code> elements with the <span
data-x="attr-input-type-number">Number</span> state.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, and
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-month">Month</dfn> state (<code data-x="">type=month</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-month">Month</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a specific <span
data-x="concept-month">month</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the <span data-x="concept-month">month</span> represented by its <span
data-x="concept-fe-value">value</span>, as obtained by <span data-x="parse a month string">parsing a
month</span> from it. User agents must not allow the user to set the <span
data-x="concept-fe-value">value</span> to a non-empty string that is not a <span>valid month
string</span>. If the user agent provides a user interface for selecting a <span
data-x="concept-month">month</span>, then the <span data-x="concept-fe-value">value</span> must be
set to a <span>valid month string</span> representing the user's selection. User agents should
allow the user to set the <span data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid month string</span>, the control is <span>suffering from bad
input</span>.</p>
</div>
<p class="note">See the <a href="#input-author-notes">introduction section</a> for a discussion of
the difference between the input format and submission format for date, time, and number form
controls<span w-nodev>, and the <a href="#input-impl-notes">implementation notes</a>
regarding localization of form controls</span>.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid month string</span>.</p> <!-- ok to set out-of-range value, we
never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid month string</span>,
then set it to the empty string instead.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid month string</span>. The <code data-x="attr-input-max">max</code> attribute, if
specified, must have a value that is a <span>valid month string</span>.</p>
<p>The <code data-x="attr-input-step">step</code> attribute is expressed in months. <span
w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is 1 (there is no
conversion needed as the algorithms use months).</span> The <span
data-x="concept-input-step-default">default step</span> is 1 month.</p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest <span
data-x="concept-month">month</span> for which the element would not <span data-x="suffering from a
step mismatch">suffer from a step mismatch</span>.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a month string">parsing a month</span> from <var>input</var> results in an
error, then return an error; otherwise, return the number of months between January 1970 and the
parsed <span data-x="concept-month">month</span>.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid month string</span> that represents the <span data-x="concept-month">month</span> that
has <var>input</var> months between it and January 1970.</p>
<!-- note - it doesn't matter exactly how many months are "between" two months, so long as the UA
implements this consistently. The number is never actually exposed. -->
<p><strong>The <span data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</span>, given a string <var>input</var>, is as follows</strong>:
If <span data-x="parse a month string">parsing a month</span> from <var>input</var>
results in an error, then return an error; otherwise, return <span data-x="create a Date object">a
new <code>Date</code> object</span> representing midnight UTC on the morning of the first day of
the parsed <span data-x="concept-month">month</span>.</p>
<p><strong>The <span data-x="concept-input-value-date-string">algorithm to convert a
<code>Date</code> object to a string</span>, given a <code>Date</code> object <var>input</var>, is
as follows</strong>: Return a <span>valid month string</span> that represents the <span
data-x="concept-month">month</span> current at the time represented by <var>input</var> in the UTC
time zone.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, and
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-week">Week</dfn> state (<code data-x="">type=week</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-week">Week</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a specific <span
data-x="concept-week">week</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the <span data-x="concept-week">week</span> represented by its <span
data-x="concept-fe-value">value</span>, as obtained by <span data-x="parse a week string">parsing a
week</span> from it. User agents must not allow the user to set the <span
data-x="concept-fe-value">value</span> to a non-empty string that is not a <span>valid week
string</span>. If the user agent provides a user interface for selecting a <span
data-x="concept-week">week</span>, then the <span data-x="concept-fe-value">value</span> must be set
to a <span>valid week string</span> representing the user's selection. User agents should allow
the user to set the <span data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid week string</span>, the control is <span>suffering from bad
input</span>.</p>
</div>
<p class="note">See the <a href="#input-author-notes">introduction section</a> for a discussion of
the difference between the input format and submission format for date, time, and number form
controls<span w-nodev>, and the <a href="#input-impl-notes">implementation notes</a>
regarding localization of form controls</span>.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid week string</span>.</p> <!-- ok to set out-of-range value, we
never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid week string</span>, then
set it to the empty string instead.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid week string</span>. The <code data-x="attr-input-max">max</code> attribute, if
specified, must have a value that is a <span>valid week string</span>.</p>
<p>The <code data-x="attr-input-step">step</code> attribute is expressed in weeks. <span
w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is 604,800,000
(which converts the weeks to milliseconds, as used in the other algorithms).</span> The <span
data-x="concept-input-step-default">default step</span> is 1 week. <span w-nodev>The <span
data-x="concept-input-step-default-base">default step base</span> is −259,200,000 (the start
of week 1970-W01).</span></p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest <span
data-x="concept-week">week</span> for which the element would not <span data-x="suffering from a
step mismatch">suffer from a step mismatch</span>.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a week string">parsing a week string</span> from <var>input</var> results in
an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value "<code
data-x="">1970-01-01T00:00:00.0Z</code>") to midnight UTC on the morning of the Monday of the
parsed <span data-x="concept-week">week</span>, ignoring leap seconds.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid week string</span> that represents the <span data-x="concept-week">week</span> that, in
UTC, is current <var>input</var> milliseconds after midnight UTC on the morning of
1970-01-01 (the time represented by the value "<code data-x="">1970-01-01T00:00:00.0Z</code>").</p>
<p><strong>The <span data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a week string">parsing a week</span> from <var>input</var> results in an error, then
return an error; otherwise, return <span data-x="create a Date object">a new <code>Date</code>
object</span> representing midnight UTC on the morning of the Monday of the parsed <span
data-x="concept-week">week</span>.</p>
<p><strong>The <span data-x="concept-input-value-date-string">algorithm to convert a
<code>Date</code> object to a string</span>, given a <code>Date</code> object <var>input</var>, is
as follows</strong>: Return a <span>valid week string</span> that represents the <span
data-x="concept-week">week</span> current at the time represented by <var>input</var> in the UTC
time zone.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes, IDL attributes, and
methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, and
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-time">Time</dfn> state (<code data-x="">type=time</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-time">Time</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a specific <span
data-x="concept-time">time</span>.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the <span data-x="concept-time">time</span> represented by its <span
data-x="concept-fe-value">value</span>, as obtained by <span data-x="parse a time string">parsing a
time</span> from it. User agents must not allow the user to set the <span
data-x="concept-fe-value">value</span> to a non-empty string that is not a <span>valid time
string</span>. If the user agent provides a user interface for selecting a <span
data-x="concept-time">time</span>, then the <span data-x="concept-fe-value">value</span> must be set
to a <span>valid time string</span> representing the user's selection. User agents should allow
the user to set the <span data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid time string</span>, the control is <span>suffering from bad
input</span>.</p>
</div>
<p class="note">See the <a href="#input-author-notes">introduction section</a> for a discussion of
the difference between the input format and submission format for date, time, and number form
controls<span w-nodev>, and the <a href="#input-impl-notes">implementation notes</a>
regarding localization of form controls</span>.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid time string</span>.</p> <!-- ok to set out-of-range value, we
never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid time string</span>, then
set it to the empty string instead.</p>
<p>The form control <span>has a periodic domain</span>.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid time string</span>. The <code data-x="attr-input-max">max</code> attribute, if
specified, must have a value that is a <span>valid time string</span>.</p>
<p>The <code data-x="attr-input-step">step</code> attribute is expressed in seconds. <span
w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is 1000 (which
converts the seconds to milliseconds, as used in the other algorithms).</span> The <span
data-x="concept-input-step-default">default step</span> is 60 seconds.</p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest <span
data-x="concept-time">time</span> for which the element would not <span data-x="suffering from a
step mismatch">suffer from a step mismatch</span>.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a time string">parsing a time</span> from <var>input</var> results in an
error, then return an error; otherwise, return the number of milliseconds elapsed from midnight to
the parsed <span data-x="concept-time">time</span> on a day with no time changes.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid time string</span> that represents the <span data-x="concept-time">time</span> that is
<var>input</var> milliseconds after midnight on a day with no time changes.</p>
<p><strong>The <span data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</span>, given a string <var>input</var>, is as
follows</strong>: If <span data-x="parse a time string">parsing a time</span> from
<var>input</var> results
in an error, then return an error; otherwise, return <span data-x="create a Date object">a new
<code>Date</code> object</span> representing the parsed <span data-x="concept-time">time</span> in
UTC on 1970-01-01.</p>
<p><strong>The <span data-x="concept-input-value-date-string">algorithm to convert a
<code>Date</code> object to a string</span>, given a <code>Date</code> object <var>input</var>, is
as follows</strong>: Return a <span>valid time string</span> that represents the UTC <span
data-x="concept-time">time</span> component that is represented by <var>input</var>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes, IDL attributes, and
methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, and
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-datetime-local">Local Date and Time</dfn> state (<code data-x="">type=datetime-local</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-datetime-local">Local Date and Time</span> state, the rules in
this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a <span
data-x="concept-datetime-local">local date and time</span>, with no time-zone offset
information.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the <span data-x="concept-datetime-local">date and time</span> represented by its
<span data-x="concept-fe-value">value</span>, as obtained by <span data-x="parse a local date and
time string">parsing a date and time</span> from it. User agents must not allow the user to set
the <span data-x="concept-fe-value">value</span> to a non-empty string that is not a <span>valid
normalized local date and time string</span>. If the user agent provides a user interface for
selecting a <span data-x="concept-datetime-local">local date and time</span>, then the <span
data-x="concept-fe-value">value</span> must be set to a <span>valid normalized local date and time
string</span> representing the user's selection. User agents should allow the user to set the
<span data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid normalized local date and time string</span>, the control is
<span>suffering from bad input</span>.</p>
</div>
<p class="note">See the <a href="#input-author-notes">introduction section</a> for a discussion of
the difference between the input format and submission format for date, time, and number form
controls<span w-nodev>, and the <a href="#input-impl-notes">implementation notes</a>
regarding localization of form controls</span>.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid local date and time string</span>.</p> <!-- ok to set
out-of-range value, we never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is a <span>valid local date and time
string</span>, then set it to a <span>valid normalized local date and time string</span>
representing the same date and time; otherwise, set it to the empty string instead.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid local date and time string</span>. The <code data-x="attr-input-max">max</code>
attribute, if specified, must have a value that is a <span>valid local date and time
string</span>.</p>
<p>The <code data-x="attr-input-step">step</code> attribute is expressed in seconds. <span
w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is 1000 (which
converts the seconds to milliseconds, as used in the other algorithms).</span> The <span
data-x="concept-input-step-default">default step</span> is 60 seconds.</p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest <span
data-x="concept-datetime-local">local date and time</span> for which the element would not <span
data-x="suffering from a step mismatch">suffer from a step mismatch</span>.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If <span
data-x="parse a local date and time string">parsing a date and time</span> from <var>input</var> results in an error, then return an error; otherwise, return the number of
milliseconds elapsed from midnight on the morning of 1970-01-01 (the time represented by the value
"<code data-x="">1970-01-01T00:00:00.0</code>") to the parsed <span
data-x="concept-datetime-local">local date and time</span>, ignoring leap seconds.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid normalized local date and time string</span> that represents the date and time that is
<var>input</var> milliseconds after midnight on the morning of 1970-01-01 (the time
represented by the value "<code data-x="">1970-01-01T00:00:00.0</code>").</p>
</div>
<p class="note">See <a href="#only-contemporary-times">the note on historical dates</a> in the
<span data-x="attr-input-type-date">Date</span> state section.</p>
<div class="bookkeeping">
<p>The following common <code>input</code> element content
attributes, IDL attributes, and methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is
in mode <span data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not
apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the
element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-valueAsDate">valueAsDate</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<div class="example">
<p>The following example shows part of a flight booking application. The application uses an
<code>input</code> element with its <code data-x="attr-input-type">type</code> attribute set to
<code data-x="attr-input-type-datetime-local">datetime-local</code>, and it then interprets the
given date and time in the time zone of the selected airport.</p>
<pre><code class="html"><fieldset>
<legend>Destination</legend>
<p><label>Airport: <input type=text name=to list=airports></label></p>
<p><label>Departure time: <input type=datetime-local name=totime step=3600></label></p>
</fieldset>
<datalist id=airports>
<option value=ATL label="Atlanta">
<option value=MEM label="Memphis">
<option value=LHR label="London Heathrow">
<option value=LAX label="Los Angeles">
<option value=FRA label="Frankfurt">
</datalist></code></pre>
</div>
<h6><dfn element-state for="input" id="number-state" data-x="attr-input-type-number">Number</dfn> state (<code data-x="">type=number</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-number">Number</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a number.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the number represented by its <span data-x="concept-fe-value">value</span>, as
obtained from applying the <span>rules for parsing floating-point number values</span> to it. User
agents must not allow the user to set the <span data-x="concept-fe-value">value</span> to a
non-empty string that is not a <span>valid floating-point number</span>. If the user agent
provides a user interface for selecting a number, then the <span
data-x="concept-fe-value">value</span> must be set to the <span data-x="best representation of the
number as a floating-point number">best representation of the number representing the user's
selection as a floating-point number</span>. User agents should allow the user to set the <span
data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid floating-point number</span>, the control is <span>suffering
from bad input</span>.</p>
</div>
<p class="note">This specification does not define what user interface user agents are to use;
user agent vendors are encouraged to consider what would best serve their users' needs. For
example, a user agent in Persian or Arabic markets might support Persian and Arabic numeric input
(converting it to the format required for submission as described above). Similarly, a user agent
designed for Romans might display the value in Roman numerals rather than in decimal; or (more
realistically) a user agent designed for the French market might display the value with
apostrophes between thousands and commas before the decimals, and allow the user to enter a value
in that manner, internally converting it to the submission format described above.</p>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not empty, must
have a value that is a <span>valid floating-point number</span>.</p> <!-- ok to set out-of-range
value, we never know when we might have to represent bogus input -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid floating-point
number</span>, then set it to the empty string instead.</p>
</div>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid floating-point number</span>. The <code data-x="attr-input-max">max</code> attribute,
if specified, must have a value that is a <span>valid floating-point number</span>.</p>
<p><span w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is
1.</span> The <span data-x="concept-input-step-default">default step</span> is 1 (allowing only
integers to be selected by the user, unless the <span data-x="concept-input-min-zero">step
base</span> has a non-integer value).</p>
<div w-nodev>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent may round the
element's <span data-x="concept-fe-value">value</span> to the nearest number for which the element
would not <span data-x="suffering from a step mismatch">suffer from a step mismatch</span>. If
there are two such numbers, user agents are encouraged to pick the one nearest positive
infinity.</p>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If applying the
<span>rules for parsing floating-point number values</span> to <var>input</var> results
in an error, then return an error; otherwise, return the resulting number.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return a
<span>valid floating-point number</span> that represents <var>input</var>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes, IDL attributes, and
methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-valueAsDate">valueAsDate</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<div class="example">
<p>Here is an example of using a numeric input control:</p>
<pre><code class="html"><label>How much do you want to charge? $<input type=number min=0 step=0.01 name=price></label></code></pre>
<p>As described above, a user agent might support numeric input in the user's local format,
converting it to the format required for submission as described above. This might include
handling grouping separators (as in "872,000,000,000") and various decimal separators (such as
"3,99" vs "3.99") or using local digits (such as those in Arabic, Devanagari, Persian, and
Thai).</p>
</div>
<p class="note" id="when-number-is-not-appropriate">The <code data-x="">type=number</code> state
is not appropriate for input that happens to only consist of numbers but isn't strictly speaking a
number. For example, it would be inappropriate for credit card numbers or US postal codes. A
simple way of determining whether to use <code data-x="">type=number</code> is to consider whether
it would make sense for the input control to have a spinbox interface (e.g. with "up" and "down"
arrows). Getting a credit card number wrong by 1 in the last digit isn't a minor mistake, it's as
wrong as getting every digit incorrect. So it would not make sense for the user to select a credit
card number using "up" and "down" buttons. When a spinbox interface is not appropriate, <code
data-x="">type=text</code> is probably the right choice (possibly with an <code
data-x="attr-inputmode">inputmode</code> or <code data-x="attr-input-pattern">pattern</code>
attribute).</p>
<h6><dfn element-state for="input" data-x="attr-input-type-range">Range</dfn> state (<code data-x="">type=range</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-range">Range</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control for setting the element's
<span data-x="concept-fe-value">value</span> to a string representing a number, but with the
caveat that the exact value is not important, letting UAs provide a simpler interface than they
do for the <span data-x="attr-input-type-number">Number</span> state.</p>
<div w-nodev>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the number represented by its <span data-x="concept-fe-value">value</span>, as
obtained from applying the <span>rules for parsing floating-point number values</span> to it.
User agents must not allow the user to set the <span data-x="concept-fe-value">value</span> to a
string that is not a <span>valid floating-point number</span>. If the user agent provides a user
interface for selecting a number, then the <span data-x="concept-fe-value">value</span> must be
set to a <span data-x="best representation of the number as a floating-point number">best
representation of the number representing the user's selection as a floating-point
number</span>. User agents must not allow the user to set the <span
data-x="concept-fe-value">value</span> to the empty string.</p>
<p><strong>Constraint validation</strong>: While the user interface describes input that the
user agent cannot convert to a <span>valid floating-point number</span>, the control is
<span>suffering from bad input</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified, must have a value
that is a <span>valid floating-point number</span>.</p> <!-- ok to set out-of-range value, we
never know when we might have to represent bogus input; not ok to not have a value if the
attribute is present, since you can't not have a value (attribute missing is treated as implying
a default value) -->
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: If the <span
data-x="concept-fe-value">value</span> of the element is not a <span>valid floating-point
number</span>, then set it to the <span data-x="best representation of the number as a
floating-point number">best representation, as a floating-point number</span>, of the <span
data-x="concept-input-value-default-range">default value</span>.</p>
</div>
<p>The <dfn data-x="concept-input-value-default-range">default value</dfn> is the <span
data-x="concept-input-min">minimum</span> plus half the difference between the <span
data-x="concept-input-min">minimum</span> and the <span
data-x="concept-input-max">maximum</span>, unless the <span
data-x="concept-input-max">maximum</span> is less than the <span
data-x="concept-input-min">minimum</span>, in which case the <span
data-x="concept-input-value-default-range">default value</span> is the <span
data-x="concept-input-min">minimum</span>.</p>
<div w-nodev>
<p>When the element is <span>suffering from an underflow</span>, the user agent must set the
element's <span data-x="concept-fe-value">value</span> to the <span data-x="best representation
of the number as a floating-point number">best representation, as a floating-point
number</span>, of the <span data-x="concept-input-min">minimum</span>.</p>
<p>When the element is <span>suffering from an overflow</span>, if the <span
data-x="concept-input-max">maximum</span> is not less than the <span
data-x="concept-input-min">minimum</span>, the user agent must set the element's <span
data-x="concept-fe-value">value</span> to a <span>valid floating-point number</span> that
represents the <span data-x="concept-input-max">maximum</span>.</p>
<p>When the element is <span>suffering from a step mismatch</span>, the user agent must round
the element's <span data-x="concept-fe-value">value</span> to the nearest number for which the
element would not <span data-x="suffering from a step mismatch">suffer from a step
mismatch</span>, and which is greater than or equal to the <span
data-x="concept-input-min">minimum</span>, and, if the <span
data-x="concept-input-max">maximum</span> is not less than the <span
data-x="concept-input-min">minimum</span>, which is less than or equal to the <span
data-x="concept-input-max">maximum</span>, if there is a number that matches these constraints.
If two numbers match these constraints, then user agents must use the one nearest to positive
infinity.</p>
<p class="example">For example, the markup
<code data-x=""><input type="range" min=0 max=100 step=20 value=50></code>
results in a range control whose initial value is 60.</p>
</div>
<div class="example">
<p>Here is an example of a range control using an autocomplete list with the <code
data-x="attr-input-list">list</code> attribute. This could be useful if there are values along
the full range of the control that are especially important, such as preconfigured light levels
or typical speed limits in a range control used as a speed control. The following markup
fragment:</p>
<pre><code class="html"><input type="range" min="-100" max="100" value="0" step="10" name="power" list="powers">
<datalist id="powers">
<option value="0">
<option value="-30">
<option value="30">
<span class="bad"> <option value="++50"></span>
</datalist></code></pre>
<p>...with the following style sheet applied:</p>
<pre><code class="css">input { writing-mode: vertical-lr; height: 75px; width: 49px; background: #D5CCBB; color: black; }</code></pre>
<p>...might render as:</p>
<p><img src="/images/sample-range.png" width="49" height="75" alt="A vertical slider control whose primary color is black and whose background color is beige, with the slider having five tick marks, one long one at each extremity, and three short ones clustered around the midpoint.">
<p>Note how the UA determined the orientation of the control from the ratio of the
style-sheet-specified height and width properties. The colors were similarly derived from the
style sheet. The tick marks, however, were derived from the markup. In particular, the <code
data-x="attr-input-step">step</code> attribute has not affected the placement of tick marks,
the UA deciding to only use the author-specified completion values and then adding longer tick
marks at the extremes.</p>
<p>Note also how the invalid value <code data-x="">++50</code> was ignored.</p>
</div>
<div class="example">
<p>For another example, consider the following markup fragment:</p>
<pre><code class="html"><input name=x type=range min=100 max=700 step=9.09090909 value=509.090909></code></pre>
<p>A user agent could display in a variety of ways, for instance:</p>
<p><img src="/images/sample-range-2a.png" width="231" height="57" alt="As a dial."></p>
<p>Or, alternatively, for instance:</p>
<p><img src="/images/sample-range-2b.png" width="445" height="56" alt="As a long horizontal slider with tick marks."></p>
<p>The user agent could pick which one to display based on the dimensions given in the style
sheet. This would allow it to maintain the same resolution for the tick marks, despite the
differences in width.</p>
</div>
<div class="example">
<p>Finally, here is an example of a range control with two labeled values:</p>
<pre><code class="html"><input type="range" name="a" list="a-values">
<datalist id="a-values">
<option value="10" label="Low">
<option value="90" label="High">
</datalist></code></pre>
<p>With styles that make the control draw vertically, it might look as follows:</p>
<p><img src="/images/sample-range-labels.png" width="103" height="164" alt="A vertical slider control with two tick marks, one near the top labeled 'High', and one near the bottom labeled 'Low'.">
</div>
<p class="note">In this state, the range and step constraints are enforced even during user input,
and there is no way to set the value to the empty string.</p>
<p>The <code data-x="attr-input-min">min</code> attribute, if specified, must have a value that is
a <span>valid floating-point number</span>. The <span data-x="concept-input-min-default">default
minimum</span> is 0. The <code data-x="attr-input-max">max</code> attribute, if specified, must
have a value that is a <span>valid floating-point number</span>. The <span
data-x="concept-input-max-default">default maximum</span> is 100.</p>
<p><span w-nodev>The <span data-x="concept-input-step-scale">step scale factor</span> is
1.</span> The <span data-x="concept-input-step-default">default step</span> is 1 (allowing only
integers, unless the <code data-x="attr-input-min">min</code> attribute has a non-integer
value).</p>
<div w-nodev>
<p><strong>The <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span>, given a string <var>input</var>, is as follows</strong>: If applying the
<span>rules for parsing floating-point number values</span> to <var>input</var> results
in an error, then return an error; otherwise, return the resulting number.</p>
<p><strong>The <span data-x="concept-input-value-number-string">algorithm to convert a number to a
string</span>, given a number <var>input</var>, is as follows</strong>: Return the <span
data-x="best representation of the number as a floating-point number">best representation, as a
floating-point number</span>, of <var>input</var>.</p>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes, IDL attributes, and
methods <span data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-min">min</code>, and
<code data-x="attr-input-step">step</code> content attributes;
<code data-x="dom-input-list">list</code>,
<code data-x="dom-input-value">value</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-input-stepDown">stepDown()</code> and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, and
<code data-x="dom-input-valueAsDate">valueAsDate</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods.</p>
</div>
<h6 id="color-state-(type=color)"><dfn element-state for="input" data-x="attr-input-type-color">Color</dfn> state (<code data-x="">type=color</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-color">Color</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a color well control, for setting the
element's <span data-x="concept-fe-value">value</span> to a string representing the serialization
of a CSS color.</p>
<p class="note">In this state, there is always a CSS color picked, and there is no way for the end
user to set the value to the empty string.</p>
<p>The <dfn element-attr for="input"><code data-x="attr-input-alpha">alpha</code></dfn> attribute
is a <span>boolean attribute</span>. If present, it indicates the CSS color's alpha component can
be manipulated by the end user and does not have to be fully opaque.</p>
<p>The <dfn element-attr for="input"><code data-x="attr-input-colorspace">colorspace</code></dfn>
attribute indicates the color space of the serialized CSS color. It also hints at the desired user
interface for selecting a CSS color. It is an <span>enumerated attribute</span> with the following
keywords and states:</p>
<table>
<thead>
<tr>
<th> Keyword
<th> State
<th> Brief description
<tbody>
<tr>
<td><dfn attr-value for="input/colorspace"><code
data-x="attr-input-colorspace-limited-srgb">limited-srgb</code></dfn>
<td><dfn data-x="attr-input-colorspace-limited-srgb-state">Limited sRGB</dfn>
<td>The CSS color is converted to the <span>'srgb'</span> color space and limited to 8-bits per
component, e.g., "<code data-x="">#123456</code>" or "<code
data-x="">color(srgb 0 1 0 / 0.5)</code>".
<tr>
<td><dfn attr-value for="input/colorspace"><code
data-x="attr-input-colorspace-display-p3">display-p3</code></dfn>
<td><dfn data-x="attr-input-colorspace-display-p3-state">Display P3</dfn>
<td>The CSS color is converted to the <span>'display-p3'</span> color space, e.g., "<code
data-x="">color(display-p3 1.84 -0.19 0.72 / 0.6)</code>".
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-input-colorspace-limited-srgb-state">Limited sRGB</span> state.</p>
<div w-nodev>
<p>Whenever the element's <code data-x="attr-input-alpha">alpha</code> or <code
data-x="attr-input-colorspace">colorspace</code> attributes are changed, the user agent must run
<span>update a color well control color</span> given the element.</p>
<!-- As per the statement earlier in this section this only applies when the type attribute is in
the Color state. -->
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the color represented by its <span data-x="concept-fe-value">value</span>, as
obtained from <span data-x="parse a CSS <color> value">parsing</span> it. User agents must not
allow the user to set the <span data-x="concept-fe-value">value</span> to a string that running
<span>update a color well control color</span> for the element would not set it to. If the user
agent provides a user interface for selecting a CSS color, then the <span
data-x="concept-fe-value">value</span> must be set to the result of <span data-x="serialize a
color well control color">serializing a color well control color</span> given the element and the
end user's selection.</p>
<p>The <span>input activation behavior</span> for such an element <var>element</var> is to
<span>show the picker, if applicable</span>, for <var>element</var>.</p>
<p><strong>Constraint validation</strong>: While the element's <span
data-x="concept-fe-value">value</span> is not the empty string and <span data-x="parse a CSS
<color> value">parsing</span> it returns failure, the control is <span>suffering from bad
input</span>.</p>
</div>
<p>The <code data-x="attr-input-value">value</code> attribute, if specified and not the empty
string, must have a value that is a CSS color.</p>
<div w-nodev>
<p><strong>The <span>value sanitization algorithm</span> is as follows</strong>: Run <span>update
a color well control color</span> for the element.</p>
<p>To <dfn>update a color well control color</dfn>, given an element <var>element</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-color">Color</span> state.</p></li>
<li><p>Let <var>color</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> <var>element</var>'s <span data-x="concept-fe-value">value</span>.</p></li>
<li><p>If <var>color</var> is failure, then set <var>color</var> to <span>opaque
black</span>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-fe-value">value</span> to the result of <span
data-x="serialize a color well control color">serializing a color well control color</span> given
<var>element</var> and <var>color</var>.</p></li>
</ol>
<p>To <dfn>serialize a color well control color</dfn>, given an element <var>element</var> and a
CSS color <var>color</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-color">Color</span> state.</p></li>
<li><p>Let <var>htmlCompatible</var> be false.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-input-alpha">alpha</code> attribute is not
specified, then set <var>color</var>'s alpha component to be fully opaque.</p></li>
<li>
<p>If <var>element</var>'s <code data-x="attr-input-colorspace">colorspace</code> attribute is
in the <span data-x="attr-input-colorspace-limited-srgb-state">Limited sRGB</span> state:</p>
<ol>
<li><p>Set <var>color</var> to <var>color</var> <span data-x="Converting
Colors">converted</span> to the <span>'srgb'</span> color space.</p></li>
<li><p>Round each of <var>color</var>'s components so they are in the range 0 to 255,
inclusive. Components are to be <a
href="https://drafts.csswg.org/css-values-4/#combine-integers">rounded towards +∞</a>.</p></li>
<!-- This matches similar wording in CSS Color. -->
<li>
<p>If <var>element</var>'s <code data-x="attr-input-alpha">alpha</code> attribute is not
specified, then set <var>htmlCompatible</var> to true.</p>
<p class="note">This intentionally uses a different serialization path for compatibility with
an earlier version of the color well control.</p>
</li>
<li><p>Otherwise, set <var>color</var> to <var>color</var> converted to using the
<span>'color()'</span> function.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var>'s <code
data-x="attr-input-colorspace">colorspace</code> attribute is in the <span
data-x="attr-input-colorspace-display-p3-state">Display P3</span> state.</p></li>
<li><p>Set <var>color</var> to <var>color</var> <span data-x="Converting
Colors">converted</span> to the <span>'display-p3'</span> color space.</p></li>
</ol>
</li>
<li><p>Return the result of <span data-x="serialize a CSS <color> value">serializing</span>
<var>color</var>. If <var>htmlCompatible</var> is true, then do so with <span
data-x="HTML-compatible serialization is requested">HTML-compatible serialization
requested</span>.</p></li>
</ol>
</div>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-colorspace">colorspace</code>, and
<code data-x="attr-input-list">list</code> content attributes;
<code data-x="dom-input-list">list</code> and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code> method.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-value">value</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code> and,
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-checkbox">Checkbox</dfn> state (<code data-x="">type=checkbox</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state, the rules in this section
apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a two-state control that represents the
element's <span data-x="concept-fe-checked">checkedness</span> state. If the element's <span
data-x="concept-fe-checked">checkedness</span> state is true, the control represents a positive
selection, and if it is false, a negative selection. If the element's <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute is set to true, then the
control's selection should be obscured as if the control was in a third, indeterminate, state.</p>
<p class="note">The control is never a true tri-state control, even if the element's <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute is set to true. The <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute only gives the appearance of a
third state.</p>
<div w-nodev>
<p>The <span>input activation behavior</span> is to run the following steps:</p>
<ol>
<li><p>If the element is not <span>connected</span>, then return.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-input">input</code> at the element with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-change">change</code> at the element with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
</ol>
<!-- These are not cancelable. Once this fires, the control is checked, end of story. -->
<p><strong>Constraint validation</strong>: If the element is <i
data-x="concept-input-required">required</i> and its <span
data-x="concept-fe-checked">checkedness</span> is false, then the element is <span>suffering from
being missing</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-indeterminate">indeterminate</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>When set, overrides the rendering of <span data-x="attr-input-type-checkbox">checkbox</span>
controls so that the current value is not visible.</p>
</dd>
</dl>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-input-checked">checked</code>, and
<code data-x="attr-input-required">required</code> content attributes;
<code data-x="dom-input-checked">checked</code> and
<code data-x="dom-input-value">value</code> IDL attributes.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-default-on">default/on</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-radio">Radio Button</dfn> state (<code data-x="">type=radio</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state, the rules in this section
apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a control that, when used in conjunction
with other <code>input</code> elements, forms a <i data-x="radio button group">radio button group</i> in which only one
control can have its <span data-x="concept-fe-checked">checkedness</span> state set to true. If
the element's <span data-x="concept-fe-checked">checkedness</span> state is true, the control
represents the selected control in the group, and if it is false, it indicates a control in the
group that is not selected.</p>
<p>The <dfn><i>radio button group</i></dfn> that contains an <code>input</code> element
<var>a</var> also contains all the other <code>input</code> elements <var>b</var> that fulfill all
of the following conditions:</p>
<ul>
<li>The <code>input</code> element <var>b</var>'s <code
data-x="attr-input-type">type</code> attribute is in the <span data-x="attr-input-type-radio">Radio
Button</span> state.</li>
<li>Either <var>a</var> and <var>b</var> have the same <span>form owner</span>,
or they both have no <span>form owner</span>.</li>
<li>Both <var>a</var> and <var>b</var> are in the same <span>tree</span>.</li>
<li>They both have a <code data-x="attr-fe-name">name</code> attribute, their <code
data-x="attr-fe-name">name</code> attributes are not empty, and the value of <var>a</var>'s <code
data-x="attr-fe-name">name</code> attribute equals the value of <var>b</var>'s <code
data-x="attr-fe-name">name</code> attribute.</li>
<!-- Historical details of case-sensitivity: https://github.com/whatwg/html/issues/1666 -->
</ul>
<p>A <span>tree</span> must not contain an <code>input</code> element whose <i data-x="radio
button group">radio button group</i> contains only that element.</p>
<div w-nodev>
<p>When any of the following phenomena occur, if the element's <span
data-x="concept-fe-checked">checkedness</span> state is true after the occurrence, the <span
data-x="concept-fe-checked">checkedness</span> state of all the other elements in the same <i data-x="radio button group">radio
button group</i> must be set to false:</p>
<ul>
<li>The element's <span data-x="concept-fe-checked">checkedness</span> state is set to true (for
whatever reason).</li>
<li>The element's <code data-x="attr-fe-name">name</code> attribute is set, changed, or
removed.</li>
<li>The element's <span>form owner</span> changes.</li>
<li><span data-x="signal a type change">A type change is signalled</span> for the element.</li>
<li>The element <span>becomes connected</span>.</li>
</ul>
<p>The <span>input activation behavior</span> is to run the following steps:</p>
<ol>
<li><p>If the element is not <span>connected</span>, then return.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-input">input</code> at the element with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-change">change</code> at the element with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
</ol>
<!-- These are not cancelable. Once this fires, the control is checked, end of story. -->
<p><strong>Constraint validation</strong>: If an element in the <i data-x="radio button
group">radio button group</i> is <i data-x="concept-input-required">required</i>, and all of the
<code>input</code> elements in the <i data-x="radio button group">radio button group</i> have a
<span data-x="concept-fe-checked">checkedness</span> that is false, then the element is
<span>suffering from being missing</span>.</p>
<div class="example">
<p>The following example, for some reason, has specified that puppers are both <span
data-x="concept-input-required">required</span> and <span
data-x="concept-fe-disabled">disabled</span>:</p>
<pre><code class="html"><form>
<p><label><input type="radio" name="dog-type" value="pupper" required disabled> Pupper</label>
<p><label><input type="radio" name="dog-type" value="doggo"> Doggo</label>
<p><button>Make your choice</button>
</form></code></pre>
<p>If the user tries to submit this form without first selecting "Doggo", then <em>both</em>
<code>input</code> elements will be <span>suffering from being missing</span>, since an element
in the <span>radio button group</span> is <span data-x="concept-input-required">required</span>
(viz. the first element), and both of the elements in the radio button group have a false <span
data-x="concept-fe-checked">checkedness</span>.</p>
<p>On the other hand, if the user selects "Doggo" and then submits the form, then neither
<code>input</code> element will be <span>suffering from being missing</span>, since while one of
them is <span data-x="concept-input-required">required</span>, not all of them have a false <span
data-x="concept-fe-checked">checkedness</span>.</p>
</div>
</div>
<p class="note">If none of the radio buttons in a <span>radio button group</span> are checked,
then they will all be initially unchecked in the interface, until such time as one of them is
checked (either by the user or by script).</p>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-input-checked">checked</code> and
<code data-x="attr-input-required">required</code> content attributes;
<code data-x="dom-input-checked">checked</code> and
<code data-x="dom-input-value">value</code> IDL attributes.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-default-on">default/on</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-file">File Upload</dfn> state (<code data-x="">type=file</code>)</h6>
<!-- v2 ideas:
* maximum height/width or required ratio for image uploads? - Leons Petrazickis
* maximum per-file upload size - Alfonso Martínez de Lizarrondo
-->
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-file">File Upload</span> state, the rules in this section
apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a list of <dfn
data-x="concept-input-type-file-selected">selected files</dfn>, each file consisting of a
filename, a file type, and a file body (the contents of the file).</p>
<div w-nodev>
<p>Filenames must not contain <span data-x="concept-input-file-path">path components</span>, even
in the case that a user has selected an entire directory hierarchy or multiple files with the same
name from different directories. <dfn data-x="concept-input-file-path">Path components</dfn>, for
the purposes of the <span data-x="attr-input-type-file">File Upload</span> state, are those parts
of filenames that are separated by U+005C REVERSE SOLIDUS character (\) characters.</p>
<p>Unless the <code data-x="attr-input-multiple">multiple</code> attribute is set, there must be
no more than one file in the list of <span data-x="concept-input-type-file-selected">selected
files</span>.</p>
<p>The <span>input activation behavior</span> for such an element <var>element</var> is to
<span>show the picker, if applicable</span>, for <var>element</var>.</p>
<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
user to change the files on the list in other ways also, e.g., adding or removing files by
drag-and-drop. When the user does so, the user agent must <span>update the file selection</span>
for the element.</p>
<p>If the element is not <i data-x="concept-fe-mutable">mutable</i>, the user agent must not allow
the user to change the element's selection.</p>
<p>To <dfn>update the file selection</dfn> for an element <var>element</var>:</p>
<ol>
<li>
<p><span>Queue an element task</span> on the <span>user interaction task source</span> given
<var>element</var> and the following steps:</p>
<ol>
<li><p>Update <var>element</var>'s <span data-x="concept-input-type-file-selected">selected
files</span> so that it represents the user's selection.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-input">input</code> at the <code>input</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-change">change</code> at the <code>input</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
</ol>
</li>
</ol>
<p><strong>Constraint validation</strong>: If the element is <i
data-x="concept-input-required">required</i> and the list of <span
data-x="concept-input-type-file-selected">selected files</span> is empty, then the element is
<span>suffering from being missing</span>.</p>
</div>
<hr>
<p>The <dfn element-attr for="input"><code data-x="attr-input-accept">accept</code></dfn>
attribute may be specified to provide user agents with a hint of what file types will be
accepted.</p>
<p>If specified, the attribute must consist of a <span>set of comma-separated tokens</span>, each
of which must be an <span>ASCII case-insensitive</span> match for one of the following:</p>
<dl>
<dt>The string "<code data-x="">audio/*</code>"</dt>
<dd>Indicates that sound files are accepted.</dd>
<dt>The string "<code data-x="">video/*</code>"</dt>
<dd>Indicates that video files are accepted.</dd>
<dt>The string "<code data-x="">image/*</code>"</dt>
<dd>Indicates that image files are accepted.</dd>
<dt>A <span>valid MIME type string with no parameters</span></dt>
<dd>Indicates that files of the specified type are accepted.</dd>
<dt>A string whose first character is a U+002E FULL STOP character (.)</dt>
<dd>Indicates that files with the specified file extension are accepted.</dd>
</dl>
<p>The tokens must not be <span>ASCII case-insensitive</span> matches for any of the other tokens
(i.e. duplicates are not allowed). <span w-nodev>To obtain the list of tokens from the
attribute, the user agent must <span data-x="split a string on commas">split the attribute value on
commas</span>.</span></p>
<p>User agents may use the value of this attribute to display a more appropriate user interface
than a generic file picker. For instance, given the value <code data-x="">image/*</code>, a user
agent could offer the user the option of using a local camera or selecting a photograph from their
photo collection; given the value <code data-x="">audio/*</code>, a user agent could offer the user
the option of recording a clip using a headset microphone.</p>
<div w-nodev>
<p>User agents should prevent the user from selecting files that are not accepted by one (or more)
of these tokens.</p>
</div>
<p class="note">Authors are encouraged to specify both any MIME types and any corresponding
extensions when looking for data in a specific format.</p>
<div class="example">
<p>For example, consider an application that converts Microsoft Word documents to Open Document
Format files. Since Microsoft Word documents are described with a wide variety of MIME types and
extensions, the site can list several, as follows:</p>
<pre><code class="html"><input type="file" accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"></code></pre>
<p>On platforms that only use file extensions to describe file types, the extensions listed here
can be used to filter the allowed documents, while the MIME types can be used with the system's
type registration table (mapping MIME types to extensions used by the system), if any, to
determine any other extensions to allow. Similarly, on a system that does not have filenames or
extensions but labels documents with MIME types internally, the MIME types can be used to pick
the allowed files, while the extensions can be used if the system has an extension registration
table that maps known extensions to MIME types used by the system.</p>
</div>
<p class="warning">Extensions tend to be ambiguous (e.g. there are an untold number of formats
that use the "<code data-x="">.dat</code>" extension, and users can typically quite easily rename
their files to have a "<code data-x="">.doc</code>" extension even if they are not Microsoft Word
documents), and MIME types tend to be unreliable (e.g. many formats have no formally registered
types, and many formats are in practice labeled using a number of different MIME types). Authors
are reminded that, as usual, data received from a client should be treated with caution, as it may
not be in an expected format even if the user is not hostile and the user agent fully obeyed the
<code data-x="attr-input-accept">accept</code> attribute's requirements.</p>
<div class="example" id="fakepath-srsly">
<p>For historical reasons, the <code data-x="dom-input-value">value</code> IDL attribute prefixes
the filename with the string "<code data-x="">C:\fakepath\</code>". Some legacy user agents
actually included the full path (which was a security vulnerability). As a result of this,
obtaining the filename from the <code data-x="dom-input-value">value</code> IDL attribute in a
backwards-compatible way is non-trivial. The following function extracts the filename in a
suitably compatible manner:</p>
<pre><code class="js">function extractFilename(path) {
if (path.substr(0, 12) == "C:\\fakepath\\")
return path.substr(12); // modern browser
var x;
x = path.lastIndexOf('/');
if (x >= 0) // Unix-based path
return path.substr(x+1);
x = path.lastIndexOf('\\');
if (x >= 0) // Windows-based path
return path.substr(x+1);
return path; // just the filename
}</code></pre>
<p>This can be used as follows:</p>
<pre><code class="html"><p><input type=file name=image onchange="updateFilename(this.value)"></p>
<p>The name of the file you picked is: <span id="filename">(none)</span></p>
<script>
function updateFilename(path) {
var name = extractFilename(path);
document.getElementById('filename').textContent = name;
}
</script></code></pre>
<!-- How useful this actually is... is unclear. -->
</div>
<hr>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-multiple">multiple</code>, and
<code data-x="attr-input-required">required</code> content attributes;
<code data-x="dom-input-files">files</code> and
<code data-x="dom-input-value">value</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code> method.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-filename">filename</span>.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span
data-x="concept-input-apply">apply</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The element's <code data-x="attr-input-value">value</code> attribute must be omitted.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-submit">Submit Button</dfn> state (<code data-x="">type=submit</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-submit">Submit Button</span> state, the rules in this section
apply.</p>
</div>
<p>
<!--INSERT TRACKING-->
The <code>input</code> element <span>represents</span> a button that, when activated, submits the
form. <span w-nodev>If the element has a <code data-x="attr-input-value">value</code> attribute,
the button's label must be the value of that attribute; otherwise, it must be an
<span>implementation-defined</span> string that means "Submit" or some such.</span> The element is
a <span data-x="concept-button">button</span>, specifically a <span
data-x="concept-submit-button">submit button</span>.</p>
<p class="note">Since the default label is <span>implementation-defined</span>, and the width of
the button typically depends on the button's label, the button's width can leak a few bits of
fingerprintable information. These bits are likely to be strongly correlated to the identity of
the user agent and the user's locale.</p>
<div w-nodev>
<p>The element's <span>input activation behavior</span> given <var>event</var> is as follows:</p>
<ol>
<li><p>If the element does not have a <span>form owner</span>, then return.</p></li>
<li><p>If the element's <span>node document</span> is not <span>fully active</span>, then
return.</p></li>
<li><p><span data-x="concept-form-submit">Submit</span> the element's <span>form owner</span>
from the element with <i data-x="submit-user-involvement">userInvolvement</i> set to
<var>event</var>'s <span data-x="event-uni">user navigation involvement</span>.</p>
</ol>
</div>
<p>The <code data-x="attr-fs-formaction">formaction</code>, <code
data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code> attributes are <span>attributes for form
submission</span>.</p>
<p class="note">The <code data-x="attr-fs-formnovalidate">formnovalidate</code> attribute can be
used to make submit buttons that do not trigger the constraint validation.</p>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-popovertarget">popovertarget</code>, and
<code data-x="attr-popovertargetaction">popovertargetaction</code> content
attributes; <code data-x="dom-input-value">value</code> IDL attribute.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-default">default</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span>do not apply</span>.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-image">Image Button</dfn> state (<code data-x="">type=image</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-image">Image Button</span> state, the rules in this section
apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> either an image from which a user can
select a coordinate and submit the form, or alternatively a button from which the user can submit
the form. The element is a <span data-x="concept-button">button</span>, specifically a <span
data-x="concept-submit-button">submit button</span>.</p>
<p class="note">The coordinate is sent to the server <span data-x="constructing the entry
list">during form submission</span> by sending two entries for the element, derived from the name
of the control but with "<code data-x="">.x</code>" and "<code data-x="">.y</code>" appended to
the name with the <var>x</var> and <var>y</var> components of the coordinate respectively.</p>
<hr>
<p>The image is given by the <dfn element-attr for="input"><code
data-x="attr-input-src">src</code></dfn> attribute. The <code data-x="attr-input-src">src</code>
attribute must be present, and must contain a <span>valid non-empty URL potentially surrounded by
spaces</span> referencing a non-interactive, optionally animated, image resource that is neither
paged nor scripted.</p>
<div w-nodev>
<p>When any of the these events occur
<ul>
<li>the <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is
first set to the <span data-x="attr-input-type-image">Image Button</span> state (possibly when
the element is first created), and the <code data-x="attr-input-src">src</code> attribute is
present</li>
<li>the <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is
changed back to the <span data-x="attr-input-type-image">Image Button</span> state, and the <code
data-x="attr-input-src">src</code> attribute is present, and its value has changed since the last
time the <code data-x="attr-input-type">type</code> attribute was in the <span
data-x="attr-input-type-image">Image Button</span> state</li>
<li>the <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-image">Image Button</span> state, and the <code
data-x="attr-input-src">src</code> attribute is set or changed</li>
</ul> <!-- Note how this does NOT happen when the base URL changes. -->
<p>then unless the user agent cannot support images, or its support for images has been disabled,
or the user agent only fetches images on demand, or the <code data-x="attr-input-src">src</code>
attribute's value is the empty string, run these steps:
<ol>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given the <code
data-x="attr-input-src">src</code> attribute's value, relative to the element's <span>node
document</span>.</p></li>
<li><p>If <var>url</var> is failure, then return.</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is the element's <span>node document</span>'s
<span>relevant settings object</span>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">image</code>", <span
data-x="concept-request-initiator-type">initiator type</span> is "<code data-x="">input</code>",
<span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", and whose <span>use-URL-credentials flag</span> is set.</p></li>
<li>
<p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var>, with
<i data-x="processResponseEndOfBody">processResponseEndOfBody</i> set to the following steps
given <span data-x="concept-response">response</span> <var>response</var>:</p>
<ol>
<li><p>If the download was successful and the image is <i
data-x="input-img-available">available</i>, <span>queue an element task</span> on the
<span>user interaction task source</span> given the <code>input</code> element to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code>
at the <code>input</code> element.</p></li>
<li><p>Otherwise, if the fetching process fails without a response from the remote server, or
completes but the image is not a valid or supported image, then <span>queue an element
task</span> on the <span>user interaction task source</span> given the <code>input</code>
element to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> on the <code>input</code> element.</p></li>
</ol>
</li>
</ol>
<!-- same text in <img> section and similar text elsewhere -->
<p>Fetching the image must <span>delay the load event</span> of the element's <span>node document</span> until the
<span data-x="concept-task">task</span> that is <span data-x="queue a task">queued</span> by the
<span>networking task source</span> once the resource has been fetched (defined below) has been
run.</p>
<p>If the image was successfully obtained, with no network errors, and the image's type is a
supported image type, and the image is a valid image of that type, then the image is said to be
<dfn data-x="input-img-available"><i>available</i></dfn>. If this is true before the image is
completely downloaded, each <span data-x="concept-task">task</span> that is <span data-x="queue a
task">queued</span> by the <span>networking task source</span> while the image is being fetched
must update the presentation of the image appropriately.</p>
<p>The user agent should apply the <span data-x="Content-Type sniffing: image">image sniffing
rules</span> to determine the type of the image, with the image's <span
data-x="Content-Type">associated Content-Type headers</span> giving the <var>official
type</var>. If these rules are not applied, then the type of the image must be the type given by
the image's <span data-x="Content-Type">associated Content-Type headers</span>.</p>
<p>User agents must not support non-image resources with the <code>input</code> element. User
agents must not run executable code embedded in the image resource. User agents must only display
the first page of a multipage resource. User agents must not allow the resource to act in an
interactive fashion, but should honor any animation in the resource.</p>
<hr>
</div>
<p>The <dfn element-attr for="input"><code data-x="attr-input-alt">alt</code></dfn> attribute
provides the textual label for the button for users and user agents who cannot use the image. The
<code data-x="attr-input-alt">alt</code> attribute must be present, and must contain a non-empty
string giving the label that would be appropriate for an equivalent button if the image was
unavailable.</p>
<p>The <code>input</code> element supports <span>dimension attributes</span>.</p>
<hr>
<p>If the <code data-x="attr-input-src">src</code> attribute is set, and the image is <i
data-x="input-img-available">available</i> and the user agent is configured to display that image,
then the element <span>represents</span> a control for selecting a <span
data-x="concept-input-type-image-coordinate">coordinate</span> from the image specified by the
<code data-x="attr-input-src">src</code> attribute. In that case, if the element is <i
data-x="concept-fe-mutable">mutable</i>, the user agent should allow the user to select this <span
data-x="concept-input-type-image-coordinate">coordinate</span>.</p>
<p>Otherwise, the element <span>represents</span> a submit button whose label is given by the
value of the <code data-x="attr-input-alt">alt</code> attribute.</p>
<div w-nodev>
<p>The element's <span>input activation behavior</span> given <var>event</var> is as follows:</p>
<ol>
<li><p>If the element does not have a <span>form owner</span>, then return.</p></li>
<li><p>If the element's <span>node document</span> is not <span>fully active</span>, then
return.</p></li>
<li>
<p>If the user activated the control while explicitly selecting a coordinate, then set the
element's <span data-x="concept-input-type-image-coordinate">selected coordinate</span> to that
coordinate.</p>
<p class="note">This is only possible under the conditions outlined above, when the element
<span>represents</span> a control for selecting such a coordinate. Even then, the user
might activate the control without explicitly selecting a coordinate.</p>
</li>
<li><p><span data-x="concept-form-submit">Submit</span> the element's <span>form owner</span>
from the element with <i data-x="submit-user-involvement">userInvolvement</i> set to
<var>event</var>'s <span data-x="event-uni">user navigation involvement</span>.</p></li>
</ol>
<p>The element's <dfn data-x="concept-input-type-image-coordinate">selected coordinate</dfn>
consists of an <var>x</var>-component and a <var>y</var>-component. It is initially (0, 0). The
coordinates represent the position relative to the edge of the element's image, with the
coordinate space having the positive <var>x</var> direction to the right, and the positive
<var>y</var> direction downwards.</p>
<p>The <var>x</var>-component must be a <span>valid integer</span> representing a number
<var>x</var> in the range <span data-x="">−(<var>border<sub>left</sub></var>+<var>padding<sub>left</sub></var>) ≤ <var>x</var> ≤ <var>width</var>+<var>border<sub>right</sub></var>+<var>padding<sub>right</sub></var></span>, where <var>width</var> is the rendered width of the image, <var>border<sub>left</sub></var> is the width of the border on the left of the image, <var>padding<sub>left</sub></var> is the width of the padding on the left of the
image, <var>border<sub>right</sub></var> is the width of the border on the right
of the image, and <var>padding<sub>right</sub></var> is the width of the padding
on the right of the image, with all dimensions given in <span data-x="'px'">CSS pixels</span>.</p>
<p>The <var>y</var>-component must be a <span>valid integer</span> representing a number
<var>y</var> in the range <span data-x="">−(<var>border<sub>top</sub></var>+<var>padding<sub>top</sub></var>) ≤ <var>y</var> ≤ <var>height</var>+<var>border<sub>bottom</sub></var>+<var>padding<sub>bottom</sub></var></span>, where
<var>height</var> is the rendered height of the image, <var>border<sub>top</sub></var> is the width of the border above the image, <var>padding<sub>top</sub></var> is the width of the padding above the image, <var>border<sub>bottom</sub></var> is the width of the border below the image, and <var>padding<sub>bottom</sub></var> is the width of the padding below the image, with
all dimensions given in <span data-x="'px'">CSS pixels</span>.</p>
<p>Where a border or padding is missing, its width is zero <span data-x="'px'">CSS
pixels</span>.</p>
<hr>
</div>
<p>The <code data-x="attr-fs-formaction">formaction</code>, <code
data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code> attributes are <span>attributes for form
submission</span>.</p>
<dl class="domintro">
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-input-width">width</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>image</var>.<span subdfn data-x="dom-input-height">height</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>These attributes return the actual rendered dimensions of the image, or 0 if the dimensions
are not known.</p>
<p>They can be set, to change the corresponding content attributes.</p>
</dd>
</dl>
<div class="bookkeeping">
<p>The following common <code>input</code> element content attributes and IDL attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-popovertarget">popovertarget</code>,
<code data-x="attr-popovertargetaction">popovertargetaction</code>,
<code data-x="attr-input-src">src</code>, and
<code data-x="attr-dim-width">width</code> content attributes;
<code data-x="dom-input-value">value</code> IDL attribute.</p>
<p>The <code data-x="dom-input-value">value</code> IDL attribute is in mode <span
data-x="dom-input-value-default">default</span>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>, and
<code data-x="attr-input-step">step</code>.</p>
<p>The element's <code data-x="attr-input-value">value</code> attribute must be omitted.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span>do not apply</span>.</p>
</div>
<p class="note">Many aspects of this state's behavior are similar to the behavior of the
<code>img</code> element. Readers are encouraged to read that section, where many of the same
requirements are described in more detail.</p>
<div class="example">
<p>Take the following form:</p>
<pre><code class="html"><form action="process.cgi">
<input type=image src=map.png name=where alt="Show location list">
</form></code></pre>
<p>If the user clicked on the image at coordinate (127,40) then the URL used to submit the form
would be "<code data-x="">process.cgi?where.x=127&where.y=40</code>".</p>
<p>(In this example, it's assumed that for users who don't see the map, and who instead just see
a button labeled "Show location list", clicking the button will cause the server to show a list
of locations to pick from instead of the map.)</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-reset">Reset Button</dfn> state (<code data-x="">type=reset</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-reset">Reset Button</span> state, the rules in this section
apply.</p>
</div>
<p>
<!--INSERT TRACKING-->
The <code>input</code> element <span>represents</span> a button that, when activated, resets the
form. <span w-nodev>If the element has a <code data-x="attr-input-value">value</code> attribute,
the button's label must be the value of that attribute; otherwise, it must be an
<span>implementation-defined</span> string that means "Reset" or some such.</span> The element is
a <span data-x="concept-button">button</span>.</p>
<p class="note">Since the default label is <span>implementation-defined</span>, and the width of
the button typically depends on the button's label, the button's width can leak a few bits of
fingerprintable information. These bits are likely to be strongly correlated to the identity of
the user agent and the user's locale.</p>
<div w-nodev>
<p>The element's <span>input activation behavior</span> is as follows:</p>
<ol>
<li><p>If the element does not have a <span>form owner</span>, then return.</p></li>
<li><p>If the element's <span>node document</span> is not <span>fully active</span>, then
return.</p></li>
<li><p><span data-x="concept-form-reset">Reset</span> the <span>form owner</span> from the
element.</p>
</ol>
<p><strong>Constraint validation</strong>: The element is <span>barred from constraint
validation</span>.</p>
</div>
<div class="bookkeeping">
<p>The <code data-x="dom-input-value">value</code> IDL attribute <span
data-x="concept-input-apply">applies</span> to this element and is in mode <span
data-x="dom-input-value-default">default</span>.</p>
<p>The following common <code>input</code> element content attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-popovertarget">popovertarget</code> and
<code data-x="attr-popovertargetaction">popovertargetaction</code>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span>do not apply</span>.</p>
</div>
<h6><dfn element-state for="input" data-x="attr-input-type-button">Button</dfn> state (<code data-x="">type=button</code>)</h6>
<div w-nodev>
<p>When an <code>input</code> element's <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-button">Button</span> state, the rules in this section apply.</p>
</div>
<p>The <code>input</code> element <span>represents</span> a button with no default behavior. A
label for the button must be provided in the <code data-x="attr-input-value">value</code>
attribute, though it may be the empty string. <span w-nodev>If the element has a <code
data-x="attr-input-value">value</code> attribute, the button's label must be the value of that
attribute; otherwise, it must be the empty string.</span> The element is a <span
data-x="concept-button">button</span>.</p>
<div w-nodev>
<p>The element has no <span>input activation behavior</span>.</p>
<p><strong>Constraint validation</strong>: The element is <span>barred from constraint
validation</span>.</p>
</div>
<div class="bookkeeping">
<p>The <code data-x="dom-input-value">value</code> IDL attribute <span
data-x="concept-input-apply">applies</span> to this element and is in mode <span
data-x="dom-input-value-default">default</span>.</p>
<p>The following common <code>input</code> element content attributes <span
data-x="concept-input-apply">apply</span> to the element:
<code data-x="attr-popovertarget">popovertarget</code> and
<code data-x="attr-popovertargetaction">popovertargetaction</code>.</p>
<p>The following content attributes must not be specified and <span>do not apply</span> to the
element:
<code data-x="attr-input-accept">accept</code>,
<code data-x="attr-input-alpha">alpha</code>,
<code data-x="attr-input-alt">alt</code>,
<code data-x="attr-fe-autocomplete">autocomplete</code>,
<code data-x="attr-input-checked">checked</code>,
<code data-x="attr-input-colorspace">colorspace</code>,
<code data-x="attr-fe-dirname">dirname</code>,
<code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>,
<code data-x="attr-fs-formmethod">formmethod</code>,
<code data-x="attr-fs-formnovalidate">formnovalidate</code>,
<code data-x="attr-fs-formtarget">formtarget</code>,
<code data-x="attr-dim-height">height</code>,
<code data-x="attr-input-list">list</code>,
<code data-x="attr-input-max">max</code>,
<code data-x="attr-input-maxlength">maxlength</code>,
<code data-x="attr-input-min">min</code>,
<code data-x="attr-input-minlength">minlength</code>,
<code data-x="attr-input-multiple">multiple</code>,
<code data-x="attr-input-pattern">pattern</code>,
<code data-x="attr-input-placeholder">placeholder</code>,
<code data-x="attr-input-readonly">readonly</code>,
<code data-x="attr-input-required">required</code>,
<code data-x="attr-input-size">size</code>,
<code data-x="attr-input-src">src</code>,
<code data-x="attr-input-step">step</code>, and
<code data-x="attr-dim-width">width</code>.</p>
<p>The following IDL attributes and methods <span>do not apply</span> to the element:
<code data-x="dom-input-checked">checked</code>,
<code data-x="dom-input-files">files</code>,
<code data-x="dom-input-list">list</code>,
<code data-x="dom-textarea/input-selectionStart">selectionStart</code>,
<code data-x="dom-textarea/input-selectionEnd">selectionEnd</code>,
<code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>,
<code data-x="dom-input-valueAsDate">valueAsDate</code>, and
<code data-x="dom-input-valueAsNumber">valueAsNumber</code> IDL attributes;
<code data-x="dom-textarea/input-select">select()</code>,
<code data-x="dom-textarea/input-setRangeText">setRangeText()</code>,
<code data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code>,
<code data-x="dom-input-stepDown">stepDown()</code>, and
<code data-x="dom-input-stepUp">stepUp()</code> methods.</p>
<p>The <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span>do not apply</span>.</p>
</div>
<div w-nodev>
<h5 id="input-impl-notes">Implementation notes regarding localization of form controls</h5>
<!-- ID referenced from other parts of the spec -->
<!-- NON-NORMATIVE SECTION -->
<p>The formats shown to the user in date, time, and number controls is independent of the format
used for form submission.</p>
<p>Browsers are encouraged to use user interfaces that present dates, times, and numbers according
to the conventions of either the locale implied by the <code>input</code> element's
<span>language</span> or the user's preferred locale. Using the page's locale will ensure
consistency with page-provided data.
<p class="example">For example, it would be confusing to users if an American English page claimed
that a Cirque De Soleil show was going to be showing on 02/03<!-- Feb 3 (year) -->, but their
browser, configured to use the British English locale, only showed the date 03/02<!-- 3 Feb (year)
--> in the ticket purchase date picker. Using the page's locale would at least ensure that the
date was presented in the same format everywhere. (There's still a risk that the user would end up
arriving a month late, of course, but there's only so much that can be done about such cultural
differences...)</p>
</div>
<h5 id="common-input-element-attributes">Common <code>input</code> element attributes</h5>
<div w-nodev>
<p>These attributes only <span data-x="concept-input-apply">apply</span> to an <code>input</code>
element if its <code data-x="attr-input-type">type</code> attribute is in a state whose definition
declares that the attribute <span data-x="concept-input-apply">applies</span>. When an attribute
<span data-x="do not apply">doesn't apply</span> to an <code>input</code> element, user agents must
<span>ignore</span> the attribute, regardless of the requirements and definitions below.</p>
</div>
<h6>The <code data-x="attr-input-maxlength">maxlength</code> and <code data-x="attr-input-minlength">minlength</code> attributes</h6>
<p>The <dfn element-attr for="input"><code data-x="attr-input-maxlength">maxlength</code></dfn>
attribute<span w-nodev>, when it <span data-x="concept-input-apply">applies</span>,</span> is a
<span data-x="attr-fe-maxlength">form control <code data-x="">maxlength</code>
attribute</span>.</p>
<p>The <dfn element-attr for="input"><code data-x="attr-input-minlength">minlength</code></dfn>
attribute<span w-nodev>, when it <span data-x="concept-input-apply">applies</span>,</span> is a
<span data-x="attr-fe-minlength">form control <code data-x="">minlength</code>
attribute</span>.</p>
<p>If the <code>input</code> element has a <span>maximum allowed value length</span>, then the
<span>length</span> of the value of the element's <code data-x="attr-input-value">value</code>
attribute must be less than or equal to the element's <span>maximum allowed value
length</span>.</p>
<!-- we allow the default to be smaller than the minimum, so that you can have incomplete, but not
empty, input already in the form, like a template that needs to be filled in -->
<div class="example">
<p>The following extract shows how a messaging client's text entry could be arbitrarily
restricted to a fixed number of characters, thus forcing any conversation through this medium to
be terse and discouraging intelligent discourse.</p>
<pre><code class="html"><label>What are you doing? <input name=status maxlength=140></label></code></pre>
</div>
<div class="example">
<p>Here, a password is given a minimum length:</p>
<pre><code class="html"><p><label>Username: <input name=u required></label>
<p><label>Password: <input name=p required minlength=12></label></code></pre>
</div>
<h6>The <code data-x="attr-input-size">size</code> attribute</h6>
<p>The <dfn element-attr for="input"><code data-x="attr-input-size">size</code></dfn> attribute
gives the number of characters that, in a visual rendering, the user agent is to allow the user to
see while editing the element's <span data-x="concept-fe-value">value</span>.</p>
<p>The <code data-x="attr-input-size">size</code> attribute, if specified, must have a value that
is a <span>valid non-negative integer</span> greater than zero.</p>
<div w-nodev>
<p>If the attribute is present, then its value must be parsed using the <span>rules for parsing
non-negative integers</span>, and if the result is a number greater than zero, then the user agent
should ensure that at least that many characters are visible.</p>
<p>The <code data-x="dom-input-size">size</code> IDL attribute is <span>limited to only positive
numbers</span> and has a <span>default value</span> of 20.</p>
</div>
<h6>The <code data-x="attr-input-readonly">readonly</code> attribute</h6>
<p>The <dfn element-attr for="input"><code data-x="attr-input-readonly">readonly</code></dfn>
attribute is a <span>boolean attribute</span> that controls whether or not the user can edit the
form control. <span w-nodev>When specified, the element is not <i
data-x="concept-fe-mutable">mutable</i>.</span></p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If the <code
data-x="attr-input-readonly">readonly</code> attribute is specified on an <code>input</code>
element, the element is <span>barred from constraint validation</span>.</p>
</div>
<div class="note">
<p>The difference between <code data-x="attr-fe-disabled">disabled</code> and <code
data-x="attr-input-readonly">readonly</code> is that read-only controls can still function,
whereas disabled controls generally do not function as controls until they are enabled. This is
spelled out in more detail elsewhere in this specification with normative requirements that refer
to the <span data-x="concept-fe-disabled">disabled</span> concept (for example, the element's
<span>activation behavior</span>, whether or not it is a <span>focusable area</span>, or when
<span>constructing the entry list</span>). Any other behavior related to user interaction with
disabled controls, such as whether text can be selected or copied, is not defined in this
standard.</p>
<p>Only text controls can be made read-only, since for other controls (such as checkboxes and
buttons) there is no useful distinction between being read-only and being disabled, so the
<code data-x="attr-input-readonly">readonly</code> attribute <span data-x="do not apply">does not
apply</span>.</p>
</div>
<div class="example">
<p>In the following example, the existing product identifiers cannot be modified, but they are
still displayed as part of the form, for consistency with the row representing a new product
(where the identifier is not yet filled in).</p>
<pre><code class="html"><form action="products.cgi" method="post" enctype="multipart/form-data">
<table>
<tr> <th> Product ID <th> Product name <th> Price <th> Action
<tr>
<td> <input readonly="readonly" name="1.pid" value="H412">
<td> <input required="required" name="1.pname" value="Floor lamp Ulke">
<td> $<input required="required" type="number" min="0" step="0.01" name="1.pprice" value="49.99">
<td> <button formnovalidate="formnovalidate" name="action" value="delete:1">Delete</button>
<tr>
<td> <input readonly="readonly" name="2.pid" value="FG28">
<td> <input required="required" name="2.pname" value="Table lamp Ulke">
<td> $<input required="required" type="number" min="0" step="0.01" name="2.pprice" value="24.99">
<td> <button formnovalidate="formnovalidate" name="action" value="delete:2">Delete</button>
<tr>
<td> <input required="required" name="3.pid" value="" pattern="[A-Z0-9]+">
<td> <input required="required" name="3.pname" value="">
<td> $<input required="required" type="number" min="0" step="0.01" name="3.pprice" value="">
<td> <button formnovalidate="formnovalidate" name="action" value="delete:3">Delete</button>
</table>
<p> <button formnovalidate="formnovalidate" name="action" value="add">Add</button> </p>
<p> <button name="action" value="update">Save</button> </p>
</form></code></pre>
</div>
<h6>The <code data-x="attr-input-required">required</code> attribute</h6>
<p>The <dfn element-attr for="input"><code data-x="attr-input-required">required</code></dfn>
attribute is a <span>boolean attribute</span>. When specified, the element is <dfn
data-x="concept-input-required"><i>required</i></dfn>.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If the element is <i
data-x="concept-input-required">required</i>, and its <code data-x="dom-input-value">value</code>
IDL attribute <span data-x="concept-input-apply">applies</span> and is in the mode <span
data-x="dom-input-value-value">value</span>, and the element is <i
data-x="concept-fe-mutable">mutable</i>, and the element's <span
data-x="concept-fe-value">value</span> is the empty string, then the element is <span>suffering
from being missing</span>.</p>
</div>
<div class="example">
<p>The following form has two required fields, one for an email address and one for a password.
It also has a third field that is only considered valid if the user types the same password in
the password field and this third field.</p>
<pre><code class="html"><h1>Create new account</h1>
<form action="/newaccount" method=post
oninput="up2.setCustomValidity(up2.value != up.value ? 'Passwords do not match.' : '')">
<p>
<label for="username">Email address:</label>
<input id="username" type=email required name=un>
<p>
<label for="password1">Password:</label>
<input id="password1" type=password required name=up>
<p>
<label for="password2">Confirm password:</label>
<input id="password2" type=password name=up2>
<p>
<input type=submit value="Create account">
</form></code></pre>
</div>
<div class="example">
<p>For radio buttons, the <code data-x="attr-input-required">required</code> attribute is
satisfied if any of the radio buttons in the <span data-x="radio button group">group</span> is
selected. Thus, in the following example, any of the radio buttons can be checked, not just the
one marked as required:</p>
<pre><code class="html"><fieldset>
<legend>Did the movie pass the Bechdel test?</legend>
<p><label><input type="radio" name="bechdel" value="no-characters"> No, there are not even two female characters in the movie. </label>
<p><label><input type="radio" name="bechdel" value="no-names"> No, the female characters never talk to each other. </label>
<p><label><input type="radio" name="bechdel" value="no-topic"> No, when female characters talk to each other it's always about a male character. </label>
<p><label><input type="radio" name="bechdel" value="yes" <strong>required</strong>> Yes. </label>
<p><label><input type="radio" name="bechdel" value="unknown"> I don't know. </label>
</fieldset></code></pre>
<p>To avoid confusion as to whether a <span>radio button group</span> is required or not, authors
are encouraged to specify the attribute on all the radio buttons in a group. Indeed, in general,
authors are encouraged to avoid having radio button groups that do not have any initially checked
controls in the first place, as this is a state that the user cannot return to, and is therefore
generally considered a poor user interface.</p>
</div>
<h6>The <code data-x="attr-input-multiple">multiple</code> attribute</h6>
<p>The <dfn element-attr for="input"><code data-x="attr-input-multiple">multiple</code></dfn>
attribute is a <span>boolean attribute</span> that indicates whether the user is to be allowed to
specify more than one value.</p>
<div class="example">
<p>The following extract shows how an email client's "To" field could accept multiple email
addresses.</p>
<pre><code class="html"><label>To: <input type=email multiple name=to></label></code></pre>
<p>If the user had, amongst many friends in their user contacts database, two friends
"Spider-Man" (with address "spider@parker.example.net") and "Scarlet Witch" (with address
"scarlet@avengers.example.net"), then, after the user has typed "<kbd>s</kbd>", the user agent
might suggest these two email addresses to the user.</p>
<!-- Having alternative text in the following image would be bogus and non-conforming use of
HTML, since the image is redundant with the previous paragraph. In particular, just describing
the image would be especially bad for accessibility as it would be disorienting, there having
been no mention that an image is present. -->
<p><img src="/images/sample-email-1.svg" width="330" height="100" alt="" class="darkmode-aware"></p>
<p>The page could also link in the user's contacts database from the site:</p>
<pre><code class="html"><label>To: <input type=email multiple name=to list=contacts></label>
...
<datalist id="contacts">
<option value="hedral@damowmow.com">
<option value="pillar@example.com">
<option value="astrophy@cute.example">
<option value="astronomy@science.example.org">
</datalist></code></pre>
<p>Suppose the user had entered "<kbd>bob@example.net</kbd>" into this text control, and then
started typing a second email address starting with "<kbd>s</kbd>". The user agent might show
both the two friends mentioned earlier, as well as the "astrophy" and "astronomy" values given in
the <code>datalist</code> element.</p>
<!-- As above, having a non-empty alt="" attribute on the following image would be dumb, which is
why it's left blank. The pertinent parts of the image are already described in the prose, and the
non-pertinent parts aren't relevant to users who can't see the image, obviously. -->
<p><img src="/images/sample-email-2.svg" width="330" height="140" alt="" class="darkmode-aware"></p>
</div>
<div class="example">
<p>The following extract shows how an email client's "Attachments" field could accept multiple
files for upload.</p>
<pre><code class="html"><label>Attachments: <input type=file multiple name=att></label></code></pre>
</div>
<h6>The <code data-x="attr-input-pattern">pattern</code> attribute</h6>
<!-- if more text control types start supporting multiple="", this will need to be refactored -->
<p>The <dfn element-attr for="input"><code data-x="attr-input-pattern">pattern</code></dfn>
attribute specifies a regular expression against which the control's <span
data-x="concept-fe-value">value</span>, or, when the <code
data-x="attr-input-multiple">multiple</code> attribute <span
data-x="concept-input-apply">applies</span> and is set, the control's <span
data-x="concept-fe-values">values</span>, are to be checked.</p>
<p>If specified, the attribute's value must match the JavaScript <i
data-x="js-prod-Pattern">Pattern</i><sub><code data-x="">[+UnicodeSetsMode, +N]</code></sub> production.</p>
<div w-nodev>
<p>The <dfn>compiled pattern regular expression</dfn> of an <code>input</code> element, if it
exists, is a JavaScript <code>RegExp</code> object. It is determined as follows:</p>
<ol>
<li><p>If the element does not have a <code data-x="attr-input-pattern">pattern</code> attribute
specified, then return nothing. The element has no <span>compiled pattern regular
expression</span>.</p></li>
<li><p>Let <var>pattern</var> be the value of the <code
data-x="attr-input-pattern">pattern</code> attribute of the element.</p></li>
<li><p>Let <var>regexpCompletion</var> be <span>RegExpCreate</span>(<var>pattern</var>,
"<code data-x="">v</code>").</p></li>
<li>
<p>If <var>regexpCompletion</var> is an <span data-x="Completion Record">abrupt
completion</span>, then return nothing. The element has no <span>compiled pattern regular
expression</span>.</p>
<p class="note">User agents are encouraged to log this error in a developer console, to aid
debugging.</p>
</li>
<li><p>Let <var>anchoredPattern</var> be the string "<code data-x="">^(?:</code>", followed by
<var>pattern</var>, followed by "<code data-x="">)$</code>".</p></li>
<li><p>Return ! <span>RegExpCreate</span>(<var>anchoredPattern</var>, "<code
data-x="">v</code>").</p></li>
</ol>
<p class="note">The reasoning behind these steps, instead of just using the value of the <code
data-x="attr-input-pattern">pattern</code> attribute directly, is twofold. First, we want to
ensure that when matched against a string, the regular expression's start is anchored to the start
of the string and its end to the end of the string. Second, we want to ensure that the regular
expression is valid in standalone form, instead of only becoming valid after being surrounded by
the "<code data-x="">^(?:</code>" and "<code data-x="">)$</code>" anchors.</p>
<p>A <code>RegExp</code> object <var>regexp</var> <dfn data-x="RegExp match a
string">matches</dfn> a string <var>input</var>, if !
<span>RegExpBuiltinExec</span>(<var>regexp</var>, <var>input</var>) is not null.</p>
<p><strong>Constraint validation</strong>: If the element's <span
data-x="concept-fe-value">value</span> is not the empty string, and either the element's <code
data-x="attr-input-multiple">multiple</code> attribute is not specified or it <span data-x="do not
apply">does not apply</span> to the <code>input</code> element given its <code
data-x="attr-input-type">type</code> attribute's current state, and the element has a
<span>compiled pattern regular expression</span> but that regular expression does not <span
data-x="RegExp match a string">match</span> the element's <span
data-x="concept-fe-value">value</span>, then the element is <span>suffering from a pattern
mismatch</span>.</p>
<p><strong>Constraint validation</strong>: If the element's <span
data-x="concept-fe-value">value</span> is not the empty string, and the element's <code
data-x="attr-input-multiple">multiple</code> attribute is specified and <span
data-x="concept-input-apply">applies</span> to the <code>input</code> element, and the element has
a <span>compiled pattern regular expression</span> but that regular expression does not <span
data-x="RegExp match a string">match</span> each of the element's <span
data-x="concept-fe-values">values</span>, then the element is <span>suffering from a pattern
mismatch</span>.</p>
</div>
<p>When an <code>input</code> element has a <code data-x="attr-input-pattern">pattern</code>
attribute specified, authors should include a <dfn element-attr for="input"><code
data-x="attr-input-title">title</code></dfn> attribute to give a description of the pattern. User
agents may use the contents of this attribute, if it is present, when informing the user that the
pattern is not matched, or at any other suitable time, such as in a tooltip or read out by
assistive technology when the control <span>gains focus</span>.</p>
<div class="example">
<p>For example, the following snippet:</p>
<pre><code class="html"><label> Part number:
<input pattern="[0-9][A-Z]{3}" name="part"
title="A part number is a digit followed by three uppercase letters."/>
</label></code></pre>
<p>...could cause the UA to display an alert such as:</p>
<pre><samp>A part number is a digit followed by three uppercase letters.
You cannot submit this form when the field is incorrect.</samp></pre>
</div>
<p>When a control has a <code data-x="attr-input-pattern">pattern</code> attribute, the <code
data-x="attr-input-title">title</code> attribute, if used, must describe the pattern. Additional
information could also be included, so long as it assists the user in filling in the control.
Otherwise, assistive technology would be impaired.</p>
<p class="example">For instance, if the title attribute contained the caption of the control,
assistive technology could end up saying something like <samp>The text you have entered does not
match the required pattern. Birthday</samp>, which is not useful.</p>
<p>UAs may still show the <code data-x="attr-title">title</code> in non-error situations (for
example, as a tooltip when hovering over the control), so authors should be careful not to word
<code data-x="attr-input-title">title</code>s as if an error has necessarily occurred.</p>
<h6>The <code data-x="attr-input-min">min</code> and <code data-x="attr-input-max">max</code> attributes</h6>
<!-- if more numeric control types start supporting multiple="", this will need to be refactored -->
<p>Some form controls can have explicit constraints applied limiting the allowed range of values
that the user can provide. Normally, such a range would be linear and continuous. A form control
can <dfn data-x="has a periodic domain">have a periodic domain</dfn>, however, in which case the
form control's broadest possible range is finite, and authors can specify explicit ranges within
it that span the boundaries.</p>
<p class="example">Specifically, the broadest range of a <code
data-x="attr-input-type-time">type=time</code> control is midnight to midnight (24 hours), and
authors can set both continuous linear ranges (such as 9pm to 11pm) and discontinuous ranges
spanning midnight (such as 11pm to 1am).</p>
<p>The <dfn element-attr for="input"><code data-x="attr-input-min">min</code></dfn> and <dfn
element-attr for="input"><code data-x="attr-input-max">max</code></dfn> attributes indicate the
allowed range of values for the element.</p>
<div w-nodev>
<p>Their syntax is defined by the section that defines the <code
data-x="attr-input-type">type</code> attribute's current state.</p>
<p>If the element has a <code data-x="attr-input-min">min</code> attribute, and the result of
applying the <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span> to the value of the <code data-x="attr-input-min">min</code> attribute is a number,
then that number is the element's <dfn data-x="concept-input-min">minimum</dfn>; otherwise, if the
<code data-x="attr-input-type">type</code> attribute's current state defines a <dfn
data-x="concept-input-min-default">default minimum</dfn>, then that is the <span
data-x="concept-input-min">minimum</span>; otherwise, the element has no <span
data-x="concept-input-min">minimum</span>.</p>
<p>The <code data-x="attr-input-min">min</code> attribute also defines the <span
data-x="concept-input-min-zero">step base</span>.</p>
<p>If the element has a <code data-x="attr-input-max">max</code> attribute, and the result of
applying the <span data-x="concept-input-value-string-number">algorithm to convert a string to a
number</span> to the value of the <code data-x="attr-input-max">max</code> attribute is a number,
then that number is the element's <dfn data-x="concept-input-max">maximum</dfn>; otherwise, if the
<code data-x="attr-input-type">type</code> attribute's current state defines a <dfn
data-x="concept-input-max-default">default maximum</dfn>, then that is the <span
data-x="concept-input-max">maximum</span>; otherwise, the element has no <span
data-x="concept-input-max">maximum</span>.</p>
</div>
<p>If the element does not <span data-x="has a periodic domain">have a periodic domain</span>, the
<code data-x="attr-input-max">max</code> attribute's value (the <span
data-x="concept-input-max">maximum</span>) must not be less than the <code
data-x="attr-input-min">min</code> attribute's value (its <span
data-x="concept-input-min">minimum</span>).</p>
<div w-nodev>
<p class="note">If an element that does not <span data-x="has a periodic domain">have a periodic
domain</span> has a <span data-x="attr-input-max">maximum</span> that is less than its <span
data-x="attr-input-min">minimum</span>, then so long as the element has a <span
data-x="concept-fe-value">value</span>, it will either be <span>suffering from an underflow</span>
or <span>suffering from an overflow</span>.</p>
<p>An element <dfn>has a reversed range</dfn> if it <span>has a periodic domain</span> and its
<span data-x="concept-input-max">maximum</span> is less than its <span
data-x="concept-input-min">minimum</span>.</p>
</div>
<p>An element <dfn data-x="have range limitations">has range limitations</dfn> if it has a defined
<span data-x="concept-input-min">minimum</span> or a defined <span
data-x="concept-input-max">maximum</span>.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: When the element has a <span
data-x="attr-input-min">minimum</span> and does not <span data-x="has a reversed range">have a
reversed range</span>, and the result of applying the <span
data-x="concept-input-value-string-number">algorithm to convert a string to a number</span> to
the string given by the element's <span data-x="concept-fe-value">value</span> is a number, and
the number obtained from that algorithm is less than the <span
data-x="attr-input-min">minimum</span>, the element is <span>suffering from an
underflow</span>.</p>
<p><strong>Constraint validation</strong>: When the element has a <span
data-x="attr-input-max">maximum</span> and does not <span data-x="has a reversed range">have a
reversed range</span>, and the result of applying the <span
data-x="concept-input-value-string-number">algorithm to convert a string to a number</span> to
the string given by the element's <span data-x="concept-fe-value">value</span> is a number, and
the number obtained from that algorithm is more than the <span
data-x="attr-input-max">maximum</span>, the element is <span>suffering from an
overflow</span>.</p>
<p><strong>Constraint validation</strong>: When an element <span>has a reversed range</span>,
and the result of applying the <span data-x="concept-input-value-string-number">algorithm to
convert a string to a number</span> to the string given by the element's <span
data-x="concept-fe-value">value</span> is a number, and the number obtained from that algorithm
is more than the <span data-x="attr-input-max">maximum</span> <em>and</em> less than the <span
data-x="attr-input-min">minimum</span>, the element is simultaneously <span>suffering from an
underflow</span> and <span>suffering from an overflow</span>.</p>
</div>
<div class="example">
<p>The following date control limits input to dates that are before the 1980s:</p>
<pre><code class="html"><input name=bday type=date max="1979-12-31"></code></pre>
</div>
<div class="example">
<p>The following number control limits input to whole numbers greater than zero:</p>
<pre><code class="html"><input name=quantity required="" type="number" min="1" value="1"></code></pre>
</div>
<div class="example">
<p>The following time control limits input to those minutes that occur between 9pm and 6am,
defaulting to midnight:</p>
<pre><code class="html"><input name="sleepStart" type=time min="21:00" max="06:00" step="60" value="00:00"></code></pre>
</div>
<h6>The <code data-x="attr-input-step">step</code> attribute</h6>
<!-- if more numeric control types start supporting multiple="", this will need to be refactored -->
<p>The <dfn element-attr for="input"><code data-x="attr-input-step">step</code></dfn> attribute
indicates the granularity that is expected (and required) of the <span
data-x="concept-fe-value">value</span> or <span data-x="concept-fe-values">values</span>, by
limiting the allowed values. <span w-nodev>The section that defines the <code
data-x="attr-input-type">type</code> attribute's current state also defines the <dfn
data-x="concept-input-step-default">default step</dfn>, the <dfn
data-x="concept-input-step-scale">step scale factor</dfn>, and in some cases the <dfn
data-x="concept-input-step-default-base">default step base</dfn>, which are used in processing the
attribute as described below.</span></p>
<p>The <code data-x="attr-input-step">step</code> attribute, if specified, must either have a
value that is a <span>valid floating-point number</span> that <span data-x="rules for parsing
floating-point number values">parses</span> to a number that is greater than zero, or must have a
value that is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">any</code>".</p>
<div w-nodev>
<p>The attribute provides the <dfn data-x="concept-input-step">allowed value step</dfn> for the
element, as follows:</p>
<ol>
<li><p>If the attribute does not <span data-x="concept-input-apply">apply</span>, then there is
no <span data-x="concept-input-step">allowed value step</span>.</p></li>
<li><p>Otherwise, if the attribute is absent, then the <span data-x="concept-input-step">allowed
value step</span> is the <span data-x="concept-input-step-default">default step</span> multiplied
by the <span data-x="concept-input-step-scale">step scale factor</span>.</p></li>
<li><p>Otherwise, if the attribute's value is an <span>ASCII case-insensitive</span> match for the
string "<code data-x="">any</code>", then there is no <span data-x="concept-input-step">allowed
value step</span>.</p></li>
<li><p>Otherwise, if the <span>rules for parsing floating-point number values</span>, when they are
applied to the attribute's value, return an error, zero, or a number less than zero, then the
<span data-x="concept-input-step">allowed value step</span> is the <span
data-x="concept-input-step-default">default step</span> multiplied by the <span
data-x="concept-input-step-scale">step scale factor</span>.</p></li>
<li><p>Otherwise, the <span data-x="concept-input-step">allowed value step</span> is the number
returned by the <span>rules for parsing floating-point number values</span> when they are applied
to the attribute's value, multiplied by the <span data-x="concept-input-step-scale">step scale
factor</span>.</p></li>
</ol>
<p>The <dfn data-x="concept-input-min-zero">step base</dfn> is the value returned by the following
algorithm:</p>
<ol>
<li><p>If the element has a <code data-x="attr-input-min">min</code> content attribute, and the
result of applying the <span data-x="concept-input-value-string-number">algorithm to convert a
string to a number</span> to the value of the <code data-x="attr-input-min">min</code> content
attribute is not an error, then return that result.</p></li>
<li><p>If the element has a <code data-x="attr-input-value">value</code> content attribute, and
the result of applying the <span data-x="concept-input-value-string-number">algorithm to convert
a string to a number</span> to the value of the <code data-x="attr-input-value">value</code>
content attribute is not an error, then return that result.</p></li>
<li><p>If a <span data-x="concept-input-step-default-base">default step base</span> is defined for
this element given its <code data-x="attr-input-type">type</code> attribute's state, then return
it.</p>
<li><p>Return zero.</p></li>
</ol>
<p><strong>Constraint validation</strong>: When the element has an <span
data-x="concept-input-step">allowed value step</span>, and the result of applying the <span
data-x="concept-input-value-string-number">algorithm to convert a string to a number</span> to
the string given by the element's <span data-x="concept-fe-value">value</span> is a number, and
that number subtracted from the <span data-x="concept-input-min-zero">step base</span> is not an
integral multiple of the <span data-x="concept-input-step">allowed value step</span>, the
element is <span>suffering from a step mismatch</span>.</p>
</div>
<div class="example">
<p>The following range control only accepts values in the range 0..1, and allows 256 steps in
that range:</p>
<pre><code class="html"><input name=opacity type=range min=0 max=1 step=0.00392156863></code></pre>
</div>
<div class="example">
<p>The following control allows any time in the day to be selected, with any accuracy (e.g.
thousandth-of-a-second accuracy or more):</p>
<pre><code class="html"><input name=favtime type=time step=any></code></pre>
<p>Normally, time controls are limited to an accuracy of one minute.</p>
</div>
<h6>The <code data-x="attr-input-list">list</code> attribute</h6>
<!-- if we add any more types of controls, the handling of multiple="" below needs refactoring -->
<p>The <dfn element-attr for="input"><code data-x="attr-input-list">list</code></dfn> attribute is
used to identify an element that lists predefined options suggested to the user.</p>
<p>If present, its value must be the <span data-x="concept-id">ID</span> of a <code>datalist</code>
element in the same <span>tree</span>.</p>
<div w-nodev>
<p>The <dfn data-x="concept-input-list">suggestions source element</dfn> is the first element in
the <span>tree</span> in <span>tree order</span> to have an <span data-x="concept-id">ID</span>
equal to the value of the <code data-x="attr-input-list">list</code> attribute, if that element
is a <code>datalist</code> element. If there is no <code data-x="attr-input-list">list</code>
attribute, or if there is no element with that <span data-x="concept-id">ID</span>, or if the
first element with that <span data-x="concept-id">ID</span> is not a <code>datalist</code>
element, then there is no <span data-x="concept-input-list">suggestions source
element</span>.</p>
<p>If there is a <span data-x="concept-input-list">suggestions source element</span>, then, when
the user agent is allowing the user to edit the <code>input</code> element's <span
data-x="concept-fe-value">value</span>, the user agent should offer the suggestions represented by
the <span data-x="concept-input-list">suggestions source element</span> to the user in a manner
suitable for the type of control used. If appropriate, the user agent should use the suggestion's
<span data-x="concept-option-label">label</span> and <span
data-x="concept-option-value">value</span> to identify the suggestion to the user.</p>
<p>User agents are encouraged to filter the suggestions represented by the <span
data-x="concept-input-list">suggestions source element</span> when the number of suggestions is
large, including only the most relevant ones (e.g. based on the user's input so far). No precise
threshold is defined, but capping the list at four to seven values is reasonable. If filtering
based on the user's input, user agents should search within both the <span
data-x="concept-option-label">label</span> and <span data-x="concept-option-value">value</span>
of the suggestions for matches. User agents should consider how input variations affect the
matching process. Unicode normalization should be applied so that different underlying Unicode
code point sequences, caused by different keyboard- or input-specific mechanisms, do not
interfere with the matching process. Case variations should be ignored, which may require
language-specific case mapping. For examples of these, see <cite>Character Model for the World
Wide Web: String Matching</cite>. User agents may also provide other matching features: for
illustration, a few examples include matching different forms of kana to each other (or to kanji),
ignoring accents, or applying spelling correction. <ref>CHARMODNORM</ref></p>
<div class="example">
<p>This text field allows you to choose a type of JavaScript function.</p>
<pre><code class="html"><input type="text" list="function-types">
<datalist id="function-types">
<option value="function">function</option>
<option value="async function">async function</option>
<option value="function*">generator function</option>
<option value="=>">arrow function</option>
<option value="async =>">async arrow function</option>
<option value="async function*">async generator function</option>
</datalist></code></pre>
<p>For user agents that follow the above suggestions, both the <span
data-x="concept-option-label">label</span> and <span data-x="concept-option-value">value</span>
would be shown:</p>
<p><img src="/images/sample-datalist.svg" width="280" height="150" alt="A text box with a drop down button on the right hand side; with, below, a drop down box containing a list of the six values the left and the six labels on the right." class="darkmode-aware"></p>
<p>Then, typing "<kbd>arrow</kbd>" or "<kbd>=></kbd>" would filter the list to the entries with
labels "arrow function" and "async arrow function". Typing "<kbd>generator</kbd>" or
"<kbd>*</kbd>" would filter the list to the entries with labels "generator function" and "async
generator function".</p>
</div>
<p class="note">As always, user agents are free to make user interface decisions which are
appropriate for their particular requirements and for the user's particular circumstances. However,
this has historically been an area of confusion for implementers, web developers, and users alike,
so we've given some "should" suggestions above.</p>
<p>How user selections of suggestions are handled depends on whether the element is a control
accepting a single value only, or whether it accepts multiple values:</p>
<dl class="switch">
<dt>If the element does not have a <code data-x="attr-input-multiple">multiple</code> attribute
specified or if the <code data-x="attr-input-multiple">multiple</code> attribute <span data-x="do
not apply">does not apply</span></dt>
<dd>
<p>When the user selects a suggestion, the <code>input</code> element's <span
data-x="concept-fe-value">value</span> must be set to the selected suggestion's <span
data-x="concept-option-value">value</span>, as if the user had written that value themself.</p>
</dd>
<!-- multiple types where there's a potentially growing number of values -->
<dt>If the element's <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-email">Email</span> state and the element has a <code
data-x="attr-input-multiple">multiple</code> attribute specified<!--, and the <code
data-x="attr-input-multiple">multiple</code> attribute does <span
data-x="concept-input-apply">apply</span>--></dt>
<dd>
<p>When the user selects a suggestion, the user agent must either add a new entry to the
<code>input</code> element's <span data-x="concept-fe-values">values</span>, whose value
is the selected suggestion's <span data-x="concept-option-value">value</span>, or change an
existing entry in the <code>input</code> element's <span
data-x="concept-fe-values">values</span> to have the value given by the selected
suggestion's <span data-x="concept-option-value">value</span>, as if the user had themself added
an entry with that value, or edited an existing entry to be that value. Which behavior is to be
applied depends on the user interface in an <span>implementation-defined</span> manner.</p>
</dd>
</dl>
<hr>
<p>If the <code data-x="attr-input-list">list</code> attribute <span data-x="do not apply">does not
apply</span>, there is no <span data-x="concept-input-list">suggestions source element</span>.</p>
</div>
<div class="example">
<p>This URL field offers some suggestions.</p>
<pre><code class="html"><label>Homepage: <input name=hp type=url list=hpurls></label>
<datalist id=hpurls>
<option value="https://www.google.com/" label="Google">
<option value="https://www.reddit.com/" label="Reddit">
</datalist></code></pre>
<p>Other URLs from the user's history might show also; this is up to the user agent.</p>
</div>
<div class="example">
<p>This example demonstrates how to design a form that uses the autocompletion list feature while
still degrading usefully in legacy user agents.</p>
<p>If the autocompletion list is merely an aid, and is not important to the content, then simply
using a <code>datalist</code> element with children <code>option</code> elements is enough. To
prevent the values from being rendered in legacy user agents, they need to be placed inside the
<code data-x="attr-option-value">value</code> attribute instead of inline.</p>
<pre><code class="html"><p>
<label>
Enter a breed:
<input type="text" name="breed" list="breeds">
<datalist id="breeds">
<option value="Abyssinian">
<option value="Alpaca">
<!-- ... -->
</datalist>
</label>
</p></code></pre>
<p>However, if the values need to be shown in legacy UAs, then fallback content can be placed
inside the <code>datalist</code> element, as follows:</p>
<pre><code class="html"><p>
<label>
Enter a breed:
<input type="text" name="breed" list="breeds">
</label>
<datalist id="breeds">
<label>
or select one from the list:
<select name="breed">
<option value=""> (none selected)
<option>Abyssinian
<option>Alpaca
<!-- ... -->
</select>
</label>
</datalist>
</p></code></pre>
<p>The fallback content will only be shown in UAs that don't support <code>datalist</code>. The
options, on the other hand, will be detected by all UAs, even though they are not children of the
<code>datalist</code> element.</p>
<p>Note that if an <code>option</code> element used in a <code>datalist</code> is <code
data-x="attr-option-selected">selected</code>, it will be selected by default by legacy UAs
(because it affects the <code>select</code> element), but it will not have any effect on the
<code>input</code> element in UAs that support <code>datalist</code>.</p>
</div>
<h6>The <code data-x="attr-input-placeholder">placeholder</code> attribute</h6>
<!-- substantially similar text in the <textarea> section -->
<p>The <dfn element-attr for="input"><code
data-x="attr-input-placeholder">placeholder</code></dfn> attribute represents a <em>short</em>
hint (a word or short phrase) intended to aid the user with data entry when the control has no
value. A hint could be a sample value or a brief description of the expected format. The
attribute, if specified, must have a value that contains no U+000A LINE FEED (LF) or U+000D
CARRIAGE RETURN (CR) characters.</p>
<p>The <code data-x="attr-input-placeholder">placeholder</code> attribute should not be used as an
alternative to a <code>label</code>. For a longer hint or other advisory text, the <code
data-x="attr-title">title</code> attribute is more appropriate.</p>
<p class="note">These mechanisms are very similar but subtly different: the hint given by the
control's <code>label</code> is shown at all times; the short hint given in the <code
data-x="attr-input-placeholder">placeholder</code> attribute is shown before the user enters a
value; and the hint in the <code data-x="attr-title">title</code> attribute is shown when the user
requests further help.</p>
<div w-nodev>
<p>User agents should present this hint to the user, after having <span data-x="strip
newlines">stripped newlines</span> from it, when the element's <span
data-x="concept-fe-value">value</span> is the empty string, especially if the control is not
<span>focused</span>.</p>
<p>If a user agent normally doesn't show this hint to the user when the control is
<span>focused</span>, then the user agent should nonetheless show the hint for the control if it
was focused as a result of the <code data-x="attr-fe-autofocus">autofocus</code> attribute, since
in that case the user will not have had an opportunity to examine the control before focusing
it.</p>
</div>
<div class="example">
<p>Here is an example of a mail configuration user interface that uses the <code
data-x="attr-input-placeholder">placeholder</code> attribute:</p>
<pre><code class="html"><fieldset>
<legend>Mail Account</legend>
<p><label>Name: <input type="text" name="fullname" placeholder="John Ratzenberger"></label></p>
<p><label>Address: <input type="email" name="address" placeholder="john@example.net"></label></p>
<p><label>Password: <input type="password" name="password"></label></p>
<p><label>Description: <input type="text" name="desc" placeholder="My Email Account"></label></p>
</fieldset></code></pre>
</div>
<div class="example">
<p>In situations where the control's content has one directionality but the placeholder needs to
have a different directionality, Unicode's bidirectional-algorithm formatting characters can be
used in the attribute value:</p>
<pre><code class="html"><input name=t1 type=tel placeholder="<strong>&#x202B;</strong> <bdo dir=rtl>رقم الهاتف 1</bdo> <strong>&#x202E;</strong>">
<input name=t2 type=tel placeholder="<strong>&#x202B;</strong> <bdo dir=rtl>رقم الهاتف 2</bdo> <strong>&#x202E;</strong>"></code></pre>
<p>For slightly more clarity, here's the same example using numeric character references instead of inline Arabic:</p>
<pre><code class="html"><input name=t1 type=tel placeholder="<strong>&#x202B;</strong>&#1585;&#1602;&#1605; &#1575;&#1604;&#1607;&#1575;&#1578;&#1601; 1<strong>&#x202E;</strong>">
<input name=t2 type=tel placeholder="<strong>&#x202B;</strong>&#1585;&#1602;&#1605; &#1575;&#1604;&#1607;&#1575;&#1578;&#1601; 2<strong>&#x202E;</strong>"></code></pre>
</div>
<h5 id="common-input-element-apis">Common <code>input</code> element APIs</h5>
<dl class="domintro">
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-value">value</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current <span data-x="concept-fe-value">value</span> of the form control.</p>
<p>Can be set, to change the value.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if it is
set to any value other than the empty string when the control is a file upload control.</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-checked">checked</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current <span data-x="concept-fe-checked">checkedness</span> of the form
control.</p>
<p>Can be set, to change the <span data-x="concept-fe-checked">checkedness</span>.</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-files">files</span> [ = <var>files</var> ]</code></dt>
<dd>
<p>Returns a <code>FileList</code> object listing the <span
data-x="concept-input-type-file-selected">selected files</span> of the form control.</p>
<p>Returns null if the control isn't a file control.</p>
<p>Can be set to a <code>FileList</code> object to change the <span
data-x="concept-input-type-file-selected">selected files</span> of the form control. For
instance, as the result of a drag-and-drop operation.</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-valueAsDate">valueAsDate</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns a <code>Date</code> object representing the form control's <span
data-x="concept-fe-value">value</span>, if applicable; otherwise, returns null.</p>
<p>Can be set, to change the value.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
control isn't date- or time-based.</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-valueAsNumber">valueAsNumber</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns a number representing the form control's <span
data-x="concept-fe-value">value</span>, if applicable; otherwise, returns NaN.</p>
<p>Can be set, to change the value. Setting this to NaN will set the underlying value to the
empty string.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
control is neither date- or time-based nor numeric.</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-stepUp">stepUp</span>([ <var>n</var> ])</code></dt>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-stepDown">stepDown</span>([ <var>n</var> ])</code></dt>
<dd>
<p>Changes the form control's <span data-x="concept-fe-value">value</span> by the value given in
the <code data-x="attr-input-step">step</code> attribute, multiplied by <var>n</var>. The
default value for <var>n</var> is 1.</p>
<p>Throws <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the control
is neither date- or time-based nor numeric, or if the <code data-x="attr-input-step">step</code>
attribute's value is "<code data-x="">any</code>".</p>
</dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-list">list</span></code></dt>
<dd><p>Returns the <code>datalist</code> element indicated by the <code
data-x="attr-input-list">list</code> attribute.</p></dd>
<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-showPicker">showPicker</span>()</code></dt>
<dd>
<p>Shows any applicable picker UI for <var>input</var>, so that the user can select a value.</p>
<p>If <var>input</var> does not <span data-x="input-support-picker">support a picker</span>,
this method does nothing.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if
<var>input</var> is not <span data-x="concept-fe-mutable">mutable</span>.</p>
<p>Throws a <span>"<code>NotAllowedError</code>"</span> <code>DOMException</code> if called
without <span data-x="transient activation">transient user activation</span>.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if
<var>input</var> is inside a cross-origin <code>iframe</code>, unless <var>input</var> is in the
<span data-x="attr-input-type-file">File Upload</span> or <span
data-x="attr-input-type-color">Color</span> states.</p>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-value">value</code></dfn> IDL
attribute allows scripts to manipulate the <span data-x="concept-fe-value">value</span> of an
<code>input</code> element. The attribute is in one of the following modes, which define its
behavior:</p>
<dl>
<dt><dfn data-x="dom-input-value-value">value</dfn>
<dd>
<p>On getting, return the current <span data-x="concept-fe-value">value</span> of the
element.</p>
<p>On setting:</p>
<ol>
<li><p>Let <var>oldValue</var> be the element's <span
data-x="concept-fe-value">value</span>.</p></li>
<li><p>Set the element's <span data-x="concept-fe-value">value</span> to the new
value.</p></li>
<li><p>Set the element's <span data-x="concept-fe-dirty">dirty value flag</span> to
true.</p></li>
<li><p>Invoke the <span>value sanitization algorithm</span>, if the element's <code
data-x="attr-input-type">type</code> attribute's current state defines one.</p></li>
<li><p>If the element's <span data-x="concept-fe-value">value</span> (after applying the
<span>value sanitization algorithm</span>) is different from <var>oldValue</var>, and the
element has a <span data-x="concept-textarea/input-cursor">text entry cursor position</span>,
move the <span data-x="concept-textarea/input-cursor">text entry cursor position</span> to the
end of the text control, unselecting any selected text and <span data-x="set the selection
direction">resetting the selection direction</span> to "<code data-x="">none</code>".</p></li>
</ol>
</dd>
<dt><dfn data-x="dom-input-value-default">default</dfn>
<dd>
<p>On getting, if the element has a <code data-x="attr-input-value">value</code> content
attribute, return that attribute's value; otherwise, return the empty string.</p>
<p>On setting, set the value of the element's <code data-x="attr-input-value">value</code>
content attribute to the new value.</p>
</dd>
<dt><dfn data-x="dom-input-value-default-on">default/on</dfn>
<dd>
<p>On getting, if the element has a <code data-x="attr-input-value">value</code> content
attribute, return that attribute's value; otherwise, return the string "<code
data-x="">on</code>".</p>
<p>On setting, set the value of the element's <code data-x="attr-input-value">value</code>
content attribute to the new value.</p>
</dd>
<dt><dfn data-x="dom-input-value-filename">filename</dfn>
<dd id="fakepath-orly">
<p>On getting, return the string "<code data-x="">C:\fakepath\</code>" followed by the name of
the first file in the list of <span data-x="concept-input-type-file-selected">selected
files</span>, if any, or the empty string if the list is empty.</p>
<p>On setting, if the new value is the empty string, empty the list of <span
data-x="concept-input-type-file-selected">selected files</span>; otherwise, throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
<p class="note">This "fakepath" requirement is a sad accident of history. See <a
href="#fakepath-srsly">the example in the File Upload state section</a> for more
information.</p>
<p class="note">Since <span data-x="concept-input-file-path">path components</span> are not
permitted in filenames in the list of <span data-x="concept-input-type-file-selected">selected
files</span>, the "\fakepath\" cannot be mistaken for a path component.</p>
</dd>
</dl>
<hr>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-checked">checked</code></dfn>
IDL attribute allows scripts to manipulate the <span
data-x="concept-fe-checked">checkedness</span> of an <code>input</code> element. On getting, it
must return the current <span data-x="concept-fe-checked">checkedness</span> of the element; and
on setting, it must set the element's <span data-x="concept-fe-checked">checkedness</span> to the
new value and set the element's <span data-x="concept-input-checked-dirty-flag">dirty checkedness
flag</span> to true.</p>
<hr>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-files">files</code></dfn> IDL
attribute allows scripts to access the element's <span
data-x="concept-input-type-file-selected">selected files</span>.
<p>On getting, if the IDL attribute <span data-x="concept-input-apply">applies</span>, it must
return a <code>FileList</code> object that represents the current <span
data-x="concept-input-type-file-selected">selected files</span>. The same object must be returned
until the list of <span data-x="concept-input-type-file-selected">selected files</span> changes.
If the IDL attribute <span data-x="do not apply">does not apply</span>, then it must instead
return null. <ref>FILEAPI</ref></p>
<p>On setting, it must run these steps:
<ol>
<li><p>If the IDL attribute <span data-x="do not apply">does not apply</span> or the given value
is null, then return.</p></li>
<!-- This is inconsistent with other attributes, but Chrome and Safari already shipped so doesn't
seem worth the churn. -->
<li><p>Replace the element's <span data-x="concept-input-type-file-selected">selected
files</span> with the given value.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-valueAsDate">valueAsDate</code></dfn> IDL attribute represents the <span
data-x="concept-fe-value">value</span> of the element, interpreted as a date.</p>
<p>On getting, if the <code data-x="dom-input-valueAsDate">valueAsDate</code> attribute <span
data-x="do not apply">does not apply</span>, as defined for the <code>input</code> element's <code
data-x="attr-input-type">type</code> attribute's current state, then return null. Otherwise, run
the <span data-x="concept-input-value-string-date">algorithm to convert a string to a
<code>Date</code> object</span> defined for that state to the element's <span
data-x="concept-fe-value">value</span>; if the algorithm returned a <code>Date</code> object, then
return it, otherwise, return null.</p>
<p>On setting, if the <code data-x="dom-input-valueAsDate">valueAsDate</code> attribute <span
data-x="do not apply">does not apply</span>, as defined for the <code>input</code> element's <code
data-x="attr-input-type">type</code> attribute's current state, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>; otherwise, if the new
value is not null and not a <code >Date</code> object throw a <code>TypeError</code> exception;
otherwise, if the new value is null or a <code>Date</code> object representing the NaN time value,
then set the <span data-x="concept-fe-value">value</span> of the element to the empty string;
otherwise, run the <span data-x="concept-input-value-date-string">algorithm to convert a
<code>Date</code> object to a string</span>, as defined for that state, on the new value, and set
the <span data-x="concept-fe-value">value</span> of the element to the resulting string.</p>
<hr>
<p>The <dfn attribute for="HTMLInputElement"><code
data-x="dom-input-valueAsNumber">valueAsNumber</code></dfn> IDL attribute represents the <span
data-x="concept-fe-value">value</span> of the element, interpreted as a number.</p>
<p>On getting, if the <code data-x="dom-input-valueAsNumber">valueAsNumber</code> attribute <span
data-x="do not apply">does not apply</span>, as defined for the <code>input</code> element's <code
data-x="attr-input-type">type</code> attribute's current state, then return a Not-a-Number (NaN)
value. Otherwise, run the <span data-x="concept-input-value-string-number">algorithm to convert a
string to a number</span> defined for that state to the element's <span
data-x="concept-fe-value">value</span>; if the algorithm returned a number, then return it,
otherwise, return a Not-a-Number (NaN) value.</p>
<p>On setting, if the new value is infinite, then throw a <code>TypeError</code> exception.
Otherwise, if the <code data-x="dom-input-valueAsNumber">valueAsNumber</code> attribute <span
data-x="do not apply">does not apply</span>, as defined for the <code>input</code> element's <code
data-x="attr-input-type">type</code> attribute's current state, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>. Otherwise, if the new
value is a Not-a-Number (NaN) value, then set the <span data-x="concept-fe-value">value</span> of
the element to the empty string. Otherwise, run the <span
data-x="concept-input-value-number-string">algorithm to convert a number to a string</span>, as
defined for that state, on the new value, and set the <span data-x="concept-fe-value">value</span>
of the element to the resulting string.</p>
<hr>
<p>The <dfn method for="HTMLInputElement"><code
data-x="dom-input-stepDown">stepDown(<var>n</var>)</code></dfn> and <dfn method
for="HTMLInputElement"><code data-x="dom-input-stepUp">stepUp(<var>n</var>)</code></dfn> methods,
when invoked, must run the following algorithm:</p>
<ol>
<li><p>If the <code data-x="dom-input-stepDown">stepDown()</code> and <code
data-x="dom-input-stepUp">stepUp()</code> methods <span>do not apply</span>, as defined for the
<code>input</code> element's <code data-x="attr-input-type">type</code> attribute's current state,
then throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the element has no <span data-x="concept-input-step">allowed value step</span>, then
throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the element has a <span data-x="concept-input-min">minimum</span> and a <span
data-x="concept-input-max">maximum</span> and the <span data-x="concept-input-min">minimum</span>
is greater than the <span data-x="concept-input-max">maximum</span>, then return.</p>
<li><p>If the element has a <span data-x="concept-input-min">minimum</span> and a <span
data-x="concept-input-max">maximum</span> and there is no value greater than or equal to the
element's <span data-x="concept-input-min">minimum</span> and less than or equal to the element's
<span data-x="concept-input-max">maximum</span> that, when subtracted from the <span
data-x="concept-input-min-zero">step base</span>, is an integral multiple of the <span
data-x="concept-input-step">allowed value step</span>, then return.</p>
<li><p>If applying the <span data-x="concept-input-value-string-number">algorithm to convert a
string to a number</span> to the string given by the element's <span
data-x="concept-fe-value">value</span> does not result in an error, then let <var>value</var> be the result of that algorithm. Otherwise, let <var>value</var>
be zero.</p></li>
<li><p>Let <var>valueBeforeStepping</var> be <var>value</var>.</p></li>
<li>
<p>If <var>value</var> subtracted from the <span data-x="concept-input-min-zero">step
base</span> is not an integral multiple of the <span data-x="concept-input-step">allowed value
step</span>, then set <var>value</var> to the nearest value that, when subtracted from
the <span data-x="concept-input-min-zero">step base</span>, is an integral multiple of the <span
data-x="concept-input-step">allowed value step</span>, and that is less than <var>value</var> if
the method invoked was the <code data-x="dom-input-stepDown">stepDown()</code> method, and more
than <var>value</var> otherwise.</p>
<p>Otherwise (<var>value</var> subtracted from the <span
data-x="concept-input-min-zero">step base</span> is an integral multiple of the <span
data-x="concept-input-step">allowed value step</span>):</p>
<ol>
<li><p>Let <var>n</var> be the argument.</p></li>
<li><p>Let <var>delta</var> be the <span data-x="concept-input-step">allowed value
step</span> multiplied by <var>n</var>.</p></li>
<li><p>If the method invoked was the <code data-x="dom-input-stepDown">stepDown()</code> method,
negate <var>delta</var>.</p></li>
<li><p>Let <var>value</var> be the result of adding <var>delta</var> to <var>value</var>.</p></li>
</ol>
</li>
<li><p>If the element has a <span data-x="concept-input-min">minimum</span>, and <var>value</var>
is less than that <span data-x="concept-input-min">minimum</span>, then set
<var>value</var> to the smallest value that, when subtracted from the <span
data-x="concept-input-min-zero">step base</span>, is an integral multiple of the <span
data-x="concept-input-step">allowed value step</span>, and that is more than or equal to
that <span data-x="concept-input-min">minimum</span>.</p></li>
<li><p>If the element has a <span data-x="concept-input-max">maximum</span>, and <var>value</var>
is greater than that <span data-x="concept-input-max">maximum</span>, then
set <var>value</var> to the largest value that, when subtracted from the <span
data-x="concept-input-min-zero">step base</span>, is an integral multiple of the <span
data-x="concept-input-step">allowed value step</span>, and that is less than or equal to
that <span data-x="concept-input-max">maximum</span>.</p></li>
<li>
<p>If either the method invoked was the <code data-x="dom-input-stepDown">stepDown()</code>
method and <var>value</var> is greater than <var>valueBeforeStepping</var>, or the method
invoked was the <code data-x="dom-input-stepUp">stepUp()</code> method and <var>value</var> is
less than <var>valueBeforeStepping</var>, then return.</p>
<div class="example">
<p>This ensures that invoking the <code data-x="dom-input-stepUp">stepUp()</code> method on the
<code>input</code> element in the following example does not change the <span
data-x="concept-fe-value">value</span> of that element:</p>
<pre><code class="html"><input type=number value=1 max=0></code></pre>
</div>
</li>
<li><p>Let <var>value as string</var> be the result of running the <span
data-x="concept-input-value-number-string">algorithm to convert a number to a string</span>, as
defined for the <code>input</code> element's <code data-x="attr-input-type">type</code>
attribute's current state, on <var>value</var>.</p></li>
<li><p>Set the <span data-x="concept-fe-value">value</span> of the element to <var>value
as string</var>.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-list">list</code></dfn> IDL
attribute must return the current <span data-x="concept-input-list">suggestions source
element</span>, if any, or null otherwise.</p>
<hr>
<p>The <code>HTMLInputElement</code> <dfn method for="HTMLInputElement"><code
data-x="dom-input-showPicker">showPicker()</code></dfn> and <code>HTMLSelectElement</code> <dfn
method for="HTMLSelectElement"><code data-x="dom-select-showPicker">showPicker()</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span> is not <span data-x="concept-fe-mutable">mutable</span>, then throw
an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>If <span>this</span>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span> is not <span>same origin</span> with
<span>this</span>'s <span>relevant settings object</span>'s <span>top-level origin</span>, and
<span>this</span> is a <code>select</code> element, or
<span>this</span>'s <code data-x="attr-input-type">type</code> attribute is not in the <span
data-x="attr-input-type-file">File Upload</span> state or <span
data-x="attr-input-type-color">Color</span> state, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p>
<p class="note"><span data-x="attr-input-type-file">File</span> and <span
data-x="attr-input-type-color">Color</span> inputs are exempted from this check for historical
reason: their <span>input activation behavior</span> also shows their pickers, and has never
been guarded by an origin check.</p>
</li>
<li><p>If <span>this</span>'s <span>relevant global object</span> does not have <span>transient
activation</span>, then throw a <span>"<code>NotAllowedError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <span>this</span> is a <code>select</code> element, and <span>this</span> is not
<span>being rendered</span>, then throw a <span>"<code>NotSupportedError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span>Show the picker, if applicable</span>, for <span>this</span>.</p></li>
</ol>
<p>To <dfn>show the picker, if applicable</dfn> for an <code>input</code> or <code>select</code>
element <var>element</var>:</p>
<ol>
<li><p>If <var>element</var>'s <span>relevant global object</span> does not have <span>transient
activation</span>, then return.</p></li>
<li><p>If <var>element</var> is not <i data-x="concept-fe-mutable">mutable</i>, then
return.</p></li>
<li><p><span>Consume user activation</span> given <span>element</span>'s <span>relevant global
object</span>.</p></li>
<li><p>If <var>element</var> does not <span data-x="input-support-picker">support a
picker</span>, then return.</p></li>
<li>
<p>If <var>element</var> is an <code>input</code> element and <var>element</var>'s <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-file">File Upload</span> state, then run these steps <span>in
parallel</span>:</p>
<ol>
<li><p>Optionally, wait until any prior execution of this algorithm has terminated.</p></li>
<li><p>Let <var>dismissed</var> be the result of <span>WebDriver BiDi file dialog opened</span>
with <var>element</var>.</p></li>
<li>
<p>If <var>dismissed</var> is false:</p>
<ol>
<li><p>Display a prompt to the user requesting that the user specify some files. If the <code
data-x="attr-input-multiple">multiple</code> attribute is not set on <var>element</var>, there
must be no more than one file selected; otherwise, any number may be selected. Files can be
from the filesystem or created on the fly, e.g., a picture taken from a camera connected to the
user's device.</p></li>
<li><p>Wait for the user to have made their selection.</p></li>
</ol>
</li>
<li><p>If <var>dismissed</var> is true or if the user dismissed the prompt without changing
their selection, then <span>queue an element task</span> on the <span>user interaction task
source</span> given <var>element</var> to <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-cancel">cancel</code> at <var>element</var>, with the
<code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
<li><p>Otherwise, <span>update the file selection</span> for <var>element</var>.</p></li>
</ol>
<p class="note">As with all user interface specifications, user agents have a good deal of
freedom in how they interpret these requirements. The above text implies that a user either
dismisses the prompt or changes their selection; exactly one of these will be true. But the
mapping of these possibilities to specific user interface elements is not mandated by the
standard. For example, a user agent might interpret clicking the "Cancel" button when files were
previously selected as a change of selection to select zero files, thus firing <code
data-x="event-input">input</code> and <code data-x="event-change">change</code>. Or it might
interpret such a click as a dismissal that leaves the selection unchanged, thus firing <code
data-x="event-cancel">cancel</code>. Similarly, it's up to the user agent whether re-selecting
the same files as were previously selected counts as a dismissal, or as a change of
selection.</p>
</li>
<li>
<p>Otherwise, the user agent should show the relevant user interface for selecting a value for
<var>element</var>, in the way it normally would when the user interacts with the control.</p>
<p>When showing such a user interface, it must respect the requirements stated in the relevant
parts of the specification for how <var>element</var> behaves given its <code
data-x="attr-input-type">type</code> attribute state. (For example, various sections describe
restrictions on the resulting <span data-x="concept-fe-value">value</span> string.)</p>
<p>This step can have side effects, such as closing other pickers that were previously shown by
this algorithm. (If this closes a file selection picker, then per the above that will lead to
firing either <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events, or a <code data-x="event-cancel">cancel</code>
event.)</p>
</li>
</ol>
</div>
<div w-nodev>
<h5 id="common-input-element-events">Common event behaviors</h5>
<p>When the <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events <span data-x="concept-input-apply">apply</span>
(which is the case for all <code>input</code> controls other than <span
data-x="concept-button">buttons</span> and those with the <code
data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-hidden">Hidden</span> state), the events are fired to indicate that the
user has interacted with the control. The <code data-x="event-input">input</code> event fires
whenever the user has modified the data of the control. The <code
data-x="event-change">change</code> event fires when the value is committed, if that makes sense
for the control, or else when the control <a href="#unfocus-causes-change-event">loses focus</a>.
In all cases, the <code data-x="event-input">input</code> event comes before the corresponding
<code data-x="event-change">change</code> event (if any).</p>
<p>When an <code>input</code> element has a defined <span>input activation behavior</span>, the
rules for dispatching these events, if they <span data-x="concept-input-apply">apply</span>, are
given in the section above that defines the <code data-x="attr-input-type">type</code> attribute's
state. (This is the case for all <code>input</code> controls with the <code
data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-checkbox">Checkbox</span> state, the <span
data-x="attr-input-type-radio">Radio Button</span> state, or the <span
data-x="attr-input-type-file">File Upload</span> state.)</p>
<p>For <code>input</code> elements without a defined <span>input activation behavior</span>, but
to which these events <span data-x="concept-input-apply">apply</span>, and for which the user
interface involves both interactive manipulation and an explicit commit action, then when the
user changes the element's <span data-x="concept-fe-value">value</span>, the user agent must
<span>queue an element task</span> on the <span>user interaction task source</span> given the
<code>input</code> element to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-input">input</code> at the <code>input</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true, and any time the user commits the change, the user agent must
<span>queue an element task</span> on the <span>user interaction task source</span> given the
<code>input</code> element to set its <span>user validity</span> to true and <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-change">change</code>
at the <code>input</code> element, with the <code data-x="dom-Event-bubbles">bubbles</code>
attribute initialized to true.</p>
<p class="example">An example of a user interface involving both interactive manipulation and a
commit action would be a <span data-x="attr-input-type-range">Range</span> controls that use a
slider, when manipulated using a pointing device. While the user is dragging the control's knob,
<code data-x="event-input">input</code> events would fire whenever the position changed,
whereas the <code data-x="event-change">change</code> event would only fire when the user
let go of the knob, committing to a specific value.</p>
<p>For <code>input</code> elements without a defined <span>input activation behavior</span>, but
to which these events <span data-x="concept-input-apply">apply</span>, and for which the user
interface involves an explicit commit action but no intermediate manipulation, then any time the
user commits a change to the element's <span data-x="concept-fe-value">value</span>, the user
agent must <span>queue an element task</span> on the <span>user interaction task source</span>
given the <code>input</code> element to first <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-input">input</code> at the <code>input</code> element, with
the <code data-x="dom-Event-bubbles">bubbles</code> and <code
data-x="dom-Event-composed">composed</code> attributes initialized to true, and then <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-change">change</code>
at the <code>input</code> element, with the <code data-x="dom-Event-bubbles">bubbles</code>
attribute initialized to true.</p>
<p class="example">An example of a user interface with a commit action would be a <span
data-x="attr-input-type-color">Color</span> control that consists of a single button that brings
up a color wheel: if the <span data-x="concept-fe-value">value</span> only changes when the dialog
is closed, then that would be the explicit commit action. On the other hand, if manipulating the
control changes the color interactively, then there might be no commit action.</p>
<p class="example">Another example of a user interface with a commit action would be a <span
data-x="attr-input-type-date">Date</span> control that allows both text-based user input and user
selection from a drop-down calendar: while text input might not have an explicit commit step,
selecting a date from the drop down calendar and then dismissing the drop down would be a commit
action.</p>
<p>For <code>input</code> elements without a defined <span>input activation behavior</span>, but
to which these events <span data-x="concept-input-apply">apply</span>, any time the user causes
the element's <span data-x="concept-fe-value">value</span> to change without an explicit commit
action, the user agent must <span>queue an element task</span> on the <span>user interaction task
source</span> given the <code>input</code> element to <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-input">input</code> at the <code>input</code> element, with
the <code data-x="dom-Event-bubbles">bubbles</code> and <code
data-x="dom-Event-composed">composed</code> attributes initialized to true. The corresponding
<code data-x="event-change">change</code> event, if any, will be fired when the control <a
href="#unfocus-causes-change-event">loses focus</a>.</p>
<p class="example">Examples of a user changing the element's <span
data-x="concept-fe-value">value</span> would include the user typing into a text control, pasting
a new value into the control, or undoing an edit in that control. Some user interactions do not
cause changes to the value, e.g., hitting the "delete" key in an empty text control, or replacing
some text in the control with text from the clipboard that happens to be exactly the same
text.</p>
<p class="example">A <span data-x="attr-input-type-range">Range</span> control in the form of a
slider that the user has <span>focused</span> and is interacting with using a keyboard would be
another example of the user changing the element's <span data-x="concept-fe-value">value</span>
without a commit step.</p>
<p>In the case of <span data-x="concept-task">tasks</span> that just fire an <code
data-x="event-input">input</code> event, user agents may wait for a suitable break in the user's
interaction before <span data-x="queue an element task">queuing</span> the tasks; for example, a
user agent could wait for the user to have not hit a key for 100ms, so as to only fire the event
when the user pauses, instead of continuously for each keystroke. <!-- similar text is present in
the <textarea> section -->
<p>When the user agent is to change an <code>input</code> element's <span
data-x="concept-fe-value">value</span> on behalf of the user (e.g. as part of a form prefilling
feature), the user agent must <span>queue an element task</span> on the <span>user interaction
task source</span> given the <code>input</code> element to first update the <span
data-x="concept-fe-value">value</span> accordingly, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-input">input</code> at the <code>input</code> element, with
the <code data-x="dom-Event-bubbles">bubbles</code> and <code
data-x="dom-Event-composed">composed</code> attributes initialized to true, then <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-change">change</code>
at the <code>input</code> element, with the <code data-x="dom-Event-bubbles">bubbles</code>
attribute initialized to true.</p>
<p class="note">These events are not fired in response to changes made to the values of form
controls by scripts. (This is to make it easier to update the values of form controls in response
to the user manipulating the controls, without having to then filter out the script's own changes
to avoid an infinite loop.)</p>
<p class="note">These events are also not fired when the browser changes the values of form
controls as part of <span data-x="restore persisted state">state restoration during
navigation</span>.</p>
</div>
<h4 split-filename="form-elements">The <dfn element><code>button</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-submit">submittable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, but there must be no <span>interactive content</span>
descendant and no descendant with the <code data-x="attr-tabindex">tabindex</code> attribute
specified.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-button-command">command</code></dd>
<dd><code data-x="attr-button-commandfor">commandfor</code></dd>
<dd><code data-x="attr-fe-disabled">disabled</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-fs-formaction">formaction</code></dd>
<dd><code data-x="attr-fs-formenctype">formenctype</code></dd>
<dd><code data-x="attr-fs-formmethod">formmethod</code></dd>
<dd><code data-x="attr-fs-formnovalidate">formnovalidate</code></dd>
<dd><code data-x="attr-fs-formtarget">formtarget</code></dd>
<dd><code data-x="attr-fe-name">name</code></dd>
<dd><code data-x="attr-popovertarget">popovertarget</code></dd>
<dd><code data-x="attr-popovertargetaction">popovertargetaction</code></dd>
<dd><code data-x="attr-button-type">type</code></dd>
<dd><code data-x="attr-button-value">value</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-button">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-button">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLButtonElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-button-command">command</span>;
[<span>CEReactions</span>] attribute Element? <span data-x="dom-button-commandForElement">commandForElement</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fe-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-fs-formAction">formAction</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formEnctype">formEnctype</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formMethod">formMethod</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fs-formNoValidate">formNoValidate</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fs-formTarget">formTarget</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-button-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-button-value">value</span>;
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
};
<span>HTMLButtonElement</span> includes <span>PopoverInvokerElement</span>;</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLButtonElement</code>.</dd>
</dl>
<p>The <code>button</code> element <span>represents</span> a button labeled by its contents.</p>
<p>The element is a <span data-x="concept-button">button</span>.</p>
<p>The <dfn element-attr for="button"><code data-x="attr-button-type">type</code></dfn> attribute
controls the behavior of the button when it is activated. It is an <span>enumerated
attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th> Keyword
<th> State
<th> Brief description
<tbody>
<tr>
<td><dfn attr-value for="button/type"><code
data-x="attr-button-type-submit">submit</code></dfn>
<td><dfn data-x="attr-button-type-submit-state">Submit Button</dfn>
<td>Submits the form.
<tr>
<td><dfn attr-value for="button/type"><code data-x="attr-button-type-reset">reset</code></dfn>
<td><dfn data-x="attr-button-type-reset-state">Reset Button</dfn>
<td>Resets the form.
<tr>
<td><dfn attr-value for="button/type"><code
data-x="attr-button-type-button">button</code></dfn>
<td><dfn data-x="attr-button-type-button-state">Button</dfn>
<td>Does nothing.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-button-type-auto-state">Auto</dfn> state.</p>
<p>A <code>button</code> element is said to be a <span
data-x="concept-submit-button">submit button</span> if any of the following are true:</p>
<ul>
<li><p>the <code data-x="attr-button-type">type</code> attribute is in the <span
data-x="attr-button-type-auto-state">Auto</span> state and both the <code
data-x="attr-button-command">command</code> and <code
data-x="attr-button-commandfor">commandfor</code> content attributes are not present;
or</p></li>
<li><p>the <code data-x="attr-button-type">type</code> attribute is in the <span
data-x="attr-button-type-submit-state">Submit Button</span> state.</p></li>
</ul>
<p><strong>Constraint validation</strong>: If the element is not a <span
data-x="concept-submit-button">submit button</span>, the element is <span>barred from constraint
validation</span>.</p>
<p>If specified, the <dfn element-attr for="button"><code
data-x="attr-button-commandfor">commandfor</code></dfn> attribute value must be the <span
data-x="concept-ID">ID</span> of an element in the same <span>tree</span> as the <span
data-x="concept-button">button</span> with the <code
data-x="attr-button-commandfor">commandfor</code> attribute.</p>
<p>The <dfn element-attr for="button"><code data-x="attr-button-command">command</code></dfn>
attribute is an <span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/command"
data-x="attr-button-command-toggle-popover"><code>toggle-popover</code></dfn>
<td><dfn data-x="attr-button-command-toggle-popover-state">Toggle Popover</dfn>
<td>Shows or hides the targeted <code data-x="attr-popover">popover</code> element.
<tr>
<td><dfn attr-value for="html-global/command"
data-x="attr-button-command-show-popover"><code>show-popover</code></dfn>
<td><dfn data-x="attr-button-command-show-popover-state">Show Popover</dfn>
<td>Shows the targeted <code data-x="attr-popover">popover</code> element.
<tr>
<td><dfn attr-value for="html-global/command"
data-x="attr-button-command-hide-popover"><code>hide-popover</code></dfn>
<td><dfn data-x="attr-button-command-hide-popover-state">Hide Popover</dfn>
<td>Hides the targeted <code data-x="attr-popover">popover</code> element.
<tr>
<td><dfn attr-value for="html-global/command"
data-x="attr-button-command-close"><code>close</code></dfn>
<td><dfn data-x="attr-button-command-close-state">Close</dfn>
<td>Closes the targeted <code>dialog</code> element.
<tr>
<td><dfn attr-value for="html-global/command"
data-x="attr-button-command-show-modal"><code>show-modal</code></dfn>
<td><dfn data-x="attr-button-command-show-modal-state">Show Modal</dfn>
<td>Opens the targeted <code>dialog</code> element as modal.
<tr>
<td>A <span data-x="attr-button-command-custom">custom command keyword</span>
<td><dfn data-x="attr-button-command-custom-state">Custom</dfn>
<td>Only dispatches the <code data-x="event-command">command</code> event on the targeted
element.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-button-command-unknown-state">Unknown</dfn> state.</p>
<p>A <dfn data-x="attr-button-command-custom">custom command keyword</dfn> is a string that
<span>starts with</span> "<code data-x="">--</code>".</p>
<div w-nodev>
<p>A <code>button</code> element <var>element</var>'s <span>activation behavior</span> given
<var>event</var> is:</p>
<ol>
<li><p>If <var>element</var> is <span data-x="concept-fe-disabled">disabled</span>, then
return.</p></li>
<li><p>If <var>element</var>'s <span>node document</span> is not <span>fully active</span>, then
return.</p></li>
<li>
<p>If <var>element</var> has a <span>form owner</span>:</p>
<ol>
<li><p>If <var>element</var> is a <span data-x="concept-submit-button">submit button</span>,
then <span data-x="concept-form-submit">submit</span> <var>element</var>'s
<span>form owner</span> from <var>element</var> with <i
data-x="submit-user-involvement">userInvolvement</i> set to <var>event</var>'s <span
data-x="event-uni">user navigation involvement</span>, and return.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-button-type">type</code> attribute is in the
<span data-x="attr-button-type-reset-state">Reset Button</span> state, then <span
data-x="concept-form-reset">reset</span> <var>element</var>'s <span>form owner</span>, and
return.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-button-type">type</code> attribute is in the
<span data-x="attr-button-type-auto-state">Auto</span> state, then return.</p></li>
<!-- We do this for compatability and plan to remove this restriction in future, see
https://github.com/whatwg/html/issues/10832 -->
</ol>
</li>
<li><p>Let <var>target</var> be the result of running <var>element</var>'s <span
data-x="get the attr-associated element">get the <code data-x="">commandfor</code> associated
element</span>.</p></li>
<li>
<p>If <var>target</var> is not null:</p>
<ol>
<li><p>Let <var>command</var> be <var>element</var>'s <code
data-x="attr-button-command">command</code> attribute.</p></li>
<li><p>If <var>command</var> is in the <span
data-x="attr-button-command-unknown-state">Unknown</span> state, then return.</p></li>
<li><p>Let <var>isPopover</var> be true if <var>target</var>'s <code
data-x="attr-popover">popover</code> attribute is not in the <span
data-x="attr-popover-none-state">no popover</span> state; otherwise false.</p></li>
<li>
<p>If <var>isPopover</var> is false and <var>command</var> is not in the <span
data-x="attr-button-command-custom-state">Custom</span> state:</p>
<ol>
<li><p><span>Assert</span>: <var>target</var>'s <span
data-x="concept-element-namespace">namespace</span> is the
<span>HTML namespace</span>.</p></li>
<li><p>If this standard does not define <span>is valid invoker command steps</span> for
<var>target</var>'s <span data-x="concept-element-local-name">local name</span>, then
return.</p></li>
<li><p>Otherwise, if the result of running <var>target</var>'s corresponding <span>is valid
invoker command steps</span> given <var>command</var> is false, then
return.</p></li>
</ol>
</li>
<li>
<p>Let <var>continue</var> be the result of <span data-x="concept-event-fire">firing an
event</span> named <code data-x="event-command">command</code> at <var>target</var>, using
<code>CommandEvent</code>, with its <code data-x="dom-CommandEvent-command">command</code>
attribute initialized to <var>command</var>, its <code
data-x="dom-CommandEvent-source">source</code> attribute initialized to <var>element</var>,
and its <code data-x="dom-Event-cancelable">cancelable</code> and <code
data-x="dom-Event-composed">composed</code> attributes initialized to true.</p>
<p class="XXX"><a href="https://github.com/whatwg/dom/issues/1328">DOM standard issue
#1328</a> tracks how to better standardize associated event data in a way which makes sense on
Events. Currently an event attribute initialized to a value cannot also have a getter, and so
an internal slot (or map of additional fields) is required to properly specify this.</p>
</li>
<li><p>If <var>continue</var> is false, then return.</p></li>
<li><p>If <var>target</var> is not <span>connected</span>, then return.</p></li>
<li><p>If <var>command</var> is in the <span
data-x="attr-button-command-custom-state">Custom</span> state, then return.</p></li>
<li>
<p>If <var>command</var> is in the <span
data-x="attr-button-command-hide-popover-state">Hide Popover</span> state:</p>
<ol>
<li><p>If the result of running <span>check popover validity</span> given
<var>target</var>, true, false, and null is true, then run the
<span>hide popover algorithm</span> given <var>target</var>, true, true, and false.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>command</var> is in the <span
data-x="attr-button-command-toggle-popover-state">Toggle Popover</span> state:</p>
<ol>
<li><p>If the result of running <span>check popover validity</span> given
<var>target</var>, false, false, and null is true, then run the
<span data-x="show popover">show popover algorithm</span> given <var>target</var>, true,
true, and false.</p></li>
<li><p>Otheriwse, if the result of running <span>check popover validity</span> given
<var>target</var>, true, false, and null is true, then run the
<span>hide popover algorithm</span> given <var>target</var>, true,
true, and false.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>command</var> is in the <span
data-x="attr-button-command-show-popover-state">Show Popover</span> state:</p>
<ol>
<li><p>If the result of running <span>check popover validity</span> given <var>target</var>,
false, false, and null is true, then run the <span
data-x="show popover">show popover algorithm</span> given <var>target</var>, true, true,
and false.</p></li>
</ol>
</li>
<li><p>Otherwise, if this standard defines <span>invoker command steps</span> for
<var>target</var>'s <span data-x="concept-element-local-name">local name</span>, then run the
corresponding <span>invoker command steps</span> given <var>target</var>, <var>element</var>
and <var>command</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, run the <span>popover target attribute activation behavior</span> given
<var>element</var> and <var>event</var>'s <span
data-x="concept-event-target">target</span>.</p></li>
</ol>
<p>An <span data-x="HTML Elements">HTML element</span> can have specific
<dfn>is valid invoker command steps</dfn> and <dfn>invoker command steps</dfn> defined for the
element's <span data-x="concept-element-local-name">local name</span>.</p>
</div>
<p>The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<code>button</code> element with its <span>form owner</span>. The <code
data-x="attr-fe-name">name</code> attribute represents the element's name. The <code
data-x="attr-fe-disabled">disabled</code> attribute is used to make the control non-interactive and
to prevent its value from being submitted. The <code data-x="attr-fs-formaction">formaction</code>,
<code data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code> attributes are <span>attributes for form
submission</span>.</p>
<p class="note">The <code data-x="attr-fs-formnovalidate">formnovalidate</code> attribute can be
used to make submit buttons that do not trigger the constraint validation.</p>
<p>The <code data-x="attr-fs-formaction">formaction</code>, <code
data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code> must not be specified if the element is not
a <span data-x="concept-submit-button">submit button</span>.</p>
<p>The <dfn attribute for="HTMLButtonElement"><code
data-x="dom-button-commandForElement">commandForElement</code></dfn> IDL attribute must
<span>reflect</span> the element's <code data-x="attr-button-commandfor">commandfor</code>
content attribute.</p>
<p>The <dfn attribute for="HTMLButtonElement"><code
data-x="dom-button-command">command</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>command</var> be <span>this</span>'s <code
data-x="attr-button-command">command</code> attribute.</p></li>
<li><p>If <var>command</var> is in the <span
data-x="attr-button-command-custom-state">Custom</span> state, then return <var>command</var>'s
value.</p></li>
<li><p>If <var>command</var> is in the <span
data-x="attr-button-command-unknown-state">Unknown</span> state, then return the empty
string.</p></li>
<li><p>Return the keword corresponding to the value of <var>command</var>.</p></li>
</ol>
<p>The <code data-x="dom-button-command">command</code> setter steps are to set the <code
data-x="attr-button-command">command</code> content attribute to the given value.</p>
<p>The <dfn element-attr for="button"><code data-x="attr-button-value">value</code></dfn>
attribute gives the element's value for the purposes of form submission. The element's <span
data-x="concept-fe-value">value</span> is the value of the element's <code
data-x="attr-button-value">value</code> attribute, if there is one, or the empty string
otherwise.</p>
<p class="note">A button (and its value) is only included in the form submission if the button
itself was used to initiate the form submission.</p>
<hr>
<div w-nodev>
<p>The <dfn attribute for="HTMLButtonElement"><code data-x="dom-button-value">value</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name.</p>
<p>The <dfn attribute for="HTMLButtonElement"><code data-x="dom-button-type">type</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <var>this</var> is a <span data-x="concept-submit-button">submit button</span>, then
return "<code data-x="">submit</code>".</p></li>
<li><p>Let <var>state</var> be <span>this</span>'s <code data-x="attr-button-type">type</code>
attribute.</p></li>
<li><p><span>Assert</span>: <var>state</var> is not in the <span
data-x="attr-button-type-submit-state">Submit Button</span> state.</p></li>
<li><p>If <var>state</var> is in the <span data-x="attr-button-type-auto-state">Auto</span>
state, then return "<code data-x="">button</code>".</p></li>
<li><p>Return the keyword value corresponding to <var>state</var>.</p></li>
</ol>
<p>The <code data-x="dom-button-type">type</code> setter steps are to set the <code
data-x="attr-button-type">type</code> content attribute to the given value.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> IDL attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-lfe-labels">labels</code> IDL
attribute provides a list of the element's <code>label</code>s. The <code
data-x="dom-fe-disabled">disabled</code>, <code data-x="dom-fae-form">form</code>, and
<code data-x="dom-fe-name">name</code> IDL attributes are part of the element's forms API.</p>
</div>
<div class="example">
<p>The following button is labeled "Show hint" and pops up a dialog box when activated:</p>
<pre><code class="html"><button type=button
onclick="alert('This 15-20 minute piece was composed by George Gershwin.')">
Show hint
</button></code></pre>
</div>
<div class="example">
<p>The following shows how <span data-x="concept-button">buttons</span> can use <code
data-x="attr-button-commandfor">commandfor</code> to show and hide an element with
the <code data-x="attr-popover">popover</code> attribute when activated:</p>
<pre><code class="html"><button type=button
commandfor="the-popover"
command="show-popover">
Show menu
</button>
<div popover
id="the-popover">
<button commandfor="the-popover"
command="hide-popover">
Hide menu
</button>
</div>
</code></pre>
</div>
<div class="example">
<p>The following shows how buttons can use <code
data-x="attr-button-commandfor">commandfor</code> with a <span
data-x="attr-button-command-custom">custom command keyword</span> on an element, demonstrating
how one could use custom commands for unspecified behavior:</p>
<pre><code class="html"><button type=button
commandfor="the-image"
command="--rotate-landscape">
Rotate Left
</button>
<button type=button
commandfor="the-image"
command="--rotate-portrait">
Rotate Right
</button>
<img id="the-image"
src="photo.jpg">
<script>
const image = document.getElementById("the-image");
image.addEventListener("command", (event) => {
if ( event.command == "--rotate-landscape" ) {
event.target.style.rotate = "-90deg"
} else if ( event.command == "--rotate-portrait" ) {
event.target.style.rotate = "0deg"
}
});
</script>
</code></pre>
</div>
<h4>The <dfn element><code>select</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-submit">submittable</span>, <span data-x="category-reset">resettable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>option</code>, <code>optgroup</code>, <code>hr</code>, and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-fe-autocomplete">autocomplete</code></dd>
<dd><code data-x="attr-fe-disabled">disabled</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-select-multiple">multiple</code></dd>
<dd><code data-x="attr-fe-name">name</code></dd>
<dd><code data-x="attr-select-required">required</code></dd>
<dd><code data-x="attr-select-size">size</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>If the element has a <code data-x="attr-select-multiple">multiple</code> attribute or a <code
data-x="attr-select-size">size</code> attribute with a value > 1: <a
href="https://w3c.github.io/html-aria/#el-select-multiple-or-size-greater-1">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-select-listbox">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-select">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-select-combobox">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLSelectElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-autocomplete">autocomplete</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fe-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-select-multiple">multiple</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-select-required">required</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-select-size">size</span>;
readonly attribute DOMString <span data-x="dom-select-type">type</span>;
[SameObject] readonly attribute <span>HTMLOptionsCollection</span> <span data-x="dom-select-options">options</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-select-length">length</span>;
getter <span>HTMLOptionElement</span>? <span data-x="dom-select-item">item</span>(unsigned long index);
<span>HTMLOptionElement</span>? <span data-x="dom-select-namedItem">namedItem</span>(DOMString name);
[<span>CEReactions</span>] undefined <span data-x="dom-select-add">add</span>((<span>HTMLOptionElement</span> or <span>HTMLOptGroupElement</span>) element, optional (<span>HTMLElement</span> or long)? before = null);
[<span>CEReactions</span>] undefined <span data-x="dom-select-remove">remove</span>(); // ChildNode overload
[<span>CEReactions</span>] undefined <span data-x="dom-select-remove">remove</span>(long index);
[<span>CEReactions</span>] <a href="#dom-select-setter">setter</a> undefined (unsigned long index, <span>HTMLOptionElement</span>? option);
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-select-selectedOptions">selectedOptions</span>;
attribute long <span data-x="dom-select-selectedIndex">selectedIndex</span>;
attribute DOMString <span data-x="dom-select-value">value</span>;
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
undefined <span data-x="dom-select-showPicker">showPicker</span>();
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLSelectElement</code>.</dd>
</dl>
<!-- Proposals for v2:
* <select value=""> as an alternative to <option selected>
http://developers.slashdot.org/comments.pl?sid=426306&cid=22142072
<Philip`> http://www.ipiao.com.cn/ does <select size="1" name="to"><script>City_Default="PEK"</script><SCRIPT language=javascript
src="/js/flightcity.js"></SCRIPT></select> which is the kind of thing that could be much simpler with <select value="PEK">
-->
<p>The <code>select</code> element represents a control for selecting amongst a set of
options.</p>
<p>The <dfn element-attr for="select"><code data-x="attr-select-multiple">multiple</code></dfn>
attribute is a <span>boolean attribute</span>. If the attribute is present, then the
<code>select</code> element <span>represents</span> a control for selecting zero or more options
from the <span data-x="concept-select-option-list">list of options</span>. If the attribute is
absent, then the <code>select</code> element <span>represents</span> a control for selecting a
single option from the <span data-x="concept-select-option-list">list of options</span>.</p>
<p>The <dfn element-attr for="select"><code data-x="attr-select-size">size</code></dfn> attribute
gives the number of options to show to the user. The <code data-x="attr-select-size">size</code>
attribute, if specified, must have a value that is a <span>valid non-negative integer</span>
greater than zero.</p>
<div w-nodev>
<p>The <dfn data-x="concept-select-size">display size</dfn> of a <code>select</code> element is the
result of applying the <span>rules for parsing non-negative integers</span> to the value of
element's <code data-x="attr-select-size">size</code> attribute, if it has one and parsing it is
successful. If applying those rules to the attribute's value is not successful, or if the <code
data-x="attr-select-size">size</code> attribute is absent, then the element's <span
data-x="concept-select-size">display size</span> is 4 if the element's <code
data-x="attr-select-multiple">multiple</code> content attribute is present, and 1 otherwise.</p>
</div>
<p>The <dfn data-x="concept-select-option-list">list of options</dfn> for a <code>select</code>
element consists of all the <code>option</code> element children of the <code>select</code>
element, and all the <code>option</code> element children of all the <code>optgroup</code> element
children of the <code>select</code> element, in <span>tree order</span>.</p>
<p>The <dfn element-attr for="select"><code data-x="attr-select-required">required</code></dfn>
attribute is a <span>boolean attribute</span>. When specified, the user will be required to select
a value before submitting the form.</p>
<p>If a <code>select</code> element has a <code data-x="attr-select-required">required</code>
attribute specified, does not have a <code data-x="attr-select-multiple">multiple</code> attribute
specified, and has a <span data-x="concept-select-size">display size</span> of 1; and if the <span
data-x="concept-option-value">value</span> of the first <code>option</code> element in the
<code>select</code> element's <span data-x="concept-select-option-list">list of options</span> (if
any) is the empty string, and that <code>option</code> element's parent node is the
<code>select</code> element (and not an <code>optgroup</code> element), then that
<code>option</code> is the <code>select</code> element's <dfn>placeholder label option</dfn>.</p>
<p>If a <code>select</code> element has a <code data-x="attr-select-required">required</code>
attribute specified, does not have a <code data-x="attr-select-multiple">multiple</code> attribute
specified, and has a <span data-x="concept-select-size">display size</span> of 1, then the
<code>select</code> element must have a <span>placeholder label option</span>.</p>
<p class="note">In practice, the requirement stated in the paragraph above can only apply when a
<code>select</code> element does not have a <code data-x="attr-select-size">size</code> attribute
with a value greater than 1.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If the element has its <code
data-x="attr-select-required">required</code> attribute specified, and either none of the
<code>option</code> elements in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> have their <span
data-x="concept-option-selectedness">selectedness</span> set to true, or the only
<code>option</code> element in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> with its <span
data-x="concept-option-selectedness">selectedness</span> set to true is the <span>placeholder label
option</span>, then the element is <span>suffering from being missing</span>.</p>
</div>
<div w-nodev>
<p>If the <code data-x="attr-select-multiple">multiple</code> attribute is absent, and the element
is not <span data-x="concept-fe-disabled">disabled</span>, then the user agent should allow the
user to pick an <code>option</code> element in its <span data-x="concept-select-option-list">list
of options</span> that is itself not <span data-x="concept-option-disabled">disabled</span>. Upon
this <code>option</code> element being <dfn data-x="concept-select-pick">picked</dfn> (either
through a click, or through unfocusing the element after changing its value, or through a <span
data-x="option-command">menu command</span>, or through any other mechanism), and before the
relevant user interaction event <!-- interaction event spec point --> is queued (e.g. before the
<code data-x="event-click">click</code> event), the user agent must set the <span
data-x="concept-option-selectedness">selectedness</span> of the picked <code>option</code> element
to true, set its <span data-x="concept-option-dirtiness">dirtiness</span> to true, and then
<span>send <code>select</code> update notifications</span>.</p>
<p>If the <code data-x="attr-select-multiple">multiple</code> attribute is absent, whenever an
<code>option</code> element in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> has its <span
data-x="concept-option-selectedness">selectedness</span> set to true, and whenever an
<code>option</code> element with its <span
data-x="concept-option-selectedness">selectedness</span> set to true is added to the
<code>select</code> element's <span data-x="concept-select-option-list">list of options</span>,
the user agent must set the <span data-x="concept-option-selectedness">selectedness</span> of all
the other <code>option</code> elements in its <span data-x="concept-select-option-list">list of
options</span> to false.</p>
<p>If the <code data-x="attr-select-multiple">multiple</code> attribute is absent and the
element's <span data-x="concept-select-size">display size</span> is greater than 1, then the user
agent should also allow the user to request that the <code>option</code> whose <span
data-x="concept-option-selectedness">selectedness</span> is true, if any, be unselected. Upon this
request being conveyed to the user agent, and before the relevant user interaction event <!--
interaction event spec point --> is queued (e.g. before the <code
data-x="event-click">click</code> event), the user agent must set the <span
data-x="concept-option-selectedness">selectedness</span> of that <code>option</code> element to
false, set its <span data-x="concept-option-dirtiness">dirtiness</span> to true, and then
<span>send <code>select</code> update notifications</span>.</p>
<p>The <dfn>selectedness setting algorithm</dfn>, given a <code>select</code> element
<var>element</var>, is to run the following steps:</p>
<ol>
<li><p>If <var>element</var>'s <code data-x="attr-select-multiple">multiple</code> attribute is
absent, and <var>element</var>'s <span data-x="concept-select-size">display size</span> is 1,
and no <code>option</code> elements in the <var>element</var>'s <span
data-x="concept-select-option-list">list of options</span> have their <span
data-x="concept-option-selectedness">selectedness</span> set to true, then set the <span
data-x="concept-option-selectedness">selectedness</span> of the first <code>option</code>
element in the <span data-x="concept-select-option-list">list of options</span> in
<span>tree order</span> that is not <span data-x="concept-option-disabled">disabled</span>,
if any, to true, and return.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-select-multiple">multiple</code> attribute is
absent, and two or more <code>option</code> elements in <var>element</var>'s <span
data-x="concept-select-option-list">list of options</span> have their <span
data-x="concept-option-selectedness">selectedness</span> set to true, then set the <span
data-x="concept-option-selectedness">selectedness</span> of all but the last <code>option</code>
element with its <span data-x="concept-option-selectedness">selectedness</span> set to true in
the <span data-x="concept-select-option-list">list of options</span> in <span>tree order</span>
to false.</p></li>
</ol>
<p>The <code>option</code> <span data-x="html element insertion steps">HTML element insertion
steps</span>, given <var>insertedNode</var>, are:</p>
<ol>
<li><p>If <var>insertedNode</var>'s parent is a <code>select</code> element, or
<var>insertedNode</var>'s parent is an <code>optgroup</code> element whose parent is a
<code>select</code> element, then run that <code>select</code> element's <span>selectedness
setting algorithm</span>.</p></li>
</ol>
<p>The <code>option</code> <span data-x="html element removing steps">HTML element removing
steps</span>, given <var>removedNode</var> and <var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>select</code> element, or <var>oldParent</var> is an
<code>optgroup</code> element whose parent is a <code>select</code> element, then run that
<code>select</code> element's <span>selectedness setting algorithm</span>.</p></li>
</ol>
<p>The <code>option</code> <span>HTML element moving steps</span>, given <var>movedNode</var> and
<var>oldParent</var>, are:</p>
<ol>
<li><p>Run the <code>option</code> <span>HTML element removing steps</span> given
<var>movedNode</var> and <var>oldParent</var>.</p></li>
<li><p>Run the <code>option</code> <span>HTML element insertion steps</span> given
<var>movedNode</var>.</p></li>
</ol>
<p>The <code>optgroup</code> <span data-x="html element removing steps">HTML element removing
steps</span>, given <var>removedNode</var> and <var>oldParent</var>, are:</p>
<ol>
<li><p>If <var>oldParent</var> is a <code>select</code> element and <var>removedNode</var> has an
<code>option</code> child, then run <var>oldParent</var>'s <span>selectedness setting
algorithm</span>.</p></li>
</ol>
<p>The <code>optgroup</code> <span>HTML element moving steps</span>, given <var>movedNode</var>
and <var>oldParent</var>, are:</p>
<ol>
<li><p>Run the <code>optgroup</code> <span>HTML element removing steps</span> given
<var>movedNode</var> and <var>oldParent</var>.</p></li>
</ol>
<p>If an <code>option</code> element in the <span data-x="concept-select-option-list">list of
options</span> <dfn data-x="ask for a reset">asks for a reset</dfn>, then run that
<code>select</code> element's <span>selectedness setting algorithm</span>.</p>
<p>If the <code data-x="attr-select-multiple">multiple</code> attribute is present, and the
element is not <span data-x="concept-fe-disabled">disabled</span>, then the user agent should
allow the user to <dfn data-x="concept-select-toggle">toggle</dfn> the <span
data-x="concept-option-selectedness">selectedness</span> of the <code>option</code> elements in
its <span data-x="concept-select-option-list">list of options</span> that are themselves not <span
data-x="concept-option-disabled">disabled</span>. Upon such an element being <span
data-x="concept-select-toggle">toggled</span> (either through a click, or through a <span
data-x="option-command">menu command</span>, or any other mechanism), and before the relevant user
interaction event <!-- interaction event spec point --> is queued (e.g. before a related <code
data-x="event-click">click</code> event), the <span
data-x="concept-option-selectedness">selectedness</span> of the <code>option</code> element must
be changed (from true to false or false to true), the <span
data-x="concept-option-dirtiness">dirtiness</span> of the element must be set to true, and the
user agent must <span>send <code>select</code> update notifications</span>.</p>
<p>When the user agent is to <dfn>send <code>select</code> update notifications</dfn>, <span>queue
an element task</span> on the <span>user interaction task source</span> given the <code>select</code>
element to run these steps:</p>
<ol>
<li>Set the <code>select</code> element's <span>user validity</span> to true.</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-input">input</code> at the <code>select</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-change">change</code> at the <code>select</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
</ol>
<p>The <span data-x="concept-form-reset-control">reset algorithm</span> for a <code>select</code>
element <var>selectElement</var> is:</p>
<ol>
<li><p>Set <var>selectElement</var>'s <span>user validity</span> to false.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>optionElement</var> of
<var>selectElement</var>'s <span data-x="concept-select-option-list">list of
options</span>:</p>
<ol>
<li><p>If <var>optionElement</var> has a <code data-x="attr-option-selected">selected</code>
attribute, then set <var>optionElement</var>'s <span
data-x="concept-option-selectedness">selectedness</span> to true; otherwise set it to
false.</p></li>
<li><p>Set <var>optionElement</var>'s <span data-x="concept-option-dirtiness">dirtiness</span>
to false.</p></li>
</ol>
</li>
<li><p>Run the <span>selectedness setting algorithm</span> given
<var>selectElement</var>.</p></li>
</ol>
</div>
<p>
The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the <code>select</code> element with its <span>form owner</span>.
The <code data-x="attr-fe-name">name</code> attribute represents the element's name.
The <code data-x="attr-fe-disabled">disabled</code> attribute is used to make the control non-interactive and to prevent its value from being submitted.
The <code data-x="attr-fe-autocomplete">autocomplete</code> attribute controls how the user agent provides autofill behavior.
</p>
<p>A <code>select</code> element that is not <span data-x="concept-fe-disabled">disabled</span> is
<i data-x="concept-fe-mutable">mutable</i>.</p>
<dl class="domintro">
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-type">type</span></code></dt>
<dd>
<p>Returns "<code data-x="">select-multiple</code>" if the element has a <code
data-x="attr-select-multiple">multiple</code> attribute, and "<code data-x="">select-one</code>"
otherwise.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-options">options</span></code></dt>
<dd><p>Returns an <code>HTMLOptionsCollection</code> of the <span
data-x="concept-select-option-list">list of options</span>.</p></dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-length">length</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the number of elements in the <span data-x="concept-select-option-list">list of
options</span>.</p>
<p>When set to a smaller number, truncates the number of <code>option</code> elements in the
<code>select</code>.</p>
<p>When set to a greater number, adds new blank <code>option</code> elements to the
<code>select</code>.</p>
</dd>
<dt><code data-x=""><var>element</var> = <var>select</var>.<span subdfn data-x="dom-select-item">item</span>(<var>index</var>)</code></dt>
<dt><code data-x=""><var>select</var>[<var>index</var>]</code></dt>
<dd>
<p>Returns the item with index <var>index</var> from the <span
data-x="concept-select-option-list">list of options</span>. The items are sorted in <span>tree
order</span>.</p>
</dd>
<dt><code data-x=""><var>element</var> = <var>select</var>.<span subdfn data-x="dom-select-namedItem">namedItem</span>(<var>name</var>)</code></dt>
<dd>
<p>Returns the first item with <span data-x="concept-id">ID</span> or <code
data-x="attr-option-name">name</code> <var>name</var> from the <span
data-x="concept-select-option-list">list of options</span>.</p>
<p>Returns null if no element with that <span data-x="concept-id">ID</span> could be found.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-add">add</span>(<var>element</var> [, <var>before</var> ])</code></dt>
<dd>
<p>Inserts <var>element</var> before the node given by <var>before</var>.</p>
<p>The <var>before</var> argument can be a number, in which case <var>element</var> is inserted
before the item with that number, or an element from the <span
data-x="concept-select-option-list">list of options</span>, in which case <var>element</var> is
inserted before that element.</p>
<p>If <var>before</var> is omitted, null, or a number out of range, then <var>element</var> will
be added at the end of the list.</p>
<p>This method will throw a <span>"<code>HierarchyRequestError</code>"</span>
<code>DOMException</code> if <var>element</var> is an ancestor of the element into which it is
to be inserted.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-selectedOptions">selectedOptions</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <span data-x="concept-select-option-list">list
of options</span> that are selected.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-selectedIndex">selectedIndex</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the index of the first selected item, if any, or −1 if there is no selected
item.</p>
<p>Can be set, to change the selection.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-value">value</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span data-x="concept-option-value">value</span> of the first selected item, if
any, or the empty string if there is no selected item.</p>
<p>Can be set, to change the selection.</p>
</dd>
<dt><code data-x=""><var>select</var>.<span subdfn data-x="dom-select-showPicker">showPicker</span>()</code></dt>
<dd>
<p>Shows any applicable picker UI for <var>select</var>, so that the user can select a value.
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if
<var>select</var> is not <span data-x="concept-fe-mutable">mutable</span>.</p>
<p>Throws a <span>"<code>NotAllowedError</code>"</span> <code>DOMException</code> if called
without <span data-x="transient activation">transient user activation</span>.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if
<var>select</var> is inside a cross-origin <code>iframe</code>.</p>
<p>Throws a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code> if
<var>select</var> is not <span>being rendered</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLSelectElement"><code data-x="dom-select-type">type</code></dfn> IDL
attribute, on getting, must return the string "<code data-x="">select-one</code>" if the <code
data-x="attr-select-multiple">multiple</code> attribute is absent, and the string "<code
data-x="">select-multiple</code>" if the <code data-x="attr-select-multiple">multiple</code>
attribute is present.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code
data-x="dom-select-options">options</code></dfn> IDL attribute must return an
<code>HTMLOptionsCollection</code> rooted at the <code>select</code> node, whose filter matches
the elements in the <span data-x="concept-select-option-list">list of options</span>.</p>
<p>The <code data-x="dom-select-options">options</code> collection is also mirrored on the
<code>HTMLSelectElement</code> object. The <span>supported property indices</span> at any instant
are the indices supported by the object returned by the <code
data-x="dom-select-options">options</code> attribute at that instant.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code data-x="dom-select-length">length</code></dfn>
IDL attribute must return the number of nodes <span data-x="represented by the
collection">represented</span> by the <code data-x="dom-select-options">options</code> collection.
On setting, it must act like the attribute of the same name on the <code
data-x="dom-select-options">options</code> collection.</p>
<p>The <dfn method for="HTMLSelectElement"><code
data-x="dom-select-item">item(<var>index</var>)</code></dfn> method must return the value returned
by <span data-x="dom-HTMLCollection-item">the method of the same name</span> on the <code
data-x="dom-select-options">options</code> collection, when invoked with the same argument.</p>
<p>The <dfn method for="HTMLSelectElement"><code
data-x="dom-select-namedItem">namedItem(<var>name</var>)</code></dfn> method must return the value
returned by <span data-x="dom-HTMLCollection-namedItem">the method of the same name</span> on the
<code data-x="dom-select-options">options</code> collection, when invoked with the same
argument.</p>
<p id="dom-select-setter">When the user agent is to <span>set the value of a new indexed
property</span> or <span>set the value of an existing indexed property</span> for a
<code>select</code> element, it must instead run <a href="#dom-htmloptionscollection-setter">the
corresponding algorithm</a> on the <code>select</code> element's <code
data-x="dom-select-options">options</code> collection.</p>
<p>Similarly, the <dfn method for="HTMLSelectElement"><code
data-x="dom-select-add">add(<var>element</var>, <var>before</var>)</code></dfn> method must act
like its namesake method on that same <code data-x="dom-select-options">options</code>
collection.</p>
<p>The <dfn method for="HTMLSelectElement"><code data-x="dom-select-remove">remove()</code></dfn>
method must act like its namesake method on that same <code
data-x="dom-select-options">options</code> collection when it has arguments, and like its namesake
method on the <code>ChildNode</code> interface implemented by the <code>HTMLSelectElement</code>
ancestor interface <code>Element</code> when it has no arguments.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code
data-x="dom-select-selectedOptions">selectedOptions</code></dfn> IDL attribute must return an
<code>HTMLCollection</code> rooted at the <code>select</code> node, whose filter matches the
elements in the <span data-x="concept-select-option-list">list of options</span> that have their
<span data-x="concept-option-selectedness">selectedness</span> set to true.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code
data-x="dom-select-selectedIndex">selectedIndex</code></dfn> IDL attribute, on getting, must
return the <span data-x="concept-option-index">index</span> of the first <code>option</code>
element in the <span data-x="concept-select-option-list">list of options</span> in <span>tree
order</span> that has its <span data-x="concept-option-selectedness">selectedness</span> set to
true, if any. If there isn't one, then it must return −1.</p>
<p>On setting, the <code data-x="dom-select-selectedIndex">selectedIndex</code> attribute must set
the <span data-x="concept-option-selectedness">selectedness</span> of all the <code>option</code>
elements in the <span data-x="concept-select-option-list">list of options</span> to false, and
then the <code>option</code> element in the <span data-x="concept-select-option-list">list of
options</span> whose <span data-x="concept-option-index">index</span> is the given new value, if
any, must have its <span data-x="concept-option-selectedness">selectedness</span> set to true and
its <span data-x="concept-option-dirtiness">dirtiness</span> set to true.</p>
<p class="note">This can result in no element having a <span
data-x="concept-option-selectedness">selectedness</span> set to true even in the case of the
<code>select</code> element having no <code data-x="attr-select-multiple">multiple</code>
attribute and a <span data-x="concept-select-size">display size</span> of 1.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code data-x="dom-select-value">value</code></dfn>
IDL attribute, on getting, must return the <span data-x="concept-option-value">value</span> of the
first <code>option</code> element in the <span data-x="concept-select-option-list">list of
options</span> in <span>tree order</span> that has its <span
data-x="concept-option-selectedness">selectedness</span> set to true, if any. If there isn't one,
then it must return the empty string.</p>
<p>On setting, the <code data-x="dom-select-value">value</code> attribute must set the <span
data-x="concept-option-selectedness">selectedness</span> of all the <code>option</code> elements
in the <span data-x="concept-select-option-list">list of options</span> to false, and then the
first <code>option</code> element in the <span data-x="concept-select-option-list">list of
options</span>, in <span>tree order</span>, whose <span data-x="concept-option-value">value</span>
is equal to the given new value, if any, must have its <span
data-x="concept-option-selectedness">selectedness</span> set to true and its <span
data-x="concept-option-dirtiness">dirtiness</span> set to true.</p>
<p class="note">This can result in no element having a <span
data-x="concept-option-selectedness">selectedness</span> set to true even in the case of the
<code>select</code> element having no <code data-x="attr-select-multiple">multiple</code>
attribute and a <span data-x="concept-select-size">display size</span> of 1.</p>
<p>The <dfn attribute for="HTMLSelectElement"><code
data-x="dom-select-multiple">multiple</code></dfn>, <dfn attribute for="HTMLSelectElement"><code
data-x="dom-select-required">required</code></dfn>, and <dfn attribute
for="HTMLSelectElement"><code data-x="dom-select-size">size</code></dfn> IDL attributes must
<span>reflect</span> the respective content attributes of the same name. The <code
data-x="dom-select-size">size</code> IDL attribute has a <span>default value</span> of 0.</p>
<!-- see https://www.w3.org/Bugs/Public/show_bug.cgi?id=12288 for compat reasons why .size allows
0 (it's not limited to values greater than zero) even though that value really makes no sense
-->
<p class="note">For historical reasons, the default value of the <code
data-x="dom-select-size">size</code> IDL attribute does not return the actual size used, which, in
the absence of the <code data-x="attr-select-size">size</code> content attribute, is either 1 or 4
depending on the presence of the <code data-x="attr-select-multiple">multiple</code>
attribute.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> IDL attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-lfe-labels">labels</code> IDL
attribute provides a list of the element's <code>label</code>s. The <code
data-x="dom-fe-disabled">disabled</code>, <code data-x="dom-fae-form">form</code>, and
<code data-x="dom-fe-name">name</code> IDL attributes are part of the element's forms API.</p>
</div>
<div class="example">
<p>The following example shows how a <code>select</code> element can be used to offer the user
with a set of options from which the user can select a single option. The default option is
preselected.</p>
<pre><code class="html"><p>
<label for="unittype">Select unit type:</label>
<select id="unittype" name="unittype">
<option value="1"> Miner </option>
<option value="2"> Puffer </option>
<option value="3" selected> Snipey </option>
<option value="4"> Max </option>
<option value="5"> Firebot </option>
</select>
</p></code></pre>
<p>When there is no default option, a placeholder can be used instead:</p>
<pre><code class="html"><select name="unittype" <strong>required</strong>>
<strong><option value=""> Select unit type </option></strong>
<option value="1"> Miner </option>
<option value="2"> Puffer </option>
<option value="3"> Snipey </option>
<option value="4"> Max </option>
<option value="5"> Firebot </option>
</select></code></pre>
</div>
<div class="example">
<p>Here, the user is offered a set of options from which they can select any number. By default,
all five options are selected.</p>
<pre><code class="html"><p>
<label for="allowedunits">Select unit types to enable on this map:</label>
<select id="allowedunits" name="allowedunits" multiple>
<option value="1" selected> Miner </option>
<option value="2" selected> Puffer </option>
<option value="3" selected> Snipey </option>
<option value="4" selected> Max </option>
<option value="5" selected> Firebot </option>
</select>
</p></code></pre>
</div>
<div class="example">
<p>Sometimes, a user has to select one or more items. This example shows such an interface.</p>
<pre><code class="html"><label>
Select the songs from that you would like on your Act II Mix Tape:
<select multiple required name="act2">
<option value="s1">It Sucks to Be Me (Reprise)
<option value="s2">There is Life Outside Your Apartment
<option value="s3">The More You Ruv Someone
<option value="s4">Schadenfreude
<option value="s5">I Wish I Could Go Back to College
<option value="s6">The Money Song
<option value="s7">School for Monsters
<option value="s8">The Money Song (Reprise)
<option value="s9">There's a Fine, Fine Line (Reprise)
<option value="s10">What Do You Do With a B.A. in English? (Reprise)
<option value="s11">For Now
</select>
</label></code></pre>
</div>
<div class="example">
<p>Occasionally it can be useful to have a separator:
<pre><code class="html"><label>
Select the song to play next:
<select required name="next">
<option value="sr">Random
<hr>
<option value="s1">It Sucks to Be Me (Reprise)
<option value="s2">There is Life Outside Your Apartment
…</code></pre>
</div>
<h4>The <dfn element><code>datalist</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Either: <span>phrasing content</span>.</dd> <!-- we don't require a <select> element descendant, since there might be zero suggestions -->
<dd>Or: Zero or more <code>option</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-datalist">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-datalist">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDataListElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-datalist-options">options</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDataListElement</code>.</dd>
</dl>
<p>The <code>datalist</code> element represents a set of <code>option</code> elements that
represent predefined options for other controls. In the rendering, the <code>datalist</code>
element <span>represents</span> nothing<span w-nodev> and it, along with its children, should
be hidden</span>.</p>
<p>The <code>datalist</code> element can be used in two ways. In the simplest case, the
<code>datalist</code> element has just <code>option</code> element children.</p>
<div class="example">
<pre><code class="html"><label>
Animal:
<input name=animal list=animals>
<datalist id=animals>
<option value="Cat">
<option value="Dog">
</datalist>
</label></code></pre>
</div>
<p>In the more elaborate case, the <code>datalist</code> element can be given contents that are to
be displayed for down-level clients that don't support <code>datalist</code>. In this case, the
<code>option</code> elements are provided inside a <code>select</code> element inside the
<code>datalist</code> element.</p>
<div class="example">
<pre><code class="html"><label>
Animal:
<input name=animal list=animals>
</label>
<datalist id=animals>
<label>
or select from the list:
<select name=animal>
<option value="">
<option>Cat
<option>Dog
</select>
</label>
</datalist></code></pre>
</div>
<p>The <code>datalist</code> element is hooked up to an <code>input</code> element using the <code
data-x="attr-input-list">list</code> attribute on the <code>input</code> element.</p>
<p>Each <code>option</code> element that is a descendant of the <code>datalist</code> element,
that is not <span data-x="concept-option-disabled">disabled</span>, and whose <span
data-x="concept-option-value">value</span> is a string that isn't the empty string, represents a
suggestion. Each suggestion has a <span data-x="concept-option-value">value</span> and a <span
data-x="concept-option-label">label</span>.
<dl class="domintro">
<dt><code data-x=""><var>datalist</var>.<span subdfn data-x="dom-datalist-options">options</span></code></dt>
<dd>
<p>Returns an <code>HTMLCollection</code> of the <code>option</code> elements of the
<code>datalist</code> element.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLDataListElement"><code
data-x="dom-datalist-options">options</code></dfn> IDL attribute must return an
<code>HTMLCollection</code> rooted at the <code>datalist</code> node, whose filter matches
<code>option</code> elements.</p>
<p><strong>Constraint validation</strong>: If an element has a <code>datalist</code> element
ancestor, it is <span>barred from constraint validation</span>.</p>
</div>
<h4>The <dfn element><code>optgroup</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>select</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more <code>option</code> and <span data-x="script-supporting elements">script-supporting</span> elements.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-optgroup-disabled">disabled</code></dd>
<dd><code data-x="attr-optgroup-label">label</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-optgroup">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-optgroup">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLOptGroupElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-optgroup-disabled">disabled</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-optgroup-label">label</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLOptGroupElement</code>.</dd>
</dl>
<p>The <code>optgroup</code> element <span>represents</span> a group of <code>option</code>
elements with a common label.</p>
<p>The element's group of <code>option</code> elements consists of the <code>option</code>
elements that are children of the <code>optgroup</code> element.</p>
<div w-nodev>
<p>When showing <code>option</code> elements in <code>select</code> elements, user agents should
show the <code>option</code> elements of such groups as being related to each other and separate
from other <code>option</code> elements.</p>
</div>
<p>The <dfn element-attr for="optgroup"><code
data-x="attr-optgroup-disabled">disabled</code></dfn> attribute is a <span>boolean
attribute</span> and can be used to <span data-x="concept-option-disabled">disable</span> a group
of <code>option</code> elements together.</p>
<p>The <dfn element-attr for="optgroup"><code data-x="attr-optgroup-label">label</code></dfn>
attribute must be specified. Its value gives the name of the group, for the purposes of the user
interface. <span w-nodev>User agents should use this attribute's value when labeling the group of
<code>option</code> elements in a <code>select</code> element.</span></p>
<div w-nodev>
<p>The <dfn attribute for="HTMLOptGroupElement"><code
data-x="dom-optgroup-disabled">disabled</code></dfn> and <dfn attribute
for="HTMLOptGroupElement"><code data-x="dom-optgroup-label">label</code></dfn> attributes must
<span>reflect</span> the respective content attributes of the same name.</p>
</div>
<p class="note">There is no way to select an <code>optgroup</code> element. Only
<code>option</code> elements can be selected. An <code>optgroup</code> element merely provides a
label for a group of <code>option</code> elements.</p>
<div class="example">
<p>The following snippet shows how a set of lessons from three courses could be offered in a
<code>select</code> drop-down widget:</p>
<pre><code class="html"><form action="courseselector.dll" method="get">
<p>Which course would you like to watch today?
<p><label>Course:
<select name="c">
<optgroup label="8.01 Physics I: Classical Mechanics">
<option value="8.01.1">Lecture 01: Powers of Ten
<option value="8.01.2">Lecture 02: 1D Kinematics
<option value="8.01.3">Lecture 03: Vectors
<optgroup label="8.02 Electricity and Magnetism">
<option value="8.02.1">Lecture 01: What holds our world together?
<option value="8.02.2">Lecture 02: Electric Field
<option value="8.02.3">Lecture 03: Electric Flux
<optgroup label="8.03 Physics III: Vibrations and Waves">
<option value="8.03.1">Lecture 01: Periodic Phenomenon
<option value="8.03.2">Lecture 02: Beats
<option value="8.03.3">Lecture 03: Forced Oscillations with Damping
</select>
</label>
<p><input type=submit value="▶ Play">
</form></code></pre>
</div>
<h4>The <dfn element><code>option</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As a child of a <code>select</code> element.</dd>
<dd>As a child of a <code>datalist</code> element.</dd>
<dd>As a child of an <code>optgroup</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If the element has a <code data-x="attr-option-label">label</code> attribute and a <code data-x="attr-option-value">value</code> attribute: <span data-x="concept-content-nothing">Nothing</span>.</dd>
<dd>If the element has a <code data-x="attr-option-label">label</code> attribute but no <code data-x="attr-option-value">value</code> attribute: <span data-x="text content">Text</span>.</dd>
<dd>If the element has no <code data-x="attr-option-label">label</code> attribute and is not a
child of a <code>datalist</code> element: <span data-x="text content">Text</span> that is not
<span>inter-element whitespace</span>.</dd>
<dd>If the element has no <code data-x="attr-option-label">label</code> attribute and is a child
of a <code>datalist</code> element: <span data-x="text content">Text</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-option-disabled">disabled</code></dd>
<dd><code data-x="attr-option-label">label</code></dd>
<dd><code data-x="attr-option-selected">selected</code></dd>
<dd><code data-x="attr-option-value">value</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-option">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-option">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window,
<span>LegacyFactoryFunction</span>=<span data-x="dom-option">Option</span>(optional DOMString text = "", optional DOMString value, optional boolean defaultSelected = false, optional boolean selected = false)]
interface <dfn interface>HTMLOptionElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-option-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-option-form">form</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-option-label">label</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-option-defaultSelected">defaultSelected</span>;
attribute boolean <span data-x="dom-option-selected">selected</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-option-value">value</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-option-text">text</span>;
readonly attribute long <span data-x="dom-option-index">index</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLOptionElement</code>.</dd>
</dl>
<p>The <code>option</code> element <span>represents</span> an option in a <code>select</code>
element or as part of a list of suggestions in a <code>datalist</code> element.</p>
<p>In certain circumstances described in the definition of the <code>select</code> element, an
<code>option</code> element can be a <code>select</code> element's <span>placeholder label
option</span>. A <span>placeholder label option</span> does not represent an actual option, but
instead represents a label for the <code>select</code> control.</p>
<p>The <dfn element-attr for="option"><code data-x="attr-option-disabled">disabled</code></dfn>
attribute is a <span>boolean attribute</span>. An <code>option</code> element is <dfn
data-x="concept-option-disabled">disabled</dfn> if its <code
data-x="attr-option-disabled">disabled</code> attribute is present or if it is a child of an
<code>optgroup</code> element whose <code data-x="attr-optgroup-disabled">disabled</code>
attribute is present.</p>
<div w-nodev>
<p>An <code>option</code> element that is <span data-x="attr-option-disabled">disabled</span> must
prevent any <code data-x="event-click">click</code> events that are <span data-x="queue a
task">queued</span> on the <span>user interaction task source</span> from being dispatched on the
element.</p>
</div>
<p>The <dfn element-attr for="option"><code data-x="attr-option-label">label</code></dfn>
attribute provides a label for element. The <dfn data-x="concept-option-label">label</dfn> of an
<code>option</code> element is the value of the <code data-x="attr-option-label">label</code>
content attribute, if there is one and its value is not the empty string, or, otherwise, the value
of the element's <code data-x="dom-option-text">text</code> IDL attribute.</p>
<p>The <code data-x="attr-option-label">label</code> content attribute, if specified, must not be
empty.</p>
<p>The <dfn element-attr for="option"><code data-x="attr-option-value">value</code></dfn>
attribute provides a value for element. The <dfn data-x="concept-option-value">value</dfn> of an
<code>option</code> element is the value of the <code data-x="attr-option-value">value</code>
content attribute, if there is one, or, if there is not, the value of the element's <code
data-x="dom-option-text">text</code> IDL attribute.</p>
<p>The <dfn element-attr for="option"><code data-x="attr-option-selected">selected</code></dfn>
attribute is a <span>boolean attribute</span>. It represents the default <span
data-x="concept-option-selectedness">selectedness</span> of the element.</p>
<div w-nodev>
<p>The <dfn data-x="concept-option-dirtiness">dirtiness</dfn> of an <code>option</code> element is
a boolean state, initially false. It controls whether adding or removing the <code
data-x="attr-option-selected">selected</code> content attribute has any effect.</p>
<p>The <dfn data-x="concept-option-selectedness">selectedness</dfn> of an <code>option</code>
element is a boolean state, initially false. Except where otherwise specified, when the element is
created, its <span data-x="concept-option-selectedness">selectedness</span> must be set to true if
the element has a <code data-x="attr-option-selected">selected</code> attribute. Whenever an
<code>option</code> element's <code data-x="attr-option-selected">selected</code> attribute is
added, if its <span data-x="concept-option-dirtiness">dirtiness</span> is false, its <span
data-x="concept-option-selectedness">selectedness</span> must be set to true. Whenever an
<code>option</code> element's <code data-x="attr-option-selected">selected</code> attribute is
<em>removed</em>, if its <span data-x="concept-option-dirtiness">dirtiness</span> is false, its
<span data-x="concept-option-selectedness">selectedness</span> must be set to false.</p>
<p class="note">The <code data-x="dom-option">Option()</code> constructor, when called with three
or fewer arguments, overrides the initial state of the <span
data-x="concept-option-selectedness">selectedness</span> state to always be false even if the third
argument is true (implying that a <code data-x="attr-option-selected">selected</code> attribute is
to be set). The fourth argument can be used to explicitly set the initial <span
data-x="concept-option-selectedness">selectedness</span> state when using the constructor.</p>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=604 -->
</div>
<p>A <code>select</code> element whose <code data-x="attr-select-multiple">multiple</code>
attribute is not specified must not have more than one descendant <code>option</code> element with
its <code data-x="attr-option-selected">selected</code> attribute set.</p>
<div w-nodev>
<p>An <code>option</code> element's <dfn data-x="concept-option-index">index</dfn> is the number of
<code>option</code> elements that are in the same <span data-x="concept-select-option-list">list of
options</span> but that come before it in <span>tree order</span>. If the <code>option</code>
element is not in a <span data-x="concept-select-option-list">list of options</span>, then the
<code>option</code> element's <span data-x="concept-option-index">index</span> is zero.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>option</var>.<span subdfn data-x="dom-option-selected">selected</span></code></dt>
<dd>
<p>Returns true if the element is selected, and false otherwise.</p>
<p>Can be set, to override the current state of the element.</p>
</dd>
<dt><code data-x=""><var>option</var>.<span subdfn data-x="dom-option-index">index</span></code></dt>
<dd><p>Returns the index of the element in its <code>select</code> element's <code
data-x="dom-select-options">options</code> list.</p></dd>
<dt><code data-x=""><var>option</var>.<span subdfn data-x="dom-option-form">form</span></code></dt>
<dd><p>Returns the element's <code>form</code> element, if any, or null otherwise.</p></dd>
<dt><code data-x=""><var>option</var>.<span subdfn data-x="dom-option-text">text</span></code></dt>
<dd>
<p>Same as <code>textContent</code>, except that spaces are collapsed and <code>script</code>
elements are skipped.</p>
</dd>
<dt><code data-x=""><var>option</var> = new <span subdfn data-x="dom-option">Option</span>([ <var>text</var> [, <var>value</var> [, <var>defaultSelected</var> [, <var>selected</var> ] ] ] ])</code></dt>
<dd>
<p>Returns a new <code>option</code> element.</p>
<p>The <var>text</var> argument sets the contents of the element.</p>
<p>The <var>value</var> argument sets the <code data-x="attr-option-value">value</code>
attribute.</p>
<p>The <var>defaultSelected</var> argument sets the <code
data-x="attr-option-selected">selected</code> attribute.</p>
<p>The <var>selected</var> argument sets whether or not the element is selected. If it is
omitted, even if the <var>defaultSelected</var> argument is true, the element is not
selected.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLOptionElement"><code
data-x="dom-option-disabled">disabled</code></dfn> IDL attribute must <span>reflect</span> the
content attribute of the same name. The <dfn attribute for="HTMLOptionElement"><code
data-x="dom-option-defaultSelected">defaultSelected</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-option-selected">selected</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code data-x="dom-option-label">label</code></dfn>
IDL attribute, on getting, if there is a <code data-x="attr-option-label">label</code> content
attribute, must return that attribute's value; otherwise, it must return the element's <span
data-x="concept-option-label">label</span>. On setting, the element's <code
data-x="attr-option-label">label</code> content attribute must be set to the new value.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code data-x="dom-option-value">value</code></dfn>
IDL attribute, on getting, must return the element's <span
data-x="concept-option-value">value</span>. On setting, the element's <code
data-x="attr-option-value">value</code> content attribute must be set to the new value.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code
data-x="dom-option-selected">selected</code></dfn> IDL attribute, on getting, must return true if
the element's <span data-x="concept-option-selectedness">selectedness</span> is true, and false
otherwise. On setting, it must set the element's <span
data-x="concept-option-selectedness">selectedness</span> to the new value, set its <span
data-x="concept-option-dirtiness">dirtiness</span> to true, and then cause the element to
<span>ask for a reset</span>.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code data-x="dom-option-index">index</code></dfn>
IDL attribute must return the element's <span data-x="concept-option-index">index</span>.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code data-x="dom-option-text">text</code></dfn> IDL
attribute, on getting, must return the result of <span data-x="strip and collapse ASCII
whitespace">stripping and collapsing ASCII whitespace</span> from the concatenation of <span
data-x="concept-cd-data">data</span> of all the <code>Text</code> node descendants of the
<code>option</code> element, in <span>tree order</span>, excluding any that are descendants of
descendants of the <code>option</code> element that are themselves <code>script</code> or
<span>SVG <code>script</code></span> elements.</p>
<p>The <code data-x="dom-option-text">text</code> attribute's setter must <span>string replace
all</span> with the given value within this element.</p>
<p>The <dfn attribute for="HTMLOptionElement"><code data-x="dom-option-form">form</code></dfn> IDL
attribute's behavior depends on whether the <code>option</code> element is in a
<code>select</code> element or not. If the <code>option</code> has a <code>select</code> element
as its parent, or has an <code>optgroup</code> element as its parent and that
<code>optgroup</code> element has a <code>select</code> element as its parent, then the <code
data-x="dom-option-form">form</code> IDL attribute must return the same value as the <code
data-x="dom-fae-form">form</code> IDL attribute on that <code>select</code> element. Otherwise, it
must return null.</p>
<p>A legacy factory function is provided for creating <code>HTMLOptionElement</code> objects (in
addition to the factory methods from DOM such as <code
data-x="dom-Document-createElement">createElement()</code>): <dfn constructor
for="HTMLOptionElement"><code data-x="dom-option">Option(<var>text</var>, <var>value</var>,
<var>defaultSelected</var>, <var>selected</var>)</code></dfn>. When invoked, the legacy factory
function must perform the following steps:</p>
<ol>
<li><p>Let <var>document</var> be the <span>current global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>option</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">option</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p>If <var>text</var> is not the empty string, then append to <var>option</var> a new
<code>Text</code> node whose data is <var>text</var>.</p></li>
<li><p>If <var>value</var> is given, then <span data-x="concept-element-attributes-set-value">set
an attribute value</span> for <var>option</var> using "<code
data-x="attr-option-value">value</code>" and <var>value</var>.</p></li>
<li><p>If <var>defaultSelected</var> is true, then <span
data-x="concept-element-attributes-set-value">set an attribute value</span> for <var>option</var>
using "<code data-x="attr-option-selected">selected</code>" and the empty string.</p></li>
<li><p>If <var>selected</var> is true, then set <var>option</var>'s <span
data-x="concept-option-selectedness">selectedness</span> to true; otherwise set its <span
data-x="concept-option-selectedness">selectedness</span> to false (even if
<var>defaultSelected</var> is true).</p></li>
<li><p>Return <var>option</var>.</p></li>
</ol>
</div>
<h4>The <dfn element><code>textarea</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-submit">submittable</span>, <span data-x="category-reset">resettable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="text content">Text</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-fe-autocomplete">autocomplete</code></dd>
<dd><code data-x="attr-textarea-cols">cols</code></dd>
<dd><code data-x="attr-fe-dirname">dirname</code></dd>
<dd><code data-x="attr-fe-disabled">disabled</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-textarea-maxlength">maxlength</code></dd>
<dd><code data-x="attr-textarea-minlength">minlength</code></dd>
<dd><code data-x="attr-fe-name">name</code></dd>
<dd><code data-x="attr-textarea-placeholder">placeholder</code></dd>
<dd><code data-x="attr-textarea-readonly">readonly</code></dd>
<dd><code data-x="attr-textarea-required">required</code></dd>
<dd><code data-x="attr-textarea-rows">rows</code></dd>
<dd><code data-x="attr-textarea-wrap">wrap</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-textarea">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-textarea">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTextAreaElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-autocomplete">autocomplete</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-textarea-cols">cols</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-textarea-dirName">dirName</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fe-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-textarea-maxLength">maxLength</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-textarea-minLength">minLength</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-textarea-placeholder">placeholder</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-textarea-readOnly">readOnly</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-textarea-required">required</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-textarea-rows">rows</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-textarea-wrap">wrap</span>;
readonly attribute DOMString <span data-x="dom-textarea-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-textarea-defaultValue">defaultValue</span>;
attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-textarea-value">value</span>;
readonly attribute unsigned long <span data-x="dom-textarea-textLength">textLength</span>;
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
undefined <span data-x="dom-textarea/input-select">select</span>();
attribute unsigned long <span data-x="dom-textarea/input-selectionStart">selectionStart</span>;
attribute unsigned long <span data-x="dom-textarea/input-selectionEnd">selectionEnd</span>;
attribute DOMString <span data-x="dom-textarea/input-selectionDirection">selectionDirection</span>;
undefined <span data-x="dom-textarea/input-setRangeText">setRangeText</span>(DOMString replacement);
undefined <span data-x="dom-textarea/input-setRangeText">setRangeText</span>(DOMString replacement, unsigned long start, unsigned long end, optional <span>SelectionMode</span> selectionMode = "preserve");
undefined <span data-x="dom-textarea/input-setSelectionRange">setSelectionRange</span>(unsigned long start, unsigned long end, optional DOMString direction);
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTextAreaElement</code>.</dd>
</dl>
<p>The <code>textarea</code> element <span>represents</span> a multiline plain text edit
control<span w-nodev> for the element's <dfn data-x="concept-textarea-raw-value">raw
value</dfn></span>. The contents of the control represent the control's default value.</p>
<div w-nodev>
<p>The <span data-x="concept-textarea-raw-value">raw value</span> of a <code>textarea</code>
control must be initially the empty string.</p>
<p class="note">This element <a href="#bidireq">has rendering requirements involving the
bidirectional algorithm</a>.</p>
</div>
<p>The <dfn element-attr for="textarea"><code
data-x="attr-textarea-readonly">readonly</code></dfn> attribute is a <span>boolean
attribute</span> used to control whether the text can be edited by the user or not.</p>
<div class="example">
<p>In this example, a text control is marked read-only because it represents a read-only
file:</p>
<pre><code class="html">Filename: <code>/etc/bash.bashrc</code>
<textarea name="buffer" readonly>
# System-wide .bashrc file for interactive bash(1) shells.
# To enable the settings / commands in this file for login shells as well,
# this file has to be sourced in /etc/profile.
# If not running interactively, don't do anything
[ -z "$PS1" ] &amp;&amp; return
...</textarea></code></pre>
</div>
<div w-nodev>
<p><strong>Constraint validation</strong>: If the <code
data-x="attr-textarea-readonly">readonly</code> attribute is specified on a <code>textarea</code>
element, the element is <span>barred from constraint validation</span>.</p>
<p>A <code>textarea</code> element is <span data-x="concept-fe-mutable">mutable</span> if it is
neither <span data-x="concept-fe-disabled">disabled</span> nor has a <code
data-x="attr-textarea-readonly">readonly</code> attribute specified.</p>
<p>When a <code>textarea</code> is <span data-x="concept-fe-mutable">mutable</span>, its <span
data-x="concept-textarea-raw-value">raw value</span> should be editable by the user: the user
agent should allow the user to edit, insert, and remove text, and to insert and remove line breaks
in the form of U+000A LINE FEED (LF) characters. Any time the user causes the element's <span
data-x="concept-textarea-raw-value">raw value</span> to change, the user agent must <span>queue an
element task</span> on the <span>user interaction task source</span> given the
<code>textarea</code> element to <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-input">input</code> at the <code>textarea</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true. User agents may wait for a suitable break in the user's
interaction before queuing the task; for example, a user agent could wait for the user to have not
hit a key for 100ms, so as to only fire the event when the user pauses, instead of continuously
for each keystroke.</p>
<!-- same text is present in the <input> section -->
<p>A <code>textarea</code> element's <span data-x="concept-fe-dirty">dirty value flag</span> must
be set to true whenever the user interacts with the control in a way that changes the <span
data-x="concept-textarea-raw-value">raw value</span>.</p>
<p>The <span data-x="concept-node-clone-ext">cloning steps</span> for <code>textarea</code>
elements given <var>node</var>, <var>copy</var>, and <var>subtree</var> are to propagate the <span
data-x="concept-textarea-raw-value">raw value</span> and <span data-x="concept-fe-dirty">dirty
value flag</span> from <var>node</var> to <var>copy</var>.</p>
<p>The <span>children changed steps</span> for <code>textarea</code> elements must, if the
element's <span data-x="concept-fe-dirty">dirty value flag</span> is false, set the element's
<span data-x="concept-textarea-raw-value">raw value</span> to its <span>child text
content</span>.</p>
<p>The <span data-x="concept-form-reset-control">reset algorithm</span> for <code>textarea</code>
elements is to set the <span>user validity</span> to false, <span
data-x="concept-fe-dirty">dirty value flag</span> back to false, and set the <span
data-x="concept-textarea-raw-value">raw value</span> of element to its <span>child text
content</span>.</p>
<p>When a <code>textarea</code> element is popped off the <span>stack of open elements</span> of
an <span>HTML parser</span> or <span>XML parser</span>, then the user agent must invoke the
element's <span data-x="concept-form-reset-control">reset algorithm</span>.</p>
<!-- this next bit is also in the <input> Text/Search section -->
<!-- and something similar is in the session history section -->
<p>If the element is <span data-x="concept-fe-mutable">mutable</span>, the user agent should allow
the user to change the writing direction of the element, setting it either to a left-to-right
writing direction or a right-to-left writing direction. If the user does so, the user agent must
then run the following steps:</p>
<ol>
<li><p>Set the element's <code data-x="attr-dir">dir</code> attribute to "<code
data-x="attr-dir-ltr">ltr</code>" if the user selected a left-to-right writing direction, and
"<code data-x="attr-dir-rtl">rtl</code>" if the user selected a right-to-left writing
direction.</p></li>
<li><p><span>Queue an element task</span> on the <span>user interaction task source</span> given
the <code>textarea</code> element to <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-input">input</code> at the <code>textarea</code> element, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code data-x="dom-Event-composed">composed</code>
attributes initialized to true.</p></li>
</ol>
</div>
<p>The <dfn element-attr for="textarea"><code data-x="attr-textarea-cols">cols</code></dfn>
attribute specifies the expected maximum number of characters per line. If the <code
data-x="attr-textarea-cols">cols</code> attribute is specified, its value must be a <span>valid
non-negative integer</span> greater than zero. <span w-nodev>If applying the <span>rules for
parsing non-negative integers</span> to the attribute's value results in a number greater than
zero, then the element's <dfn data-x="attr-textarea-cols-value">character width</dfn> is that
value; otherwise, it is 20.</span></p>
<div w-nodev>
<p>The user agent may use the <code>textarea</code> element's <span
data-x="attr-textarea-cols-value">character width</span> as a hint to the user as to how many
characters the server prefers per line (e.g. for visual user agents by making the width of the
control be that many characters). In visual renderings, the user agent should wrap the user's
input in the rendering so that each line is no wider than this number of characters.</p>
</div>
<p>The <dfn element-attr for="textarea"><code data-x="attr-textarea-rows">rows</code></dfn>
attribute specifies the number of lines to show. If the <code
data-x="attr-textarea-rows">rows</code> attribute is specified, its value must be a <span>valid
non-negative integer</span> greater than zero. <span w-nodev>If applying the <span>rules for
parsing non-negative integers</span> to the attribute's value results in a number greater than
zero, then the element's <dfn data-x="attr-textarea-rows-value">character height</dfn> is that
value; otherwise, it is 2.</span></p>
<div w-nodev>
<p>Visual user agents should set the height of the control to the number of lines given by <span
data-x="attr-textarea-rows-value">character height</span>.</p>
</div>
<p>The <dfn element-attr for="textarea"><code data-x="attr-textarea-wrap">wrap</code></dfn>
attribute is an <span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="textarea/wrap"><code
data-x="attr-textarea-wrap-soft">soft</code></dfn>
<td><dfn data-x="attr-textarea-wrap-soft-state">Soft</dfn>
<td>Text is not to be wrapped when submitted (though can still be wrapped in the rendering).
<tr>
<td><dfn attr-value for="textarea/wrap"><code
data-x="attr-textarea-wrap-hard">hard</code></dfn>
<td><dfn data-x="attr-textarea-wrap-hard-state">Hard</dfn>
<td>Text is to have newlines added by the user agent so that the text is wrapped when it is
submitted.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-textarea-wrap-soft-state">Soft</span> state.</p>
<p>If the element's <code data-x="attr-textarea-wrap">wrap</code> attribute is in the <span
data-x="attr-textarea-wrap-hard-state">Hard</span> state, the <code
data-x="attr-textarea-cols">cols</code> attribute must be specified.</p>
<!-- attr-textarea-wrap-off (attr-textarea-wrap-off-state): not conforming; turns off the
rendering of wrapping but otherwise acts like 'soft' -->
<div w-nodev>
<p>For historical reasons, the element's value is normalized in three different ways for three
different purposes. The <span data-x="concept-textarea-raw-value">raw value</span> is the value as
it was originally set. It is not normalized. The <span data-x="concept-fe-api-value">API
value</span> is the value used in the <code data-x="dom-textarea-value">value</code> IDL
attribute, <code data-x="dom-textarea-textLength">textLength</code> IDL attribute, and by the
<code data-x="attr-fe-maxlength">maxlength</code> and <code
data-x="attr-fe-minlength">minlength</code> content attributes. It is normalized so that line
breaks use U+000A LINE FEED (LF) characters. Finally, there is the <span
data-x="concept-fe-value">value</span>, as used in form submission and other processing models in
this specification. It is normalized as for the <span data-x="concept-fe-api-value">API
value</span>, and in addition, if necessary given the element's <code
data-x="attr-textarea-wrap">wrap</code> attribute, additional line breaks are inserted to wrap the
text at the given width.</p>
<!--en-GB--><p id="textarea-line-break-normalisation-transformation">The algorithm for obtaining
the element's <span data-x="concept-fe-api-value">API value</span> is to return the element's
<span data-x="concept-textarea-raw-value">raw value</span>, with <span data-x="normalize
newlines">newlines normalized</span>.</p>
<p>The element's <span data-x="concept-fe-value">value</span> is defined to be the element's <span
data-x="concept-textarea-raw-value">API value</span> with the <span>textarea wrapping
transformation</span> applied. The <dfn>textarea wrapping transformation</dfn> is the following
algorithm, as applied to a string:</p>
<ol>
<li><p>If the element's <code data-x="attr-textarea-wrap">wrap</code> attribute is in the <span
data-x="attr-textarea-wrap-hard-state">Hard</span> state, insert U+000A LINE FEED (LF) characters
into the string using an <span>implementation-defined</span> algorithm so that each line has no
more than <span data-x="attr-textarea-cols-value">character width</span> characters. For the
purposes of this requirement, lines are delimited by the start of the string, the end of the
string, and U+000A LINE FEED (LF) characters.</p></li>
</ol>
</div>
<p>The <dfn element-attr for="textarea"><code
data-x="attr-textarea-maxlength">maxlength</code></dfn> attribute is a <span
data-x="attr-fe-maxlength">form control <code data-x="">maxlength</code> attribute</span>.</p>
<p>If the <code>textarea</code> element has a <span>maximum allowed value length</span>, then the
element's children must be such that the <span>length</span> of the value of the element's
<span>descendant text content</span> with <span data-x="normalize newlines">newlines
normalized</span> is less than or equal to the element's <span>maximum allowed value
length</span>.</p>
<p>The <dfn element-attr for="textarea"><code
data-x="attr-textarea-minlength">minlength</code></dfn> attribute is a <span
data-x="attr-fe-minlength">form control <code data-x="">minlength</code> attribute</span>.</p>
<!-- we allow the default to be smaller than the minimum, so that you can have incomplete, but not
empty, input already in the form, like a template that needs to be filled in -->
<p>The <dfn element-attr for="textarea"><code
data-x="attr-textarea-required">required</code></dfn> attribute is a <span>boolean
attribute</span>. When specified, the user will be required to enter a value before submitting the
form.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If the element has its <code
data-x="attr-textarea-required">required</code> attribute specified, and the element is <span
data-x="concept-fe-mutable">mutable</span>, and the element's <span
data-x="concept-fe-value">value</span> is the empty string, then the element is <span>suffering
from being missing</span>.</p>
</div>
<!-- substantially similar text in the <input> section -->
<p>The <dfn element-attr for="textarea"><code
data-x="attr-textarea-placeholder">placeholder</code></dfn> attribute represents a <em>short</em>
hint (a word or short phrase) intended to aid the user with data entry when the control has no
value. A hint could be a sample value or a brief description of the expected format.</p>
<p>The <code data-x="attr-textarea-placeholder">placeholder</code> attribute should not be used as
an alternative to a <code>label</code>. For a longer hint or other advisory text, the <code
data-x="attr-title">title</code> attribute is more appropriate.</p>
<p class="note">These mechanisms are very similar but subtly different: the hint given by the
control's <code>label</code> is shown at all times; the short hint given in the <code
data-x="attr-textarea-placeholder">placeholder</code> attribute is shown before the user enters a
value; and the hint in the <code data-x="attr-title">title</code> attribute is shown when the user
requests further help.</p>
<div w-nodev>
<p>User agents should present this hint to the user when the element's <span
data-x="concept-fe-value">value</span> is the empty string and the control is not
<span>focused</span> (e.g. by displaying it inside a blank unfocused control). All U+000D CARRIAGE
RETURN U+000A LINE FEED character pairs (CRLF) in the hint, as well as all other U+000D CARRIAGE
RETURN (CR) and U+000A LINE FEED (LF) characters in the hint, must be treated as line breaks when
rendering the hint.</p>
<p>If a user agent normally doesn't show this hint to the user when the control is
<span>focused</span>, then the user agent should nonetheless show the hint for the control if it
was focused as a result of the <code data-x="attr-fe-autofocus">autofocus</code> attribute, since
in that case the user will not have had an opportunity to examine the control before focusing
it.</p>
</div>
<p>
The <code data-x="attr-fe-name">name</code> attribute represents the element's name.
The <code data-x="attr-fe-dirname">dirname</code> attribute controls how the element's <span
data-x="the directionality">directionality</span> is submitted.
The <code data-x="attr-fe-disabled">disabled</code> attribute is used to make the control
non-interactive and to prevent its value from being submitted.
The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<code>textarea</code> element with its <span>form owner</span>.
The <code data-x="attr-fe-autocomplete">autocomplete</code> attribute controls how the user agent
provides autofill behavior.
</p>
<dl class="domintro">
<dt><code data-x=""><var>textarea</var>.<span subdfn data-x="dom-textarea-type">type</span></code></dt>
<dd><p>Returns the string "<code data-x="">textarea</code>".</p></dd>
<dt><code data-x=""><var>textarea</var>.<span subdfn data-x="dom-textarea-value">value</span></code></dt>
<dd>
<p>Returns the current value of the element.</p>
<p>Can be set, to change the value.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-cols">cols</code></dfn>, <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-placeholder">placeholder</code></dfn>, <dfn attribute
for="HTMLTextAreaElement"><code data-x="dom-textarea-required">required</code></dfn>, <dfn
attribute for="HTMLTextAreaElement"><code data-x="dom-textarea-rows">rows</code></dfn>, and <dfn
attribute for="HTMLTextAreaElement"><code data-x="dom-textarea-wrap">wrap</code></dfn> IDL
attributes must <span>reflect</span> the respective content attributes of the same name. The <code
data-x="dom-textarea-cols">cols</code> and <code data-x="dom-textarea-rows">rows</code> attributes
are <span>limited to only positive numbers with fallback</span>. The <code
data-x="dom-textarea-cols">cols</code> IDL attribute's <span>default value</span> is 20. The <code
data-x="dom-textarea-rows">rows</code> IDL attribute's <span>default value</span> is 2. The <dfn
attribute for="HTMLTextAreaElement"><code data-x="dom-textarea-dirName">dirName</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-fe-dirname">dirname</code> content
attribute. The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-maxLength">maxLength</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-textarea-maxlength">maxlength</code> content attribute, <span>limited to only
non-negative numbers</span>. The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-minLength">minLength</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-textarea-minlength">minlength</code> content attribute, <span>limited to only
non-negative numbers</span>. The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-readOnly">readOnly</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-textarea-readonly">readonly</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTextAreaElement"><code data-x="dom-textarea-type">type</code></dfn>
IDL attribute must return the value "<code data-x="">textarea</code>".</p>
<p>The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-defaultValue">defaultValue</code></dfn> attribute's getter must return the
element's <span>child text content</span>.
<p>The <code data-x="dom-textarea-defaultValue">defaultValue</code> attribute's setter must
<span>string replace all</span> with the given value within this element.</p>
<p>The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-value">value</code></dfn> IDL attribute must, on getting, return the
element's <span data-x="concept-fe-api-value">API value</span>. On setting, it must perform the
following steps:</p>
<ol>
<li><p>Let <var>oldAPIValue</var> be this element's <span
data-x="concept-fe-api-value">API value</span>.</p></li>
<li><p>Set this element's <span data-x="concept-textarea-raw-value">raw value</span> to the new
value.</p></li>
<li><p>Set this element's <span data-x="concept-fe-dirty">dirty value flag</span> to
true.</p></li>
<li><p>If the new <span data-x="concept-fe-api-value">API value</span> is different from
<var>oldAPIValue</var>, then move the <span data-x="concept-textarea/input-cursor">text entry
cursor position</span> to the end of the text control, unselecting any selected text and <span
data-x="set the selection direction">resetting the selection direction</span> to "<code
data-x="">none</code>".</p></li>
</ol>
<p>The <dfn attribute for="HTMLTextAreaElement"><code
data-x="dom-textarea-textLength">textLength</code></dfn> IDL attribute must return the
<span>length</span> of the element's <span data-x="concept-fe-api-value">API value</span>.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> IDL attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-lfe-labels">labels</code> IDL
attribute provides a list of the element's <code>label</code>s. The <code
data-x="dom-textarea/input-select">select()</code>, <code
data-x="dom-textarea/input-selectionStart">selectionStart</code>, <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code>, <code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code>, <code
data-x="dom-textarea/input-setRangeText">setRangeText()</code>, and <code
data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> methods and IDL attributes
expose the element's text selection. The <code data-x="dom-fe-disabled">disabled</code>,
<code data-x="dom-fae-form">form</code>, and <code data-x="dom-fe-name">name</code> IDL attributes
are part of the element's forms API.</p>
</div>
<div class="example">
<p>Here is an example of a <code>textarea</code> being used for unrestricted free-form text input
in a form:</p>
<pre><code class="html"><p>If you have any comments, please let us know: <textarea cols=80 name=comments></textarea></p></code></pre>
<p>To specify a maximum length for the comments, one can use the <code
data-x="attr-textarea-maxlength">maxlength</code> attribute:</p>
<pre><code class="html"><p>If you have any short comments, please let us know: <textarea cols=80 name=comments maxlength=200></textarea></p></code></pre>
<p>To give a default value, text can be included inside the element:</p>
<pre><code class="html"><p>If you have any comments, please let us know: <textarea cols=80 name=comments>You rock!</textarea></p></code></pre>
<p>You can also give a minimum length. Here, a letter needs to be filled out by the user; a
template (which is shorter than the minimum length) is provided, but is insufficient to submit
the form:</p>
<pre><code class="html"><textarea required minlength="500">Dear Madam Speaker,
Regarding your letter dated ...
...
Yours Sincerely,
...</textarea></code></pre>
<p>A placeholder can be given as well, to suggest the basic form to the user, without providing
an explicit template:</p>
<pre><code class="html"><textarea placeholder="Dear Francine,
They closed the parks this week, so we won't be able to
meet your there. Should we just have dinner?
Love,
Daddy"></textarea></code></pre>
<p>To have the browser submit <span>the directionality</span> of the element along with the
value, the <code data-x="attr-fe-dirname">dirname</code> attribute can be specified:</p>
<pre><code class="html"><p>If you have any comments, please let us know (you may use either English or Hebrew for your comments):
<textarea cols=80 name=comments dirname=comments.dir></textarea></p></code></pre>
</div>
<h4>The <dfn element><code>output</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-reset">resettable</span>, and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-output-for">for</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-fe-name">name</code> <!-- variant --> </dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-output">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-output">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLOutputElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-output-htmlFor">htmlFor</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
readonly attribute DOMString <span data-x="dom-output-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-output-defaultValue">defaultValue</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-output-value">value</span>;
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLOutputElement</code>.</dd>
</dl>
<p>The <code>output</code> element <span>represents</span> the result of a calculation performed
by the application, or the result of a user action.</p>
<p class="note">This element can be contrasted with the <code>samp</code> element, which is the
appropriate element for quoting the output of other programs run previously.</p>
<p>The <dfn element-attr for="output"><code data-x="attr-output-for">for</code></dfn> content
attribute allows an explicit relationship to be made between the result of a calculation and the
elements that represent the values that went into the calculation or that otherwise influenced the
calculation. The <code data-x="attr-output-for">for</code> attribute, if specified, must contain a
string consisting of an <span>unordered set of unique space-separated tokens</span>, none of which
are <span>identical to</span> another token and each of which must have the value of an <span
data-x="concept-id">ID</span> of an element in the same <span>tree</span>.</p>
<p>The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<code>output</code> element with its <span>form owner</span>. The <code
data-x="attr-fe-name">name</code> attribute represents the element's name. The <code>output</code>
element is associated with a form so that it can be easily <span>referenced</span> from the event
handlers of form controls; the element's value itself is not submitted when the form is
submitted.</p>
<div w-nodev>
<p>The element has a <dfn data-x="concept-output-default-value-override">default value
override</dfn> (null or a string). Initially it must be null.</p>
<p>The element's <dfn data-x="concept-output-default-value">default value</dfn> is determined by
the following steps:</p>
<ol>
<li><p>If this element's <span data-x="concept-output-default-value-override">default value
override</span> is non-null, then return it.</p></li>
<li><p>Return this element's <span>descendant text content</span>.</p></li>
</ol>
<p>The <span data-x="concept-form-reset-control">reset algorithm</span> for <code>output</code>
elements is to run these steps:
<ol>
<li><p><span>String replace all</span> with this element's <span
data-x="concept-output-default-value">default value</span> within this element.</p></li>
<li><p>Set this element's <span data-x="concept-output-default-value-override">default value
override</span> to null.</p></li>
</ol>
</div>
<dl class="domintro">
<dt><code data-x=""><var>output</var>.<span subdfn data-x="dom-output-value">value</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the element's current value.</p>
<p>Can be set, to change the value.</p>
</dd>
<dt><code data-x=""><var>output</var>.<span subdfn data-x="dom-output-defaultValue">defaultValue</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the element's current default value.</p>
<p>Can be set, to change the default value.</p>
</dd>
<dt><code data-x=""><var>output</var>.<span subdfn data-x="dom-output-type">type</span></code></dt>
<dd><p>Returns the string "<code data-x="">output</code>".</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLOutputElement"><code data-x="dom-output-value">value</code></dfn>
getter steps are to return <span>this</span>'s <span>descendant text content</span>.</p>
<p>The <code data-x="dom-output-value">value</code> setter steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <span data-x="concept-output-default-value-override">default value
override</span> to its <span data-x="concept-output-default-value">default value</span>.</p></li>
<li><p><span>String replace all</span> with the given value within <span>this</span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLOutputElement"><code
data-x="dom-output-defaultValue">defaultValue</code></dfn> getter steps are to return the result
of running <span>this</span>'s <span data-x="concept-output-default-value">default
value</span>.</p>
<p>The <code data-x="dom-output-defaultValue">defaultValue</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-output-default-value-override">default value
override</span> is null, then <span>string replace all</span> with the given value within
<span>this</span> and return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-output-default-value-override">default value
override</span> to the given value.</p></li>
</ol>
<p>The <dfn attribute for="HTMLOutputElement"><code data-x="dom-output-type">type</code></dfn>
getter steps are to return "<code data-x="">output</code>".</p>
<p>The <dfn attribute for="HTMLOutputElement"><code
data-x="dom-output-htmlFor">htmlFor</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-output-for">for</code> content attribute.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> IDL attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-lfe-labels">labels</code> IDL
attribute provides a list of the element's <code>label</code>s. The <code
data-x="dom-fae-form">form</code> and <code data-x="dom-fe-name">name</code> IDL attributes are
part of the element's forms API.</p>
</div>
<div class="example">
<p>A simple calculator could use <code>output</code> for its display of calculated results:</p>
<pre><code class="html"><form onsubmit="return false" oninput="o.value = a.valueAsNumber + b.valueAsNumber">
<input id=a type=number step=any> +
<input id=b type=number step=any> =
<output id=o for="a b"></output>
</form></code></pre>
</div>
<div class="example">
<p>In this example, an <code>output</code> element is used to report the results of a calculation performed by a remote
server, as they come in:</p>
<pre><code class="html"><output id="result"></output>
<script>
var primeSource = new WebSocket('ws://primes.example.net/');
primeSource.onmessage = function (event) {
document.getElementById('result').value = event.data;
}
</script></code></pre>
</div>
<h4>The <dfn element><code>progress</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span data-x="category-label">Labelable element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, but there must be no <code>progress</code> element descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-progress-value">value</code></dd>
<dd><code data-x="attr-progress-max">max</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-progress">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-progress">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLProgressElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute double <span data-x="dom-progress-value">value</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-progress-max">max</span>;
readonly attribute double <span data-x="dom-progress-position">position</span>;
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLProgressElement</code>.</dd>
</dl>
<p>The <code>progress</code> element <span>represents</span> the completion progress of a task.
The progress is either indeterminate, indicating that progress is being made but that it is not
clear how much more work remains to be done before the task is complete (e.g. because the task is
waiting for a remote host to respond), or the progress is a number in the range zero to a maximum,
giving the fraction of work that has so far been completed.</p>
<p>There are two attributes that determine the current task completion represented by the element.
The <dfn element-attr for="progress"><code data-x="attr-progress-value">value</code></dfn>
attribute specifies how much of the task has been completed, and the <dfn element-attr
for="progress"><code data-x="attr-progress-max">max</code></dfn> attribute specifies how much work
the task requires in total. The units are arbitrary and not specified.</p>
<p class="note">To make a determinate progress bar, add a <code
data-x="attr-progress-value">value</code> attribute with the current progress (either a number from
0.0 to 1.0, or, if the <code data-x="attr-progress-max">max</code> attribute is specified, a number
from 0 to the value of the <code data-x="attr-progress-max">max</code> attribute). To make an
indeterminate progress bar, remove the <code data-x="attr-progress-value">value</code>
attribute.</p>
<p>Authors are encouraged to also include the current value and the maximum value inline as text
inside the element, so that the progress is made available to users of legacy user agents.</p>
<div class="example">
<p>Here is a snippet of a web application that shows the progress of some automated task:</p>
<pre><code class="html"><section>
<h2>Task Progress</h2>
<p>Progress: <progress id=p max=100><span>0</span>%</progress></p>
<script>
var progressBar = document.getElementById('p');
function updateProgress(newValue) {
progressBar.value = newValue;
progressBar.getElementsByTagName('span')[0].textContent = newValue;
}
</script>
</section></code></pre>
<p>(The <code data-x="">updateProgress()</code> method in this example would be called by some
other code on the page to update the actual progress bar as the task progressed.)</p>
</div>
<p>The <code data-x="attr-progress-value">value</code> and <code
data-x="attr-progress-max">max</code> attributes, when present, must have values that are <span
data-x="valid floating-point number">valid floating-point numbers</span>. The <code
data-x="attr-progress-value">value</code> attribute, if present, must have a value greater than or
equal to zero, and less than or equal to the value of the <code
data-x="attr-progress-max">max</code> attribute, if present, or 1.0, otherwise. The <code
data-x="attr-progress-max">max</code> attribute, if present, must have a value greater than
zero.</p>
<p class="note">The <code>progress</code> element is the wrong element to use for something that
is just a gauge, as opposed to task progress. For instance, indicating disk space usage using
<code>progress</code> would be inappropriate. Instead, the <code>meter</code> element is available
for such use cases.</p>
<div w-nodev>
<p><strong>User agent requirements</strong>: If the <code data-x="attr-progress-value">value</code>
attribute is omitted, then the progress bar is an indeterminate progress bar. Otherwise, it is a
determinate progress bar.</p>
<p>If the progress bar is a determinate progress bar and the element has a <code
data-x="attr-progress-max">max</code> attribute, the user agent must parse the <code
data-x="attr-progress-max">max</code> attribute's value according to the <span>rules for parsing
floating-point number values</span>. If this does not result in an error, and if the parsed value
is greater than zero, then the <dfn data-x="concept-progress-maximum">maximum value</dfn> of the
progress bar is that value. Otherwise, if the element has no <code
data-x="attr-progress-max">max</code> attribute, or if it has one but parsing it resulted in an
error, or if the parsed value was less than or equal to zero, then the <span
data-x="concept-progress-maximum">maximum value</span> of the progress bar is 1.0.</p>
<p>If the progress bar is a determinate progress bar, user agents must parse the <code
data-x="attr-progress-value">value</code> attribute's value according to the <span>rules for
parsing floating-point number values</span>. If this does not result in an error and the parsed
value is greater than zero, then the <dfn data-x="concept-progress-value">value</dfn> of the
progress bar is that parsed value. Otherwise, if parsing the <code
data-x="attr-progress-value">value</code> attribute's value resulted in an error or a number less
than or equal to zero, then the <span data-x="concept-progress-value">value</span> of the progress
bar is zero.</p>
<p>If the progress bar is a determinate progress bar, then the <dfn
data-x="concept-progress-current-value">current value</dfn> is the <span
data-x="concept-progress-maximum">maximum value</span>, if <span
data-x="concept-progress-value">value</span> is greater than the <span
data-x="concept-progress-maximum">maximum value</span>, and <span
data-x="concept-progress-value">value</span> otherwise.</p>
<p><strong>UA requirements for showing the progress bar</strong>: When representing a
<code>progress</code> element to the user, the UA should indicate whether it is a determinate or
indeterminate progress bar, and in the former case, should indicate the relative position of the
<span data-x="concept-progress-current-value">current value</span> relative to the <span
data-x="concept-progress-maximum">maximum value</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>progress</var>.<span subdfn data-x="dom-progress-position">position</span></code></dt>
<dd>
<p>For a determinate progress bar (one with known current and maximum values), returns the
result of dividing the current value by the maximum value.</p>
<p>For an indeterminate progress bar, returns −1.</p>
</dd>
</dl>
<div w-nodev>
<p>If the progress bar is an indeterminate progress bar, then the <dfn attribute
for="HTMLProgressElement"><code data-x="dom-progress-position">position</code></dfn> IDL attribute
must return −1. Otherwise, it must return the result of dividing the <span
data-x="concept-progress-current-value">current value</span> by the <span
data-x="concept-progress-maximum">maximum value</span>.</p>
<p>If the progress bar is an indeterminate progress bar, then the <dfn attribute
for="HTMLProgressElement"><code data-x="dom-progress-value">value</code></dfn> IDL attribute, on
getting, must return 0. Otherwise, it must return the <span
data-x="concept-progress-value">current value</span>. On setting, the given value must be
converted to the <span>best representation of the number as a floating-point number</span> and
then the <code data-x="dom-progress-value">value</code> content attribute must be set to that
string.</p>
<p class="note">Setting the <code data-x="dom-progress-value">value</code> IDL attribute to itself
when the corresponding content attribute is absent would change the progress bar from an
indeterminate progress bar to a determinate progress bar with no progress.</p>
<p>The <dfn attribute for="HTMLProgressElement"><code data-x="dom-progress-max">max</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name, <span>limited to
only positive numbers</span>. The <span>default value</span> for <code
data-x="dom-progress-max">max</code> is 1.0.</p>
<p>The <code data-x="dom-lfe-labels">labels</code> IDL attribute provides a list of the element's
<code>label</code>s.</p>
</div>
<h4>The <dfn element><code>meter</code></dfn> element</h4>
<!-- Keep this after <progress> and NOT close to <time> -->
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span data-x="category-label">Labelable element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, but there must be no <code>meter</code> element descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-meter-value">value</code></dd>
<dd><code data-x="attr-meter-min">min</code></dd>
<dd><code data-x="attr-meter-max">max</code></dd>
<dd><code data-x="attr-meter-low">low</code></dd>
<dd><code data-x="attr-meter-high">high</code></dd>
<dd><code data-x="attr-meter-optimum">optimum</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-meter">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-meter">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLMeterElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-value">value</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-min">min</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-max">max</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-low">low</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-high">high</span>;
[<span>CEReactions</span>] attribute double <span data-x="dom-meter-optimum">optimum</span>;
readonly attribute <span>NodeList</span> <span data-x="dom-lfe-labels">labels</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLMeterElement</code>.</dd>
</dl>
<p>The <code>meter</code> element <span>represents</span> a scalar measurement within a known
range, or a fractional value; for example disk usage, the relevance of a query result, or the
fraction of a voting population to have selected a particular candidate.</p>
<p>This is also known as a gauge.</p>
<p>The <code>meter</code> element should not be used to indicate progress (as in a progress bar).
For that role, HTML provides a separate <code>progress</code> element.</p>
<p class="note">The <code>meter</code> element also does not represent a scalar value of arbitrary
range — for example, it would be wrong to use this to report a weight, or height, unless
there is a known maximum value.</p>
<p>There are six attributes that determine the semantics of the gauge represented by the
element.</p>
<p>The <dfn element-attr for="meter"><code data-x="attr-meter-min">min</code></dfn> attribute
specifies the lower bound of the range, and the <dfn element-attr for="meter"><code
data-x="attr-meter-max">max</code></dfn> attribute specifies the upper bound. The <dfn
element-attr for="meter"><code data-x="attr-meter-value">value</code></dfn> attribute specifies
the value to have the gauge indicate as the "measured" value.</p>
<p>The other three attributes can be used to segment the gauge's range into "low", "medium", and
"high" parts, and to indicate which part of the gauge is the "optimum" part. The <dfn element-attr
for="meter"><code data-x="attr-meter-low">low</code></dfn> attribute specifies the range that is
considered to be the "low" part, and the <dfn element-attr for="meter"><code
data-x="attr-meter-high">high</code></dfn> attribute specifies the range that is considered to be
the "high" part. The <dfn element-attr for="meter"><code
data-x="attr-meter-optimum">optimum</code></dfn> attribute gives the position that is "optimum";
if that is higher than the "high" value then this indicates that the higher the value, the better;
if it's lower than the "low" mark then it indicates that lower values are better, and naturally if
it is in between then it indicates that neither high nor low values are good.</p>
<p><span w-nodev><strong>Authoring requirements</strong>:</span> The <code
data-x="attr-meter-value">value</code> attribute must be specified. The <code
data-x="attr-meter-value">value</code>, <code data-x="attr-meter-min">min</code>, <code
data-x="attr-meter-low">low</code>, <code data-x="attr-meter-high">high</code>, <code
data-x="attr-meter-max">max</code>, and <code data-x="attr-meter-optimum">optimum</code> attributes,
when present, must have values that are <span data-x="valid floating-point number">valid
floating-point numbers</span>.</p>
<p>In addition, the attributes' values are further constrained:</p>
<p>Let <var>value</var> be the <code data-x="attr-meter-value">value</code> attribute's
number.</p>
<p>If the <code data-x="attr-meter-min">min</code> attribute is specified, then let <var>minimum</var> be that attribute's value; otherwise, let it be zero.</p>
<p>If the <code data-x="attr-meter-max">max</code> attribute is specified, then let <var>maximum</var> be that attribute's value; otherwise, let it be 1.0.</p>
<p>The following inequalities must hold, as applicable:</p>
<ul>
<li><p><var>minimum</var> ≤ <var>value</var> ≤ <var>maximum</var></p></li>
<li><p><var>minimum</var> ≤ <code data-x="attr-meter-low">low</code> ≤ <var>maximum</var>
(if <code data-x="attr-meter-low">low</code> is specified)</p></li>
<li><p><var>minimum</var> ≤ <code data-x="attr-meter-high">high</code> ≤
<var>maximum</var> (if <code data-x="attr-meter-high">high</code> is specified)</p></li>
<li><p><var>minimum</var> ≤ <code data-x="attr-meter-optimum">optimum</code> ≤
<var>maximum</var> (if <code data-x="attr-meter-optimum">optimum</code> is specified)</p></li>
<li><p><code data-x="attr-meter-low">low</code> ≤ <code data-x="attr-meter-high">high</code>
(if both <code data-x="attr-meter-low">low</code> and <code data-x="attr-meter-high">high</code>
are specified)</p></li>
</ul>
<p class="note">If no minimum or maximum is specified, then the range is assumed to be 0..1, and
the value thus has to be within that range.</p>
<p>Authors are encouraged to include a textual representation of the gauge's state in the
element's contents, for users of user agents that do not support the <code>meter</code>
element.</p>
<p>When used with <span>microdata</span>, the <code>meter</code> element's <code
data-x="attr-meter-value">value</code> attribute provides the element's machine-readable value.</p>
<div class="example">
<p>The following examples show three gauges that would all be three-quarters full:</p>
<pre><code class="html">Storage space usage: <meter value=6 max=8>6 blocks used (out of 8 total)</meter></code></pre>
<pre><code class="html">Voter turnout: <meter value=0.75><img alt="75%" src="graph75.png"></meter></code></pre>
<pre><code class="html">Tickets sold: <meter min="0" max="100" value="75"></meter></code></pre>
<p>The following example is incorrect use of the element, because it doesn't give a range (and
since the default maximum is 1, both of the gauges would end up looking maxed out):</p>
<pre class="bad"><code class="html"><p>The grapefruit pie had a radius of <meter value=12>12cm</meter>
and a height of <meter value=2>2cm</meter>.</p> <!-- <strong>BAD!</strong> --></code></pre>
<p>Instead, one would either not include the meter element, or use the meter element with a
defined range to give the dimensions in context compared to other pies:</p>
<pre><code class="html"><p>The grapefruit pie had a radius of 12cm and a height of
2cm.</p>
<dl>
<dt>Radius: <dd> <meter min=0 max=20 value=12>12cm</meter>
<dt>Height: <dd> <meter min=0 max=10 value=2>2cm</meter>
</dl></code></pre>
</div>
<p>There is no explicit way to specify units in the <code>meter</code> element, but the units may
be specified in the <code data-x="attr-title">title</code> attribute in free-form text.</p>
<div class="example">
<p>The example above could be extended to mention the units:</p>
<pre><code class="html"><dl>
<dt>Radius: <dd> <meter min=0 max=20 value=12 title="centimeters">12cm</meter>
<dt>Height: <dd> <meter min=0 max=10 value=2 title="centimeters">2cm</meter>
</dl></code></pre>
</div>
<div w-nodev>
<p><strong>User agent requirements</strong>: User agents must parse the <code
data-x="attr-meter-min">min</code>, <code data-x="attr-meter-max">max</code>, <code
data-x="attr-meter-value">value</code>, <code data-x="attr-meter-low">low</code>, <code
data-x="attr-meter-high">high</code>, and <code data-x="attr-meter-optimum">optimum</code>
attributes using the <span>rules for parsing floating-point number values</span>.</p>
<p>User agents must then use all these numbers to obtain values for six points on the gauge, as
follows. (The order in which these are evaluated is important, as some of the values refer to
earlier ones.)</p>
<dl>
<dt>The <dfn data-x="concept-meter-minimum">minimum value</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-min">min</code> attribute is specified and a value could be
parsed out of it, then the minimum value is that value. Otherwise, the minimum value is
zero.</p>
</dd>
<dt>The <dfn data-x="concept-meter-maximum">maximum value</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-max">max</code> attribute is specified and a value could be
parsed out of it, then the candidate maximum value is that value. Otherwise, the candidate
maximum value is 1.0.</p>
<p>If the candidate maximum value is greater than or equal to the minimum value, then the
maximum value is the candidate maximum value. Otherwise, the maximum value is the same as the
minimum value.</p>
</dd>
<dt>The <dfn data-x="concept-meter-actual">actual value</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-value">value</code> attribute is specified and a value could
be parsed out of it, then that value is the candidate actual value. Otherwise, the candidate
actual value is zero.</p>
<p>If the candidate actual value is less than the minimum value, then the actual value is the
minimum value.</p>
<p>Otherwise, if the candidate actual value is greater than the maximum value, then the actual
value is the maximum value.</p>
<p>Otherwise, the actual value is the candidate actual value.</p>
</dd>
<dt>The <dfn data-x="concept-meter-low">low boundary</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-low">low</code> attribute is specified and a value could be
parsed out of it, then the candidate low boundary is that value. Otherwise, the candidate low
boundary is the same as the minimum value.</p>
<p>If the candidate low boundary is less than the minimum value, then the low boundary is the
minimum value.</p>
<p>Otherwise, if the candidate low boundary is greater than the maximum value, then the low
boundary is the maximum value.</p>
<p>Otherwise, the low boundary is the candidate low boundary.</p>
</dd>
<dt>The <dfn data-x="concept-meter-high">high boundary</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-high">high</code> attribute is specified and a value could be
parsed out of it, then the candidate high boundary is that value. Otherwise, the candidate high
boundary is the same as the maximum value.</p>
<p>If the candidate high boundary is less than the low boundary, then the high boundary is the
low boundary.</p>
<p>Otherwise, if the candidate high boundary is greater than the maximum value, then the high
boundary is the maximum value.</p>
<p>Otherwise, the high boundary is the candidate high boundary.</p>
</dd>
<dt>The <dfn data-x="concept-meter-optimum">optimum point</dfn></dt>
<dd>
<p>If the <code data-x="attr-meter-optimum">optimum</code> attribute is specified and a value
could be parsed out of it, then the candidate optimum point is that value. Otherwise, the
candidate optimum point is the midpoint between the minimum value and the maximum value.</p>
<p>If the candidate optimum point is less than the minimum value, then the optimum point is the
minimum value.</p>
<p>Otherwise, if the candidate optimum point is greater than the maximum value, then the optimum
point is the maximum value.</p>
<p>Otherwise, the optimum point is the candidate optimum point.</p>
</dd>
</dl>
<p>All of which will result in the following inequalities all being true:</p>
<ul>
<li><p>minimum value ≤ actual value ≤ maximum value</p></li>
<li><p>minimum value ≤ low boundary ≤ high boundary ≤ maximum value</p></li>
<li><p>minimum value ≤ optimum point ≤ maximum value</p></li>
</ul>
<p><strong>UA requirements for regions of the gauge</strong>: If the optimum point is equal to the
low boundary or the high boundary, or anywhere in between them, then the region between the low
and high boundaries of the gauge must be treated as the optimum region, and the low and high
parts, if any, must be treated as suboptimal. Otherwise, if the optimum point is less than the low
boundary, then the region between the minimum value and the low boundary must be treated as the
optimum region, the region from the low boundary up to the high boundary must be treated as a
suboptimal region, and the remaining region must be treated as an even less good region. Finally,
if the optimum point is higher than the high boundary, then the situation is reversed; the region
between the high boundary and the maximum value must be treated as the optimum region, the region
from the high boundary down to the low boundary must be treated as a suboptimal region, and the
remaining region must be treated as an even less good region.</p>
<p><strong>UA requirements for showing the gauge</strong>: When representing a <code>meter</code>
element to the user, the UA should indicate the relative position of the actual value to the
minimum and maximum values, and the relationship between the actual value and the three regions of
the gauge.</p>
</div>
<div class="example">
<p>The following markup:</p>
<pre><code class="html"><h3>Suggested groups</h3>
<menu>
<li><a href="?cmd=hsg" onclick="hideSuggestedGroups()">Hide suggested groups</a></li>
</menu>
<ul>
<li>
<p><a href="/group/comp.infosystems.www.authoring.stylesheets/view">comp.infosystems.www.authoring.stylesheets</a> -
<a href="/group/comp.infosystems.www.authoring.stylesheets/subscribe">join</a></p>
<p>Group description: <strong>Layout/presentation on the WWW.</strong></p>
<p><strong><meter value="0.5">Moderate activity,</meter></strong> Usenet, 618 subscribers</p>
</li>
<li>
<p><a href="/group/netscape.public.mozilla.xpinstall/view">netscape.public.mozilla.xpinstall</a> -
<a href="/group/netscape.public.mozilla.xpinstall/subscribe">join</a></p>
<p>Group description: <strong>Mozilla XPInstall discussion.</strong></p>
<p><strong><meter value="0.25">Low activity,</meter></strong> Usenet, 22 subscribers</p>
</li>
<li>
<p><a href="/group/mozilla.dev.general/view">mozilla.dev.general</a> -
<a href="/group/mozilla.dev.general/subscribe">join</a></p>
<p><strong><meter value="0.25">Low activity,</meter></strong> Usenet, 66 subscribers</p>
</li>
</ul></code></pre>
<p>Might be rendered as follows:</p>
<p><img src="/images/sample-meter.png" width="332" height="178" alt="With the <meter> elements rendered as inline green bars of varying lengths."></p>
</div>
<p>User agents <span w-nodev>may</span> combine the value of the <code
data-x="attr-title">title</code> attribute and the other attributes to provide context-sensitive
help or inline text detailing the actual values.</p>
<div class="example">
<p>For example, the following snippet:</p>
<pre><code class="html"><meter min=0 max=60 value=23.2 title=seconds></meter></code></pre>
<p>...might cause the user agent to display a gauge with a tooltip
saying "Value: 23.2 out of 60." on one line and "seconds" on a
second line.</p>
</div>
<div w-nodev>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-value">value</code></dfn> IDL
attribute, on getting, must return the <span data-x="concept-meter-actual">actual value</span>. On
setting, the given value must be converted to the <span>best representation of the number as a
floating-point number</span> and then the <code data-x="attr-meter-value">value</code> content
attribute must be set to that string.</p>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-min">min</code></dfn> IDL
attribute, on getting, must return the <span data-x="concept-meter-minimum">minimum value</span>.
On setting, the given value must be converted to the <span>best representation of the number as a
floating-point number</span> and then the <code data-x="attr-meter-min">min</code> content
attribute must be set to that string.</p>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-max">max</code></dfn> IDL
attribute, on getting, must return the <span data-x="concept-meter-maximum">maximum value</span>.
On setting, the given value must be converted to the <span>best representation of the number as a
floating-point number</span> and then the <code data-x="attr-meter-max">max</code> content
attribute must be set to that string.</p>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-low">low</code></dfn> IDL
attribute, on getting, must return the <span data-x="concept-meter-low">low boundary</span>. On
setting, the given value must be converted to the <span>best representation of the number as a
floating-point number</span> and then the <code data-x="attr-meter-low">low</code> content
attribute must be set to that string.</p>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-high">high</code></dfn> IDL
attribute, on getting, must return the <span data-x="concept-meter-high">high boundary</span>. On
setting, the given value must be converted to the <span>best representation of the number as a
floating-point number</span> and then the <code data-x="attr-meter-high">high</code> content
attribute must be set to that string.</p>
<p>The <dfn attribute for="HTMLMeterElement"><code data-x="dom-meter-optimum">optimum</code></dfn>
IDL attribute, on getting, must return the <span data-x="concept-meter-optimum">optimum
value</span>. On setting, the given value must be converted to the <span>best representation of
the number as a floating-point number</span> and then the <code
data-x="attr-meter-optimum">optimum</code> content attribute must be set to that string.</p>
<p>The <code data-x="dom-lfe-labels">labels</code> IDL attribute provides a list of the element's
<code>label</code>s.</p>
</div>
<div class="example">
<p>The following example shows how a gauge could fall back to localized or pretty-printed
text.</p>
<pre><code class="html"><p>Disk usage: <meter min=0 value=170261928 max=233257824>170 261 928 bytes used
out of 233 257 824 bytes available</meter></p></code></pre>
</div>
<h4>The <dfn element><code>fieldset</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span data-x="category-listed">Listed</span> and <span data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting</span> <span>form-associated element</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Optionally a <code>legend</code> element, followed by <span>flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-fieldset-disabled">disabled</code></dd>
<dd><code data-x="attr-fae-form">form</code></dd>
<dd><code data-x="attr-fe-name">name</code> <!-- variant --> </dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-fieldset">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-fieldset">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLFieldSetElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-fieldset-disabled">disabled</span>;
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-fae-form">form</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-fe-name">name</span>;
readonly attribute DOMString <span data-x="dom-fieldset-type">type</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-fieldset-elements">elements</span>;
readonly attribute boolean <span data-x="dom-cva-willValidate">willValidate</span>;
[SameObject] readonly attribute <span>ValidityState</span> <span data-x="dom-cva-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-cva-validationMessage">validationMessage</span>;
boolean <span data-x="dom-cva-checkValidity">checkValidity</span>();
boolean <span data-x="dom-cva-reportValidity">reportValidity</span>();
undefined <span data-x="dom-cva-setCustomValidity">setCustomValidity</span>(DOMString error);
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLFieldSetElement</code>.</dd>
</dl>
<p>The <code>fieldset</code> element <span>represents</span> a set of form controls (or other
content) grouped together, optionally with a caption. The caption is given by the first
<code>legend</code> element that is a child of the <code>fieldset</code> element, if any. The
remainder of the descendants form the group.</p>
<p>The <dfn element-attr for="fieldset"><code
data-x="attr-fieldset-disabled">disabled</code></dfn> attribute, when specified, causes all the
form control descendants of the <code>fieldset</code> element, excluding those that are
descendants of the <code>fieldset</code> element's first <code>legend</code> element child, if
any, to be <span data-x="concept-fe-disabled">disabled</span>.</p>
<p>A <code>fieldset</code> element is a <dfn data-x="concept-fieldset-disabled">disabled
fieldset</dfn> if it matches any of the following conditions:</p>
<ul>
<li>Its <code data-x="attr-fieldset-disabled">disabled</code> attribute is specified
<li>It is a descendant of another <code>fieldset</code> element whose <code
data-x="attr-fieldset-disabled">disabled</code> attribute is specified, and is <em>not</em> a
descendant of that <code>fieldset</code> element's first <code>legend</code> element child, if
any.</li>
</ul>
<p>The <code data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<code>fieldset</code> element with its <span>form owner</span>. The <code
data-x="attr-fe-name">name</code> attribute represents the element's name.</p>
<dl class="domintro">
<dt><code data-x=""><var>fieldset</var>.<span subdfn data-x="dom-fieldset-type">type</span></code></dt>
<dd><p>Returns the string "fieldset".</p></dd>
<dt><code data-x=""><var>fieldset</var>.<span subdfn data-x="dom-fieldset-elements">elements</span></code></dt>
<dd><p>Returns an <code>HTMLCollection</code> of the form controls in the element.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLFieldSetElement"><code
data-x="dom-fieldset-disabled">disabled</code></dfn> IDL attribute must <span>reflect</span> the
content attribute of the same name.</p>
<p>The <dfn attribute for="HTMLFieldSetElement"><code data-x="dom-fieldset-type">type</code></dfn>
IDL attribute must return the string "<code data-x="">fieldset</code>".</p>
<p>The <dfn attribute for="HTMLFieldSetElement"><code
data-x="dom-fieldset-elements">elements</code></dfn> IDL attribute must return an
<code>HTMLCollection</code> rooted at the <code>fieldset</code> element, whose filter matches
<span data-x="category-listed">listed elements</span>.</p>
<p>The <code data-x="dom-cva-willValidate">willValidate</code>, <code
data-x="dom-cva-validity">validity</code>, and <code
data-x="dom-cva-validationMessage">validationMessage</code> attributes, and the <code
data-x="dom-cva-checkValidity">checkValidity()</code>, <code
data-x="dom-cva-reportValidity">reportValidity()</code>, and <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> methods, are part of the
<span>constraint validation API</span>. The <code data-x="dom-fae-form">form</code> and <code
data-x="dom-fe-name">name</code> IDL attributes are part of the element's forms API.</p>
</div>
<div class="example">
<p>This example shows a <code>fieldset</code> element being used to group a set of related
controls:</p>
<pre><code class="html"><fieldset>
<legend>Display</legend>
<p><label><input type=radio name=c value=0 checked> Black on White</label>
<p><label><input type=radio name=c value=1> White on Black</label>
<p><label><input type=checkbox name=g> Use grayscale</label>
<p><label>Enhance contrast <input type=range name=e list=contrast min=0 max=100 value=0 step=1></label>
<datalist id=contrast>
<option label=Normal value=0>
<option label=Maximum value=100>
</datalist>
</fieldset></code></pre>
</div>
<div class="example">
<p>The following snippet shows a fieldset with a checkbox in the legend that controls whether or
not the fieldset is enabled. The contents of the fieldset consist of two required text controls
and an optional year/month control.</p>
<pre><code class="html"><fieldset name="clubfields" disabled>
<legend> <label>
<input type=checkbox name=club onchange="form.clubfields.disabled = !checked">
Use Club Card
</label> </legend>
<p><label>Name on card: <input name=clubname required></label></p>
<p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p>
<p><label>Expiry date: <input name=clubexp type=month></label></p>
</fieldset></code></pre>
</div>
<div class="example">
<p>You can also nest <code>fieldset</code> elements. Here is an example expanding on the previous
one that does so:</p>
<pre><code class="html"><fieldset name="clubfields" disabled>
<legend> <label>
<input type=checkbox name=club onchange="form.clubfields.disabled = !checked">
Use Club Card
</label> </legend>
<p><label>Name on card: <input name=clubname required></label></p>
<fieldset name="numfields">
<legend> <label>
<input type=radio checked name=clubtype onchange="form.numfields.disabled = !checked">
My card has numbers on it
</label> </legend>
<p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p>
</fieldset>
<fieldset name="letfields" disabled>
<legend> <label>
<input type=radio name=clubtype onchange="form.letfields.disabled = !checked">
My card has letters on it
</label> </legend>
<p><label>Card code: <input name=clublet required pattern="[A-Za-z]+"></label></p>
</fieldset>
</fieldset></code></pre>
<p>In this example, if the outer "Use Club Card" checkbox is not checked, everything inside the
outer <code>fieldset</code>, including the two radio buttons in the legends of the two nested
<code>fieldset</code>s, will be disabled. However, if the checkbox is checked, then the radio
buttons will both be enabled and will let you select which of the two inner
<code>fieldset</code>s is to be enabled.</p>
</div>
<div class="example">
<p>This example shows a grouping of controls where the <code>legend</code> element both labels
the grouping, and the nested heading element surfaces the grouping in the document outline:</p>
<pre><code class="html"><fieldset>
<legend> <h2>
How can we best reach you?
</h2> </legend>
<p> <label>
<input type=radio checked name=contact_pref>
Phone
</label> </p>
<p> <label>
<input type=radio name=contact_pref>
Text
</label> </p>
<p> <label>
<input type=radio name=contact_pref>
Email
</label> </p>
</fieldset></code></pre>
</div>
<h4>The <dfn element><code>legend</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the <span>first child</span> of a <code>fieldset</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, optionally intermixed with <span>heading content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-legend">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-legend">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLLegendElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-legend-form">form</span>;
// <a href="#HTMLLegendElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLLegendElement</code>.</dd>
</dl>
<p>The <code>legend</code> element <span>represents</span> a caption for the rest of the contents
of the <code>legend</code> element's parent <code>fieldset</code> element<span w-nodev>, if
any</span>.</p>
<dl class="domintro">
<dt><code data-x=""><var>legend</var>.<span subdfn data-x="dom-legend-form">form</span></code></dt>
<dd><p>Returns the element's <code>form</code> element, if any, or null otherwise.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLLegendElement"><code data-x="dom-legend-form">form</code></dfn> IDL
attribute's behavior depends on whether the <code>legend</code> element is in a
<code>fieldset</code> element or not. If the <code>legend</code> has a <code>fieldset</code>
element as its parent, then the <code data-x="dom-legend-form">form</code> IDL attribute must
return the same value as the <code data-x="dom-fae-form">form</code> IDL attribute on that
<code>fieldset</code> element. Otherwise, it must return null.</p>
</div>
<h4 split-filename="form-control-infrastructure">Form control infrastructure</h4>
<h5>A form control's value</h5>
<p>Most form controls have a <dfn data-x="concept-fe-value">value</dfn> and a <dfn
data-x="concept-fe-checked">checkedness</dfn>. (The latter is only used by <code>input</code>
elements.) These are used to describe how the user interacts with the control.</p>
<p>A control's <span data-x="concept-fe-value">value</span> is its internal state. As such, it
might not match the user's current input.</p>
<p class="example">For instance, if a user enters the word "<kbd>three</kbd>" into <span
data-x="attr-input-type-number">a numeric field</span> that expects digits, the user's input would
be the string "three" but the control's <span data-x="concept-fe-value">value</span> would remain
unchanged. Or, if a user enters the email address "<kbd> awesome@example.com</kbd>"
(with leading whitespace) into <span data-x="attr-input-type-email">an email field</span>, the
user's input would be the string " awesome@example.com" but the browser's UI for
email fields might translate that into a <span data-x="concept-fe-value">value</span> of "<code
data-x="">awesome@example.com</code>" (without the leading whitespace).</p>
<p id="concept-input-value-dirty-flag"><span id="concept-textarea-dirty"></span><code>input</code>
and <code>textarea</code> elements have a <dfn data-x="concept-fe-dirty">dirty value flag</dfn>.
This is used to track the interaction between the <span data-x="concept-fe-value">value</span> and
default value. If it is false, <span data-x="concept-fe-value">value</span> mirrors the default
value. If it is true, the default value is ignored.</p>
<p><code>input</code>, <code>textarea</code>, and <code>select</code> elements have a
<dfn>user validity</dfn> boolean. It is initially set to false.</p>
<p>To define the behavior of constraint validation in the face of the <code>input</code>
element's <code data-x="attr-input-multiple">multiple</code> attribute, <code>input</code> elements
can also have separately defined <dfn data-x="concept-fe-values">value<em>s</em></dfn>.</p>
<p>To define the behavior of the <code data-x="attr-fe-maxlength">maxlength</code> and <code
data-x="attr-fe-minlength">minlength</code> attributes, as well as other APIs specific to the
<code>textarea</code> element, all form control with a <span
data-x="concept-fe-value">value</span> also have an algorithm for obtaining an <span
id="concept-textarea-api-value"></span><dfn data-x="concept-fe-api-value">API value</dfn>. By
default this algorithm is to simply return the control's <span
data-x="concept-fe-value">value</span>.</p>
<p>The <code>select</code> element does not have a <span data-x="concept-fe-value">value</span>;
the <span data-x="concept-option-selectedness">selectedness</span> of its <code>option</code>
elements is what is used instead.</p>
<h5>Mutability</h5>
<p>A form control can be designated as <dfn data-x="concept-fe-mutable"><i>mutable</i></dfn>.</p>
<p class="note">This determines (by means of definitions and requirements in this specification
that rely on whether an element is so designated) whether or not the user can modify the <span
data-x="concept-fe-value">value</span> or <span data-x="concept-fe-checked">checkedness</span> of a
form control, or whether or not a control can be automatically prefilled.</p>
<!-- or the concept-option-selectedness, or the concept-fe-values... -->
<h5>Association of controls and forms</h5>
<p>A <span>form-associated element</span> can have a relationship with a <code>form</code>
element, which is called the element's <dfn export
for="button,fieldset,input,object,output,select,textarea,img,form-associated custom element">form
owner</dfn>. If a <span>form-associated element</span> is not associated with a <code>form</code>
element, its <span>form owner</span> is said to be null.</p>
<p>A <span>form-associated element</span> has an associated <dfn>parser inserted flag</dfn>.</p>
<p>A <span>form-associated element</span> is, by default, associated with its <span
w-nodev>nearest</span> ancestor <code>form</code> element<span w-nodev> (as described
below)</span>, but, if it is <span data-x="category-listed">listed</span>, may have a <dfn
element-attr for="button,fieldset,input,object,output,select,textarea"><code
data-x="attr-fae-form">form</code></dfn> attribute specified to override this.</p>
<p class="note">This feature allows authors to work around the lack of support for nested
<code>form</code> elements.</p>
<p>If a <span data-x="category-listed">listed</span> <span>form-associated element</span> has a
<code data-x="attr-fae-form">form</code> attribute specified, then that attribute's value must be
the <span data-x="concept-id">ID</span> of a <code>form</code> element in the element's
<span>tree</span>.</p>
<div w-nodev>
<p class="note">The rules in this section are complicated by the fact that although conforming
documents or <span data-x="tree">trees</span> will never contain nested <code>form</code>
elements, it is quite possible (e.g., using a script that performs DOM manipulation) to generate
<span data-x="tree">trees</span> that have such nested elements. They are also complicated by
rules in the HTML parser that, for historical reasons, can result in a <span>form-associated
element</span> being associated with a <code>form</code> element that is not its ancestor.</p>
<p>When a <span>form-associated element</span> is created, its <span>form owner</span> must be
initialized to null (no owner).</p>
<p>When a <span>form-associated element</span> is to be <dfn
data-x="concept-form-association">associated</dfn> with a form, its <span>form owner</span> must
be set to that form.</p>
<p>When a <span data-x="category-listed">listed</span> <span>form-associated element</span>'s
<code data-x="attr-fae-form">form</code> attribute is set, changed, or removed, then the user
agent must <span>reset the form owner</span> of that element.</p>
<p>When a <span data-x="category-listed">listed</span> <span>form-associated element</span> has a
<code data-x="attr-fae-form">form</code> attribute and the <span data-x="concept-id">ID</span> of
any of the elements in the <span>tree</span> changes, then the user agent must <span>reset the
form owner</span> of that <span>form-associated element</span>.</p>
<p>When a <span data-x="category-listed">listed</span> <span>form-associated element</span> has a
<code data-x="attr-fae-form">form</code> attribute and an element with an <span
data-x="concept-id">ID</span> is <span data-x="node is inserted into a document">inserted
into</span> or <span data-x="node is removed from a document">removed from</span> the
<code>Document</code>, or its <span>HTML element moving steps</span> are run, then the user agent
must <span>reset the form owner</span> of that <span>form-associated element</span>.</p>
<p class="note">The form owner is also reset by the <span>HTML element insertion steps</span>,
<span>HTML element removing steps</span>, and <span>HTML element moving steps</span>.</p>
<p>To <dfn>reset the form owner</dfn> of a <span>form-associated element</span>
<var>element</var>:</p>
<ol>
<li><p>Unset <var>element</var>'s <span>parser inserted flag</span>.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>element</var>'s <span>form owner</span> is not null;</p></li>
<li><p><var>element</var> is not <span data-x="category-listed">listed</span> or its <code
data-x="attr-fae-form">form</code> content attribute is not present; and</p></li>
<li><p><var>element</var>'s <span>form owner</span> is its nearest <code>form</code> element
ancestor after the change to the ancestor chain,</p></li>
</ul>
<p>then return.</p>
</li>
<li><p>Set <var>element</var>'s <span>form owner</span> to null.</p></li>
<li>
<p>If <var>element</var> is <span data-x="category-listed">listed</span>, has a <code
data-x="attr-fae-form">form</code> content attribute, and is <span>connected</span>, then:</p>
<ol>
<li><p>If the first element in <var>element</var>'s <span>tree</span>, in <span>tree
order</span>, to have an <span data-x="concept-id">ID</span> that is <span>identical to</span>
<var>element</var>'s <code data-x="attr-fae-form">form</code> content attribute's value, is a
<code>form</code> element, then <span data-x="concept-form-association">associate</span> the
<var>element</var> with that <code>form</code> element.</p></li>
<!-- note that this ignores the name="" attribute and is unaffected by quirks mode (it's always
case sensitive) -->
</ol>
</li>
<li><p>Otherwise, if <var>element</var> has an ancestor <code>form</code> element, then <span
data-x="concept-form-association">associate</span> <var>element</var> with the nearest such
ancestor <code>form</code> element.</p></li>
</ol>
<div class="example">
<p>In the following non-conforming snippet</p>
<pre class="bad"><code class="html">...
<form id="a">
<div id="b"></div>
</form>
<script>
document.getElementById('b').innerHTML =
'<table><tr><td></form><form id="c"><input id="d"></table>' +
'<input id="e">';
</script>
...</code></pre>
<p>the <span>form owner</span> of "d" would be the inner nested form "c", while the <span>form
owner</span> of "e" would be the outer form "a".</p>
<p>This happens as follows: First, the "e" node gets associated with "c" in the <span>HTML
parser</span>. Then, the <code data-x="dom-element-innerHTML">innerHTML</code> algorithm moves the nodes
from the temporary document to the "b" element. At this point, the nodes see their ancestor chain
change, and thus all the "magic" associations done by the parser are reset to normal ancestor
associations.</p>
<p>This example is a non-conforming document, though, as it is a violation of the content models
to nest <code>form</code> elements, and there is a <span>parse error</span> for the <code
data-x=""></form></code> tag.</p>
</div>
</div>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-fae-form">form</span></code></dt>
<dd>
<p>Returns the element's <span>form owner</span>.</p>
<p>Returns null if there isn't one.</p>
</dd>
</dl>
<div w-nodev>
<p><span data-x="category-listed">Listed</span> <span data-x="form-associated
element">form-associated elements</span> except for <span data-x="form-associated custom
element">form-associated custom elements</span> have a <dfn attribute
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-fae-form">form</code></dfn> IDL attribute, which, on getting, must return the
element's <span>form owner</span>, or null if there isn't one.</p>
<p><span data-x="form-associated custom element">Form-associated custom elements</span> don't have
<code data-x="dom-fae-form">form</code> IDL attribute. Instead, their
<code>ElementInternals</code> object has a <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-form">form</code></dfn> IDL attribute. On getting, it must throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code> if the <span
data-x="internals-target">target element</span> is not a <span>form-associated custom
element</span>. Otherwise, it must return the element's <span>form owner</span>, or null if there
isn't one.</p>
</div>
<h4>Attributes common to form controls</h4>
<h5>Naming form controls: the <code data-x="attr-fe-name">name</code> attribute</h5>
<p>The <dfn element-attr for="button,fieldset,input,output,select,textarea"><code
data-x="attr-fe-name">name</code></dfn> content attribute gives the name of the form control, as
used in <span>form submission</span> and in the <code>form</code> element's <code
data-x="dom-form-elements">elements</code> object. If the attribute is specified, its value must
not be the empty string or <code data-x="">isindex</code>.</p>
<p class="note">A number of user agents historically implemented special support for first-in-form
text controls with the name <code data-x="">isindex</code>, and this specification previously
defined related user agent requirements for it. However, some user agents subsequently dropped
that special support, and the related requirements were removed from this specification. So, to
avoid problematic reinterpretations in legacy user agents, the name <code data-x="">isindex</code>
is no longer allowed.</p>
<p>Other than <code data-x="">isindex</code>, any non-empty value for <code
data-x="attr-form-name">name</code> is allowed. An <span>ASCII case-insensitive</span> match for
the name <dfn><code data-x="attr-fe-name-charset">_charset_</code></dfn> is special: if used as
the name of a <span data-x="attr-input-type-hidden">Hidden</span> control with no <code
data-x="attr-input-value">value</code> attribute, then during submission the <code
data-x="attr-input-value">value</code> attribute is automatically given a value consisting of the
submission character encoding.</p>
<div w-nodev>
<p>The <dfn attribute
for="HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-fe-name">name</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-fe-name">name</code> content attribute.</p>
</div>
<div class="note">
<p>DOM clobbering is a common cause of security issues. Avoid using the names of
built-in form properties with the <code data-x="attr-fe-name">name</code> content attribute.</p>
<p>In this example, the <code>input</code> element overrides the built-in <code
data-x="attr-fs-method">method</code> property:</p>
<pre><code class="js">let form = document.createElement("form");
let input = document.createElement("input");
form.appendChild(input);
form.method; // => "get"
input.name = "method"; // DOM clobbering occurs here
form.method === input; // => true</code></pre>
<p>Since the input name takes precedence over built-in form properties, the JavaScript reference
<code data-x="">form.method</code> will point to the <code>input</code> element named "method"
instead of the built-in <code data-x="attr-fs-method">method</code> property.</p>
</div>
<h5>Submitting element directionality: the <code data-x="attr-fe-dirname">dirname</code> attribute</h5>
<p>The <dfn element-attr for="input,textarea"><code data-x="attr-fe-dirname">dirname</code></dfn>
attribute on a form control element enables the submission of <span>the directionality</span> of
the element, and gives the name of the control that contains this value during <span>form
submission</span>. If such an attribute is specified, its value must not be the empty string.</p>
<div class="example">
<p>In this example, a form contains a text control and a submission button:</p>
<pre><code class="html"><form action="addcomment.cgi" method=post>
<p><label>Comment: <input type=text name="comment" dirname="comment.dir" required></label></p>
<p><button name="mode" type=submit value="add">Post Comment</button></p>
</form></code></pre>
<p>When the user submits the form, the user agent includes three fields, one called "comment",
one called "comment.dir", and one called "mode"; so if the user types "Hello", the submission
body might be something like:</p>
<pre>comment=Hello&<strong>comment.dir=ltr</strong>&mode=add</pre>
<p>If the user manually switches to a right-to-left writing direction and enters "<span data-x=""
dir=rtl lang=ar>مرحبا</span>", the submission body might be
something like:</p>
<pre>comment=%D9%85%D8%B1%D8%AD%D8%A8%D8%A7&<strong>comment.dir=rtl</strong>&mode=add</pre>
</div>
<h5>Limiting user input length: the <code data-x="attr-fe-maxlength">maxlength</code> attribute</h5>
<p>A <dfn data-lt="maxlength" element-attr for="input,textarea" data-x="attr-fe-maxlength">form
control <code data-x="">maxlength</code> attribute</dfn>, controlled by the <span
data-x="concept-fe-dirty">dirty value flag</span>, declares a limit on the number of characters a
user can input. The number of characters is measured using <span>length</span> and, in the case
of <code>textarea</code> elements, with all newlines normalized to a single character (as opposed
to CRLF pairs).</p>
<p>If an element has its <span data-x="attr-fe-maxlength">form control <code
data-x="">maxlength</code> attribute</span> specified, the attribute's value must be a <span>valid
non-negative integer</span>. If the attribute is specified and applying the <span>rules for
parsing non-negative integers</span> to its value results in a number, then that number is the
element's <dfn>maximum allowed value length</dfn>. If the attribute is omitted or parsing its
value results in an error, then there is no <span>maximum allowed value length</span>.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If an element has a <span>maximum allowed value
length</span>, its <span data-x="concept-fe-dirty">dirty value flag</span> is true, its <span
data-x="concept-fe-value">value</span> was last changed by a user edit (as opposed to a change
made by a script), and the <span>length</span> of the element's <span
data-x="concept-fe-api-value">API value</span> is greater than the element's <span>maximum allowed
value length</span>, then the element is <span>suffering from being too long</span>.</p>
<p>User agents may prevent the user from causing the element's <span
data-x="concept-fe-api-value">API value</span> to be set to a value whose <span>length</span> is
greater than the element's <span>maximum allowed value length</span>.</p>
<p class="note">In the case of <code>textarea</code> elements, the <span
data-x="concept-fe-api-value">API value</span> and <span data-x="concept-fe-value">value</span>
differ. In particular, <span data-x="normalize newlines">newline normalization</span> is applied
before the <span>maximum allowed value length</span> is checked (whereas the <span>textarea
wrapping transformation</span> is not applied).</p>
</div>
<h5>Setting minimum input length requirements: the <code data-x="attr-fe-minlength">minlength</code> attribute</h5>
<p>A <dfn data-lt="minlength" element-attr for="input,textarea" data-x="attr-fe-minlength">form
control <code data-x="">minlength</code> attribute</dfn>, controlled by the <span
data-x="concept-fe-dirty">dirty value flag</span>, declares a lower bound on the number of
characters a user can input. The "number of characters" is measured using <span>length</span> and,
in the case of <code>textarea</code> elements, with all newlines normalized to a single character
(as opposed to CRLF pairs).</p>
<p class="note">The <code data-x="attr-fe-minlength">minlength</code> attribute does not imply the
<code data-x="">required</code> attribute. If the form control has no <code
data-x="">required</code> attribute, then the value can still be omitted; the <code
data-x="attr-fe-minlength">minlength</code> attribute only kicks in once the user has entered a
value at all. If the empty string is not allowed, then the <code data-x="">required</code>
attribute also needs to be set.</p>
<p>If an element has its <span data-x="attr-fe-minlength">form control <code
data-x="">minlength</code> attribute</span> specified, the attribute's value must be a <span>valid
non-negative integer</span>. If the attribute is specified and applying the <span>rules for
parsing non-negative integers</span> to its value results in a number, then that number is the
element's <dfn>minimum allowed value length</dfn>. If the attribute is omitted or parsing its
value results in an error, then there is no <span>minimum allowed value length</span>.</p>
<p>If an element has both a <span>maximum allowed value length</span> and a <span>minimum allowed
value length</span>, the <span>minimum allowed value length</span> must be smaller than or equal
to the <span>maximum allowed value length</span>.</p>
<div w-nodev>
<p><strong>Constraint validation</strong>: If an element has a <span>minimum allowed value
length</span>, its <span data-x="concept-fe-dirty">dirty value flag</span> is true, its <span
data-x="concept-fe-value">value</span> was last changed by a user edit (as opposed to a change
made by a script), its <span data-x="concept-fe-value">value</span> is not the empty string, and
the <span>length</span> of the element's <span data-x="concept-fe-api-value">API value</span> is
less than the element's <span>minimum allowed value length</span>, then the element is
<span>suffering from being too short</span>.</p>
</div>
<div class="example">
<p>In this example, there are four text controls. The first is required, and has to be at least 5
characters long. The other three are optional, but if the user fills one in, the user has to
enter at least 10 characters.</p>
<pre><code class="html"><form action="/events/menu.cgi" method="post">
<p><label>Name of Event: <input required minlength=5 maxlength=50 name=event></label></p>
<p><label>Describe what you would like for breakfast, if anything:
<textarea name="breakfast" minlength="10"></textarea></label></p>
<p><label>Describe what you would like for lunch, if anything:
<textarea name="lunch" minlength="10"></textarea></label></p>
<p><label>Describe what you would like for dinner, if anything:
<textarea name="dinner" minlength="10"></textarea></label></p>
<p><input type=submit value="Submit Request"></p>
</form></code></pre>
</div>
<h5>Enabling and disabling form controls: the <code data-x="attr-fe-disabled">disabled</code> attribute</h5>
<p>The <dfn element-attr for="button,fieldset,input,object,output,select,textarea"><code
data-x="attr-fe-disabled">disabled</code></dfn> content attribute is a <span>boolean
attribute</span>.</p>
<p class="note">The <code data-x="attr-option-disabled">disabled</code> attribute for
<code>option</code> elements and the <code data-x="attr-optgroup-disabled">disabled</code>
attribute for <code>optgroup</code> elements are defined separately.</p>
<p>A form control is <dfn data-x="concept-fe-disabled">disabled</dfn> if any of the following are
true:</p>
<ul>
<li><p>the element is a <code>button</code>, <code>input</code>, <code>select</code>,
<code>textarea</code>, or <span>form-associated custom element</span>, and the <code
data-x="attr-fe-disabled">disabled</code> attribute is specified on this element (regardless of
its value); or</p></li>
<li><p>the element is a descendant of a <code>fieldset</code> element whose <code
data-x="attr-fieldset-disabled">disabled</code> attribute is specified, and is <em>not</em> a
descendant of that <code>fieldset</code> element's first <code>legend</code> element child, if
any.</p></li>
</ul>
<div w-nodev>
<p>A form control that is <span data-x="concept-fe-disabled">disabled</span> must prevent any <code
data-x="event-click">click</code> events that are <span data-x="queue a task">queued</span> on the
<span>user interaction task source</span> from being dispatched on the element.</p>
<p><strong>Constraint validation</strong>: If an element is <span
data-x="concept-fe-disabled">disabled</span>, it is <span>barred from constraint
validation</span>.</p>
<p>The <dfn attribute
for="HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement"><code
data-x="dom-fe-disabled">disabled</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-fe-disabled">disabled</code> content attribute.</p>
</div>
<h5>Form submission attributes</h5>
<p><dfn>Attributes for form submission</dfn> can be specified both on <code>form</code> elements
and on <span data-x="concept-submit-button">submit buttons</span> (elements that represent buttons
that submit forms, e.g. an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-submit">Submit Button</span> state).
<p>The <span>attributes for form submission</span> that may be specified on <code>form</code>
elements are <code data-x="attr-fs-action">action</code>, <code
data-x="attr-fs-enctype">enctype</code>, <code data-x="attr-fs-method">method</code>, <code
data-x="attr-fs-novalidate">novalidate</code>, and <code data-x="attr-fs-target">target</code>.</p>
<p>The corresponding <span>attributes for form submission</span> that may be specified on <span
data-x="concept-submit-button">submit buttons</span> are <code
data-x="attr-fs-formaction">formaction</code>, <code
data-x="attr-fs-formenctype">formenctype</code>, <code
data-x="attr-fs-formmethod">formmethod</code>, <code
data-x="attr-fs-formnovalidate">formnovalidate</code>, and <code
data-x="attr-fs-formtarget">formtarget</code>. When omitted, they default to the values given on
the corresponding attributes on the <code>form</code> element.</p>
<hr>
<p>The <dfn element-attr for="form,button"><code data-x="attr-fs-action">action</code></dfn> and
<dfn element-attr for="form,button"><code data-x="attr-fs-formaction">formaction</code></dfn>
content attributes, if specified, must have a value that is a <span>valid non-empty URL
potentially surrounded by spaces</span>.</p>
<p>The <dfn data-x="concept-fs-action">action</dfn> of an element is the value of the element's
<code data-x="attr-fs-formaction">formaction</code> attribute, if the element is a <span
data-x="concept-submit-button">submit button</span> and has such an attribute, or the value of its
<span>form owner</span>'s <code data-x="attr-fs-action">action</code> attribute, if <em>it</em> has
one, or else the empty string.</p>
<hr>
<p>The <dfn element-attr for="form,button"><code data-x="attr-fs-method">method</code></dfn> and
<dfn element-attr for="form,button"><code data-x="attr-fs-formmethod">formmethod</code></dfn>
content attributes are <span data-x="enumerated attribute">enumerated attributes</span> with the
following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="form/method,button/formmethod,input/formmethod"><code
data-x="attr-fs-method-GET-keyword">get</code></dfn>
<td><dfn data-x="attr-fs-method-GET">GET</dfn>
<td>Indicates the <code>form</code> will use the HTTP GET method.
<tr>
<td><dfn attr-value for="form/method,button/formmethod,input/formmethod"><code
data-x="attr-fs-method-POST-keyword">post</code></dfn>
<td><dfn data-x="attr-fs-method-POST">POST</dfn>
<td>Indicates the <code>form</code> will use the HTTP POST method.
<tr>
<td><dfn attr-value for="form/method,button/formmethod,input/formmethod"><code
data-x="attr-fs-method-dialog-keyword">dialog</code></dfn>
<td><dfn data-x="attr-fs-method-dialog">Dialog</dfn>
<td>Indicates the <code>form</code> is intended to close the <code>dialog</code> box in which
the form finds itself, if any, and otherwise not submit.
</table>
<p>The <code data-x="attr-fs-method">method</code> attribute's <i data-x="missing value
default">missing value default</i> and <i data-x="invalid value default">invalid value default</i>
are both the <span data-x="attr-fs-method-GET">GET</span> state.</p>
<p>The <code data-x="attr-fs-formmethod">formmethod</code> attribute has no <i data-x="missing
value default">missing value default</i>, and its <i data-x="invalid value default">invalid value
default</i> is the <span data-x="attr-fs-method-GET">GET</span> state.</p>
<p>The <dfn data-x="concept-fs-method">method</dfn> of an element is one of those states. If the
element is a <span data-x="concept-submit-button">submit button</span> and has a <code
data-x="attr-fs-formmethod">formmethod</code> attribute, then the element's <span
data-x="concept-fs-method">method</span> is that attribute's state; otherwise, it is the <span>form
owner</span>'s <code data-x="attr-fs-method">method</code> attribute's state.</p>
<div class="example">
<p>Here the <code data-x="attr-fs-method">method</code> attribute is used to explicitly specify
the default value, "<code data-x="attr-fs-method-GET-keyword">get</code>", so that the search
query is submitted in the URL:</p>
<pre><code class="html"><form method="get" action="/search.cgi">
<p><label>Search terms: <input type=search name=q></label></p>
<p><input type=submit></p>
</form></code></pre>
</div>
<div class="example">
<p>On the other hand, here the <code data-x="attr-fs-method">method</code> attribute is used to
specify the value "<code data-x="attr-fs-method-POST-keyword">post</code>", so that the user's
message is submitted in the HTTP request's body:</p>
<pre><code class="html"><form method="post" action="/post-message.cgi">
<p><label>Message: <input type=text name=m></label></p>
<p><input type=submit value="Submit message"></p>
</form></code></pre>
</div>
<div class="example">
<p>In this example, a <code>form</code> is used with a <code>dialog</code>. The <code
data-x="attr-fs-method">method</code> attribute's "<code
data-x="attr-fs-method-dialog-keyword">dialog</code>" keyword is used to have the dialog
automatically close when the form is submitted.</p>
<pre lang="en-GB"><code class="html"><dialog id="ship">
<form method=dialog>
<p>A ship has arrived in the harbour.</p>
<button type=submit value="board">Board the ship</button>
<button type=submit value="call">Call to the captain</button>
</form>
</dialog>
<script>
var ship = document.getElementById('ship');
ship.showModal();
ship.onclose = function (event) {
if (ship.returnValue == 'board') {
// ...
} else {
// ...
}
};
</script></code></pre>
</div>
<hr>
<p>The <dfn element-attr for="form,button"><code data-x="attr-fs-enctype">enctype</code></dfn> and
<dfn element-attr for="form,button"><code data-x="attr-fs-formenctype">formenctype</code></dfn>
content attributes are <span data-x="enumerated attribute">enumerated attributes</span> with the
following keywords and states:</p>
<ul>
<li>The "<dfn attr-value for="form/enctype,button/enctype"><code
data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code></dfn>" keyword and
corresponding state.</li>
<li>The "<dfn attr-value for="form/enctype,button/enctype"><code
data-x="attr-fs-enctype-formdata">multipart/form-data</code></dfn>" keyword and corresponding
state.</li>
<li>The "<dfn attr-value for="form/enctype,button/enctype"><code
data-x="attr-fs-enctype-text">text/plain</code></dfn>" keyword and corresponding state.</li>
</ul>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <code
data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code> state.</p>
<p>The <code data-x="attr-fs-formenctype">formenctype</code> attribute has no <i data-x="missing
value default">missing value default</i>, and its <i data-x="invalid value default">invalid value
default</i> is the <code
data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code> state.</p>
<p>The <dfn data-x="concept-fs-enctype">enctype</dfn> of an element is one of those three states.
If the element is a <span data-x="concept-submit-button">submit button</span> and has a <code
data-x="attr-fs-formenctype">formenctype</code> attribute, then the element's <span
data-x="concept-fs-enctype">enctype</span> is that attribute's state; otherwise, it is the
<span>form owner</span>'s <code data-x="attr-fs-enctype">enctype</code> attribute's state.</p>
<hr>
<p>The <dfn element-attr for="form,button"><code data-x="attr-fs-target">target</code></dfn> and
<dfn element-attr for="form,button"><code data-x="attr-fs-formtarget">formtarget</code></dfn>
content attributes, if specified, must have values that are <span data-x="valid navigable target
name or keyword">valid navigable target names or keywords</span>.</p>
<hr>
<p>The <dfn element-attr for="form,button"><code
data-x="attr-fs-novalidate">novalidate</code></dfn> and <dfn element-attr for="form,button"><code
data-x="attr-fs-formnovalidate">formnovalidate</code></dfn> content attributes are <span
data-x="boolean attribute">boolean attributes</span>. If present, they indicate that the form is
not to be validated during submission.</p>
<p>The <dfn data-x="concept-fs-novalidate">no-validate state</dfn> of an element is true if the
element is a <span data-x="concept-submit-button">submit button</span> and the element's <code
data-x="attr-fs-formnovalidate">formnovalidate</code> attribute is present, or if the element's
<span>form owner</span>'s <code data-x="attr-fs-novalidate">novalidate</code> attribute is present,
and false otherwise.</p>
<div class="example">
<p>This attribute is useful to include "save" buttons on forms that have validation constraints,
to allow users to save their progress even though they haven't fully entered the data in the
form. The following example shows a simple form that has two required fields. There are three
buttons: one to submit the form, which requires both fields to be filled in; one to save the form
so that the user can come back and fill it in later; and one to cancel the form altogether.</p>
<pre><code class="html"><form action="editor.cgi" method="post">
<p><label>Name: <input required name=fn></label></p>
<p><label>Essay: <textarea required name=essay></textarea></label></p>
<p><input type=submit name=submit value="Submit essay"></p>
<p><input type=submit formnovalidate name=save value="Save essay"></p>
<p><input type=submit formnovalidate name=cancel value="Cancel"></p>
</form></code></pre>
</div>
<div w-nodev>
<hr>
<p>The <dfn attribute for="HTMLFormElement"><code data-x="dom-fs-action">action</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name, except that on
getting, when the content attribute is missing or its value is the empty string, the element's
<span>node document</span>'s <span data-x="concept-document-url">URL</span> must be returned
instead. The <dfn attribute for="HTMLFormElement"><code data-x="dom-fs-target">target</code></dfn>
IDL attribute must <span>reflect</span> the content attribute of the same name. The <dfn attribute
for="HTMLFormElement"><code data-x="dom-fs-method">method</code></dfn> and <dfn attribute
for="HTMLFormElement"><code data-x="dom-fs-enctype">enctype</code></dfn> IDL attributes must
<span>reflect</span> the respective content attributes of the same name, <span>limited to only
known values</span>. The <dfn attribute for="HTMLFormElement"><code
data-x="dom-fs-encoding">encoding</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-fs-enctype">enctype</code> content attribute, <span>limited to only known
values</span>. The <dfn attribute for="HTMLFormElement"><code
data-x="dom-fs-noValidate">noValidate</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-fs-novalidate">novalidate</code> content attribute. The <dfn attribute
for="HTMLButtonElement,HTMLInputElement"><code data-x="dom-fs-formAction">formAction</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-fs-formaction">formaction</code>
content attribute, except that on getting, when the content attribute is missing or its value is
the empty string, the element's <span>node document</span>'s <span
data-x="concept-document-url">URL</span> must be returned instead. The <dfn attribute
for="HTMLButtonElement,HTMLInputElement"><code
data-x="dom-fs-formEnctype">formEnctype</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-fs-formenctype">formenctype</code> content attribute, <span>limited to only
known values</span>. The <dfn attribute for="HTMLButtonElement,HTMLInputElement"><code
data-x="dom-fs-formMethod">formMethod</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-fs-formmethod">formmethod</code> content attribute, <span>limited to only known
values</span>. The <dfn attribute for="HTMLButtonElement,HTMLInputElement"><code
data-x="dom-fs-formNoValidate">formNoValidate</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-fs-formnovalidate">formnovalidate</code> content attribute. The <dfn
attribute for="HTMLButtonElement,HTMLInputElement"><code data-x="dom-fs-formTarget">formTarget</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-fs-formtarget">formtarget</code>
content attribute.
</div>
<h5>Autofill</h5>
<h6>Autofilling form controls: the <code data-x="attr-fe-autocomplete">autocomplete</code> attribute</h6>
<p>User agents sometimes have features for helping users fill forms in, for example prefilling the
user's address based on earlier user input. The <dfn element-attr
for="button,fieldset,input,object,output,select,textarea"><code
data-x="attr-fe-autocomplete">autocomplete</code></dfn> content attribute can be used to hint to
the user agent how to, or indeed whether to, provide such a feature.</p>
<!-- "mode" is already used by enumerated attributes... "role" is used by role=""... "mantle" it is. -->
<p>There are two ways this attribute is used. When wearing the <dfn>autofill expectation
mantle</dfn>, the <code data-x="attr-fe-autocomplete">autocomplete</code> attribute describes what
input is expected from users. When wearing the <dfn>autofill anchor mantle</dfn>, the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute describes the meaning of the given
value.</p>
<p>On an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is
in the <span data-x="attr-input-type-hidden">Hidden</span> state, the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute wears the <span>autofill anchor
mantle</span>. In all other cases, it wears the <span>autofill expectation mantle</span>.</p>
<p>When wearing the <span>autofill expectation mantle</span>, the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute, if specified, must have a value that
is an ordered <span>set of space-separated tokens</span> consisting of either a single token that
is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="attr-fe-autocomplete-off">off</code>", or a single token that is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="attr-fe-autocomplete-on">on</code>",
or <span>autofill detail tokens</span>.</p>
<p>When wearing the <span>autofill anchor
mantle</span>, the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute, if specified, must have a value that is an ordered <span>set of
space-separated tokens</span> consisting of just <span>autofill detail tokens</span> (i.e. the
"<code data-x="attr-fe-autocomplete-on">on</code>" and "<code
data-x="attr-fe-autocomplete-off">off</code>" keywords are not allowed).</p>
<p><dfn>Autofill detail tokens</dfn> are the following, in the order given below:</p>
<ol>
<li>
<p>Optionally, a token whose first eight characters are an <span>ASCII case-insensitive</span>
match for the string "<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-section">section-</code></dfn>", meaning that the field belongs to
the named group.</p>
<div class="example">
<p>For example, if there are two shipping addresses in the form, then they could be marked up
as:</p>
<pre><code class="html"><fieldset>
<legend>Ship the blue gift to...</legend>
<p> <label> Address: <textarea name=ba autocomplete="section-blue shipping street-address"></textarea> </label>
<p> <label> City: <input name=bc autocomplete="section-blue shipping address-level2"> </label>
<p> <label> Postal Code: <input name=bp autocomplete="section-blue shipping postal-code"> </label>
</fieldset>
<fieldset>
<legend>Ship the red gift to...</legend>
<p> <label> Address: <textarea name=ra autocomplete="section-red shipping street-address"></textarea> </label>
<p> <label> City: <input name=rc autocomplete="section-red shipping address-level2"> </label>
<p> <label> Postal Code: <input name=rp autocomplete="section-red shipping postal-code"> </label>
</fieldset></code></pre>
</div>
</li>
<li>
<p>Optionally, a token that is an <span>ASCII case-insensitive</span> match for one of the
following strings:</p>
<ul class="brief">
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-shipping">shipping</code></dfn>", meaning the field is part of the
shipping address or contact information
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-billing">billing</code></dfn>", meaning the field is part of the
billing address or contact information
</ul>
</li>
<li>
<p>Either of the following two options:</p>
<ul>
<li>
<p>A token that is an <span>ASCII case-insensitive</span> match for one of the following
<span>autofill field</span> names, excluding those that are <span>inappropriate for the
control</span>:</p>
<ul class="brief">
<li>"<code data-x="attr-fe-autocomplete-name">name</code>"
<li>"<code data-x="attr-fe-autocomplete-honorific-prefix">honorific-prefix</code>"
<li>"<code data-x="attr-fe-autocomplete-given-name">given-name</code>"
<li>"<code data-x="attr-fe-autocomplete-additional-name">additional-name</code>"
<li>"<code data-x="attr-fe-autocomplete-family-name">family-name</code>"
<li>"<code data-x="attr-fe-autocomplete-honorific-suffix">honorific-suffix</code>"
<li>"<code data-x="attr-fe-autocomplete-nickname">nickname</code>"
<li>"<code data-x="attr-fe-autocomplete-username">username</code>"
<li>"<code data-x="attr-fe-autocomplete-new-password">new-password</code>"
<li>"<code data-x="attr-fe-autocomplete-current-password">current-password</code>"
<li>"<code data-x="attr-fe-autocomplete-one-time-code">one-time-code</code>"
<li>"<code data-x="attr-fe-autocomplete-organization-title">organization-title</code>"
<li>"<code data-x="attr-fe-autocomplete-organization">organization</code>"
<li>"<code data-x="attr-fe-autocomplete-street-address">street-address</code>"
<li>"<code data-x="attr-fe-autocomplete-address-line1">address-line1</code>"
<li>"<code data-x="attr-fe-autocomplete-address-line2">address-line2</code>"
<li>"<code data-x="attr-fe-autocomplete-address-line3">address-line3</code>"
<li>"<code data-x="attr-fe-autocomplete-address-level4">address-level4</code>"
<li>"<code data-x="attr-fe-autocomplete-address-level3">address-level3</code>"
<li>"<code data-x="attr-fe-autocomplete-address-level2">address-level2</code>"
<li>"<code data-x="attr-fe-autocomplete-address-level1">address-level1</code>"
<li>"<code data-x="attr-fe-autocomplete-country">country</code>"
<li>"<code data-x="attr-fe-autocomplete-country-name">country-name</code>"
<li>"<code data-x="attr-fe-autocomplete-postal-code">postal-code</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-name">cc-name</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-given-name">cc-given-name</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-additional-name">cc-additional-name</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-family-name">cc-family-name</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-number">cc-number</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-exp">cc-exp</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-exp-month">cc-exp-month</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-exp-year">cc-exp-year</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-csc">cc-csc</code>"
<li>"<code data-x="attr-fe-autocomplete-cc-type">cc-type</code>"
<li>"<code data-x="attr-fe-autocomplete-transaction-currency">transaction-currency</code>"
<li>"<code data-x="attr-fe-autocomplete-transaction-amount">transaction-amount</code>"
<li>"<code data-x="attr-fe-autocomplete-language">language</code>"
<li>"<code data-x="attr-fe-autocomplete-bday">bday</code>"
<li>"<code data-x="attr-fe-autocomplete-bday-day">bday-day</code>"
<li>"<code data-x="attr-fe-autocomplete-bday-month">bday-month</code>"
<li>"<code data-x="attr-fe-autocomplete-bday-year">bday-year</code>"
<li>"<code data-x="attr-fe-autocomplete-sex">sex</code>"
<li>"<code data-x="attr-fe-autocomplete-url">url</code>"
<li>"<code data-x="attr-fe-autocomplete-photo">photo</code>"
</ul>
<p>(See the table below for descriptions of these values.)</p>
</li>
<li>
<p>The following, in the given order:</p>
<ol>
<li>
<p>Optionally, a token that is an <span>ASCII case-insensitive</span> match for one of the
following strings:</p>
<ul class="brief">
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-home">home</code></dfn>", meaning the field is for contacting
someone at their residence
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-work">work</code></dfn>", meaning the field is for contacting
someone at their workplace
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-mobile">mobile</code></dfn>"<!-- or "cell"? -->, meaning the
field is for contacting someone regardless of location
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-fax">fax</code></dfn>", meaning the field describes a fax
machine's contact details
<li>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-pager">pager</code></dfn>", meaning the field describes a
pager's or beeper's contact details
</ul>
</li>
<li>
<p>A token that is an <span>ASCII case-insensitive</span> match for one of the following
<span>autofill field</span> names, excluding those that are <span>inappropriate for the
control</span>:</p>
<ul class="brief">
<li>"<code data-x="attr-fe-autocomplete-tel">tel</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-country-code">tel-country-code</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-national">tel-national</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-area-code">tel-area-code</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-local">tel-local</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-local-prefix">tel-local-prefix</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-local-suffix">tel-local-suffix</code>"
<li>"<code data-x="attr-fe-autocomplete-tel-extension">tel-extension</code>"
<li>"<code data-x="attr-fe-autocomplete-email">email</code>"
<li>"<code data-x="attr-fe-autocomplete-impp">impp</code>"
</ul>
<p>(See the table below for descriptions of these values.)</p>
</li>
</ol>
</li>
</ul>
</li>
<li><p>Optionally, a token that is an <span>ASCII case-insensitive</span> match for the string
"<dfn data-x="attr-fe-autocomplete-webauthn"><code>webauthn</code></dfn>", meaning the user agent
should show <span data-x="public key credential">public key credentials</span> available via
<code data-x="conditional mediation">conditional</code> mediation when the user interacts with the
form control. <code data-x="attr-fe-autocomplete-webauthn">webauthn</code> is only valid for
<code>input</code> and <code>textarea</code> elements.</p></li>
</ol>
<p>As noted earlier, the meaning of the attribute and its keywords depends on the mantle that the
attribute is wearing.</p>
<dl class="switch">
<dt>When wearing the <span>autofill expectation mantle</span>...
<dd>
<p>The "<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-off">off</code></dfn>" keyword indicates either that the control's
input data is particularly sensitive (for example the activation code for a nuclear weapon); or
that it is a value that will never be reused (for example a one-time-key for a bank login) and
the user will therefore have to explicitly enter the data each time, instead of being able to
rely on the UA to prefill the value for them; or that the document provides its own autocomplete
mechanism and does not want the user agent to provide autocompletion values.</p>
<p>The "<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-on">on</code></dfn>" keyword indicates that the user agent is
allowed to provide the user with autocompletion values, but does not provide any further
information about what kind of data the user might be expected to enter. User agents would have
to use heuristics to decide what autocompletion values to suggest.</p>
<p>The <span>autofill field</span> listed above indicate that the user agent is allowed to
provide the user with autocompletion values, and specifies what kind of value is expected. The
meaning of each such keyword is described in the table below.</p>
<p>If the <code data-x="attr-fe-autocomplete">autocomplete</code> attribute is omitted, the default
value corresponding to the state of the element's <span>form owner</span>'s <code
data-x="attr-form-autocomplete">autocomplete</code> attribute is used instead (either "<code
data-x="attr-fe-autocomplete-on">on</code>" or "<code
data-x="attr-fe-autocomplete-off">off</code>"). If there is no <span>form owner</span>, then the
value "<code data-x="attr-fe-autocomplete-on">on</code>" is used.</p>
</dd>
<dt>When wearing the <span>autofill anchor mantle</span>...
<dd>
<p>The <span>autofill field</span> listed above indicate that the value of the particular kind
of value specified is that value provided for this element. The meaning of each such keyword is
described in the table below.</p>
<div class="example">
<p>In this example the page has explicitly specified the currency and amount of the
transaction. The form requests a credit card and other billing details. The user agent could
use this information to suggest a credit card that it knows has sufficient balance and that
supports the relevant currency.</p>
<pre><code class="html"><form method=post action="step2.cgi">
<input type=hidden autocomplete=transaction-currency value="CHF">
<input type=hidden autocomplete=transaction-amount value="15.00">
<p><label>Credit card number: <input type=text inputmode=numeric autocomplete=cc-number></label>
<p><label>Expiry Date: <input type=month autocomplete=cc-exp></label>
<p><input type=submit value="Continue...">
</form></code></pre>
</div>
</dd>
</dl>
<p>The <dfn>autofill field</dfn> keywords relate to each other as described in the table below. Each field name
listed on a row of this table corresponds to the meaning given in the cell for that row in the
column labeled "Meaning". Some fields correspond to subparts of other fields; for example, a
credit card expiry date can be expressed as one field giving both the month and year of expiry
("<code data-x="attr-fe-autocomplete-cc-exp">cc-exp</code>"), or as two fields, one giving the
month ("<code data-x="attr-fe-autocomplete-cc-exp-month">cc-exp-month</code>") and one the year
("<code data-x="attr-fe-autocomplete-cc-exp-year">cc-exp-year</code>"). In such cases, the names of
the broader fields cover multiple rows, in which the narrower fields are defined.</p>
<p class="note">Generally, authors are encouraged to use the broader fields rather than the
narrower fields, as the narrower fields tend to expose Western biases. For example, while it is
common in some Western cultures to have a given name and a family name, in that order (and thus
often referred to as a <i>first name</i> and a <i>surname</i>), many cultures put the family name
first and the given name second, and many others simply have one name (a <i>mononym</i>). Having a
single field is therefore more flexible.</p>
<p>Some fields are only appropriate for certain form controls. An <span>autofill field</span> name
is <dfn data-x="inappropriate for the control">inappropriate for a control</dfn> if the control
does not belong to the group listed for that <span>autofill field</span> in the fifth column of
the first row describing that <span>autofill field</span> in the table below. What controls fall
into each group is described below the table.</p>
<table>
<thead>
<tr>
<th colspan=4> Field name
<th> Meaning
<th> Canonical Format
<th> Canonical Format Example
<th> Control group
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-name">name</code></dfn>"
<td>Full name
<td>Free-form text, no newlines
<td>Sir Timothy John Berners-Lee, OM, KBE, FRS, FREng, FRSA
<td><span data-x="Control Group Text">Text</span>
<tr>
<td rowspan=5 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code data-x="attr-fe-autocomplete-honorific-prefix">honorific-prefix</code></dfn>"
<td>Prefix or title (e.g. "Mr.", "Ms.", "Dr.", "<span lang="fr" data-x="">M<sup>lle</sup></span>")
<td>Free-form text, no newlines
<td>Sir
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-given-name">given-name</code></dfn>"
<td>Given name (in some Western cultures, also known as the <i>first name</i>)
<td>Free-form text, no newlines
<td>Timothy
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-additional-name">additional-name</code></dfn>"
<td>Additional names (in some Western cultures, also known as <i>middle names</i>, forenames other than the first name)
<td>Free-form text, no newlines
<td>John
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-family-name">family-name</code></dfn>"
<td>Family name (in some Western cultures, also known as the <i>last name</i> or <i>surname</i>)
<td>Free-form text, no newlines
<td>Berners-Lee
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-honorific-suffix">honorific-suffix</code></dfn>"
<td>Suffix (e.g. "Jr.", "B.Sc.", "MBASW", "II")
<td>Free-form text, no newlines
<td>OM, KBE, FRS, FREng, FRSA
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-nickname">nickname</code></dfn>"
<td>Nickname, screen name, handle: a typically short name used instead of the full name
<td>Free-form text, no newlines
<td>Tim
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-organization-title">organization-title</code></dfn>"
<td>Job title (e.g. "Software Engineer", "Senior Vice President", "Deputy Managing Director")
<td>Free-form text, no newlines
<td>Professor
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-username">username</code></dfn>"
<td>A username
<td>Free-form text, no newlines
<td>timbl
<td><span data-x="Control Group Username">Username</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-new-password">new-password</code></dfn>"
<td>A new password (e.g. when creating an account or changing a password)
<td>Free-form text, no newlines
<td>GUMFXbadyrS3
<td><span data-x="Control Group Password">Password</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-current-password">current-password</code></dfn>"
<td>The current password for the account identified by the <code data-x="attr-fe-autocomplete-username">username</code> field (e.g. when logging in)
<td>Free-form text, no newlines
<td>qwerty <!-- http://splashdata.com/press/worstpasswords2013.htm -->
<td><span data-x="Control Group Password">Password</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-one-time-code">one-time-code</code></dfn>"
<td>One-time code used for verifying user identity
<td>Free-form text, no newlines
<td>123456
<td><span data-x="Control Group Password">Password</span>
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-organization">organization</code></dfn>"
<td>Company name corresponding to the person, address, or contact information in the other fields associated with this field
<td>Free-form text, no newlines
<td>World Wide Web Consortium
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-street-address">street-address</code></dfn>"
<td>Street address (multiple lines, newlines preserved)
<td>Free-form text
<td>32 Vassar Street<br>
MIT Room 32-G524
<td><span data-x="Control Group Multiline">Multiline</span>
<tr>
<td rowspan=3 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-line1">address-line1</code></dfn>"
<td rowspan=3>Street address (one line per field)
<td>Free-form text, no newlines
<td>32 Vassar Street
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-line2">address-line2</code></dfn>"
<td>Free-form text, no newlines
<td>MIT Room 32-G524
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-line3">address-line3</code></dfn>"
<td>Free-form text, no newlines
<td>
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-level4">address-level4</code></dfn>"
<td>The most fine-grained <a href="#more-on-address-levels">administrative level</a>, in
addresses with four administrative levels
<td>Free-form text, no newlines
<td>
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-level3">address-level3</code></dfn>"
<td>The <a href="#more-on-address-levels">third administrative level</a>, in addresses with
three or more administrative levels
<td>Free-form text, no newlines
<td>
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-level2">address-level2</code></dfn>"
<td>The <a href="#more-on-address-levels">second administrative level</a>, in addresses with
two or more administrative levels; in the countries with two administrative levels, this would
typically be the city, town, village, or other locality within which the relevant street
address is found
<td>Free-form text, no newlines
<td>Cambridge
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-address-level1">address-level1</code></dfn>"
<td>The broadest <a href="#more-on-address-levels">administrative level</a> in the address,
i.e. the province within which the locality is found; for example, in the US, this would be the
state; in Switzerland it would be the canton; in the UK, the post town
<td>Free-form text, no newlines
<td>MA
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-country">country</code></dfn>"
<td>Country code
<td>Valid <a href="https://www.iso.org/iso-3166-country-codes.html">ISO 3166-1-alpha-2 country code</a> <ref>ISO3166</ref>
<td>US
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-country-name">country-name</code></dfn>"
<td>Country name
<td>Free-form text, no newlines; <a href="#autofill-country">derived from <code data-x="attr-fe-autocomplete-country">country</code> in some cases</a>
<td>US
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-postal-code">postal-code</code></dfn>"
<td>Postal code, post code, ZIP code, CEDEX code (if CEDEX, append "CEDEX", and the <i lang="fr">arrondissement</i>, if relevant, to the <code data-x="attr-fe-autocomplete-address-level2">address-level2</code> field)
<td>Free-form text, no newlines
<td>02139
<td><span data-x="Control Group Text">Text</span>
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-name">cc-name</code></dfn>"
<td>Full name as given on the payment instrument
<td>Free-form text, no newlines
<td>Tim Berners-Lee
<td><span data-x="Control Group Text">Text</span>
<tr>
<td rowspan=3 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-given-name">cc-given-name</code></dfn>"
<td>Given name as given on the payment instrument (in some Western cultures, also known as the <i>first name</i>)
<td>Free-form text, no newlines
<td>Tim
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-additional-name">cc-additional-name</code></dfn>"
<td>Additional names given on the payment instrument (in some Western cultures, also known as <i>middle names</i>, forenames other than the first name)
<td>Free-form text, no newlines
<td>
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-family-name">cc-family-name</code></dfn>"
<td>Family name given on the payment instrument (in some Western cultures, also known as the <i>last name</i> or <i>surname</i>)
<td>Free-form text, no newlines
<td>Berners-Lee
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-number">cc-number</code></dfn>"
<td>Code identifying the payment instrument (e.g. the credit card number)
<td><span>ASCII digits</span>
<td>4114360123456785 <!-- http://www.auricsystems.com/support-center/sample-credit-card-numbers -->
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-exp">cc-exp</code></dfn>"
<td>Expiration date of the payment instrument
<td><span>Valid month string</span>
<td>2014-12
<td><span data-x="Control Group Month">Month</span>
<tr>
<td rowspan=2 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-exp-month">cc-exp-month</code></dfn>"
<td>Month component of the expiration date of the payment instrument
<td><span>Valid integer</span> in the range 1..12
<td>12
<td><span data-x="Control Group Numeric">Numeric</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-exp-year">cc-exp-year</code></dfn>"
<td>Year component of the expiration date of the payment instrument
<td><span>Valid integer</span> greater than zero
<td>2014
<td><span data-x="Control Group Numeric">Numeric</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-csc">cc-csc</code></dfn>"
<td>Security code for the payment instrument (also known as the card security code (CSC), card validation code (CVC), card verification value (CVV), signature panel code (SPC), credit card ID (CCID), etc.)
<td><span>ASCII digits</span>
<td>419
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-cc-type">cc-type</code></dfn>"
<td>Type of payment instrument
<td>Free-form text, no newlines
<td>Visa
<td><span data-x="Control Group Text">Text</span>
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-transaction-currency">transaction-currency</code></dfn>"
<td>The currency that the user would prefer the transaction to use
<td>ISO 4217 currency code <ref>ISO4217</ref>
<td>GBP
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-transaction-amount">transaction-amount</code></dfn>"
<td>The amount that the user would like for the transaction (e.g. when entering a bid or sale price)
<td><span>Valid floating-point number</span>
<td>401.00
<td><span data-x="Control Group Numeric">Numeric</span>
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-language">language</code></dfn>"
<td>Preferred language
<td>Valid BCP 47 language tag <ref>BCP47</ref>
<td>en
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-bday">bday</code></dfn>"
<td>Birthday
<td><span>Valid date string</span>
<td>1955-06-08
<td><span data-x="Control Group Date">Date</span>
<tr>
<td rowspan=3 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-bday-day">bday-day</code></dfn>"
<td>Day component of birthday
<td><span>Valid integer</span> in the range 1..31
<td>8
<td><span data-x="Control Group Numeric">Numeric</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-bday-month">bday-month</code></dfn>"
<td>Month component of birthday
<td><span>Valid integer</span> in the range 1..12
<td>6
<td><span data-x="Control Group Numeric">Numeric</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-bday-year">bday-year</code></dfn>"
<td>Year component of birthday
<td><span>Valid integer</span> greater than zero
<td>1955
<td><span data-x="Control Group Numeric">Numeric</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-sex">sex</code></dfn>"
<td>Gender identity (e.g. Female, Fa'afafine)
<td>Free-form text, no newlines
<td>Male
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-url">url</code></dfn>"
<td>Home page or other web page corresponding to the company, person, address, or contact information in the other fields associated with this field
<td><span>Valid URL string</span>
<td>https://www.w3.org/People/Berners-Lee/
<td><span data-x="Control Group URL">URL</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-photo">photo</code></dfn>"
<td>Photograph, icon, or other image corresponding to the company, person, address, or contact information in the other fields associated with this field
<td><!--File or--> <span>Valid URL string</span>
<td>https://www.w3.org/Press/Stock/Berners-Lee/2001-europaeum-eighth.jpg
<td><!--<span data-x="Control Group File">File</span>--> <span data-x="Control Group URL">URL</span>
<tbody>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel">tel</code></dfn>"
<td>Full telephone number, including country code
<td><span>ASCII digits</span> and U+0020 SPACE characters, prefixed by a U+002B PLUS SIGN character (+)
<td>+1 617 253 5702
<td><span data-x="Control Group Tel">Tel</span>
<tr>
<td rowspan=6 class="non-rectangular-cell-indentation">
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-country-code">tel-country-code</code></dfn>"
<td>Country code component of the telephone number
<td><span>ASCII digits</span> prefixed by a U+002B PLUS SIGN character (+)
<td>+1
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=3>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-national">tel-national</code></dfn>"
<td>Telephone number without the county code component, with a country-internal prefix applied if applicable
<td><span>ASCII digits</span> and U+0020 SPACE characters
<td>617 253 5702
<td><span data-x="Control Group Text">Text</span>
<tr>
<td rowspan=4 class="non-rectangular-cell-indentation">
<td colspan=2>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-area-code">tel-area-code</code></dfn>"
<td>Area code component of the telephone number, with a country-internal prefix applied if applicable
<td><span>ASCII digits</span>
<td>617
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=2>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-local">tel-local</code></dfn>"
<td>Telephone number without the country code and area code components
<td><span>ASCII digits</span>
<td>2535702
<td><span data-x="Control Group Text">Text</span>
<tr>
<td rowspan=2 class="non-rectangular-cell-indentation">
<td>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-local-prefix">tel-local-prefix</code></dfn>"
<td>First part of the component of the telephone number that follows the area code, when that component is split into two components
<td><span>ASCII digits</span>
<td>253
<td><span data-x="Control Group Text">Text</span>
<tr>
<td>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-local-suffix">tel-local-suffix</code></dfn>"
<td>Second part of the component of the telephone number that follows the area code, when that component is split into two components
<td><span>ASCII digits</span>
<td>5702
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-tel-extension">tel-extension</code></dfn>"
<td>Telephone number internal extension code
<td><span>ASCII digits</span>
<td>1000
<td><span data-x="Control Group Text">Text</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-email">email</code></dfn>"
<td>Email address
<td><span>Valid email address</span>
<td>timbl@w3.org
<td><span data-x="Control Group Username">Username</span>
<tr>
<td colspan=4>"<dfn attr-value
for="button/autocomplete,fieldset/autocomplete,input/autocomplete,object/autocomplete,output/autocomplete,select/autocomplete,textarea/autocomplete"><code
data-x="attr-fe-autocomplete-impp">impp</code></dfn>"
<td>URL representing an instant messaging protocol endpoint (for example, "<code data-x="">aim:goim?screenname=example</code>" or "<code data-x="">xmpp:fred@example.net</code>")
<td><span>Valid URL string</span>
<td>irc://example.org/timbl,isuser
<td><span data-x="Control Group URL">URL</span>
</table>
<p>The groups correspond to controls as follows:</p>
<dl>
<dt><dfn data-x="Control Group Text">Text</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Multiline">Multiline</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Password">Password</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-password">Password</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group URL">URL</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-url">URL</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Username">Username</dfn><span id="control-group-e-mail"></span>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-email">Email</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Tel">Tel</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-tel">Telephone</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Numeric">Numeric</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-number">Number</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Month">Month</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-month">Month</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<dt><dfn data-x="Control Group Date">Date</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-date">Date</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
<!--
<dt><dfn data-x="Control Group File">File</dfn>
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-hidden">Hidden</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-text">Text</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-search">Search</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-url">URL</span> state
<dd><code>input</code> elements with a <code data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-file">File</span> state
<dd><code>textarea</code> elements
<dd><code>select</code> elements
-->
</dl>
<p id="more-on-address-levels"><strong>Address levels</strong>: The "<code
data-x="attr-fe-autocomplete-address-level1">address-level1</code>" – "<code
data-x="attr-fe-autocomplete-address-level4">address-level4</code>" fields are used to describe
the locality of the street address. Different locales have different numbers of levels. For
example, the US uses two levels (state and town), the UK uses one or two depending on the address
(the post town, and in some cases the locality), and China can use three (province, city,
district). The "<code data-x="attr-fe-autocomplete-address-level1">address-level1</code>" field
represents the widest administrative division. Different locales order the fields in different
ways; for example, in the US the town (level 2) precedes the state (level 1); while in Japan the
prefecture (level 1) precedes the city (level 2) which precedes the district (level 3). Authors
are encouraged to provide forms that are presented in a way that matches the country's conventions
(hiding, showing, and rearranging fields accordingly as the user changes the country).</p>
<div w-nodev>
<h6 id="autofill-processing-model"><span id="processing-model-3"></span>Processing model</h6>
<p>Each <code>input</code> element to which the <code data-x="attr-fe-autocomplete">autocomplete</code> attribute <span data-x="concept-input-apply">applies</span>, each <code>select</code> element, and each <code>textarea</code> element, has an
<dfn>autofill hint set</dfn>, an <dfn>autofill scope</dfn>, an <dfn>autofill field name</dfn>, a
<dfn>non-autofill credential type</dfn>, and an <dfn>IDL-exposed autofill value</dfn>.</p>
<p>The <span>autofill field name</span> specifies the specific kind of data expected in the field,
e.g. "<code data-x="attr-fe-autocomplete-street-address">street-address</code>" or "<code
data-x="attr-fe-autocomplete-cc-exp">cc-exp</code>".</p>
<p>The <span>autofill hint set</span> identifies what address or contact information type the user
agent is to look at, e.g. "<code data-x="attr-fe-autocomplete-shipping">shipping</code> <code
data-x="attr-fe-autocomplete-fax">fax</code>" or "<code
data-x="attr-fe-autocomplete-billing">billing</code>".</p>
<p>The <span>non-autofill credential type</span> identifies a type of
<span data-x="credman-credential">credential</span> that may be offered by the user agent when the
user interacts with the field alongside other <span>autofill field</span> values. If this value is
"<code data-x="">webauthn</code>" instead of null, selecting a credential of that type will resolve
a pending <code data-x="conditional mediation">conditional</code> mediation
<code>navigator.credentials.get()</code> request, instead of autofilling the field.</p>
<div class="example">
<p>For example, a sign-in page could instruct the user agent to either autofill a saved password,
or show a <span>public key credential</span> that will resolve a pending
<code>navigator.credentials.get()</code> request. A user can select either to sign-in.</p>
<pre><code class="html"><input name=password type=password autocomplete="current-password webauthn"></code></pre>
</div>
<p>The <span>autofill scope</span> identifies the group of fields whose information concerns the
same subject, and consists of the <span>autofill hint set</span> with, if
applicable, the "<code data-x="">section-*</code>" prefix, e.g. "<code data-x="">billing</code>",
"<code data-x="">section-parent shipping</code>", or "<code data-x="">section-child shipping
home</code>".</p>
<p>These values are defined as the result of running the following algorithm:</p>
<ol>
<li><p>If the element has no <code data-x="attr-fe-autocomplete">autocomplete</code> attribute,
then jump to the step labeled <i>default</i>.</p></li>
<li><p>Let <var>tokens</var> be the result of <span data-x="split a string on ASCII
whitespace">splitting the attribute's value on ASCII whitespace</span>.</p></li>
<li><p>If <var>tokens</var> is empty, then jump to the step labeled <i>default</i>.</p></li>
<li><p>Let <var>index</var> be the index of the last token in <var>tokens</var>.</p></li>
<li><p>Let <var>field</var> be the <var>index</var>th token in <var>tokens</var>.</p></li>
<li><p>Set the <var>category</var>, <var>maximum tokens</var> pair to the result of <span
data-x="determine a field's category">determining a field's category</span> given
<var>field</var>.</p></li>
<li><p>If <var>category</var> is null, then jump to the step labeled <i>default</i>.</p></li>
<li><p>If the number of tokens in <var>tokens</var> is greater than <var>maximum tokens</var>,
then jump to the step labeled <i>default</i>.</p></li>
<li><p>If <var>category</var> is Off or Automatic but the element's <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute is wearing the <span>autofill anchor
mantle</span>, then jump to the step labeled <i>default</i>.</p></li>
<li><p>If <var>category</var> is Off, let the element's <span>autofill field name</span>
be the string "<code data-x="">off</code>", let its <span>autofill hint set</span> be empty, and
let its <span>IDL-exposed autofill value</span> be the string "<code data-x="">off</code>". Then,
return.</p>
<li><p>If <var>category</var> is Automatic, let the element's <span>autofill field
name</span> be the string "<code data-x="">on</code>", let its <span>autofill hint set</span> be
empty, and let its <span>IDL-exposed autofill value</span> be the string "<code
data-x="">on</code>". Then, return.</p>
<li><p>Let <var>scope tokens</var> be an empty list.</p></li>
<li><p>Let <var>hint tokens</var> be an empty set.</p></li>
<li><p>Let <var>credential type</var> be null.</p></li>
<li><p>Let <var>IDL value</var> have the same value as <var>field</var>.</p></li>
<li>
<p>If <var>category</var> is Credential and the <var>index</var>th token in <var>tokens</var> is
an <span>ASCII case-insensitive</span> match for "<code
data-x="attr-fe-autocomplete-webauthn">webauthn</code>", then run the substeps that follow:</p>
<ol>
<li><p>Set <var>credential type</var> to "<code data-x="">webauthn</code>".</p></li>
<li><p>If the <var>index</var>th token in <var>tokens</var> is the first entry,
then skip to the step labeled <i>done</i>.</p></li>
<li><p>Decrement <var>index</var> by one.</p></li>
<li><p>Set the <var>category</var>, <var>maximum tokens</var> pair to the result of <span
data-x="determine a field's category">determining a field's category</span> given
the <var>index</var>th token in <var>tokens</var>.</p></li>
<li><p>If <var>category</var> is not Normal and <var>category</var> is not Contact, then jump to
the step labeled <i>default</i>.</p></li>
<li><p>If <var>index</var> is greater than <var>maximum tokens</var> minus one (i.e. if the
number of remaining tokens is greater than <var>maximum tokens</var>), then jump to the step
labeled <i>default</i>.</p></li>
<li><p>Set <var>IDL value</var> to the concatenation of the <var>index</var>th token in
<var>tokens</var>, a U+0020 SPACE character, and the previous value of <var>IDL
value</var>.</p></li>
</ol>
</li>
<li><p>If the <var>index</var>th token in <var>tokens</var> is the first entry,
then skip to the step labeled <i>done</i>.</p></li>
<li><p>Decrement <var>index</var> by one.</p></li>
<li>
<p>If <var>category</var> is Contact and the <var>index</var>th token in <var>tokens</var> is an <span>ASCII case-insensitive</span> match for one of the strings in
the following list, then run the substeps that follow:</p>
<ul class="brief">
<li>"<code data-x="attr-fe-autocomplete-home">home</code>"
<li>"<code data-x="attr-fe-autocomplete-work">work</code>"
<li>"<code data-x="attr-fe-autocomplete-mobile">mobile</code>"
<li>"<code data-x="attr-fe-autocomplete-fax">fax</code>"
<li>"<code data-x="attr-fe-autocomplete-pager">pager</code>"
</ul>
<p>The substeps are:</p>
<ol>
<li><p>Let <var>contact</var> be the matching string from the list above.</p></li>
<li><p>Insert <var>contact</var> at the start of <var>scope
tokens</var>.</p></li>
<li><p>Add <var>contact</var> to <var>hint tokens</var>.</p></li>
<li><p>Let <var>IDL value</var> be the concatenation of <var>contact</var>, a
U+0020 SPACE character, and the previous value of <var>IDL value</var>.</p></li>
<li><p>If the <var>index</var>th entry in <var>tokens</var> is the first
entry, then skip to the step labeled <i>done</i>.</p></li>
<li><p>Decrement <var>index</var> by one.</p></li>
</ol>
</li>
<li>
<p>If the <var>index</var>th token in <var>tokens</var> is an <span>ASCII
case-insensitive</span> match for one of the strings in the following list, then run the
substeps that follow:</p>
<ul class="brief">
<li>"<code data-x="attr-fe-autocomplete-shipping">shipping</code>"
<li>"<code data-x="attr-fe-autocomplete-billing">billing</code>"
</ul>
<p>The substeps are:</p>
<ol>
<li><p>Let <var>mode</var> be the matching string from the list above.</p></li>
<li><p>Insert <var>mode</var> at the start of <var>scope
tokens</var>.</p></li>
<li><p>Add <var>mode</var> to <var>hint tokens</var>.</p></li>
<li><p>Let <var>IDL value</var> be the concatenation of <var>mode</var>, a
U+0020 SPACE character, and the previous value of <var>IDL value</var>.</p></li>
<li><p>If the <var>index</var>th entry in <var>tokens</var> is the first
entry, then skip to the step labeled <i>done</i>.</p></li>
<li><p>Decrement <var>index</var> by one.</p></li>
</ol>
</li>
<li><p>If the <var>index</var>th entry in <var>tokens</var> is not the first entry, then jump to
the step labeled <i>default</i>.</p></li>
<li><p>If the first eight characters of the <var>index</var>th token in <var>tokens</var> are not
an <span>ASCII case-insensitive</span> match for the string "<code
data-x="attr-fe-autocomplete-section">section-</code>", then jump to the step labeled
<i>default</i>.</p></li>
<li><p>Let <var>section</var> be the <var>index</var>th token in <var>tokens</var>,
<span>converted to ASCII lowercase</span>.</p></li>
<li><p>Insert <var>section</var> at the start of <var>scope tokens</var>.</p></li>
<li><p>Let <var>IDL value</var> be the concatenation of <var>section</var>, a U+0020 SPACE
character, and the previous value of <var>IDL value</var>.</p></li>
<li><p><i>Done</i>: Let the element's <span>autofill hint set</span> be <var>hint
tokens</var>.</p>
<li><p>Let the element's <span>non-autofill credential type</span> be <var>credential
type</var>.</p></li>
<li><p>Let the element's <span>autofill scope</span> be <var>scope tokens</var>.</p>
<li><p>Let the element's <span>autofill field name</span> be <var>field</var>.</p>
<li><p>Let the element's <span>IDL-exposed autofill value</span> be <var>IDL value</var>.</p>
<li><p>Return.</p></li>
<li><p><i>Default</i>: Let the element's <span>IDL-exposed autofill value</span> be the empty
string, and its <span>autofill hint set</span> and <span>autofill scope</span> be empty.</p></li>
<li><p>If the element's <code data-x="attr-fe-autocomplete">autocomplete</code> attribute is
wearing the <span>autofill anchor mantle</span>, then let the element's <span>autofill field
name</span> be the empty string and return.</p></li>
<li><p>Let <var>form</var> be the element's <span>form owner</span>, if any, or null
otherwise.</p></li>
<li>
<p>If <var>form</var> is not null and <var>form</var>'s <code
data-x="attr-form-autocomplete">autocomplete</code> attribute is in the <span
data-x="attr-form-autocomplete-off-state">off</span> state, then let the element's
<span>autofill field name</span> be "<code data-x="attr-fe-autocomplete-off">off</code>".</p>
<p>Otherwise, let the element's <span>autofill field name</span> be "<code
data-x="attr-fe-autocomplete-on">on</code>".</p>
</li>
</ol>
<p>To <dfn>determine a field's category</dfn>, given <var>field</var>:</p>
<ol>
<li>
<p>If the <var>field</var> is not an <span>ASCII case-insensitive</span> match for one of the
tokens given in the first column of the following table, return the pair (null, null).</p>
<table>
<thead>
<tr>
<th>Token
<th>Maximum number of tokens
<th>Category
<tbody>
<tr>
<td>"<code data-x="attr-fe-autocomplete-off">off</code>"
<td>1
<td>Off
<tr>
<td>"<code data-x="attr-fe-autocomplete-on">on</code>"
<td>1
<td>Automatic
<tbody>
<tr>
<td>"<code data-x="attr-fe-autocomplete-name">name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-honorific-prefix">honorific-prefix</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-given-name">given-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-additional-name">additional-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-family-name">family-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-honorific-suffix">honorific-suffix</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-nickname">nickname</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-organization-title">organization-title</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-username">username</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-new-password">new-password</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-current-password">current-password</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-one-time-code">one-time-code</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-organization">organization</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-street-address">street-address</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-line1">address-line1</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-line2">address-line2</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-line3">address-line3</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-level4">address-level4</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-level3">address-level3</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-level2">address-level2</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-address-level1">address-level1</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-country">country</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-country-name">country-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-postal-code">postal-code</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-name">cc-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-given-name">cc-given-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-additional-name">cc-additional-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-family-name">cc-family-name</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-number">cc-number</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-exp">cc-exp</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-exp-month">cc-exp-month</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-exp-year">cc-exp-year</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-csc">cc-csc</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-cc-type">cc-type</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-transaction-currency">transaction-currency</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-transaction-amount">transaction-amount</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-language">language</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-bday">bday</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-bday-day">bday-day</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-bday-month">bday-month</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-bday-year">bday-year</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-sex">sex</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-url">url</code>"
<td>3
<td>Normal
<tr>
<td>"<code data-x="attr-fe-autocomplete-photo">photo</code>"
<td>3
<td>Normal
<tbody>
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel">tel</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-country-code">tel-country-code</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-national">tel-national</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-area-code">tel-area-code</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-local">tel-local</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-local-prefix">tel-local-prefix</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-local-suffix">tel-local-suffix</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-tel-extension">tel-extension</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-email">email</code>"
<td>4
<td>Contact
<tr>
<td>"<code data-x="attr-fe-autocomplete-impp">impp</code>"
<td>4
<td>Contact
<tbody>
<tr>
<td>"<code data-x="attr-fe-autocomplete-webauthn">webauthn</code>"
<td>5
<td>Credential
</table>
</li>
<li><p>Otherwise, let <var>maximum tokens</var> and <var>category</var> be the values of the
cells in the second and third columns of that row respectively.</p></li>
<li><p>Return the pair (<var>category</var>, <var>maximum tokens</var>).</p></li>
</ol>
<hr>
<p>For the purposes of autofill, a <dfn>control's data</dfn> depends on the kind of control:</p>
<dl>
<dt>An <code>input</code> element with its <code data-x="attr-input-type">type</code> attribute
in the <span data-x="attr-input-type-email">Email</span> state and with the <code
data-x="attr-input-multiple">multiple</code> attribute specified</dt>
<dd>The element's <span data-x="concept-fe-values">value<em>s</em></span>.</dd>
<!--
<dt>An <code>input</code> element with its <code data-x="attr-input-type">type</code> attribute
in the <span data-x="attr-input-type-range">Range</span> state and with the <code
data-x="attr-input-multiple">multiple</code> attribute specified</dt>
-->
<dt>Any other <code>input</code> element</dt>
<dt>A <code>textarea</code> element</dt>
<dd>The element's <span data-x="concept-fe-value">value</span>.</dd>
<dt>A <code>select</code> element with its <code data-x="attr-select-multiple">multiple</code>
attribute specified</dt>
<dd>The <code>option</code> elements in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> that have their <span
data-x="concept-option-selectedness">selectedness</span> set to true.</dd>
<dt>Any other <code>select</code> element</dt>
<dd>The <code>option</code> element in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> that has its <span
data-x="concept-option-selectedness">selectedness</span> set to true.</dd>
</dl>
<hr>
<p>How to process the <span>autofill hint set</span>, <span>autofill scope</span>, and
<span>autofill field name</span> depends on the mantle that the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute is wearing.</p>
<dl class="switch">
<dt>When wearing the <span>autofill expectation mantle</span>...
<dd>
<p>When an element's <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-off">off</code>", the user agent should not remember the <span>control's
data</span>, and should not offer past values to the user.</p>
<p class="note">In addition, when an element's <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-off">off</code>", <a href="#history-autocomplete">values are
reset</a> when <span data-x="reactivate a document">reactivating a document</span>.</p>
<div class="example">
<p>Banks frequently do not want UAs to prefill login information:</p>
<pre><code class="html"><p><label>Account: <input type="text" name="ac" autocomplete="off"></label></p>
<p><label>PIN: <input type="password" name="pin" autocomplete="off"></label></p></code></pre>
</div>
<p>When an element's <span>autofill field name</span> is <em>not</em> "<code
data-x="attr-fe-autocomplete-off">off</code>", the user agent may store the <span>control's
data</span>, and may offer previously stored values to the user.</p>
<div class="example">
<p>For example, suppose a user visits a page with this control:</p>
<pre><code class="html"><select name="country">
<option>Afghanistan
<option>Albania
<option>Algeria
<option>Andorra
<option>Angola
<option>Antigua and Barbuda
<option>Argentina
<option>Armenia
<!-- <em>...</em> -->
<option>Yemen
<option>Zambia
<option>Zimbabwe
</select></code></pre>
<p>This might render as follows:</p>
<p><img src="/images/select-country-1.png" alt="A drop-down control with a long alphabetical list of countries."></p>
<p>Suppose that on the first visit to this page, the user selects "Zambia". On the second visit,
the user agent could duplicate the entry for Zambia at the top of the list, so that the interface
instead looks like this:</p>
<p><img src="/images/select-country-2.png" alt="The same drop-down control with the alphabetical list of countries, but with Zambia as an entry at the top."></p>
</div>
<p>When the <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-on">on</code>", the user agent should attempt to use heuristics to
determine the most appropriate values to offer the user, e.g. based on the element's <code
data-x="attr-fe-name">name</code> value, the position of the element in its <span>tree</span>,
what other fields exist in the form, and so forth.</p>
<p>When the <span>autofill field name</span> is one of the names of the <span data-x="autofill
field">autofill fields</span> described above, the user agent should provide suggestions that
match the meaning of the field name as given in the table earlier in this section. The
<span>autofill hint set</span> should be used to select amongst multiple possible suggestions.</p>
<p class="example">For example, if a user once entered one address into fields that used the
"<code data-x="attr-fe-autocomplete-shipping">shipping</code>" keyword, and another address into
fields that used the "<code data-x="attr-fe-autocomplete-billing">billing</code>" keyword, then in
subsequent forms only the first address would be suggested for form controls whose <span>autofill
hint set</span> contains the keyword "<code
data-x="attr-fe-autocomplete-shipping">shipping</code>". Both addresses might be suggested,
however, for address-related form controls whose <span>autofill hint set</span> does not contain
either keyword.</p>
</dd>
<dt>When wearing the <span>autofill anchor mantle</span>...
<dd>
<p>When the <span>autofill field name</span> is not the empty string, then the user agent must
act as if the user had specified the <span>control's data</span> for the given <span>autofill
hint set</span>, <span>autofill scope</span>, and <span>autofill field name</span>
combination.</p>
</dd>
</dl>
<p>When the user agent <dfn data-x="concept-fe-autofill">autofills form controls</dfn>, elements
with the same <span>form owner</span> and the same <span>autofill scope</span> must use data
relating to the same person, address, payment instrument, and contact details. <span
id="autofill-country" data-x="">When a user agent autofills "<code
data-x="attr-fe-autocomplete-country">country</code>" and "<code
data-x="attr-fe-autocomplete-country-name">country-name</code>" fields with the same <span>form
owner</span> and <span>autofill scope</span>, and the user agent has a value for the <code
data-x="attr-fe-autocomplete-country">country</code>" field(s), then the "<code
data-x="attr-fe-autocomplete-country-name">country-name</code>" field(s) must be filled using a
human-readable name for the same country.</span> When a user agent fills in multiple fields at
once, all fields with the same <span>autofill field name</span>, <span>form owner</span>, and
<span>autofill scope</span> must be filled with the same value.</p>
<p class="example">Suppose a user agent knows of two phone numbers, +1 555 123 1234 and +1 555 666
7777. It would not be conforming for the user agent to fill a field with <code
data-x="">autocomplete="shipping tel-local-prefix"</code> with the value "123" and another field
in the same form with <code data-x="">autocomplete="shipping tel-local-suffix"</code> with the
value "7777". The only valid prefilled values given the aforementioned information would be "123"
and "1234", or "666" and "7777", respectively.</p>
<p class="example">Similarly, if a form for some reason contained both a "<code
data-x="attr-fe-autocomplete-cc-exp">cc-exp</code>" field and a "<code
data-x="attr-fe-autocomplete-cc-exp-month">cc-exp-month</code>" field, and the user agent
prefilled the form, then the month component of the former would have to match the latter.</p>
<div class="example">
<p>This requirement interacts with the <span>autofill anchor mantle</span> also. Consider the
following markup snippet:</p>
<pre><code class="html"><form>
<input type=hidden autocomplete="nickname" value="TreePlate">
<input type=text autocomplete="nickname">
</form></code></pre>
<p>The only value that a conforming user agent could suggest in the text control is "TreePlate",
the value given by the hidden <code>input</code> element.</p>
</div>
<p>The "<code data-x="">section-*</code>" tokens in the <span>autofill scope</span> are opaque;
user agents must not attempt to derive meaning from the precise values of these tokens.</p>
<p class="example">For example, it would not be conforming if the user agent decided that it
<!--non-normative-->should offer the address it knows to be the user's daughter's address for
"<code data-x="">section-child</code>" and the addresses it knows to be the user's spouses'
addresses for "<code data-x="">section-spouse</code>".</p>
<p>The autocompletion mechanism must be implemented by the user agent acting as if the user had
modified the <span>control's data</span>, and must be done at a time where the element is <i
data-x="concept-fe-mutable">mutable</i> (e.g. just after the element has been inserted into the
document, or when the user agent <span data-x="stop parsing">stops parsing</span>). User agents
must only prefill controls using values that the user could have entered.</p>
<p class="example">For example, if a <code>select</code> element only has <code>option</code>
elements with values "Steve" and "Rebecca", "Jay", and "Bob", and has an <span>autofill field
name</span> "<code data-x="attr-fe-autocomplete-given-name">given-name</code>", but the user
agent's only idea for what to prefill the field with is "Evan", then the user agent cannot prefill
the field. It would not be conforming to somehow set the <code>select</code> element to the value
"Evan", since the user could not have done so themselves.</p>
<p>A user agent prefilling a form control must not discriminate between form controls that are
<span>in a document tree</span> and those that are <span>connected</span>; that is, it is not
conforming to make the decision on whether or not to autofill based on whether the element's
<span>root</span> is a <span>shadow root</span> versus a <code>Document</code>.</p>
<p>A user agent prefilling a form control's <span data-x="concept-fe-value">value</span> must not
cause that control to <span data-x="suffering from a type mismatch">suffer from a type
mismatch</span>, <span data-x="suffering from being too long">suffer from being too long</span>,
<span data-x="suffering from being too short">suffer from being too short</span>, <span
data-x="suffering from an underflow">suffer from an underflow</span>, <span data-x="suffering from
an overflow">suffer from an overflow</span>, or <span data-x="suffering from a step
mismatch">suffer from a step mismatch</span>. A user agent prefilling a form control's <span
data-x="concept-fe-value">value</span> must not cause that control to <span data-x="suffering from
a pattern mismatch">suffer from a pattern mismatch</span> either. Where possible given the
control's constraints, user agents must use the format given as canonical in the aforementioned
table. Where it's not possible for the canonical format to be used, user agents should use
heuristics to attempt to convert values so that they can be used.</p>
<div class="example">
<p>For example, if the user agent knows that the user's middle name is "Ines", and attempts to
prefill a form control that looks like this:</p>
<pre><code class="html"><input name=middle-initial maxlength=1 autocomplete="additional-name"></code></pre>
<p>...then the user agent could convert "Ines" to "I" and prefill it that way.</p>
</div>
<div class="example">
<p>A more elaborate example would be with month values. If the user agent knows that the user's
birthday is the 27th of July 2012, then it might try to prefill all of the following controls
with slightly different values, all driven from this information:</p>
<table>
<tr>
<td>
<pre><code class="html"><input name=b type=month autocomplete="bday"></code></pre>
<td>
2012-07
<td>
The day is dropped since the <span
data-x="attr-input-type-month">Month</span> state only accepts a
month/year combination. (Note that this example is non-conforming, because the <span>autofill
field name</span> <code data-x="attr-fe-autocomplete-bday">bday</code> is not allowed with the
<span data-x="attr-input-type-month">Month</span> state.)
<tr>
<td>
<pre><code class="html"><select name=c autocomplete="bday">
<option>Jan
<option>Feb
<em>...</em>
<option>Jul
<option>Aug
<em>...</em>
</select></code></pre>
<td>
July
<td>
The user agent picks the month from the listed options, either by noticing there are twelve
options and picking the 7th, or by recognizing that one of the strings (three characters "Jul"
followed by a newline and a space) is a close match for the name of the month (July) in one of
the user agent's supported languages, or through some other similar mechanism.
<tr>
<td>
<pre><code class="html"><input name=a type=number min=1 max=12 autocomplete="bday-month"></code></pre>
<td>
7
<td>
User agent converts "July" to a month number in the range 1..12, like the field.
<tr>
<td>
<pre><code class="html"><input name=a type=number min=0 max=11 autocomplete="bday-month"></code></pre>
<td>
6
<td>
User agent converts "July" to a month number in the range 0..11, like the field.
<tr>
<td>
<pre><code class="html"><input name=a type=number min=1 max=11 autocomplete="bday-month"></code></pre>
<td>
<td>
User agent doesn't fill in the field, since it can't make a good guess as to what the form expects.
</table>
</div>
<p>A user agent may allow the user to override an element's <span>autofill field name</span>, e.g.
to change it from "<code data-x="attr-fe-autocomplete-off">off</code>" to "<code
data-x="attr-fe-autocomplete-on">on</code>" to allow values to be remembered and prefilled despite
the page author's objections, or to always "<code data-x="attr-fe-autocomplete-off">off</code>",
never remembering values.</p>
<p>More specifically, user agents may in particular consider replacing the <span>autofill field
name</span> of form controls that match the description given in the first column of the following
table, when their <span>autofill field name</span> is either "<code
data-x="attr-fe-autocomplete-on">on</code>" or "<code
data-x="attr-fe-autocomplete-off">off</code>", with the value given in the second cell of that
row. If this table is used, the replacements must be done in <span>tree order</span>, since all
but the first row references the <span>autofill field name</span> of earlier elements. When the
descriptions below refer to form controls being preceded or followed by others, they mean in the
list of <span data-x="category-listed">listed elements</span> that share the same <span>form
owner</span>.</p>
<table>
<thead>
<tr>
<th>Form control
<th>New <span>autofill field name</span>
<tbody>
<tr>
<td>
an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-text">Text</span> state that is followed by an
<code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state
<td>
"<code data-x="attr-fe-autocomplete-username">username</code>"
<tr>
<td>
an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state that is preceded by an
<code>input</code> element whose <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-username">username</code>"
<td>
"<code data-x="attr-fe-autocomplete-current-password">current-password</code>"
<tr>
<td>
an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state that is preceded by an
<code>input</code> element whose <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-current-password">current-password</code>"
<td>
"<code data-x="attr-fe-autocomplete-new-password">new-password</code>"
<tr>
<td>
an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state that is preceded by an
<code>input</code> element whose <span>autofill field name</span> is "<code
data-x="attr-fe-autocomplete-new-password">new-password</code>"
<td>
"<code data-x="attr-fe-autocomplete-new-password">new-password</code>"
</table>
<p>The <dfn attribute for="HTMLInputElement,HTMLSelectElement,HTMLTextAreaElement"><code
data-x="dom-fe-autocomplete">autocomplete</code></dfn> IDL attribute, on getting, must return the
element's <span>IDL-exposed autofill value</span>, and on setting, must <span>reflect</span> the
content attribute of the same name.</p>
</div>
<h4 id="textFieldSelection">APIs for the text control selections</h4>
<!-- v2 idea: DOM Range APIs to expose the textarea/input edited value (ack martijnw) -->
<p>The <code>input</code> and <code>textarea</code> elements define several attributes and methods
for handling their selection. Their shared algorithms are defined here.</p>
<!-- v2: also add textLength? it seems to be widely used -->
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-select">select</span>()</code></dt>
<dd><p>Selects everything in the text control.</p></dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-selectionStart">selectionStart</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the offset to the start of the selection.</p>
<p>Can be set, to change the start of the selection.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-selectionEnd">selectionEnd</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the offset to the end of the selection.</p>
<p>Can be set, to change the end of the selection.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-selectionDirection">selectionDirection</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current direction of the selection.</p>
<p>Can be set, to change the direction of the selection.</p>
<p>The possible values are "<code data-x="">forward</code>", "<code data-x="">backward</code>",
and "<code data-x="">none</code>".</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-setSelectionRange">setSelectionRange</span>(<var>start</var>, <var>end</var> [, <var>direction</var>])</code></dt>
<dd>
<p>Changes the selection to cover the given substring in the given direction. If the direction
is omitted, it will be reset to be the platform default (none or forward).</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-textarea/input-setRangeText">setRangeText</span>(<var>replacement</var> [, <var>start</var>, <var>end</var> [, <var>selectionMode</var> ] ])</code></dt>
<dd>
<p>Replaces a range of text with the new text. If the <var>start</var> and <var>end</var>
arguments are not provided, the range is assumed to be the selection.</p>
<p>The final argument determines how the selection will be set after the text has been replaced.
The possible values are:</p>
<dl>
<dt>"<code subdfn data-x="dom-SelectionMode-select">select</code>"</dt>
<dd>Selects the newly inserted text.</dd>
<dt>"<code subdfn data-x="dom-SelectionMode-start">start</code>"</dt>
<dd>Moves the selection to just before the inserted text.</dd>
<dt>"<code subdfn data-x="dom-SelectionMode-end">end</code>"</dt>
<dd>Moves the selection to just after the selected text.</dd>
<dt>"<code subdfn data-x="dom-SelectionMode-preserve">preserve</code>"</dt>
<dd>Attempts to preserve the selection. This is the default.</dd>
</dl>
</dd>
</dl>
<div w-nodev>
<p>All <code>input</code> elements to which these APIs <span
data-x="concept-input-apply">apply</span>, and all <code>textarea</code> elements, have either a
<dfn data-x="concept-textarea/input-selection">selection</dfn> or a <dfn
data-x="concept-textarea/input-cursor">text entry cursor position</dfn> at all times (even for
elements that are not <span>being rendered</span>), measured in offsets into the <span
data-x="code unit">code units</span> of the control's <span
data-x="concept-textarea/input-relevant-value">relevant value</span>. The initial state must
consist of a <span data-x="concept-textarea/input-cursor">text entry cursor</span> at the
beginning of the control.</p>
<!-- Previously the spec said to let platform conventions decide, but the web depends on it being
at the beginning; see https://bugzilla.mozilla.org/show_bug.cgi?id=1337392 -->
<p>For <code>input</code> elements, these APIs must operate on the element's <span
data-x="concept-fe-value">value</span>. For <code>textarea</code> elements, these APIs must
operate on the element's <span data-x="concept-fe-api-value">API value</span>. In the below
algorithms, we call the value string being operated on the <dfn
data-x="concept-textarea/input-relevant-value">relevant value</dfn>.</p>
<div class="example">
<p>The use of <span data-x="concept-fe-api-value">API value</span> instead of <span
data-x="concept-textarea-raw-value">raw value</span> for <code>textarea</code> elements means
that U+000D (CR) characters are normalized away. For example,
<pre><code class="html"><textarea id="demo"></textarea>
<script>
demo.value = "A\r\nB";
demo.setRangeText("replaced", 0, 2);
assert(demo.value === "replacedB");
</script></code></pre>
<p>If we had operated on the <span data-x="concept-textarea-raw-value">raw value</span> of "<code
data-x="">A\r\nB</code>", then we would have replaced the characters "<code
data-x="">A\r</code>", ending up with a result of "<code data-x="">replaced\nB</code>". But since
we used the <span data-x="concept-fe-api-value">API value</span> of "<code
data-x="">A\nB</code>", we replaced the characters "<code data-x="">A\n</code>", giving "<code
data-x="">replacedB</code>".</p>
</div>
<p class="note">Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still
count as characters. Thus, for instance, the selection can include just an invisible character,
and the text insertion cursor can be placed to one side or another of such a character.</p>
<p>Whenever the <span data-x="concept-textarea/input-relevant-value">relevant value</span> changes
for an element to which these APIs apply, run these steps:</p>
<ol>
<li>
<p>If the element has a <span data-x="concept-textarea/input-selection">selection</span>:</p>
<ol>
<li><p>If the start of the selection is now past the end of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span>, set it to the end of the
<span data-x="concept-textarea/input-relevant-value">relevant value</span>.</p></li>
<li><p>If the end of the selection is now past the end of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span>, set it to the end of the
<span data-x="concept-textarea/input-relevant-value">relevant value</span>.</p></li>
<li><p>If the user agent does not support empty selection, and both the start and end of the
selection are now pointing to the end of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span>, then instead set the
element's <span data-x="concept-textarea/input-cursor">text entry cursor position</span> to the
end of the <span data-x="concept-textarea/input-relevant-value">relevant value</span>, removing
any selection.</p></li>
</ol>
</li>
<li><p>Otherwise, the element must have a <span data-x="concept-textarea/input-cursor">text entry
cursor position</span> position. If it is now past the end of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span>, set it to the end of the
<span data-x="concept-textarea/input-relevant-value">relevant value</span>.</p></li>
</ol>
<p class="note">In some cases where the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> changes, other parts of the
specification will also modify the <span data-x="concept-textarea/input-cursor">text entry cursor
position</span>, beyond just the clamping steps above. For example, see the <code
data-x="dom-textarea-value">value</code> setter for <code>textarea</code>.</p>
<p>Where possible, user interface features for changing the <span
data-x="concept-textarea/input-selection">text selection</span> in <code>input</code> and
<code>textarea</code> elements must be implemented using the <span>set the selection range</span>
algorithm so that, e.g., all the same events fire.</p>
<p>The <span data-x="concept-textarea/input-selection">selections</span> of <code>input</code> and
<code>textarea</code> elements have a <dfn>selection direction</dfn>, which is either "<code
data-x="">forward</code>", "<code data-x="">backward</code>", or "<code data-x="">none</code>".
The exact meaning of the selection direction depends on the platform. This direction is set when
the user manipulates the selection. The initial <span>selection direction</span> must be "<code
data-x="">none</code>" if the platform supports that direction, or "<code
data-x="">forward</code>" otherwise.</p>
<p>To <dfn>set the selection direction</dfn> of an element to a given direction, update the
element's <span>selection direction</span> to the given direction, unless the direction is "<code
data-x="">none</code>" and the platform does not support that direction; in that case, update the
element's <span>selection direction</span> to "<code data-x="">forward</code>".</p>
<div class="note">
<p>On Windows, the direction indicates the position of the caret relative to
the selection: a "<code data-x="">forward</code>" selection has the caret at the end of the
selection and a "<code data-x="">backward</code>" selection has the caret at the start of the
selection. Windows has no "<code data-x="">none</code>" direction.</p>
<p>On Mac, the direction indicates which end of the selection is affected when the user adjusts
the size of the selection using the arrow keys with the Shift modifier: the "<code
data-x="">forward</code>" direction means the end of the selection is modified, and the "<code
data-x="">backward</code>" direction means the start of the selection is modified. The "<code
data-x="">none</code>" direction is the default on Mac, it indicates that no particular direction
has yet been selected. The user sets the direction implicitly when first adjusting the selection,
based on which directional arrow key was used.</p>
</div>
<p>The <dfn method for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-select">select()</code></dfn> method, when invoked, must run the
following steps:</p>
<ol>
<li>
<p>If this element is an <code>input</code> element, and either <code
data-x="dom-textarea/input-select">select()</code> <span data-x="do not apply">does not
apply</span> to this element or the corresponding control has no selectable text, return.</p>
<p class="example">For instance, in a user agent where <code
data-x="attr-input-type-color"><input type=color></code> is rendered as a color well with a
picker, as opposed to a text control accepting a hexadecimal color code, there would be no
selectable text, and thus calls to the method are ignored.</p>
</li>
<li><p><span>Set the selection range</span> with 0 and infinity.</p></li>
</ol>
<p>The <dfn attribute for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-selectionStart">selectionStart</code></dfn> attribute's getter must run
the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> <span data-x="do not apply">does
not apply</span> to this element, return null.</p></li>
<li><p>If there is no <span data-x="concept-textarea/input-selection">selection</span>, return
the <span>code unit</span> offset within the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> to the character that
immediately follows the <span data-x="concept-textarea/input-cursor">text entry
cursor</span>.</p></li>
<li><p>Return the <span>code unit</span> offset within the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> to the character that
immediately follows the start of the <span
data-x="concept-textarea/input-selection">selection</span>.</p></li>
</ol>
<p>The <code data-x="dom-textarea/input-selectionStart">selectionStart</code> attribute's setter
must run the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> <span data-x="do not apply">does
not apply</span> to this element, throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>end</var> be the value of this element's <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code> attribute.</p></li>
<li><p>If <var>end</var> is less than the given value, set <var>end</var> to the given
value.</p></li>
<li><p><span>Set the selection range</span> with the given value, <var>end</var>, and the value
of this element's <code data-x="dom-textarea/input-selectionDirection">selectionDirection</code>
attribute.</p></li>
</ol>
<p>The <dfn attribute for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code></dfn> attribute's getter must run the
following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code> <span data-x="do not apply">does
not apply</span> to this element, return null.</p></li>
<li><p>If there is no <span data-x="concept-textarea/input-selection">selection</span>, return
the <span>code unit</span> offset within the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> to the character that
immediately follows the <span data-x="concept-textarea/input-cursor">text entry
cursor</span>.</p></li>
<li><p>Return the <span>code unit</span> offset within the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> to the character that
immediately follows the end of the <span
data-x="concept-textarea/input-selection">selection</span>.</p></li>
</ol>
<p>The <code data-x="dom-textarea/input-selectionEnd">selectionEnd</code> attribute's setter must
run the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code> <span data-x="do not apply">does not
apply</span> to this element, throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span>Set the selection range</span> with the value of this element's <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> attribute, the given value, and
the value of this element's <code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code> attribute.</p></li>
</ol>
<p>The <dfn attribute for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code></dfn> attribute's getter
must run the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code> <span data-x="do not
apply">does not apply</span> to this element, return null.</p></li>
<li><p>Return this element's <span>selection direction</span>.</p></li>
</ol>
<p>The <code data-x="dom-textarea/input-selectionDirection">selectionDirection</code> attribute's
setter must run the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-selectionDirection">selectionDirection</code> <span data-x="do not
apply">does not apply</span> to this element, throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span>Set the selection range</span> with the value of this element's <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> attribute, the value of this
element's <code data-x="dom-textarea/input-selectionEnd">selectionEnd</code> attribute, and the
given value.</p></li>
</ol>
<p>The <dfn method for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-setSelectionRange">setSelectionRange(<var>start</var>, <var>end</var>,
<var>direction</var>)</code></dfn> method, when invoked, must run the following steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-setSelectionRange">setSelectionRange()</code> <span data-x="do not
apply">does not apply</span> to this element, throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span>Set the selection range</span> with <var>start</var>, <var>end</var>, and
<var>direction</var>.</p></li>
</ol>
<p>To <dfn>set the selection range</dfn> with an integer or null <var>start</var>, an integer or
null or the special value infinity <var>end</var>, and optionally a string <var>direction</var>,
run the following steps:</p>
<ol>
<li><p>If <var>start</var> is null, let <var>start</var> be zero.</p></li>
<li><p>If <var>end</var> is null, let <var>end</var> be zero.</p></li>
<li><p>Set the <span data-x="concept-textarea/input-selection">selection</span> of the text
control to the sequence of <span data-x="code unit">code units</span> within the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> starting with the code unit
at the <var>start</var>th position (in logical order) and ending with the code unit at the <span
data-x="">(<var>end</var>-1)</span>th position. Arguments greater than the <span>length</span> of
the <span data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control
(including the special value infinity) must be treated as pointing at the end of the text
control. If <var>end</var> is less than or equal to <var>start</var> then the start of the
selection and the end of the selection must both be placed immediately before the character with
offset <var>end</var>. In UAs where there is no concept of an empty selection, this must set the
cursor to be just before the character with offset <var>end</var>.</p></li>
<li><p>If <var>direction</var> is not <span>identical to</span> either "<code
data-x="">backward</code>" or "<code data-x="">forward</code>", or if the <var>direction</var>
argument was not given, set <var>direction</var> to "<code data-x="">none</code>".</p></li>
<li><p><span>Set the selection direction</span> of the text control to
<var>direction</var>.</p></li>
<li><p>If the previous steps caused the <span
data-x="concept-textarea/input-selection">selection</span> of the text control to be modified (in
either extent or <span data-x="selection direction">direction</span>), then <span>queue an
element task</span> on the <span>user interaction task source</span> given the element to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-select">select</code>
at the element, with the <code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to
true.</p></li>
</ol>
<p>The <dfn method for="HTMLInputElement,HTMLTextAreaElement"><code
data-x="dom-textarea/input-setRangeText">setRangeText(<var>replacement</var>, <var>start</var>,
<var>end</var>, <var>selectMode</var>)</code></dfn> method, when invoked, must run the following
steps:</p>
<ol>
<li><p>If this element is an <code>input</code> element, and <code
data-x="dom-textarea/input-setRangeText">setRangeText()</code> <span data-x="do not apply">does
not apply</span> to this element, throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set this element's <span data-x="concept-fe-dirty">dirty value flag</span> to
true.</p></li>
<li>
<p>If the method has only one argument, then let <var>start</var> and <var>end</var> have the values of the <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> attribute and the <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code> attribute respectively.</p>
<p>Otherwise, let <var>start</var>, <var>end</var> have the values of the
second and third arguments respectively.</p>
</li>
<li><p>If <var>start</var> is greater than <var>end</var>, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>start</var> is greater than the <span>length</span> of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control, then
set it to the <span>length</span> of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control.</p></li>
<li><p>If <var>end</var> is greater than the <span>length</span> of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control, then
set it to the <span>length</span> of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control.</p></li>
<li><p>Let <var>selection start</var> be the current value of the <code
data-x="dom-textarea/input-selectionStart">selectionStart</code> attribute.</p></li>
<li><p>Let <var>selection end</var> be the current value of the <code
data-x="dom-textarea/input-selectionEnd">selectionEnd</code> attribute.</p></li>
<li><p>If <var>start</var> is less than <var>end</var>, delete the sequence of <span data-x="code
unit">code units</span> within the element's <span
data-x="concept-textarea/input-relevant-value">relevant value</span> starting with the code unit
at the <var>start</var>th position and ending with the code unit at the <span
data-x="">(<var>end</var>-1)</span>th position.</p></li>
<li><p>Insert the value of the first argument into the text of the <span
data-x="concept-textarea/input-relevant-value">relevant value</span> of the text control,
immediately before the <var>start</var>th <span>code unit</span>.</p></li>
<li><p>Let <var>new length</var> be the <span>length</span> of the value of the first
argument.</p></li>
<li><p>Let <var>new end</var> be the sum of <var>start</var> and <var>new length</var>.</p></li>
<li>
<p>Run the appropriate set of substeps from the following list:</p>
<dl class="switch">
<dt>If the fourth argument's value is "<dfn enum-value for="SelectionMode"><code data-x="dom-SelectionMode-select">select</code></dfn>"</dt>
<dd>
<p>Let <var>selection start</var> be <var>start</var>.</p>
<p>Let <var>selection end</var> be <var>new end</var>.</p>
</dd>
<dt>If the fourth argument's value is "<dfn enum-value for="SelectionMode"><code data-x="dom-SelectionMode-start">start</code></dfn>"</dt>
<dd>
<p>Let <var>selection start</var> and <var>selection end</var> be <var>start</var>.</p>
</dd>
<dt>If the fourth argument's value is "<dfn enum-value for="SelectionMode"><code data-x="dom-SelectionMode-end">end</code></dfn>"</dt>
<dd>
<p>Let <var>selection start</var> and <var>selection end</var> be <var>new end</var>.</p>
</dd>
<dt>If the fourth argument's value is "<dfn enum-value for="SelectionMode"><code data-x="dom-SelectionMode-preserve">preserve</code></dfn>"</dt>
<dt>If the method has only one argument</dt>
<dd>
<ol>
<li><p>Let <var>old length</var> be <var>end</var> minus <var>start</var>.</p>
<li><p>Let <var>delta</var> be <var>new length</var> minus <var>old length</var>.</p>
<li>
<p>If <var>selection start</var> is greater than <var>end</var>, then
increment it by <var>delta</var>. (If <var>delta</var> is negative, i.e.
the new text is shorter than the old text, then this will <em>decrease</em> the value of
<var>selection start</var>.)</p>
<p>Otherwise: if <var>selection start</var> is greater than <var>start</var>, then set it to <var>start</var>. (This snaps the start of the
selection to the start of the new text if it was in the middle of the text that it
replaced.)</p>
</li>
<li>
<p>If <var>selection end</var> is greater than <var>end</var>, then
increment it by <var>delta</var> in the same way.</p>
<p>Otherwise: if <var>selection end</var> is greater than <var>start</var>, then set it to <var>new end</var>. (This snaps the end of the
selection to the end of the new text if it was in the middle of the text that it
replaced.)</p>
</li>
</ol>
</dd>
</dl>
</li>
<li><p><span>Set the selection range</span> with <var>selection start</var> and <var>selection
end</var>.</p></li>
</ol>
<p>The <code data-x="dom-textarea/input-setRangeText">setRangeText()</code> method uses the
following enumeration:<span w-dev> "<span data-x="dom-SelectionMode-select">select</span>", "<span
data-x="dom-SelectionMode-start">start</span>", "<span data-x="dom-SelectionMode-end">end</span>",
"<span data-x="dom-SelectionMode-preserve">preserve</span>" (default).</span></p>
<pre><code class="idl">enum <dfn enum>SelectionMode</dfn> {
"<span data-x="dom-SelectionMode-select">select</span>",
"<span data-x="dom-SelectionMode-start">start</span>",
"<span data-x="dom-SelectionMode-end">end</span>",
"<span data-x="dom-SelectionMode-preserve">preserve</span>" // default
};</code></pre>
<hr>
</div>
<div class="example">
<p>To obtain the currently selected text, the following JavaScript suffices:</p>
<pre><code class="js">var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);</code></pre>
<p>...where <var>control</var> is the <code>input</code> or <code>textarea</code>
element.</p>
</div>
<div class="example">
<p>To add some text at the start of a text control, while maintaining the text selection, the
three attributes must be preserved:</p>
<pre><code class="js">var oldStart = control.selectionStart;
var oldEnd = control.selectionEnd;
var oldDirection = control.selectionDirection;
var prefix = "http://";
control.value = prefix + control.value;
control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);</code></pre>
<p>...where <var>control</var> is the <code>input</code> or <code>textarea</code>
element.</p>
</div>
<h4>Constraints</h4>
<div w-nodev>
<h5>Definitions</h5>
<p>A <span data-x="category-submit">submittable element</span> is a <dfn>candidate for constraint
validation</dfn> except when a condition has <dfn data-x="barred from constraint validation">barred
the element from constraint validation</dfn>. (For example, an element is <span>barred from
constraint validation</span> if it has a <code>datalist</code> element ancestor.)</p>
<p>An element can have a <dfn>custom validity error message</dfn> defined. Initially, an element
must have its <span>custom validity error message</span> set to the empty string. When its value
is not the empty string, the element is <span>suffering from a custom error</span>. It can be set
using the <code data-x="dom-cva-setCustomValidity">setCustomValidity()</code> method, except for
<span data-x="form-associated custom element">form-associated custom elements</span>. <span
data-x="form-associated custom element">Form-associated custom elements</span> can have a
<span>custom validity error message</span> set via their <code>ElementInternals</code> object's
<code data-x="dom-ElementInternals-setValidity">setValidity()</code> method. The user agent should use the
<span>custom validity error message</span> when alerting the user to the problem with the
control.</p>
<p>An element can be constrained in various ways. The following is the list of <dfn>validity
states</dfn> that a form control can be in, making the control invalid for the purposes of
constraint validation. (The definitions below are non-normative; other parts of this specification
define more precisely when each state applies or does not.)</p>
<dl>
<dt> <dfn>Suffering from being missing</dfn> </dt>
<dd>
<p>When a control has no <span data-x="concept-fe-value">value</span> but has a <code
data-x="">required</code> attribute (<code>input</code> <code
data-x="attr-input-required">required</code>, <code>textarea</code> <code
data-x="attr-textarea-required">required</code>); or, more complicated rules for
<code>select</code> elements and controls in <span data-x="radio button group">radio button
groups</span>, as specified in their sections.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">valueMissing</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from a type mismatch</dfn> </dt>
<dd>
<p>When a control that allows arbitrary user input has a <span
data-x="concept-fe-value">value</span> that is not in the correct syntax (<span
data-x="attr-input-type-email">Email</span>, <span data-x="attr-input-type-url">URL</span>).
</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">typeMismatch</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from a pattern mismatch</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that doesn't satisfy the
<code data-x="attr-input-pattern">pattern</code> attribute.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">patternMismatch</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from being too long</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that is too long for the
<span data-x="attr-fe-maxlength">form control <code data-x="">maxlength</code> attribute</span>
(<code>input</code> <code data-x="attr-input-maxlength">maxlength</code>, <code>textarea</code>
<code data-x="attr-textarea-maxlength">maxlength</code>). </p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">tooLong</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from being too short</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that is too short for the
<span data-x="attr-fe-minlength">form control <code data-x="">minlength</code> attribute</span>
(<code>input</code> <code data-x="attr-input-minlength">minlength</code>, <code>textarea</code>
<code data-x="attr-textarea-minlength">minlength</code>). </p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">tooShort</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from an underflow</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that is not the empty
string and is too low for the <code data-x="attr-input-min">min</code> attribute.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">rangeUnderflow</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from an overflow</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that is not the empty
string and is too high for the <code data-x="attr-input-max">max</code> attribute.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">rangeOverflow</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from a step mismatch</dfn> </dt>
<dd>
<p>When a control has a <span data-x="concept-fe-value">value</span> that doesn't fit the
rules given by the <code data-x="attr-input-step">step</code> attribute.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">stepMismatch</code> flag to true for a
<span>form-associated custom element</span>.</p>
</dd>
<dt> <dfn>Suffering from bad input</dfn> </dt>
<dd>
<p>When a control has incomplete input and the user agent does not think the user ought to
be able to submit the form in its current state.</p>
<p>When the <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method sets
<code data-x="">badInput</code> flag to true for a <span>form-associated custom element</span>.
</p>
</dd>
<dt> <dfn>Suffering from a custom error</dfn> </dt>
<dd> <p>When a control's <span>custom validity error message</span> (as set by the element's
<code data-x="dom-cva-setCustomValidity">setCustomValidity()</code> method or
<code>ElementInternals</code>'s <code data-x="dom-ElementInternals-setValidity">setValidity()</code> method) is
not the empty string.</p> </dd>
</dl>
<p class="note">An element can still suffer from these states even when the element is <span
data-x="concept-fe-disabled">disabled</span>; thus these states can be represented in the DOM even
if validating the form during submission wouldn't indicate a problem to the user.</p>
<p>An element <dfn data-x="concept-fv-valid">satisfies its constraints</dfn> if it is not suffering
from any of the above <span>validity states</span>.</p>
</div>
<div w-nodev>
<h5>Constraint validation</h5>
<p>When the user agent is required to <dfn>statically validate the constraints</dfn> of
<code>form</code> element <var>form</var>, it must run the following steps, which return
either a <i>positive</i> result (all the controls in the form are valid) or a <i>negative</i>
result (there are invalid controls) along with a (possibly empty) list of elements that are
invalid and for which no script has claimed responsibility:</p>
<ol>
<li><p>Let <var>controls</var> be a list of all the <span
data-x="category-submit">submittable elements</span> whose <span>form owner</span> is <var>form</var>, in <span>tree order</span>.</p></li>
<li><p>Let <var>invalid controls</var> be an initially empty list of elements.</p></li>
<li>
<p>For each element <var>field</var> in <var>controls</var>, in <span>tree order</span>:</p>
<ol>
<li><p>If <var>field</var> is not a <span>candidate for constraint validation</span>,
then move on to the next element.</p></li>
<li><p>Otherwise, if <var>field</var> <span data-x="concept-fv-valid">satisfies its
constraints</span>, then move on to the next element.</p></li>
<li><p>Otherwise, add <var>field</var> to <var>invalid
controls</var>.</p></li>
</ol>
</li>
<li><p>If <var>invalid controls</var> is empty, then return a <i>positive</i> result.</p></li>
<li><p>Let <var>unhandled invalid controls</var> be an initially empty list of
elements.</p></li>
<li>
<p>For each element <var>field</var> in <var>invalid controls</var>, if any, in <span>tree
order</span>:</p>
<ol>
<li><p>Let <var>notCanceled</var> be the result of <span data-x="concept-event-fire">firing an
event</span> named <code data-x="event-invalid">invalid</code> at <var>field</var>, with the
<code data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true.</p></li>
<li><p>If <var>notCanceled</var> is true, then add <var>field</var> to <var>unhandled invalid
controls</var>.</p></li>
</ol>
</li>
<li><p>Return a <i>negative</i> result with the list of elements in the <var>unhandled
invalid controls</var> list.</p></li>
</ol>
<p>If a user agent is to <dfn>interactively validate the constraints</dfn> of <code>form</code>
element <var>form</var>, then the user agent must run the following steps:</p>
<ol>
<li><p><span>Statically validate the constraints</span> of <var>form</var>, and let
<var>unhandled invalid controls</var> be the list of elements returned if the result was
<i>negative</i>.</p></li>
<li><p>If the result was <i>positive</i>, then return that result.</p></li>
<li>
<p>Report the problems with the constraints of at least one of the elements given in
<var>unhandled invalid controls</var> to the user.</p>
<ul>
<li><p>User agents may focus one of those elements in the process, by running the
<span>focusing steps</span> for that element, and may change the scrolling position of the
document, or perform some other action that brings the element to the user's attention. For
elements that are <span data-x="form-associated custom element">form-associated custom
elements</span>, user agents should use their <span data-x="face-validation-anchor">validation
anchor</span> instead, for the purposes of these actions.</p></li>
<li><p>User agents may report more than one constraint violation.</p></li>
<li><p>User agents may coalesce related constraint violation reports if appropriate (e.g. if
multiple radio buttons in a <span data-x="radio button group">group</span> are marked as
required, only one error need be reported).</p></li>
<li><p>If one of the controls is not <span>being rendered</span> (e.g. it has the <code
data-x="attr-hidden">hidden</code> attribute set) then user agents may report a script
error.</p></li>
</ul>
</li>
<li><p>Return a <i>negative</i> result.</p></li>
</ol>
</div>
<h5>The <dfn>constraint validation API</dfn></h5>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-cva-willValidate">willValidate</span></code></dt>
<dd>
<p>Returns true if the element will be validated when the form is submitted; false
otherwise.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-cva-setCustomValidity">setCustomValidity</span>(<var>message</var>)</code></dt>
<dd>
<p>Sets a custom error, so that the element would fail to validate. The given message is the
message to be shown to the user when reporting the problem to the user.</p>
<p>If the argument is the empty string, clears the custom error.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-valueMissing">valueMissing</span></code></dt>
<dd><p>Returns true if the element has no value but is a required field; false
otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-typeMismatch">typeMismatch</span></code></dt>
<dd><p>Returns true if the element's value is not in the correct syntax; false
otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-patternMismatch">patternMismatch</span></code></dt>
<dd><p>Returns true if the element's value doesn't match the provided pattern; false
otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-tooLong">tooLong</span></code></dt>
<dd>
<p>Returns true if the element's value is longer than the provided maximum length; false
otherwise.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-tooShort">tooShort</span></code></dt>
<dd>
<p>Returns true if the element's value, if it is not the empty string, is shorter than the
provided minimum length; false otherwise.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-rangeUnderflow">rangeUnderflow</span></code></dt>
<dd><p>Returns true if the element's value is lower than the provided minimum; false
otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-rangeOverflow">rangeOverflow</span></code></dt>
<dd><p>Returns true if the element's value is higher than the provided maximum; false
otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-stepMismatch">stepMismatch</span></code></dt>
<dd><p>Returns true if the element's value doesn't fit the rules given by the <code
data-x="attr-input-step">step</code> attribute; false otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-badInput">badInput</span></code></dt>
<dd>
<p>Returns true if the user has provided input in the user interface that the user agent is
unable to convert to a value; false otherwise.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-customError">customError</span></code></dt>
<dd><p>Returns true if the element has a custom error; false otherwise.</p></dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-cva-validity">validity</span>.<span subdfn data-x="dom-validitystate-valid">valid</span></code></dt>
<dd><p>Returns true if the element's value has no validity problems; false otherwise.</p></dd>
<dt><code data-x=""><var>valid</var> = <var>element</var>.<span subdfn data-x="dom-cva-checkValidity">checkValidity</span>()</code></dt>
<dd><p>Returns true if the element's value has no validity problems; false otherwise. Fires an
<code data-x="event-invalid">invalid</code> event at the element in the latter case.</p></dd>
<dt><code data-x=""><var>valid</var> = <var>element</var>.<span subdfn data-x="dom-cva-reportValidity">reportValidity</span>()</code></dt>
<dd>
<p>Returns true if the element's value has no validity problems; otherwise, returns false, fires
an <code data-x="event-invalid">invalid</code> event at the element, and (if the event isn't
canceled) reports the problem to the user.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-cva-validationMessage">validationMessage</span></code></dt>
<dd>
<p>Returns the error message that would be shown to the user if the element was to be checked
for validity.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-willValidate">willValidate</code></dfn> attribute's getter must return true, if
this element is a <span>candidate for constraint validation</span>, and false otherwise (i.e.,
false if any conditions are <span data-x="barred from constraint validation">barring it from
constraint validation</span>).</p>
<p>The <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-willValidate">willValidate</code></dfn> attribute of
<code>ElementInternals</code> interface, on getting, must throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code> if the <span
data-x="internals-target">target element</span> is not a <span>form-associated custom
element</span>. Otherwise, it must return true if the <span data-x="internals-target">target
element</span> is a <span>candidate for constraint validation</span>, and false otherwise.</p>
<p>The <dfn method
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-setCustomValidity">setCustomValidity(<var>error</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>Set <var>error</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>error</var>.</p></li>
<li><p>Set the <span>custom validity error message</span> to <var>error</var>.</p></li>
</ol>
</div>
<div class="example">
<p>In the following example, a script checks the value of a form control each time it is edited,
and whenever it is not a valid value, uses the <code
data-x="dom-cva-setCustomValidity">setCustomValidity()</code> method to set an appropriate
message.</p>
<pre><code class="html"><label>Feeling: <input name=f type="text" oninput="check(this)"></label>
<script>
function check(input) {
if (input.value == "good" ||
input.value == "fine" ||
input.value == "tired") {
input.setCustomValidity('"' + input.value + '" is not a feeling.');
<!-- } else if (input.value == "...") {
input.setCustomValidity('...');
--> } else {
// input is fine -- reset the error message
input.setCustomValidity('');
}
}
</script></code></pre>
</div>
<div w-nodev>
<p>The <dfn attribute
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-validity">validity</code></dfn> attribute's getter must return a
<code>ValidityState</code> object that represents the <span>validity states</span> of this
element. This object is <span>live</span>.</p>
<p>The <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-validity">validity</code></dfn> attribute of
<code>ElementInternals</code> interface, on getting, must throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code> if the <span
data-x="internals-target">target element</span> is not a <span>form-associated custom
element</span>. Otherwise, it must return a <code>ValidityState</code> object that represents the
<span>validity states</span> of the <span data-x="internals-target">target element</span>. This
object is <span>live</span>.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>ValidityState</dfn> {
readonly attribute boolean <span data-x="dom-ValidityState-valueMissing">valueMissing</span>;
readonly attribute boolean <span data-x="dom-ValidityState-typeMismatch">typeMismatch</span>;
readonly attribute boolean <span data-x="dom-ValidityState-patternMismatch">patternMismatch</span>;
readonly attribute boolean <span data-x="dom-ValidityState-tooLong">tooLong</span>;
readonly attribute boolean <span data-x="dom-ValidityState-tooShort">tooShort</span>;
readonly attribute boolean <span data-x="dom-ValidityState-rangeUnderflow">rangeUnderflow</span>;
readonly attribute boolean <span data-x="dom-ValidityState-rangeOverflow">rangeOverflow</span>;
readonly attribute boolean <span data-x="dom-ValidityState-stepMismatch">stepMismatch</span>;
readonly attribute boolean <span data-x="dom-ValidityState-badInput">badInput</span>;
readonly attribute boolean <span data-x="dom-ValidityState-customError">customError</span>;
readonly attribute boolean <span data-x="dom-ValidityState-valid">valid</span>;
};</code></pre>
<p>A <code>ValidityState</code> object has the following attributes. On getting, they must return
true if the corresponding condition given in the following list is true, and false otherwise.</p>
<dl>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-valueMissing">valueMissing</code></dfn></dt>
<dd> <p>The control is <span>suffering from being missing</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-typeMismatch">typeMismatch</code></dfn></dt>
<dd> <p>The control is <span>suffering from a type mismatch</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-patternMismatch">patternMismatch</code></dfn></dt>
<dd> <p>The control is <span>suffering from a pattern mismatch</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-tooLong">tooLong</code></dfn></dt>
<dd> <p>The control is <span>suffering from being too long</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-tooShort">tooShort</code></dfn></dt>
<dd> <p>The control is <span>suffering from being too short</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-rangeUnderflow">rangeUnderflow</code></dfn></dt>
<dd> <p>The control is <span>suffering from an underflow</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-rangeOverflow">rangeOverflow</code></dfn></dt>
<dd> <p>The control is <span>suffering from an overflow</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-stepMismatch">stepMismatch</code></dfn></dt>
<dd> <p>The control is <span>suffering from a step mismatch</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-badInput">badInput</code></dfn></dt>
<dd> <p>The control is <span>suffering from bad input</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-customError">customError</code></dfn></dt>
<dd> <p>The control is <span>suffering from a custom error</span>.</p> </dd>
<dt><dfn attribute for="ValidityState"><code data-x="dom-ValidityState-valid">valid</code></dfn></dt>
<dd> <p>None of the other conditions are true.</p> </dd>
</dl>
<p>The <dfn>check validity steps</dfn> for an element <var>element</var> are:</p>
<ol>
<li>
<p>If <var>element</var> is a <span>candidate for constraint validation</span> and does not
<span data-x="concept-fv-valid">satisfy its constraints</span>, then:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-invalid">invalid</code> at <var>element</var>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true (though canceling
has no effect).</p></li>
<li><p>Return false.</p></li>
</ol>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn method
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-checkValidity">checkValidity()</code></dfn> method, when invoked, must run the
<span>check validity steps</span> on this element.</p>
<p>The <dfn method for="ElementInternals"><code
data-x="dom-ElementInternals-checkValidity">checkValidity()</code></dfn> method of the
<code>ElementInternals</code> interface must run these steps:</p>
<ol>
<li><p>Let <var>element</var> be this <code>ElementInternals</code>'s <span
data-x="internals-target">target element</span>.</p></li>
<li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Run the <span>check validity steps</span> on <var>element</var>.</p></li>
</ol>
<p>The <dfn>report validity steps</dfn> for an element <var>element</var> are:</p>
<ol>
<li>
<p>If <var>element</var> is a <span>candidate for constraint validation</span> and does not
<span data-x="concept-fv-valid">satisfy its constraints</span>, then:
<ol>
<li><p>Let <var>report</var> be the result of <span data-x="concept-event-fire">firing an
event</span> named <code data-x="event-invalid">invalid</code> at <var>element</var>, with the
<code data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true.</p></li>
<li><p>If <var>report</var> is true, then report the problems with the constraints of this
element to the user. When reporting the problem with the constraints to the user, the user
agent may run the <span>focusing steps</span> for <var>element</var>, and may change the
scrolling position of the document, or perform some other action that brings <var>element</var>
to the user's attention. User agents may report more than one constraint violation, if
<var>element</var> suffers from multiple problems at once.</p>
<li><p>Return false.</p></li>
</ol>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn method
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-reportValidity">reportValidity()</code></dfn> method, when invoked, must run the
<span>report validity steps</span> on this element.</p>
<p>The <dfn method for="ElementInternals"><code
data-x="dom-ElementInternals-reportValidity">reportValidity()</code></dfn> method of the
<code>ElementInternals</code> interface must run these steps:</p>
<ol>
<li><p>Let <var>element</var> be this <code>ElementInternals</code>'s <span
data-x="internals-target">target element</span>.</p></li>
<li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Run the <span>report validity steps</span> on <var>element</var>.</p></li>
</ol>
<p>The <dfn attribute
for="HTMLObjectElement,HTMLInputElement,HTMLButtonElement,HTMLSelectElement,HTMLTextAreaElement,HTMLOutputElement,HTMLFieldSetElement"><code
data-x="dom-cva-validationMessage">validationMessage</code></dfn> attribute's getter must run
these steps:</p>
<ol>
<li><p>If this element is not a <span>candidate for constraint validation</span> or if this
element <span data-x="concept-fv-valid">satisfies its constraints</span>, then return the empty
string.</p></li>
<li><p>Return a suitably localized message that the user agent would show the user if this were
the only form control with a validity constraint problem. If the user agent would not actually
show a textual message in such a situation (e.g., it would show a graphical cue instead), then
return a suitably localized message that expresses (one or more of) the validity constraint(s)
that the control does not satisfy. If the element is a <span>candidate for constraint
validation</span> and is <span>suffering from a custom error</span>, then the
<span>custom validity error message</span> should be present in the return value.</p></li>
</ol>
</div>
<h5 id="security-forms">Security</h5>
<p id="security-0">Servers should not rely on client-side validation. Client-side validation can
be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user
agents or automated tools that do not implement these features. The constraint validation features
are only intended to improve the user experience, not to provide any kind of security
mechanism.</p>
<h4 id="form-submission-2"><dfn id="form-submission">Form submission</dfn></h4>
<div w-nodev>
<h5>Introduction</h5>
</div>
<!-- NON-NORMATIVE SECTION -->
<p>When a form is submitted, the data in the form is converted into the structure specified by the
<span data-x="concept-fs-enctype">enctype</span>, and then sent to the destination specified by the
<span data-x="concept-fs-action">action</span> using the given <span
data-x="concept-fs-method">method</span>.</p>
<p>For example, take the following form:</p>
<pre><code class="html"><form action="/find.cgi" method=get>
<input type=text name=t>
<input type=search name=q>
<input type=submit>
</form></code></pre>
<p>If the user types in "cats" in the first field and "fur" in the second, and then hits the
submit button, then the user agent will load <code data-x="">/find.cgi?t=cats&q=fur</code>.</p>
<p>On the other hand, consider this form:</p>
<pre><code class="html"><form action="/find.cgi" method=post enctype="multipart/form-data">
<input type=text name=t>
<input type=search name=q>
<input type=submit>
</form></code></pre>
<p>Given the same user input, the result on submission is quite different: the user agent instead
does an HTTP POST to the given URL, with as the entity body something like the following text:</p>
<pre>------kYFrd4jNJEgCervE
Content-Disposition: form-data; name="t"
cats
------kYFrd4jNJEgCervE
Content-Disposition: form-data; name="q"
fur
------kYFrd4jNJEgCervE--</pre>
<div w-nodev>
<h5>Implicit submission</h5>
<p>A <code>form</code> element's <dfn>default button</dfn> is the first <span
data-x="concept-submit-button">submit button</span> in <span>tree order</span> whose <span>form
owner</span> is that <code>form</code> element.</p>
<p>If the user agent supports letting the user submit a form implicitly (for example, on some
platforms hitting the "enter" key while a text control is <span>focused</span> implicitly submits
the form), then doing so for a form, whose <span>default button</span> has <span>activation
behavior</span> and is not <span data-x="concept-fe-disabled">disabled</span>, must cause the user
agent to <span>fire a <code data-x="event-click">click</code> event</span> at that <span>default
button</span>.</p>
<p class="note">There are pages on the web that are only usable if there is a way to implicitly
submit forms, so user agents are strongly encouraged to support this.</p>
<p><!-- For web compatibility reasons caused by obscure historical accidents, -->If the form has
no <span data-x="concept-submit-button">submit button</span>, then the implicit submission
mechanism must perform the following steps:
<ol>
<li><p>If the form has more than one <span>field that blocks implicit submission</span>, then
return.</p></li>
<li><p><span data-x="concept-form-submit">Submit</span> the <code>form</code> element from the
<code>form</code> element itself with <i data-x="submit-user-involvement">userInvolvement</i> set
to "<code data-x="uni-activation">activation</code>".</p></li>
</ol>
<p>For the purpose of the previous paragraph, an element is a <dfn>field that blocks implicit
submission</dfn> of a <code>form</code> element if it is an <code>input</code> element whose
<span>form owner</span> is that <code>form</code> element and whose <code
data-x="attr-input-type">type</code> attribute is in one of the following states:
<span data-x="attr-input-type-text">Text</span>,
<span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-tel">Telephone</span>,
<span data-x="attr-input-type-url">URL</span>,
<span data-x="attr-input-type-email">Email</span>,
<span data-x="attr-input-type-password">Password</span>,
<span data-x="attr-input-type-date">Date</span>,
<span data-x="attr-input-type-month">Month</span>,
<span data-x="attr-input-type-week">Week</span>,
<span data-x="attr-input-type-time">Time</span>,
<span data-x="attr-input-type-datetime-local">Local Date and Time</span>,
<span data-x="attr-input-type-number">Number</span>
</p>
</div>
<div w-nodev>
<h5>Form submission algorithm</h5>
<p>Each <code>form</code> element has a <dfn>constructing entry list</dfn> boolean, initially
false.</p>
<p>Each <code>form</code> element has a <dfn>firing submission events</dfn> boolean, initially
false.</p>
<p>To <dfn data-x="concept-form-submit">submit</dfn> a <code>form</code> element <var>form</var>
from an element <var>submitter</var> (typically a button), given an optional boolean <dfn
data-x="submit-subbmitted-from-method"><var>submitted from <code
data-x="dom-form-submit">submit()</code> method</var></dfn> (default false) and an optional
<span>user navigation involvement</span> <dfn
data-x="submit-user-involvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"):</p>
<ol>
<li><p>If <var>form</var> <span>cannot navigate</span>, then return.</p></li>
<li><p>If <var>form</var>'s <span>constructing entry list</span> is true, then return.</p></li>
<li><p>Let <var>form document</var> be <var>form</var>'s <span>node document</span>.</p></li>
<li id="sandboxSubmitBlocked"><p>If <var>form document</var>'s <span>active sandboxing flag
set</span> has its <span>sandboxed forms browsing context flag</span> set, then return.</p></li>
<li>
<p>If <var>submitted from <code data-x="dom-form-submit">submit()</code> method</var> is false,
then:</p>
<ol>
<li><p>If <var>form</var>'s <span>firing submission events</span> is true, then
return.</p></li>
<li><p>Set <var>form</var>'s <span>firing submission events</span> to true.</p></li>
<li><p>For each element <var>field</var> in the list of
<span data-x="category-submit">submittable elements</span> whose <span>form owner</span> is
<var>form</var>, set <var>field</var>'s <span>user validity</span> to true.
<li>
<p>If the <var>submitter</var> element's <span data-x="concept-fs-novalidate">no-validate
state</span> is false, then <span>interactively validate the constraints</span> of
<var>form</var> and examine the result. If the result is negative (i.e., the constraint
validation concluded that there were invalid fields and probably informed the user of this),
then:</p>
<ol>
<li><p>Set <var>form</var>'s <span>firing submission events</span> to false.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>submitterButton</var> be null if <var>submitter</var> is <var>form</var>.
Otherwise, let <var>submitterButton</var> be <var>submitter</var>.</p></li>
<li><p>Let <var>shouldContinue</var> be the result of <span data-x="concept-event-fire">firing an
event</span> named <code data-x="event-submit">submit</code> at <var>form</var> using
<code>SubmitEvent</code>, with the <code data-x="dom-SubmitEvent-submitter">submitter</code>
attribute initialized to <var>submitterButton</var>, the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true, and the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true.</p></li>
<li><p>Set <var>form</var>'s <span>firing submission events</span> to false.</p></li>
<li><p>If <var>shouldContinue</var> is false, then return.</p></li>
<li>
<p>If <var>form</var> <span>cannot navigate</span>, then return.</p>
<p class="note"><span>Cannot navigate</span> is run again as dispatching the <code
data-x="event-submit">submit</code> event could have changed the outcome.</p>
</li>
</ol>
</li>
<li><p>Let <var>encoding</var> be the result of <span>picking an encoding for the
form</span>.</p>
<li><p>Let <var>entry list</var> be the result of <span>constructing the entry list</span> with
<var>form</var>, <var>submitter</var>, and <var>encoding</var>.</p></li>
<li><p><span>Assert</span>: <var>entry list</var> is not null.</p></li>
<li>
<p>If <var>form</var> <span>cannot navigate</span>, then return.</p>
<p class="note"><span>Cannot navigate</span> is run again as dispatching the <code
data-x="event-formdata">formdata</code> event in <span>constructing the entry list</span>
could have changed the outcome.</p>
</li>
<li><p>Let <var>method</var> be the <var>submitter</var> element's <span
data-x="concept-fs-method">method</span>.</p></li>
<li>
<p>If <var>method</var> is <span data-x="attr-fs-method-dialog">dialog</span>, then:
<ol>
<li><p>If <var>form</var> does not have an ancestor <code>dialog</code> element, then
return.</p></li>
<li><p>Let <var>subject</var> be <var>form</var>'s nearest ancestor <code>dialog</code>
element.</p></li>
<li><p>Let <var>result</var> be null.</p></li>
<li>
<p>If <var>submitter</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-image">Image Button</span> state, then:</p>
<ol>
<li><p>Let (<var>x</var>, <var>y</var>) be the <span
data-x="concept-input-type-image-coordinate">selected coordinate</span>.</p></li>
<li><p>Set <var>result</var> to the concatenation of <var>x</var>, "<code
data-x="">,</code>", and <var>y</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>submitter</var> has a <span data-x="concept-fe-value">value</span>,
then set <var>result</var> to that <span data-x="concept-fe-value">value</span>.</p></li>
<li><p><span>Close the dialog</span> <var>subject</var> with <var>result</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>action</var> be the <var>submitter</var> element's <span
data-x="concept-fs-action">action</span>.</p></li>
<li>
<p>If <var>action</var> is the empty string, let <var>action</var> be the <span
data-x="concept-document-url">URL</span> of the <var>form document</var>.</p>
<!-- Don't ask me why. But that's what IE does. It even treats action="" differently from
action=" " or action="#" (the latter two resolve to the base URL, the first one resolves to the
doc URL). And other browsers concur. It is even required, see e.g.
https://bugs.webkit.org/show_bug.cgi?id=7763
https://bugzilla.mozilla.org/show_bug.cgi?id=297761
-->
</li>
<li><p>Let <var>parsed action</var> be the result of <span>encoding-parsing a URL</span> given
<var>action</var>, relative to <var>submitter</var>'s <span>node document</span>.</p></li>
<li><p>If <var>parsed action</var> is failure, then return.</p></li>
<li><p>Let <var>scheme</var> be the <span data-x="concept-url-scheme">scheme</span> of
<var>parsed action</var>.</p></li>
<li><p>Let <var>enctype</var> be the <var>submitter</var> element's <span
data-x="concept-fs-enctype">enctype</span>.</p></li>
<li><p>Let <var>formTarget</var> be null.</p></li>
<li><p>If the <var>submitter</var> element is a <span data-x="concept-submit-button">submit
button</span> and it has a <code data-x="attr-fs-formtarget">formtarget</code> attribute, then
set <var>formTarget</var> to the <code data-x="attr-fs-formtarget">formtarget</code> attribute
value.</p></li>
<li><p>Let <var>target</var> be the result of <span data-x="get an element's target">getting an
element's target</span> given <var>submitter</var>'s <span>form owner</span> and
<var>formTarget</var>.</p></li>
<li><p>Let <var>noopener</var> be the result of <span data-x="get an element's noopener">getting
an element's noopener</span> with <var>form</var>, <var>parsed action</var>, and
<var>target</var>.</p></li>
<li><p>Let <var>targetNavigable</var> be the first return value of applying <span>the rules for
choosing a navigable</span> given <var>target</var>, <var>form</var>'s <span>node
navigable</span>, and <var>noopener</var>.</p></li>
<li><p>If <var>targetNavigable</var> is null, then return.</p></li>
<li><p>Let <var>historyHandling</var> be "<code
data-x="NavigationHistoryBehavior-auto">auto</code>".</p></li>
<li><p>If <var>form document</var> equals <var>targetNavigable</var>'s <span
data-x="nav-document">active document</span>, and <var>form document</var> has not yet
<span>completely loaded</span>, then set <var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li>
<p>Select the appropriate row in the table below based on <var>scheme</var> as given by the
first cell of each row. Then, select the appropriate cell on that row based on <var>method</var>
as given in the first cell of each column. Then, jump to the steps named in that cell and
defined below the table.</p>
<table>
<thead>
<tr>
<td>
<th> <span data-x="attr-fs-method-GET">GET</span>
<th> <span data-x="attr-fs-method-POST">POST</span>
<tbody>
<tr>
<th> <code data-x="">http</code>
<td> <span data-x="submit-mutate-action">Mutate action URL</span>
<td> <span data-x="submit-body">Submit as entity body</span>
<tr>
<th> <code data-x="">https</code>
<td> <span data-x="submit-mutate-action">Mutate action URL</span>
<td> <span data-x="submit-body">Submit as entity body</span>
<tr>
<th> <code data-x="">ftp</code>
<td> <span data-x="submit-get-action">Get action URL</span>
<td> <span data-x="submit-get-action">Get action URL</span>
<tr>
<th> <code data-x="">javascript</code>
<td> <span data-x="submit-get-action">Get action URL</span>
<td> <span data-x="submit-get-action">Get action URL</span>
<tr>
<th> <code data-x="">data</code>
<td> <span data-x="submit-mutate-action">Mutate action URL</span>
<td> <span data-x="submit-get-action">Get action URL</span>
<tr>
<th> <code data-x="">mailto</code>
<td> <span data-x="submit-mailto-headers">Mail with headers</span>
<td> <span data-x="submit-mailto-body">Mail as body</span>
</table>
<p>If <var>scheme</var> is not one of those listed in this table, then the behavior is
not defined by this specification. User agents should, in the absence of another specification
defining this, act in a manner analogous to that defined in this specification for similar
schemes.</p>
<p>Each <code>form</code> element has a <dfn>planned navigation</dfn>, which is either null or a
<span data-x="concept-task">task</span>; when the <code>form</code> is first created, its
<span>planned navigation</span> must be set to null. In the behaviors described below, when the
user agent is required to <dfn>plan to navigate</dfn> to a <span>URL</span> <var>url</var> given
an optional <span>POST resource</span>-or-null <var>postResource</var> (default null), it must
run the following steps:</p>
<ol>
<li><p>Let <var>referrerPolicy</var> be the empty string.</p></li>
<li><p>If the <code>form</code> element's <a href="#linkTypes">link types</a> include the <code
data-x="rel-noreferrer">noreferrer</code> keyword, then set <var>referrerPolicy</var> to "<code
data-x="">no-referrer</code>".</p></li>
<li><p>If the <code>form</code> has a non-null <span>planned navigation</span>, remove it from
its <span>task queue</span>.</p></li>
<li>
<p><span>Queue an element task</span> on the <span>DOM manipulation task source</span> given
the <code>form</code> element and the following steps:</p>
<ol>
<li><p>Set the <code>form</code>'s <span>planned navigation</span> to null.</p></li>
<li><p><span>Navigate</span><!--DONAV form--> <var>targetNavigable</var> to <var>url</var>
using the <code>form</code> element's <span>node document</span>, with <var
data-x="navigation-hh">historyHandling</var> set to <var>historyHandling</var>, <i
data-x="navigation-user-involvement">userInvolvement</i> set to <var>userInvolvement</var>,
<i data-x="navigation-source-element">sourceElement</i> set to <var>submitter</var>,
<i data-x="navigation-referrer-policy">referrerPolicy</i> set to <var>referrerPolicy</var>,
<i data-x="navigation-resource">documentResource</i> set to <var>postResource</var>, and <i
data-x="navigation-form-data-entry-list">formDataEntryList</i> set to <var>entry
list</var>.</p>
</ol>
</li>
<li><p>Set the <code>form</code>'s <span>planned navigation</span> to the just-queued <span
data-x="concept-task">task</span>.</p>
</ol>
<p>The behaviors are as follows:</p>
<dl>
<dt><dfn data-x="submit-mutate-action">Mutate action URL</dfn>
<dd>
<p>Let <var>pairs</var> be the result of <span data-x="convert to a list of name-value
pairs">converting to a list of name-value pairs</span> with <var>entry list</var>.</p>
<p>Let <var>query</var> be the result of running the
<span><code>application/x-www-form-urlencoded</code> serializer</span> with <var>pairs</var>
and <var>encoding</var>.</p>
<p>Set <var>parsed action</var>'s <span data-x="concept-url-query">query</span>
component to <var>query</var>.</p>
<p><span>Plan to navigate</span> to <var>parsed action</var>.</p>
</dd>
<dt><dfn data-x="submit-body">Submit as entity body</dfn>
<dd>
<p><span>Assert</span>: <var>method</var> is <span
data-x="attr-fs-method-post">POST</span>.</p>
<p>Switch on <var>enctype</var>:
<dl class="switch">
<dt><code data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code></dt>
<dd>
<p>Let <var>pairs</var> be the result of <span data-x="convert to a list of name-value
pairs">converting to a list of name-value pairs</span> with <var>entry list</var>.</p>
<p>Let <var>body</var> be the result of running the
<span><code>application/x-www-form-urlencoded</code> serializer</span> with <var>pairs</var>
and <var>encoding</var>.</p>
<p>Set <var>body</var> to the result of <span data-x="UTF-8 encode">encoding</span>
<var>body</var>.</p>
<p>Let <var>mimeType</var> be `<code>application/x-www-form-urlencoded</code>`.</p>
</dd>
<dt><code data-x="attr-fs-enctype-formdata">multipart/form-data</code></dt>
<dd>
<p>Let <var>body</var> be the result of running the <span><code
data-x="">multipart/form-data</code> encoding algorithm</span> with <var>entry list</var>
and <var>encoding</var>.</p>
<p>Let <var>mimeType</var> be the <span data-x="isomorphic encode">isomorphic
encoding</span> of the concatenation of "<code
data-x="">multipart/form-data; boundary=</code>" and the <span><code
data-x="">multipart/form-data</code> boundary string</span> generated by the <span><code
data-x="">multipart/form-data</code> encoding algorithm</span>.</p>
</dd>
<dt><code data-x="attr-fs-enctype-text">text/plain</code></dt>
<dd>
<p>Let <var>pairs</var> be the result of <span data-x="convert to a list of name-value
pairs">converting to a list of name-value pairs</span> with <var>entry list</var>.</p>
<p>Let <var>body</var> be the result of running the <span><code data-x="">text/plain</code>
encoding algorithm</span> with <var>pairs</var>.</p>
<p>Set <var>body</var> to the result of <span data-x="encode">encoding</span>
<var>body</var> using <var>encoding</var>.</p>
<p>Let <var>mimeType</var> be `<code>text/plain</code>`.</p>
</dd>
</dl>
<p><span>Plan to navigate</span> to <var>parsed action</var> given a <span>POST
resource</span> whose <span data-x="post-resource-request-body">request body</span> is
<var>body</var> and <span data-x="post-resource-request-content-type">request
content-type</span> is <var>mimeType</var>.</p>
</dd>
<dt><dfn data-x="submit-get-action">Get action URL</dfn>
<dd>
<p><span>Plan to navigate</span> to <var>parsed action</var>.</p>
<p class="note"><var>entry list</var> is discarded.</p>
</dd>
<dt><dfn data-x="submit-mailto-headers">Mail with headers</dfn>
<dd>
<p>Let <var>pairs</var> be the result of <span data-x="convert to a list of name-value
pairs">converting to a list of name-value pairs</span> with <var>entry list</var>.</p>
<p>Let <var>headers</var> be the result of running the
<span><code>application/x-www-form-urlencoded</code> serializer</span> with <var>pairs</var>
and <var>encoding</var>.</p>
<p>Replace occurrences of U+002B PLUS SIGN characters (+) in <var>headers</var> with
the string "<code data-x="">%20</code>".</p>
<p>Set <var>parsed action</var>'s <span data-x="concept-url-query">query</span> to
<var>headers</var>.</p>
<p><span>Plan to navigate</span> to <var>parsed action</var>.</p>
</dd>
<dt><dfn data-x="submit-mailto-body">Mail as body</dfn>
<dd>
<p>Let <var>pairs</var> be the result of <span data-x="convert to a list of name-value
pairs">converting to a list of name-value pairs</span> with <var>entry list</var>.</p>
<p>Switch on <var>enctype</var>:
<dl class="switch">
<dt><code data-x="attr-fs-enctype-text">text/plain</code></dt>
<dd>
<p>Let <var>body</var> be the result of running the <span><code data-x="">text/plain</code>
encoding algorithm</span> with <var>pairs</var>.</p>
<p>Set <var>body</var> to the result of running <span>UTF-8 percent-encode</span> on
<var>body</var> using the <span>default encode set</span>. <ref>URL</ref></p>
</dd>
<dt>Otherwise</dt>
<dd><p>Let <var>body</var> be the result of running the
<span><code>application/x-www-form-urlencoded</code> serializer</span> with <var>pairs</var>
and <var>encoding</var>.</p></dd>
</dl>
<p>If <var>parsed action</var>'s <span data-x="concept-url-query">query</span> is null, then
set it to the empty string.
<p>If <var>parsed action</var>'s <span data-x="concept-url-query">query</span> is not the
empty string, then append a single U+0026 AMPERSAND character (&) to it.
<p>Append "<code data-x="">body=</code>" to <var>parsed action</var>'s <span
data-x="concept-url-query">query</span>.</p>
<p>Append <var>body</var> to <var>parsed action</var>'s <span
data-x="concept-url-query">query</span>.</p>
<p><span>Plan to navigate</span> to <var>parsed action</var>.</p>
</dd>
</dl>
</li>
</ol>
<h5 id="constructing-form-data-set">Constructing the entry list</h5>
<p>An <dfn export>entry list</dfn> is a <span>list</span> of <span data-x="form
entry">entries</span>, typically representing the contents of a form. An <dfn data-x="form entry"
for="entry list" export>entry</dfn> is a tuple consisting of a <dfn data-x="form entry name"
for="entry list/entry" export>name</dfn> (a <span>scalar value string</span>) and a <dfn
data-x="form entry value" for="entry list/entry" export>value</dfn> (either a <span>scalar value
string</span> or a <code>File</code> object).</p>
<p id="append-an-entry">To <dfn export for="entry list">create an entry</dfn> given a string
<var>name</var>, a string or <code>Blob</code> object <var>value</var>, and optionally a
<span>scalar value string</span> <var>filename</var>:</p>
<ol>
<li><p>Set <var>name</var> to the result of <span data-x="convert">converting</span>
<var>name</var> into a <span>scalar value string</span>.</p></li>
<li><p>If <var>value</var> is a string, then set <var>value</var> to the result of <span
data-x="convert">converting</span> <var>value</var> into a <span>scalar value
string</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>If <var>value</var> is not a <code>File</code> object, then set <var>value</var> to a
new <code>File</code> object, representing the same bytes, whose <code
data-x="dom-File-name">name</code> attribute value is "<code data-x="">blob</code>".</p></li>
<!-- XXX at some point File API should get internal slots for this -->
<li><p>If <var>filename</var> is given, then set <var>value</var> to a new <code>File</code>
object, representing the same bytes, whose <code data-x="dom-File-name">name</code> attribute
is <var>filename</var>.</p></li>
</ol>
<p class="note">These operations will create a new <code>File</code> object if either
<var>filename</var> is given or the passed <code>Blob</code> is not a <code>File</code> object.
In those cases, the identity of the passed <code>Blob</code> object is not kept.</p>
</li>
<li><p>Return an <span data-x="form entry">entry</span> whose <span data-x="form entry
name">name</span> is <var>name</var> and whose <span data-x="form entry value">value</span> is
<var>value</var>.</p></li>
</ol>
<p>To <dfn id="constructing-the-form-data-set" export data-lt="constructing the entry list"
data-x="constructing the entry list">construct the entry list</dfn> given a <var>form</var>, an
optional <var>submitter</var> (default null), and an optional <var>encoding</var> (default
<span>UTF-8</span>):
<ol>
<li><p>If <var>form</var>'s <span>constructing entry list</span> is true, then return
null.</p></li>
<li><p>Set <var>form</var>'s <span>constructing entry list</span> to true.</p></li>
<li><p>Let <var>controls</var> be a list of all the <span
data-x="category-submit">submittable elements</span> whose <span>form owner</span> is <var>form</var>, in <span>tree order</span>.</p></li>
<li><p>Let <var>entry list</var> be a new empty <span>entry list</span>.</p></li>
<li>
<p>For each element <var>field</var> in <var>controls</var>, in <span>tree order</span>:</p>
<ol>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>field</var> has a <code>datalist</code> element ancestor;</p></li>
<li><p><var>field</var> is <span data-x="concept-fe-disabled">disabled</span>;</p></li>
<li><p><var>field</var> is a <span data-x="concept-button">button</span> but it is not
<var>submitter</var>;</p></li>
<li><p><var>field</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-checkbox">Checkbox</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> is false; or</p></li>
<li><p><var>field</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-radio">Radio Button</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> is false,</p></li>
</ul>
<p>then <span>continue</span>.</p>
</li>
<li>
<p>If the <var>field</var> element is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-image">Image Button</span> state, then:</p>
<ol>
<li><p>If the <var>field</var> element is not <var>submitter</var>, then
<span>continue</span>.</p></li>
<li><p>If the <var>field</var> element has a <code data-x="attr-fe-name">name</code>
attribute specified and its value is not the empty string, let <var>name</var> be that value
followed by U+002E (.). Otherwise, let <var>name</var> be the empty string.</p></li>
<li><p>Let <var>name<sub>x</sub></var> be the concatenation of <var>name</var> and
U+0078 (x).</p></li>
<li><p>Let <var>name<sub>y</sub></var> be the concatenation of <var>name</var> and
U+0079 (y).</p></li>
<li><p>Let (<var>x</var>, <var>y</var>) be the <span
data-x="concept-input-type-image-coordinate">selected coordinate</span>.</p></li>
<li><p><span>Create an entry</span> with <var>name<sub>x</sub></var> and <var>x</var>, and
<span data-x="list append">append</span> it to <var>entry list</var>.</p></li>
<li><p><span>Create an entry</span> with <var>name<sub>y</sub></var> and <var>y</var>, and
<span data-x="list append">append</span> it to <var>entry list</var>.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>If the <var>field</var> is a <span>form-associated custom element</span>, then perform
the <span data-x="face-entry-construction">entry construction algorithm</span> given
<var>field</var> and <var>entry list</var>, then <span>continue</span>.</p></li>
<li><p>If either the <var>field</var> element does not have a
<code data-x="attr-fe-name">name</code> attribute specified, or its
<code data-x="attr-fe-name">name</code> attribute's value is the empty string, then
<span>continue</span>.</p></li>
<li><p>Let <var>name</var> be the value of the <var>field</var> element's
<code data-x="attr-fe-name">name</code> attribute.</p></li>
<li><p>If the <var>field</var> element is a <code>select</code> element, then for each
<code>option</code> element in the <code>select</code> element's <span
data-x="concept-select-option-list">list of options</span> whose <span
data-x="concept-option-selectedness">selectedness</span> is true and that is not <span
data-x="concept-option-disabled">disabled</span>, <span>create an entry</span> with
<var>name</var> and the <span data-x="concept-option-value">value</span> of the
<code>option</code> element, and <span data-x="list append">append</span> it to <var>entry
list</var>.</p></li>
<li>
<p>Otherwise, if the <var>field</var> element is an <code>input</code> element whose
<code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-checkbox">Checkbox</span> state or the <span
data-x="attr-input-type-radio">Radio Button</span> state, then:</p>
<ol>
<li><p>If the <var>field</var> element has a <code
data-x="attr-input-value">value</code> attribute specified, then let <var>value</var>
be the value of that attribute; otherwise, let <var>value</var> be the string "<code
data-x="">on</code>".</p></li>
<li><p><span>Create an entry</span> with <var>name</var> and <var>value</var>, and <span
data-x="list append">append</span> it to <var>entry list</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if the <var>field</var> element is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-file">File Upload</span> state, then:</p>
<ol>
<li><p>If there are no <span data-x="concept-input-type-file-selected">selected files</span>,
then <span>create an entry</span> with <var>name</var> and a new <code>File</code> object
with an empty name, <code>application/octet-stream</code> as type, and an empty body, and
<span data-x="list append">append</span> it to <var>entry list</var>.</p></li>
<!-- https://bugzilla.mozilla.org/show_bug.cgi?id=529859 -->
<li><p>Otherwise, for each file in <span data-x="concept-input-type-file-selected">selected
files</span>, <span>create an entry</span> with <var>name</var> and a <code>File</code>
object representing the file, and <span data-x="list append">append</span> it to <var>entry
list</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if the <var>field</var> element is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-hidden">Hidden</span> state and <var>name</var> is an <span>ASCII
case-insensitive</span> match for "<code data-x="attr-fe-name-charset">_charset_</code>":</p>
<ol>
<li><p>Let <var>charset</var> be the <span data-x="encoding name">name</span> of
<var>encoding</var>.</p></li>
<li><p><span>Create an entry</span> with <var>name</var> and <var>charset</var>, and <span
data-x="list append">append</span> it to <var>entry list</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, <span>create an entry</span> with <var>name</var> and the <span
data-x="concept-fe-value">value</span> of the <var>field</var> element, and <span
data-x="list append">append</span> it to <var>entry list</var>.</p></li>
<li>
<p>If the element has a <code data-x="attr-fe-dirname">dirname</code> attribute, that
attribute's value is not the empty string, and the element is an <span
data-x="auto-directionality form-associated elements">auto-directionality form-associated
element</span>:
<ol>
<li><p>Let <var>dirname</var> be the value of the element's <code
data-x="attr-fe-dirname">dirname</code> attribute.</p></li>
<li><p>Let <var>dir</var> be the string "<code data-x="">ltr</code>" if <span>the
directionality</span> of the element is '<span data-x="concept-ltr">ltr</span>', and "<code
data-x="">rtl</code>" otherwise (i.e., when <span>the directionality</span> of the element is
'<span data-x="concept-rtl">rtl</span>').</p></li>
<li><p><span>Create an entry</span> with <var>dirname</var> and <var>dir</var>, and <span
data-x="list append">append</span> it to <var>entry list</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>form data</var> be a new <code>FormData</code> object associated with
<var>entry list</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named
<code data-x="event-formdata">formdata</code> at <var>form</var> using
<code>FormDataEvent</code>, with the <code data-x="dom-FormDataEvent-formData">formData</code>
attribute initialized to <var>form data</var> and the
<code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
<li><p>Set <var>form</var>'s <span>constructing entry list</span> to false.</p></li>
<li><p>Return a <span data-x="list clone">clone</span> of <var>entry list</var>.</p></li>
</ol>
</div>
<div w-nodev>
<h5>Selecting a form submission encoding</h5>
<p>If the user agent is to <dfn data-x="picking an encoding for the form">pick an encoding for a
form</dfn>, it must run the following steps:</p>
<ol>
<li><p>Let <var>encoding</var> be the <span>document's character encoding</span>.</p></li>
<li>
<p>If the <code>form</code> element has an <code
data-x="attr-form-accept-charset">accept-charset</code> attribute, set <var>encoding</var> to
the return value of running these substeps:</p>
<ol>
<li><p>Let <var>input</var> be the value of the <code>form</code> element's <code
data-x="attr-form-accept-charset">accept-charset</code> attribute.</p></li>
<li><p>Let <var>candidate encoding labels</var> be the result of <span data-x="split a string
on ASCII whitespace">splitting <var>input</var> on ASCII whitespace</span>.</p></li>
<li><p>Let <var>candidate encodings</var> be an empty list of <span data-x="encoding">character
encodings</span>.</p></li>
<li><p>For each token in <var>candidate encoding labels</var> in turn (in the order in which
they were found in <var>input</var>), <span data-x="getting an encoding">get an encoding</span>
for the token and, if this does not result in failure, append the <span>encoding</span> to
<var>candidate encodings</var>.</p></li>
<li><p>If <var>candidate encodings</var> is empty, return <span>UTF-8</span>.</p></li>
<li><p>Return the first encoding in <var>candidate encodings</var>.</p></li>
</ol>
</li>
<li><p>Return the result of <span data-x="get an output encoding">getting an output
encoding</span> from <var>encoding</var>.</p></li>
</ol>
</div>
<div w-nodev>
<h5>Converting an entry list to a list of name-value pairs</h5>
<p>The <code>application/x-www-form-urlencoded</code> and <code data-x="text/plain encoding
algorithm">text/plain</code> encoding algorithms take a list of name-value pairs, where the values
must be strings, rather than an <span>entry list</span> where the value can be a
<code>File</code>. The following algorithm performs the conversion.</p>
<p>To <dfn>convert to a list of name-value pairs</dfn> an <span>entry list</span> <var>entry
list</var>, run these steps:</p>
<ol>
<li><p>Let <var>list</var> be an empty <span>list</span> of name-value pairs.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>entry list</var>:</p>
<ol>
<li><p>Let <var>name</var> be <var>entry</var>'s <span data-x="form entry name">name</span>,
with every occurrence of U+000D (CR) not followed by U+000A (LF), and every occurrence of
U+000A (LF) not preceded by U+000D (CR), replaced by a string consisting of U+000D (CR) and
U+000A (LF).</p></li>
<li><p>If <var>entry</var>'s <span data-x="form entry value">value</span> is a
<code>File</code> object, then let <var>value</var> be <var>entry</var>'s <span data-x="form
entry value">value</span>'s <code data-x="dom-file-name">name</code>. Otherwise, let
<var>value</var> be <var>entry</var>'s <span data-x="form entry value">value</span>.</p></li>
<li><p>Replace every occurrence of U+000D (CR) not followed by U+000A (LF), and every occurrence
of U+000A (LF) not preceded by U+000D (CR), in <var>value</var>, by a string consisting of
U+000D (CR) and U+000A (LF).</p></li>
<li><p><span data-x="list append">Append</span> to <var>list</var> a new name-value pair whose
name is <var>name</var> and whose value is <var>value</var>.</p></li>
</ol>
</li>
<li><p>Return <var>list</var>.</p></li>
</ol>
</div>
<h5>URL-encoded form data</h5>
<p id="application-x-www-form-urlencoded-encoding-algorithm"><span
id="application/x-www-form-urlencoded-encoding-algorithm"></span>See <cite>URL</cite> for details
on <code>application/x-www-form-urlencoded</code>. <ref>URL</ref></p>
<h5>Multipart form data</h5>
<div w-nodev>
<!-- https://hixie.ch/tests/adhoc/html/forms/submission/multipart_form-data/ -->
<!-- NOTE: This algorithm is also used by
https://fetch.spec.whatwg.org/#concept-bodyinit-extract -->
<p>The <dfn export><code>multipart/form-data</code> encoding algorithm</dfn>, given an <span>entry
list</span> <var>entry list</var> and an <span>encoding</span> <var>encoding</var>, is as
follows:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>entry list</var>:</p>
<ol>
<li><p>Replace every occurrence of U+000D (CR) not followed by U+000A (LF), and every
occurrence of U+000A (LF) not preceded by U+000D (CR), in <var>entry</var>'s <span data-x="form
entry name">name</span>, by a string consisting of a U+000D (CR) and U+000A (LF).</p></li>
<li><p>If <var>entry</var>'s <span data-x="form entry value">value</span> is not a
<code>File</code> object, then replace every occurrence of U+000D (CR) not followed by U+000A
(LF), and every occurrence of U+000A (LF) not preceded by U+000D (CR), in <var>entry</var>'s
<span data-x="form entry value">value</span>, by a string consisting of a U+000D (CR) and
U+000A (LF).</p></li>
</ol>
</li>
<li>
<p>Return the byte sequence resulting from encoding the <var>entry list</var> using the rules
described by RFC 7578, <cite>Returning Values from Forms: <code
data-x="">multipart/form-data</code></cite>, given the following conditions:
<ref>RFC7578</ref></p>
<ul>
<li><p>Each <span data-x="form entry">entry</span> in <var>entry list</var> is a <i>field</i>,
the <span data-x="form entry name">name</span> of the entry is the <i>field name</i> and the
<span data-x="form entry value">value</span> of the entry is the <i>field value</i>.</p></li>
<li><p>The order of parts must be the same as the order of fields in <var>entry list</var>.
Multiple entries with the same name must be treated as distinct fields.</p></li>
<li><p>Field names, field values for non-file fields, and filenames for file fields, in the
generated <code>multipart/form-data</code> resource must be set to the result of <span
data-x="encode">encoding</span> the corresponding entry's name or value with
<var>encoding</var>, converted to a byte sequence.</p></li>
<li><p>For field names and filenames for file fields, the result of the encoding in the
previous bullet point must be escaped by replacing any 0x0A (LF) bytes with the byte sequence
`<code data-x="">%0A</code>`, 0x0D (CR) with `<code data-x="">%0D</code>` and 0x22 (") with
`<code data-x="">%22</code>`. The user agent must not perform any other escapes.</p></li>
<li><p>The parts of the generated <code>multipart/form-data</code> resource that correspond to
non-file fields must not have a `<code>Content-Type</code>` header specified.</p></li>
<li><p>The boundary used by the user agent in generating the return value of this algorithm is
the <dfn export><code>multipart/form-data</code> boundary string</dfn>. (This value is used to
generate the MIME type of the form submission payload generated by this algorithm.)</p></li>
</ul>
</li>
</ol>
</div>
<p>For details on how to interpret <code>multipart/form-data</code> payloads, see RFC 7578.
<ref>RFC7578</ref></p>
<h5>Plain text form data</h5>
<div w-nodev>
<p>The <dfn><code data-x="">text/plain</code> encoding algorithm</dfn>, given a list of name-value
pairs <var>pairs</var>, is as follows:</p>
<ol>
<li><p>Let <var>result</var> be the empty string.</p></li>
<li>
<p>For each <var>pair</var> in <var>pairs</var>:</p>
<ol>
<li><p>Append <var>pair</var>'s name to <var>result</var>.</p></li>
<li><p>Append a single U+003D EQUALS SIGN character (=) to <var>result</var>.</p></li>
<li><p>Append <var>pair</var>'s value to <var>result</var>.</p></li>
<li><p>Append a U+000D CARRIAGE RETURN (CR) U+000A LINE FEED (LF) character pair to <var>result</var>.</p></li>
</ol>
</li>
<li><p>Return <var>result</var>.</p></li>
</ol>
</div>
<p>Payloads using the <code>text/plain</code> format are intended to be human readable. They are
not reliably interpretable by computer, as the format is ambiguous (for example, there is no way
to distinguish a literal newline in a value from the newline at the end of the value).</p>
<h5>The <code>SubmitEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>SubmitEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>SubmitEventInit</span> eventInitDict = {});
readonly attribute <span>HTMLElement</span>? <span data-x="dom-SubmitEvent-submitter">submitter</span>;
};
dictionary <dfn dictionary>SubmitEventInit</dfn> : <span>EventInit</span> {
<span>HTMLElement</span>? submitter = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span data-x="dom-SubmitEvent-submitter">submitter</span></code></dt>
<dd><p>Returns the element representing the <span data-x="concept-submit-button">submit
button</span> that triggered the <span>form submission</span>, or null if the submission was not
triggered by a button.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="SubmitEvent"><code
data-x="dom-SubmitEvent-submitter">submitter</code></dfn> attribute must return the value it was
initialized to.</p>
</div>
<h5>The <code>FormDataEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>FormDataEvent</dfn> : <span>Event</span> {
constructor(DOMString type, <span>FormDataEventInit</span> eventInitDict);
readonly attribute <span>FormData</span> <span data-x="dom-FormDataEvent-formData">formData</span>;
};
dictionary <dfn dictionary>FormDataEventInit</dfn> : <span>EventInit</span> {
required <span>FormData</span> formData;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span data-x="dom-FormDataEvent-formData">formData</span></code></dt>
<dd>
<p>Returns a <code>FormData</code> object representing names and values of elements associated
to the target <code>form</code>. Operations on the <code>FormData</code> object will affect form
data to be submitted.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="FormDataEvent"><code
data-x="dom-FormDataEvent-formData">formData</code></dfn> attribute must return the value it was
initialized to. It represents a <code>FormData</code> object associated to the <span>entry
list</span> that is <span data-x="constructing the entry list">constructed</span> when the
<code>form</code> is submitted.</p>
<h4>Resetting a form</h4>
<p>When a <code>form</code> element <var>form</var> is <dfn
data-x="concept-form-reset">reset</dfn>, run these steps:</p>
<ol>
<li><p>Let <var>reset</var> be the result of <span data-x="concept-event-fire">firing an
event</span> named <code data-x="event-reset">reset</code> at <var>form</var>, with the <code
data-x="dom-Event-bubbles">bubbles</code> and <code
data-x="dom-Event-cancelable">cancelable</code> attributes initialized to true.</p></li>
<li><p>If <var>reset</var> is true, then invoke the <span
data-x="concept-form-reset-control">reset algorithm</span> of each <span
data-x="category-reset">resettable element</span> whose <span>form owner</span> is
<var>form</var>.</p></li>
</ol>
<p>Each <span data-x="category-reset">resettable element</span> defines its own <dfn
data-x="concept-form-reset-control">reset algorithm</dfn>. Changes made to form controls as part of
these algorithms do not count as changes caused by the user (and thus, e.g., do not cause <code
data-x="event-input">input</code> events to fire).</p>
</div>
<h3 split-filename="interactive-elements" id="interactive-elements">Interactive elements</h3>
<h4>The <dfn element><code>details</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Interactive content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>One <code>summary</code> element followed by <span>flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-details-name">name</code></dd>
<dd><code data-x="attr-details-open">open</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-details">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-details">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDetailsElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-details-name">name</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-details-open">open</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDetailsElement</code>.</dd>
</dl>
<p>The <code>details</code> element <span>represents</span> a disclosure widget from which the
user can obtain additional information or controls.</p>
<p class="note">As with all HTML elements, it is not conforming to use the <code>details</code>
element when attempting to represent another type of control. For example, tab widgets and
menu widgets are not disclosure widgets, so abusing the <code>details</code> element to
implement these patterns is incorrect.</p>
<p class="note">The <code>details</code> element is not appropriate for footnotes. Please see <a
href="#footnotes">the section on footnotes</a> for details on how to mark up footnotes.</p>
<p>The <span w-nodev>first</span> <code>summary</code> element child of the element, if any,
<span>represents</span> the summary or legend of the details. <span w-nodev>If there is no
child <code>summary</code> element, the user agent should provide its own legend (e.g.
"Details").</span></p>
<p>The rest of the element's contents <span>represents</span> the additional information or
controls.</p>
<p>The <dfn element-attr for="details"><code data-x="attr-details-name">name</code></dfn> content
attribute gives the name of the group of related <code>details</code> elements that the element is
a member of. Opening one member of this group causes other members of the group to close. If the
attribute is specified, its value must not be the empty string.</p>
<p>Before using this feature, authors should consider whether this grouping of related
<code>details</code> elements into an exclusive accordion is helpful or harmful to users.
While using an exclusive accordion can reduce the maximum amount of space that a set of content
can occupy, it can also frustrate users who have to open many items to find what they want or
users who want to look at the contents of multiple items at the same time.</p>
<p>A document must not contain more than one <code>details</code> element in the same
<span>details name group</span> that has the <code data-x="attr-details-open">open</code>
attribute present. Authors must not use script to add <code>details</code> elements to a document
in a way that would cause a <span>details name group</span> to have more than one
<code>details</code> element with the <code data-x="attr-details-open">open</code> attribute
present.</p>
<p class="note">The group of elements that is created by a common <code
data-x="attr-details-name">name</code> attribute is exclusive, meaning that at most one of the
<code>details</code> elements can be open at once. While this exclusivity is enforced by user
agents, the resulting enforcement immediately changes the <code
data-x="attr-details-open">open</code> attributes in the markup. This requirement on authors
forbids such misleading markup.</p>
<p>A document must not contain a <code>details</code> element that is a descendant of another
<code>details</code> element in the same <span>details name group</span>.</p>
<p>Documents that use the <code data-x="attr-details-name">name</code> attribute to group multiple
related <code>details</code> elements should keep those related elements together in a containing
element (such as a <code>section</code> element or <code>article</code> element). When it makes
sense for the group to be introduced with a heading, authors should put that heading in a <span
data-x="concept-heading">heading</span> element at the start of the containing element.</p>
<p class="note">Visually and programmatically grouping related elements together can be important
for accessible user experiences. This can help users understand the relationship between such
elements. When related elements are in disparate sections of a web page rather than being grouped,
the elements' relationships to each other can be less discoverable or understandable.</p>
<p>The <dfn element-attr for="details"><code data-x="attr-details-open">open</code></dfn> content
attribute is a <span>boolean attribute</span>. If present, it indicates that both the summary and
the additional information is to be shown to the user. If the attribute is absent, only the
summary is to be shown.</p>
<div w-nodev>
<p>When the element is created, if the attribute is absent, the additional information should be
hidden; if the attribute is present, that information should be shown. Subsequently, if the
attribute is removed, then the information should be hidden; if the attribute is added, the
information should be shown.</p>
<p>The user agent should allow the user to request that the additional information be shown or
hidden. To honor a request for the details to be shown, the user agent must <span
data-x="concept-element-attributes-set-value">set</span> the <code
data-x="attr-details-open">open</code> attribute on the element to the empty string. To honor a
request for the information to be hidden, the user agent must <span
data-x="concept-element-attributes-remove">remove</span> the <code
data-x="attr-details-open">open</code> attribute from the element.</p>
<p class="note">This ability to request that additional information be shown or hidden
<!--non-normative-->may simply be the <span>activation behavior</span> of the appropriate
<code>summary</code> element, in the case such an element exists. However, if no such element
exists, user agents can still provide this ability through some other user interface
affordance.</p>
<p>The <dfn>details name group</dfn> that contains a <code>details</code> element <var>a</var>
also contains all the other <code>details</code> elements <var>b</var> that fulfill all of the
following conditions:</p>
<ul>
<li>Both <var>a</var> and <var>b</var> are in the same <span>tree</span>.</li>
<li>They both have a <code data-x="attr-details-name">name</code> attribute, their <code
data-x="attr-details-name">name</code> attributes are not the empty string, and the value of
<var>a</var>'s <code data-x="attr-details-name">name</code> attribute equals the value of
<var>b</var>'s <code data-x="attr-details-name">name</code> attribute.</li>
</ul>
<p>Every <code>details</code> element has a <dfn>details toggle task tracker</dfn>, which is a
<span>toggle task tracker</span> or null, initially null.</p>
<p>The following <span data-x="concept-element-attributes-change-ext">attribute change
steps</span>, given <var>element</var>, <var>localName</var>, <var>oldValue</var>,
<var>value</var>, and <var>namespace</var>, are used for all <code>details</code> elements:</p>
<ol>
<li><p>If <var>namespace</var> is not null, then return.</p></li>
<li><p>If <var>localName</var> is <code data-x="attr-details-name">name</code>, then <span>ensure
details exclusivity by closing the given element if needed</span> given
<var>element</var>.</p></li>
<li><p>If <var>localName</var> is <code data-x="attr-details-open">open</code>, then:
<ol>
<li>
<p>If one of <var>oldValue</var> or <var>value</var> is null and the other is not null,
run the following steps, which are known as the <dfn>details notification task steps</dfn>, for
this <code>details</code> element:</p>
<p class="note">When the <code data-x="attr-details-open">open</code> attribute is toggled
several times in succession, the resulting tasks essentially get coalesced so that only one
event is fired.</p>
<ol>
<li><p>If <var>oldValue</var> is null, <span>queue a details toggle event task</span> given
the <code>details</code> element, "<code data-x="">closed</code>", and "<code
data-x="">open</code>".</p></li>
<li><p>Otherwise, <span>queue a details toggle event task</span> given the
<code>details</code> element, "<code data-x="">open</code>", and "<code
data-x="">closed</code>".</p></li>
</ol>
</li>
<li><p>If <var>oldValue</var> is null and <var>value</var> is not null, then <span>ensure
details exclusivity by closing other elements if needed</span> given
<var>element</var>.</p></li>
</ol>
</li>
</ol>
<p>The <code>details</code> <span data-x="html element insertion steps">HTML element insertion
steps</span>, given <var>insertedNode</var>, are:</p>
<ol>
<li><p><span>Ensure details exclusivity by closing the given element if needed</span> given
<var>insertedNode</var>.</p></li>
</ol>
<p class="note">To be clear, these attribute change and insertion steps also run when an attribute
or element is inserted via the parser.</p>
<p>To <dfn>queue a details toggle event task</dfn> given a <code>details</code> element
<var>element</var>, a string <var>oldState</var>, and a string <var>newState</var>:
<ol>
<li>
<p>If <var>element</var>'s <span>details toggle task tracker</span> is not null, then:</p>
<ol>
<li><p>Set <var>oldState</var> to <var>element</var>'s <span>details toggle task
tracker</span>'s <span data-x="toggle-task-old-state">old state</span>.</p></li>
<li><p>Remove <var>element</var>'s <span>details toggle task tracker</span>'s <span
data-x="toggle-task-task">task</span> from its <span>task queue</span>.</p></li>
<li><p>Set <var>element</var>'s <span>details toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li>
<p><span>Queue an element task</span> given the <span>DOM manipulation task source</span> and
<var>element</var> to run the following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-toggle">toggle</code> at <var>element</var>, using <code>ToggleEvent</code>, with
the <code data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to
<var>oldState</var> and the <code data-x="dom-ToggleEvent-newState">newState</code> attribute
initialized to <var>newState</var>.</p></li>
<li><p>Set <var>element</var>'s <span>details toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li><p>Set <var>element</var>'s <span>details toggle task tracker</span> to a struct with <span
data-x="toggle-task-task">task</span> set to the just-queued <span
data-x="concept-task">task</span> and <span data-x="toggle-task-old-state">old state</span> set
to <var>oldState</var>.</p></li>
</ol>
<p>To <dfn>ensure details exclusivity by closing other elements if needed</dfn> given a
<code>details</code> element <var>element</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>element</var> has an <code
data-x="attr-details-open">open</code> attribute.</p></li>
<!-- This step is an optimization, but it may also make things clearer. -->
<li><p>If <var>element</var> does not have a <code data-x="attr-details-name">name</code>
attribute, or its <code data-x="attr-details-name">name</code> attribute is the empty string,
then return.</p></li>
<li><p>Let <var>groupMembers</var> be a list of elements, containing all elements in
<var>element</var>'s <span>details name group</span> except for <var>element</var>, in <span>tree
order</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> element <var>otherElement</var> of
<var>groupMembers</var>:</p>
<ol>
<li>
<p>If the <code data-x="attr-details-open">open</code> attribute is set on
<var>otherElement</var>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>otherElement</var> is the only element in
<var>groupMembers</var> that has the <code data-x="attr-details-open">open</code> attribute
set.</p></li>
<li><p><span data-x="concept-element-attributes-remove">Remove</span> the <code
data-x="attr-details-open">open</code> attribute on <var>otherElement</var>.</p></li>
<li><p><span>Break</span>.</p></li>
</ol>
</ol>
</li>
</ol>
<p>To <dfn>ensure details exclusivity by closing the given element if needed</dfn> given a
<code>details</code> element <var>element</var>:</p>
<ol>
<li><p>If <var>element</var> does not have an <code data-x="attr-details-open">open</code>
attribute, then return.</p></li>
<!-- This step is an optimization, but it may also make things clearer. -->
<li><p>If <var>element</var> does not have a <code data-x="attr-details-name">name</code>
attribute, or its <code data-x="attr-details-name">name</code> attribute is the empty string,
then return.</p></li>
<li><p>Let <var>groupMembers</var> be a list of elements, containing all elements in
<var>element</var>'s <span>details name group</span> except for <var>element</var>, in <span>tree
order</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> element <var>otherElement</var> of
<var>groupMembers</var>:</p>
<ol>
<li>
<p>If the <code data-x="attr-details-open">open</code> attribute is set on
<var>otherElement</var>, then:</p>
<ol>
<li><p><span data-x="concept-element-attributes-remove">Remove</span> the <code
data-x="attr-details-open">open</code> attribute on <var>element</var>.</p></li>
<li><p><span>Break</span>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p>The <dfn attribute for="HTMLDetailsElement"><code data-x="dom-details-name">name</code></dfn>
and <dfn attribute for="HTMLDetailsElement"><code data-x="dom-details-open">open</code></dfn>
IDL attributes must <span>reflect</span> the respective content attributes of the same name.</p>
</div>
<p>The <dfn>ancestor details revealing algorithm</dfn> is to run the following steps on
<var>currentNode</var>:</p>
<ol>
<li>
<p>While <var>currentNode</var> has a parent node within the <span>flat tree</span>:</p>
<ol>
<li>
<p>If <var>currentNode</var> is slotted into the second slot of a <code>details</code>
element:</p>
<ol>
<li><p>Set <var>currentNode</var> to the <code>details</code> element which
<var>currentNode</var> is slotted into.</p></li>
<li><p>If the <code data-x="attr-details-open">open</code> attribute is not set on
<var>currentNode</var>, then <span data-x="concept-element-attributes-set-value">set</span>
the <code data-x="attr-details-open">open</code> attribute on <var>currentNode</var> to the
empty string.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>currentNode</var> to the parent node of
<var>currentNode</var> within the <span>flat tree</span>.</p></li>
</ol>
</li>
</ol>
<div class="example">
<p>The following example shows the <code>details</code> element being used to hide technical
details in a progress report.</p>
<pre><code class="html"><section class="progress window">
<h1>Copying "Really Achieving Your Childhood Dreams"</h1>
<details>
<summary>Copying... <progress max="375505392" value="97543282"></progress> 25%</summary>
<dl>
<dt>Transfer rate:</dt> <dd>452KB/s</dd>
<dt>Local filename:</dt> <dd>/home/rpausch/raycd.m4v</dd>
<dt>Remote filename:</dt> <dd>/var/www/lectures/raycd.m4v</dd>
<dt>Duration:</dt> <dd>01:16:27</dd>
<dt>Color profile:</dt> <dd>SD (6-1-6)</dd>
<dt>Dimensions:</dt> <dd>320×240</dd>
</dl>
</details>
</section></code></pre>
</div>
<div class="example">
<p>The following shows how a <code>details</code> element can be used to hide some controls by
default:</p>
<pre><code class="html"><details>
<summary><label for=fn>Name & Extension:</label></summary>
<p><input type=text id=fn name=fn value="Pillar Magazine.pdf">
<p><label><input type=checkbox name=ext checked> Hide extension</label>
</details></code></pre>
<p>One could use this in conjunction with other <code>details</code> in a list to allow the user
to collapse a set of fields down to a small set of headings, with the ability to open each
one.</p>
<p class="details-example"><img src="/images/sample-details-1.png" width="345" height="611" alt=""><img src="/images/sample-details-2.png" width="345" height="666" alt=""></p>
<p>In these examples, the summary really just summarizes what the controls can change, and not
the actual values, which is less than ideal.</p>
</div>
<div class="example" id="example-details-exclusive-accordion">
<p>The following example shows the <code data-x="attr-details-name">name</code> attribute of the
<code>details</code> element being used to create an exclusive accordion, a set of
<code>details</code> elements where a user action to open one <code>details</code> element causes
any open <code>details</code> to close.</p>
<pre><code class="html"><section class="characteristics">
<details name="frame-characteristics">
<summary>Material</summary>
The picture frame is made of solid oak wood.
</details>
<details name="frame-characteristics">
<summary>Size</summary>
The picture frame fits a photo 40cm tall and 30cm wide.
The frame is 45cm tall, 35cm wide, and 2cm thick.
</details>
<details name="frame-characteristics">
<summary>Color</summary>
The picture frame is available in its natural wood
color, or with black stain.
</details>
</section></code></pre>
</div>
<div class="example" id="example-details-exclusive-accordion-setting-open">
<p>The following example shows what happens when the <code data-x="attr-details-open">open</code>
attribute is set on a <code>details</code> element that is part of a set of elements using the
<code data-x="attr-details-name">name</code> attribute to create an exclusive accordion.</p>
<p>Given the initial markup:</p>
<pre><code class="html"><section class="characteristics">
<details name="frame-characteristics" id="d1" open>...</details>
<details name="frame-characteristics" id="d2">...</details>
<details name="frame-characteristics" id="d3">...</details>
</section></code></pre>
<p>and the script:</p>
<pre><code class="js">document.getElementById("d2").setAttribute("open", "");</code></pre>
<p>then the resulting tree after the script executes will be equivalent to the markup:</p>
<pre><code class="html"><section class="characteristics">
<details name="frame-characteristics" id="d1">...</details>
<details name="frame-characteristics" id="d2" open>...</details>
<details name="frame-characteristics" id="d3">...</details>
</section></code></pre>
<p>because setting the <code data-x="attr-details-open">open</code> attribute on <code
data-x="">d2</code> removes it from <code data-x="">d1</code>.</p>
<p>The same happens when the user activates the <code>summary</code> element inside of <code
data-x="">d2</code>.</p>
</div>
<div class="example">
<p>Because the <code data-x="attr-details-open">open</code> attribute is added and removed
automatically as the user interacts with the control, it can be used in CSS to style the element
differently based on its state. Here, a style sheet is used to animate the color of the summary
when the element is opened or closed:</p>
<pre><code class="html"><style>
details > summary { transition: color 1s; color: black; }
details[open] > summary { color: red; }
</style>
<details>
<summary>Automated Status: Operational</summary>
<p>Velocity: 12m/s</p>
<p>Direction: North</p>
</details></code></pre>
</div>
<h4>The <dfn element><code>summary</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>As the <span>first child</span> of a <code>details</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Phrasing content</span>, optionally intermixed with <span>heading content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-summary">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-summary">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>summary</code> element <span>represents</span> a summary, caption, or legend for the
rest of the contents of the <code>summary</code> element's parent <code>details</code>
element<span w-nodev>, if any</span>.</p>
<div w-nodev>
<p>A <code>summary</code> element is a <dfn>summary for its parent details</dfn> if the following
algorithm returns true:</p>
<ol>
<li><p>If this <code>summary</code> element has no parent, then return false.</p></li>
<li><p>Let <var>parent</var> be this <code>summary</code> element's parent.</p></li>
<li><p>If <var>parent</var> is not a <code>details</code> element, then return false.</p></li>
<li><p>If <var>parent</var>'s first <code>summary</code> element child is not this
<code>summary</code> element, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>The <span>activation behavior</span> of <code>summary</code> elements is to run the following
steps:</p>
<ol>
<li><p>If this <code>summary</code> element is not the <span>summary for its parent
details</span>, then return.</p></li>
<li><p>Let <var>parent</var> be this <code>summary</code> element's parent.</p></li>
<li>
<p>If the <code data-x="attr-details-open">open</code> attribute is present on
<var>parent</var>, then <span data-x="concept-element-attributes-remove">remove</span> it.
Otherwise, <span data-x="concept-element-attributes-set-value">set</span> <var>parent</var>'s
<code data-x="attr-details-open">open</code> attribute to the empty string.</p>
<p class="note">This will then run the <span>details notification task steps</span>.</p>
</li>
</ol>
</div>
<h4 id="commands">Commands</h4>
<h5>Facets</h5>
<p>A <dfn data-x="concept-command">command</dfn> is the abstraction behind menu items, buttons, and
links. Once a command is defined, other parts of the interface can refer to the same command,
allowing many access points to a single feature to share facets such as the <span
data-x="command-facet-DisabledState">Disabled State</span>.</p>
<p id="facets">Commands are defined to have the following <dfn
data-x="concept-facet">facets</dfn>:</p>
<dl>
<dt><dfn data-x="command-facet-Label">Label</dfn></dt>
<dd>The name of the command as seen by the user.</dd>
<dt><dfn data-x="command-facet-AccessKey">Access Key</dfn></dt>
<dd>A key combination selected by the user agent that triggers the command. A command might not
have an Access Key.</dd>
<dt><dfn data-x="command-facet-HiddenState">Hidden State</dfn></dt>
<dd>Whether the command is hidden or not (basically, whether it should be shown in menus).</dd>
<dt><dfn data-x="command-facet-DisabledState">Disabled State</dfn></dt>
<dd>Whether the command is relevant and can be triggered or not.</dd>
<dt><dfn data-x="command-facet-Action">Action</dfn></dt>
<dd>The actual effect that triggering the command will have. This could be a scripted event
handler, a <span>URL</span> to which to <span>navigate</span>, or a form submission.</dd>
</dl>
<p id="expose-commands-in-ui">User agents may expose the <span
data-x="concept-command">commands</span> that match the following criteria:</p>
<ul>
<li><p>The <span data-x="command-facet-HiddenState">Hidden State</span> facet is false
(visible)</p></li>
<li><p>The element is <span>in a document</span> with a non-null <span
data-x="concept-document-bc">browsing context</span>.</p></li>
<li><p>Neither the element nor any of its ancestors has a <code
data-x="attr-hidden">hidden</code> attribute specified.</p></li>
</ul>
<p>User agents are encouraged to do this especially for commands that have <span
data-x="command-facet-AccessKey">Access Keys</span>, as a way to advertise those keys to the
user.</p>
<p class="example">For example, such commands could be listed in the user agent's menu bar.</p>
<div w-nodev>
<h5><dfn data-x="a-command">Using the <code>a</code> element to define a command</dfn></h5>
<p>An <code>a</code> element with an <code data-x="attr-hyperlink-href">href</code> attribute <span
data-x="concept-command">defines a command</span>.</p>
<p>The <span data-x="command-facet-Label">Label</span> of the command is the element's
<span>descendant text content</span>.</p>
<p>The <span data-x="command-facet-AccessKey">Access Key</span> of the command is the element's
<span>assigned access key</span>, if any.</p>
<p>The <span data-x="command-facet-HiddenState">Hidden State</span> of the command is true (hidden)
if the element has a <code data-x="attr-hidden">hidden</code> attribute, and false otherwise.</p>
<p>The <span data-x="command-facet-DisabledState">Disabled State</span> facet of the command is
true if the element or one of its ancestors is <span>inert</span>, and false otherwise.</p>
<p>The <span data-x="command-facet-Action">Action</span> of the command is to <span>fire a <code
data-x="event-click">click</code> event</span> at the element.</p>
<h5><dfn data-x="button-command">Using the <code>button</code> element to define a command</dfn></h5>
<p>A <code>button</code> element always <span data-x="concept-command">defines a
command</span>.</p>
<p>The <span data-x="command-facet-Label">Label</span>, <span
data-x="command-facet-AccessKey">Access Key</span>, <span
data-x="command-facet-HiddenState">Hidden State</span>, and <span
data-x="command-facet-Action">Action</span> facets of the command are determined <span
data-x="a-command">as for <code>a</code> elements</span> (see the previous section).</p>
<p>The <span data-x="command-facet-DisabledState">Disabled State</span> of the command is true if
the element or one of its ancestors is <span>inert</span>, or if the element's <span
data-x="concept-fe-disabled">disabled</span> state is set, and false otherwise.</p>
<h5><dfn data-x="input-command">Using the <code>input</code> element to define a command</dfn></h5>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
one of the <span data-x="attr-input-type-submit">Submit Button</span>, <span
data-x="attr-input-type-reset">Reset Button</span>, <span data-x="attr-input-type-image">Image
Button</span>, <span data-x="attr-input-type-button">Button</span>, <span
data-x="attr-input-type-radio">Radio Button</span>, or <span
data-x="attr-input-type-checkbox">Checkbox</span> states <span data-x="concept-command">defines a
command</span>.</p>
<p>The <span data-x="command-facet-Label">Label</span> of the command is determined as
follows:</p>
<ul>
<li><p>If the <code data-x="attr-input-type">type</code> attribute is in one of the
<span data-x="attr-input-type-submit">Submit Button</span>, <span
data-x="attr-input-type-reset">Reset Button</span>, <span data-x="attr-input-type-image">Image
Button</span>, or <span data-x="attr-input-type-button">Button</span> states, then the
<span data-x="command-facet-Label">Label</span> is the string given by the
<code data-x="attr-input-value">value</code> attribute, if any, and a UA-dependent,
locale-dependent value that the UA uses to label the button itself if the attribute is
absent.</p></li>
<li><p>Otherwise, if the element is a <span>labeled control</span>, then the <span
data-x="command-facet-Label">Label</span> is the <span>descendant text content</span> of the
first <code>label</code> element in <span>tree order</span> whose <span>labeled control</span>
is the element in question. (In JavaScript terms, this is given by <code
data-x=""><var>element</var>.labels[0].textContent</code>.)</p></li>
<li><p>Otherwise, if the <code data-x="attr-input-value">value</code> attribute is present, then
the <span data-x="command-facet-Label">Label</span> is the value of that attribute.</p></li>
<li><p>Otherwise, the <span data-x="command-facet-Label">Label</span> is the empty string.</p></li>
</ul>
<div class="note">
<p>Even though the <code data-x="attr-input-value">value</code> attribute on
<code>input</code> elements in the <span data-x="attr-input-type-image">Image Button</span>
state is non-conformant, the attribute can still contribute to the <span
data-x="command-facet-Label">Label</span> determination, if it is present and the Image Button's
<code data-x="attr-input-alt">alt</code> attribute is missing.</p>
</div>
<p>The <span data-x="command-facet-AccessKey">Access Key</span> of the command is the element's
<span>assigned access key</span>, if any.</p>
<p>The <span data-x="command-facet-HiddenState">Hidden State</span> of the command is true (hidden)
if the element has a <code data-x="attr-hidden">hidden</code> attribute, and false otherwise.</p>
<p>The <span data-x="command-facet-DisabledState">Disabled State</span> of the command is true if
the element or one of its ancestors is <span>inert</span>, or if the element's <span
data-x="concept-fe-disabled">disabled</span> state is set, and false otherwise.</p>
<p>The <span data-x="command-facet-Action">Action</span> of the command is to <span>fire a <code
data-x="event-click">click</code> event</span> at the element.</p>
<h5><dfn data-x="option-command">Using the <code>option</code> element to define a command</dfn></h5>
<p>An <code>option</code> element with an ancestor <code>select</code> element and either no <code
data-x="attr-option-value">value</code> attribute or a <code data-x="attr-option-value">value</code>
attribute that is not the empty string <span data-x="concept-command">defines a command</span>.</p>
<p>The <span data-x="command-facet-Label">Label</span> of the command is the value of the
<code>option</code> element's <code data-x="attr-option-label">label</code> attribute, if there is
one, or else the <code>option</code> element's <span>descendant text content</span>, with <span
data-x="strip and collapse ASCII whitespace">ASCII whitespace stripped and collapsed</span>.</p>
<p>The <span data-x="command-facet-AccessKey">Access Key</span> of the command is the element's
<span>assigned access key</span>, if any.</p>
<p>The <span data-x="command-facet-HiddenState">Hidden State</span> of the command is true (hidden)
if the element has a <code data-x="attr-hidden">hidden</code> attribute, and false otherwise.</p>
<p>The <span data-x="command-facet-DisabledState">Disabled State</span> of the command is true if
the element is <span data-x="concept-option-disabled">disabled</span>, or if its nearest ancestor
<code>select</code> element is <span data-x="concept-fe-disabled">disabled</span>, or if it or one
of its ancestors is <span>inert</span>, and false otherwise.</p>
<p>If the <code>option</code>'s nearest ancestor <code>select</code> element has a <code
data-x="attr-select-multiple">multiple</code> attribute, the <span
data-x="command-facet-Action">Action</span> of the command is to <span
data-x="concept-select-toggle">toggle</span> the <code>option</code> element. Otherwise, the <span
data-x="command-facet-Action">Action</span> is to <span
data-x="concept-select-pick">pick</span> the <code>option</code> element.</p>
<h5><dfn data-x="legend-command">Using the <code data-x="attr-accesskey">accesskey</code> attribute
on a <code>legend</code> element to define a command</dfn></h5>
<p>A <code>legend</code> element <span data-x="concept-command">defines a command</span> if all of
the following are true:</p>
<ul>
<li><p>It has an <span>assigned access key</span>.</p></li>
<li><p>It is a child of a <code>fieldset</code> element.</p></li>
<li><p>Its parent has a descendant that <span data-x="concept-command">defines a command</span>
that is neither a <code>label</code> element nor a <code>legend</code> element. This element,
if it exists, is <dfn>the <code>legend</code> element's <code>accesskey</code>
delegatee</dfn>.</p></li>
</ul>
<p>The <span data-x="command-facet-Label">Label</span> of the command is the element's
<span>descendant text content</span>.</p>
<p>The <span data-x="command-facet-AccessKey">Access Key</span> of the command is the element's
<span>assigned access key</span>.</p>
<p>The <span data-x="command-facet-HiddenState">Hidden State</span>, <span
data-x="command-facet-DisabledState">Disabled State</span>, and <span
data-x="command-facet-Action">Action</span> facets of the command are the same as the respective
facets of <span>the <code>legend</code> element's <code>accesskey</code> delegatee</span>.</p>
<div class="example">
<p>In this example, the <code>legend</code> element specifies an <code
data-x="attr-accesskey">accesskey</code>, which, when activated, will delegate to the
<code>input</code> element inside the <code>legend</code> element.</p>
<pre><code class="html"><fieldset>
<legend accesskey=p>
<label>I want <input name=pizza type=number step=1 value=1 min=0>
pizza(s) with these toppings</label>
</legend>
<label><input name=pizza-cheese type=checkbox checked> Cheese</label>
<label><input name=pizza-ham type=checkbox checked> Ham</label>
<label><input name=pizza-pineapple type=checkbox> Pineapple</label>
</fieldset></code></pre>
</div>
<h5><dfn data-x="accesskey-command">Using the <code data-x="attr-accesskey">accesskey</code>
attribute to define a command on other elements</dfn></h5>
<p>An element that has an <span>assigned access key</span> <span data-x="concept-command">defines a
command</span>.</p>
<p>If one of the earlier sections that define elements that <span data-x="concept-command">define
commands</span> define that this element <span data-x="concept-command">defines a command</span>,
then that section applies to this element, and this section does not. Otherwise, this section
applies to that element.</p>
<p>The <span data-x="command-facet-Label">Label</span> of the command depends on the element. If
the element is a <span>labeled control</span>, the <span>descendant text content</span> of the
first <code>label</code> element in <span>tree order</span> whose <span>labeled control</span> is
the element in question is the <span data-x="command-facet-Label">Label</span> (in JavaScript
terms, this is given by <code data-x=""><var>element</var>.labels[0].textContent</code>).
Otherwise, the <span data-x="command-facet-Label">Label</span> is the element's <span>descendant
text content</span>.</p>
<p>The <span data-x="command-facet-AccessKey">Access Key</span> of the command is the element's
<span>assigned access key</span>.</p>
<p>The <span data-x="command-facet-HiddenState">Hidden State</span> of the command is true (hidden)
if the element has a <code data-x="attr-hidden">hidden</code> attribute, and false otherwise.</p>
<p>The <span data-x="command-facet-DisabledState">Disabled State</span> of the command is true if
the element or one of its ancestors is <span>inert</span>, and false otherwise.</p>
<p>The <span data-x="command-facet-Action">Action</span> of the command is to run the following
steps:</p>
<ol>
<li>Run the <span>focusing steps</span> for the element.</li>
<li><span>Fire a <code data-x="event-click">click</code> event</span> at the element.</li>
</ol>
</div>
<h4>The <dfn element><code>dialog</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-dialog-closedby">closedby</code></dd>
<dd><code data-x="attr-dialog-open">open</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-dialog">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-dialog">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDialogElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-dialog-open">open</span>;
attribute DOMString <span data-x="dom-dialog-returnValue">returnValue</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dialog-closedBy">closedBy</span>;
[<span>CEReactions</span>] undefined <span data-x="dom-dialog-show">show</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-dialog-showModal">showModal</span>();
[<span>CEReactions</span>] undefined <span data-x="dom-dialog-close">close</span>(optional DOMString returnValue);
[<span>CEReactions</span>] undefined <span data-x="dom-dialog-requestClose">requestClose</span>(optional DOMString returnValue);
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLDialogElement</code>.</dd>
</dl>
<p>The <code>dialog</code> element represents a transitory part of an application, in the form of
a small window ("dialog box"), which the user interacts with to perform a task or gather
information. Once the user is done, the dialog can be automatically closed by the application, or
manually closed by the user.</p>
<p>Especially for modal dialogs, which are a familiar pattern across all types of applications,
authors should work to ensure that dialogs in their web applications behave in a way that is
familiar to users of non-web applications.</p>
<p class="note">As with all HTML elements, it is not conforming to use the <code>dialog</code>
element when attempting to represent another type of control. For example, context menus,
tooltips, and popup listboxes are not dialog boxes, so abusing the <code>dialog</code> element to
implement these patterns is incorrect.</p>
<p>An important part of user-facing dialog behavior is the placement of initial focus. The
<span>dialog focusing steps</span> attempt to pick a good candidate for initial focus when a
dialog is shown, but might not be a substitute for authors carefully thinking through the correct
choice to match user expectations for a specific dialog. As such, authors should use the <code
data-x="attr-fe-autofocus">autofocus</code> attribute on the descendant element of the dialog that
the user is expected to immediately interact with after the dialog opens. If there is no such
element, then authors should use the <code data-x="attr-fe-autofocus">autofocus</code> attribute
on the <code>dialog</code> element itself.</p>
<div class="example">
<p>In the following example, a dialog is used for editing the details of a product in an
inventory management web application.</p>
<pre><code class="html"><dialog>
<label>Product Number <input type="text" readonly></label>
<label>Product Name <input type="text" autofocus></label>
</dialog></code></pre>
<p>If the <code data-x="attr-fe-autofocus">autofocus</code> attribute was not present, the
Product Number field would have been focused by the dialog focusing steps. Although that is
reasonable behavior, the author determined that the more relevant field to focus was the Product
Name field, as the Product Number field is readonly and expects no user input. So, the author
used autofocus to override the default.</p>
<p>Even if the author wants to focus the Product Number field by default, they are best off
explicitly specifying that by using autofocus on that <code>input</code> element. This makes the
intent obvious to future readers of the code, and ensures the code stays robust in the face of
future updates. (For example, if another developer added a close button, and positioned it in the
node tree before the Product Number field).</p>
</div>
<p>Another important aspect of user behavior is whether dialogs are scrollable or not. In some
cases, overflow (and thus scrollability) cannot be avoided, e.g., when it is caused by the user's
high text zoom settings. But in general, scrollable dialogs are not expected by users. Adding
large text nodes directly to dialog elements is particularly bad as this is likely to cause the
dialog element itself to overflow. Authors are best off avoiding them.</p>
<div class="example">
<p>The following terms of service dialog respects the above suggestions.</p>
<pre><code class="html"><dialog style="height: 80vh;">
<div style="overflow: auto; height: 60vh;" autofocus>
<p>By placing an order via this Web site on the first day of the fourth month of the year
2010 Anno Domini, you agree to grant Us a non-transferable option to claim, for now and for
ever more, your immortal soul.</p>
<p>Should We wish to exercise this option, you agree to surrender your immortal soul,
and any claim you may have on it, within 5 (five) working days of receiving written
notification from this site or one of its duly authorized minions.</p>
<!-- ... etc., with many more <p> elements ... -->
</div>
<form method="dialog">
<button type="submit" value="agree">Agree</button>
<button type="submit" value="disagree">Disagree</button>
</form>
</dialog></code></pre>
<p>Note how the <span>dialog focusing steps</span> would have picked the scrollable
<code>div</code> element by default, but similarly to the previous example, we have placed <code
data-x="attr-fe-autofocus">autofocus</code> on the <code>div</code> so as to be more explicit and
robust against future changes.</p>
<p>In contrast, if the <code>p</code> elements expressing the terms of service did not have such
a wrapper <code>div</code> element, then the <code>dialog</code> itself would become scrollable,
violating the above advice. Furthermore, in the absence of any <code
data-x="attr-fe-autofocus">autofocus</code> attribute, such a markup pattern would have violated
the above advice and tripped up the <span>dialog focusing steps</span>'s default behavior, and
caused focus to jump to the Agree <code>button</code>, which is a bad user experience.</p>
</div>
<div class="example">
<p>This dialog box has some small print. The <code>strong</code> element is used to draw the
user's attention to the more important part.</p>
<pre><code class="html"><dialog>
<h1>Add to Wallet</h1>
<p><strong><label for=amt>How many gold coins do you want to add to your wallet?</label></strong></p>
<p><input id=amt name=amt type=number min=0 step=0.01 value=100></p>
<p><small>You add coins at your own risk.</small></p>
<p><label><input name=round type=checkbox> Only add perfectly round coins</label></p>
<p><input type=button onclick="submit()" value="Add Coins"></p>
</dialog></code></pre>
</div>
<hr>
<p>The <dfn element-attr for="dialog"><code data-x="attr-dialog-open">open</code></dfn> attribute
is a <span>boolean attribute</span>. When specified, it indicates that the <code>dialog</code>
element is active and that the user can interact with it.</p>
<p>The <dfn element-attr for="dialog"><code data-x="attr-dialog-closedby">closedby</code></dfn>
content attribute is an <span>enumerated attribute</span> with the following keywords and
states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="dialog/closedby"><code data-x="attr-dialog-closedby-any">any</code></dfn>
<td><dfn data-x="attr-dialog-closedby-any-state">Any</dfn>
<td><span data-x="close request">Close requests</span> or clicks outside close the dialog.
<tr>
<td><dfn attr-value for="dialog/closedby"><code data-x="attr-dialog-closedby-closerequest">closerequest</code></dfn>
<td><dfn data-x="attr-dialog-closedby-closerequest-state">Close Request</dfn>
<td><span data-x="close request">Close requests</span> close the dialog.
<tr>
<td><dfn attr-value for="dialog/closedby"><code data-x="attr-dialog-closedby-none">none</code></dfn>
<td><dfn data-x="attr-dialog-closedby-none-state">None</dfn>
<td>No user actions automatically close the dialog.
</table>
<p>The <code data-x="attr-dialog-closedby">closedby</code> attribute's <i data-x="invalid value
default">invalid value default</i> and <i data-x="missing value default">missing value
default</i> are both the <dfn data-x="attr-dialog-closedby-auto-state">Auto</dfn> state.</p>
<p class="note">The <span data-x="attr-dialog-closedby-auto-state">Auto</span> state behaves as
<span data-x="attr-dialog-closedby-closerequest-state">Close Request</span> state when the
<code>dialog</code> was shown using its <code data-x="dom-dialog-showModal">showModal()</code>
method; otherwise the <span data-x="attr-dialog-closedby-none-state">None</span> state.</p>
<div w-nodev>
<p>A <code>dialog</code> element without an <code data-x="attr-dialog-open">open</code> attribute
specified should not be shown to the user. This requirement may be implemented indirectly through
the style layer. For example, user agents that <a href="#renderingUA">support the suggested
default rendering</a> implement this requirement using the CSS rules described in the <a
href="#rendering">Rendering section</a>.</p>
</div>
<div class="note" id="note-dialog-remove-open-attribute">
<p>Removing the <code data-x="attr-dialog-open">open</code> attribute will usually hide the
dialog. However, doing so has a number of strange additional consequences:
<ul>
<li><p>The <code data-x="event-close">close</code> event will not be fired.</p></li>
<li><p>The <code data-x="dom-dialog-close">close()</code> method, and any <span data-x="close
request">close requests</span>, will no longer be able to close the dialog.</p></li>
<li><p>If the dialog was shown using its <code data-x="dom-dialog-showModal">showModal()</code>
method, the <code>Document</code> will still be <span data-x="blocked by a modal
dialog">blocked</span>.</p></li>
</ul>
<p>For these reasons, it is generally better to never remove the <code
data-x="attr-dialog-open">open</code> attribute manually. Instead, use the <code
data-x="dom-dialog-requestclose">requestClose()</code> or <code
data-x="dom-dialog-close">close()</code> methods to close the dialog, or the <code
data-x="attr-hidden">hidden</code> attribute to hide it.</p>
</div>
<p>The <code data-x="attr-tabindex">tabindex</code> attribute must not be specified on
<code>dialog</code> elements.</p>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>dialog</var>.<span subdfn data-x="dom-dialog-show">show</span>()</code></dt>
<dd><p>Displays the <code>dialog</code> element.</p></dd>
<dt><code data-x=""><var>dialog</var>.<span subdfn data-x="dom-dialog-showModal">showModal</span>()</code></dt>
<dd>
<p>Displays the <code>dialog</code> element and makes it the top-most modal dialog.</p>
<p>This method honors the <code data-x="attr-fe-autofocus">autofocus</code> attribute.</p>
</dd>
<dt><code data-x=""><var>dialog</var>.<span subdfn data-x="dom-dialog-close">close</span>([ <var>result</var> ])</code></dt>
<dd>
<p>Closes the <code>dialog</code> element.</p>
<p>The argument, if provided, provides a return value.</p>
</dd>
<dt><code data-x=""><var>dialog</var>.<span subdfn data-x="dom-dialog-requestClose">requestClose</span>([ <var>result</var> ])</code></dt>
<dd>
<p>Acts as if a <span data-x="close request">close request</span> was sent targeting
<var>dialog</var>, by first firing a <code data-x="event-cancel">cancel</code> event, and if
that event is not canceled with <code data-x="dom-Event-preventDefault">preventDefault()</code>,
proceeding to close the <var>dialog</var> in the same way as the <code
data-x="dom-dialog-close">close()</code> method (including firing a <code
data-x="event-close">close</code> event).</p>
<p>This is a helper utility that can be used to consolidate cancelation and closing logic into
the <code data-x="event-cancel">cancel</code> and <code data-x="event-close">close</code> event
handlers, by having all non-<span data-x="close request">close request</span> closing
affordances call this method.</p>
<p>Note that this method ignores the <code data-x="attr-dialog-closedby">closedby</code>
attribute: that is, even if <code data-x="attr-dialog-closedby">closedby</code> is set to
"<code data-x="attr-dialog-closedby-none">none</code>", the same behavior will apply.</p>
<p>The argument, if provided, provides a return value.</p>
</dd>
<dt><code data-x=""><var>dialog</var>.<span subdfn data-x="dom-dialog-returnValue">returnValue</span> [ = <var>result</var> ]</code></dt>
<dd>
<p>Returns the <code>dialog</code>'s return value.</p>
<p>Can be set, to update the return value.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLDialogElement"><code data-x="dom-dialog-show">show()</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span> has an <code data-x="attr-dialog-open">open</code> attribute and
<span>is modal</span> of <span>this</span> is false, then return.</p></li>
<li><p>If <span>this</span> has an <code data-x="attr-dialog-open">open</code> attribute, then
throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the result of <span data-x="concept-event-fire">firing an event</span> named <code
data-x="event-beforetoggle">beforetoggle</code>, using <code>ToggleEvent</code>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true, the <code
data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to "<code
data-x="">closed</code>", and the <code data-x="dom-ToggleEvent-newState">newState</code>
attribute initialized to "<code data-x="">open</code>" at <span>this</span> is false, then
return.</p></li>
<li><p>If <span>this</span> has an <code data-x="attr-dialog-open">open</code> attribute, then
return.</p></li>
<li><p><span>Queue a dialog toggle event task</span> given <span>this</span>, "<code
data-x="">closed</code>", and "<code data-x="">open</code>".</p></li>
<li><p>Add an <code data-x="attr-dialog-open">open</code> attribute to <span>this</span>, whose
value is the empty string.</p></li>
<li><p><span>Assert</span>: <span>this</span>'s <span>node document</span>'s <span>open
dialogs list</span> does not <span data-x="list contains">contain</span>
<span>this</span>.</p></li>
<li><p>Add <span>this</span> to <span>this</span>'s <span>node document</span>'s <span>open
dialogs list</span>.</p></li>
<li><p><span>Set the dialog close watcher</span> with <span>this</span>.</p></li>
<li><p>Set <span>this</span>'s <span>previously focused element</span> to the
<span>focused</span> element.</p></li>
<li><p>Let <var>document</var> be <span>this</span>'s <span>node document</span>.</p></li>
<li><p>Let <var>hideUntil</var> be the result of running <span>topmost popover ancestor</span>
given <span>this</span>, <var>document</var>'s <span>showing hint popover list</span>, null, and
false.</p></li>
<li><p>If <var>hideUntil</var> is null, then set <var>hideUntil</var> to the result of running
<span>topmost popover ancestor</span> given <span>this</span>, <var>document</var>'s
<span>showing auto popover list</span>, null, and false.</p></li>
<li><p>If <var>hideUntil</var> is null, then set <var>hideUntil</var> to
<var>document</var>.</p></li>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>hideUntil</var>, false, and true.</p></li>
<li><p>Run the <span>dialog focusing steps</span> given <span>this</span>.</p></li>
</ol>
<p>The <dfn method for="HTMLDialogElement"><code
data-x="dom-dialog-showModal">showModal()</code></dfn> method steps are to <span>show a modal
dialog</span> given <span>this</span>.</p>
<p>The <dfn method for="HTMLDialogElement"><code
data-x="dom-dialog-close">close(<var>returnValue</var>)</code></dfn> method steps are:
<ol>
<li><p>If <var>returnValue</var> is not given, then set it to null.</p></li>
<li><p><span>Close the dialog</span> <span>this</span> with <var>returnValue</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLDialogElement"><code
data-x="dom-dialog-requestClose">requestClose(<var>returnValue</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>If <span>this</span> does not have an <code data-x="attr-dialog-open">open</code>
attribute, then return.</p></li>
<li><p><span>Assert</span>: <span>this</span>'s <span data-x="dialog-close-watcher">close
watcher</span> is not null.</p></li>
<li><p>Set <var>dialog</var>'s <span>enable close watcher for <code
data-x="dom-dialog-requestClose">requestClose()</code></span> to true.</p></li>
<li><p>If <var>returnValue</var> is not given, then set it to null.</p></li>
<li><p>Set <span>this</span>'s <span>request close return value</span> to
<var>returnValue</var>.</p></li>
<li><p><span data-x="close-watcher-request-close">Request to close</span> <var>dialog</var>'s
<span data-x="dialog-close-watcher">close watcher</span> with false.</p></li>
<li><p>Set <var>dialog</var>'s <span>enable close watcher for <code
data-x="dom-dialog-requestClose">requestClose()</code></span> to false.</p></li>
</ol>
<div class="note" id="note-dialog-method-names">
<p>We use show/close as the verbs for <code>dialog</code> elements, as opposed to verb pairs that
are more commonly thought of as antonyms such as show/hide or open/close, due to the following
constraints:</p>
<ul>
<li><p>Hiding a dialog is different from closing one. Closing a dialog gives it a return value,
fires an event, unblocks the page for other dialogs, and so on. Whereas hiding a dialog is a
purely visual property, and is something you can already do with the <code
data-x="attr-hidden">hidden</code> attribute or by removing the <code
data-x="attr-dialog-open">open</code> attribute. (See also the <a
href="#note-dialog-remove-open-attribute">note above</a> about removing the <code
data-x="attr-dialog-open">open</code> attribute, and how hiding the dialog in that way is
generally not desired.)</p></li>
<li><p>Showing a dialog is different from opening one. Opening a dialog consists of creating
and showing that dialog (similar to how <code data-x="dom-open">window.open()</code> both
creates and shows a new window). Whereas showing the dialog is the process of taking a
<code>dialog</code> element that is already in the DOM, and making it interactive and visible
to the user.</p></li>
<li><p>If we were to have a <code data-x="">dialog.open()</code> method despite the above, it
would conflict with the <code data-x="dom-dialog-open">dialog.open</code> property.</p></li>
</ul>
<p>Furthermore, a <a
href="https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2013-December/041799.html">survey</a>
of many other UI frameworks contemporary to the original design of the <code>dialog</code>
element made it clear that the show/close verb pair was reasonably common.</p>
<p>In summary, it turns out that the implications of certain verbs, and how they are used in
technology contexts, mean that paired actions such as showing and closing a dialog are not
always expressible as antonyms.</p>
</div>
<div w-nodev>
<p>The <dfn attribute for="HTMLDialogElement"><code
data-x="dom-dialog-returnValue">returnValue</code></dfn> IDL attribute, on getting, must return
the last value to which it was set. On setting, it must be set to the new value. When the element
is created, it must be set to the empty string.</p>
<p>The <dfn attribute for="HTMLDialogElement"><code
data-x="dom-dialog-closedBy">closedBy</code></dfn> getter steps are to return the keyword
corresponding to the <span>computed closed-by state</span> given <span>this</span>.</p>
<p>The <code data-x="dom-dialog-closedBy">closedBy</code> setter steps are to set the <code
data-x="attr-dialog-closedby">closedby</code> content attribute to the given value.</p>
<p>The <dfn attribute for="HTMLDialogElement"><code data-x="dom-dialog-open">open</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-dialog-open">open</code> content
attribute.</p>
<hr>
<p>Each <code>Document</code> has a <dfn>dialog pointerdown target</dfn>, which is an <span
data-x="HTMLDialogElement">HTML dialog element</span> or null, initially null.</p>
<p>Each <span data-x="html elements">HTML element</span> has a <dfn>previously focused
element</dfn> which is null or an element, and it is initially null. When <code
data-x="dom-dialog-showModal">showModal()</code> and <code data-x="dom-dialog-show">show()</code>
are called, this element is set to the currently <span>focused</span> element before running the
<span>dialog focusing steps</span>. Elements with the <code data-x="attr-popover">popover</code>
attribute set this element to the currently <span>focused</span> element during the <span
data-x="show popover">show popover algorithm</span>.</p>
<p>Each <code>dialog</code> element has a <dfn>dialog toggle task tracker</dfn>, which is a
<span>toggle task tracker</span> or null, initially null.</p>
<p>Each <code>dialog</code> element has a <dfn data-x="dialog-close-watcher">close watcher</dfn>,
which is a <span>close watcher</span> or null, initially null.</p>
<p>Each <code>dialog</code> element has a <dfn>request close return value</dfn>, which is a
string, initially null.</p>
<p>Each <code>dialog</code> element has an <dfn>enable close watcher for <code
data-x="dom-dialog-requestClose">requestClose()</code></dfn> boolean, initially false.</p>
<p>Each <code>dialog</code> element has an <dfn>is modal</dfn> boolean, initially false.</p>
<hr>
</div>
<p>The <code>dialog</code> <span>HTML element removing steps</span>, given <var>removedNode</var>
and <var>oldParent</var>, are:</p>
<ol>
<li>
<p>If <var>removedNode</var>'s <span data-x="dialog-close-watcher">close watcher</span> is not
null, then:</p>
<ol>
<li><p><span data-x="close-watcher-destroy">Destroy</span> <var>removedNode</var>'s <span
data-x="dialog-close-watcher">close watcher</span>.</p></li>
<li><p>Set <var>removedNode</var>'s <span data-x="dialog-close-watcher">close watcher</span> to
null.</p></li>
</ol>
</li>
<li><p>If <var>removedNode</var>'s <span>node document</span>'s <span>top layer</span> <span
data-x="list contains">contains</span> <var>removedNode</var>, then <span>remove an element from
the top layer immediately</span> given <var>removedNode</var>.</p></li>
<li><p>Set <span>is modal</span> of <var>removedNode</var> to false.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>removedNode</var> from
<var>removedNode</var>'s <span>node document</span>'s <span>open dialogs list</span>.</p></li>
</ol>
<p>To <dfn>show a modal dialog</dfn> given a <code>dialog</code> element <var>subject</var>:</p>
<ol>
<li><p>If <var>subject</var> has an <code data-x="attr-dialog-open">open</code> attribute and
<span>is modal</span> of <var>subject</var> is true, then return.</p></li>
<li><p>If <var>subject</var> has an <code data-x="attr-dialog-open">open</code> attribute, then
throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>subject</var>'s <span>node document</span> is not <span>fully active</span>, then
throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>subject</var> is not <span>connected</span>, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>subject</var> is in the <span data-x="popover-showing-state">popover showing
state</span>, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If the result of <span data-x="concept-event-fire">firing an event</span> named <code
data-x="event-beforetoggle">beforetoggle</code>, using <code>ToggleEvent</code>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true, the <code
data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to "<code
data-x="">closed</code>", and the <code data-x="dom-ToggleEvent-newState">newState</code>
attribute initialized to "<code data-x="">open</code>" at <var>subject</var> is false, then
return.</p></li>
<li><p>If <var>subject</var> has an <code data-x="attr-dialog-open">open</code> attribute,
then return.</p></li>
<li><p>If <var>subject</var> is not <span>connected</span>, then return.</p></li>
<li><p>If <var>subject</var> is in the <span data-x="popover-showing-state">popover showing
state</span>, then return.</p></li>
<li><p><span>Queue a dialog toggle event task</span> given <var>subject</var>, "<code
data-x="">closed</code>", and "<code data-x="">open</code>".</p></li>
<li><p>Add an <code data-x="attr-dialog-open">open</code> attribute to <var>subject</var>, whose
value is the empty string.</p></li>
<li><p>Set <span>is modal</span> of <var>subject</var> to true.</p></li>
<li><p><span>Assert</span>: <var>subject</var>'s <span>node document</span>'s <span>open
dialogs list</span> does not <span data-x="list contains">contain</span>
<var>subject</var>.</p></li>
<li><p>Add <var>subject</var> to <var>subject</var>'s <span>node document</span>'s <span>open
dialogs list</span>.</p></li>
<li>
<p>Let <var>subject</var>'s <span>node document</span> be <span data-x="blocked by a modal
dialog">blocked by the modal dialog</span> <var>subject</var>.</p>
<p class="note" id="note-dialog-plus-focus-fixup">This will cause the <span>focused area of the
document</span> to become <span>inert</span> (unless that currently focused area is a
<span>shadow-including descendant</span> of <var>subject</var>). In such cases, the
<span>focused area of the document</span> will soon be <a href="#focus-fixup-rule">reset</a> to
the <span>viewport</span>. In a couple steps we will attempt to find a better candidate to
focus.</p>
</li>
<li><p>If <var>subject</var>'s <span>node document</span>'s <span>top layer</span> does not
already <span data-x="list contains">contain</span> <var>subject</var>, then <span>add an element
to the top layer</span> given <var>subject</var>.</p></li>
<li><p><span>Set the dialog close watcher</span> with <var>subject</var>.</p></li>
<li><p>Set <var>subject</var>'s <span>previously focused element</span> to the
<span>focused</span> element.</p></li>
<li><p>Let <var>document</var> be <var>subject</var>'s <span>node document</span>.</p></li>
<li><p>Let <var>hideUntil</var> be the result of running <span>topmost popover ancestor</span>
given <var>subject</var>, <var>document</var>'s <span>showing hint popover list</span>, null, and
false.</p></li>
<li><p>If <var>hideUntil</var> is null, then set <var>hideUntil</var> to the result of running
<span>topmost popover ancestor</span> given <var>subject</var>, <var>document</var>'s
<span>showing auto popover list</span>, null, and false.</p></li>
<li><p>If <var>hideUntil</var> is null, then set <var>hideUntil</var> to
<var>document</var>.</p></li>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>hideUntil</var>, false, and true.</p></li>
<li><p>Run the <span>dialog focusing steps</span> given <var>subject</var>.</p></li>
</ol>
<p id="canceling-dialogs">To <dfn>set the dialog close watcher</dfn>, given a <code>dialog</code>
element <var>dialog</var>:</p>
<ol>
<li>
<p>Set <var>dialog</var>'s <span data-x="dialog-close-watcher">close watcher</span> to the
result of <span data-x="establish a close watcher">establishing a close watcher</span> given
<var>dialog</var>'s <span>relevant global object</span>, with:</p>
<ul>
<li><p><i data-x="create-close-watcher-cancelAction">cancelAction</i> given
<var>canPreventClose</var> being to return the result of <span
data-x="concept-event-fire">firing an event</span> named <code
data-x="event-cancel">cancel</code> at <var>dialog</var>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to
<var>canPreventClose</var>.</p></li>
<li><p><i data-x="create-close-watcher-closeAction">closeAction</i> being to <span>close the
dialog</span> given <var>dialog</var> and <var>dialog</var>'s <span>request close return
value</span>.</p></li>
<li><p><i data-x="create-close-watcher-getEnabledState">getEnabledState</i> being to return
true if <var>dialog</var>'s <span>enable close watcher for <code
data-x="dom-dialog-requestClose">requestClose()</code></span> is true or <var>dialog</var>'s
<span>computed closed-by state</span> is not <span
data-x="attr-dialog-closedby-none-state">None</span>; otherwise false.</p></li>
</ul>
</li>
</ol>
<p>The <span>is valid invoker command steps</span> for <code>dialog</code> elements, given
a <code data-x="attr-button-command">command</code> attribute <var>command</var>, are:</p>
<ol>
<li><p>If <var>command</var> is in the <span
data-x="attr-button-command-close-state">Close</span> state or in the <span
data-x="attr-button-command-show-modal-state">Show Modal</span> state, then
return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>The <span>invoker command steps</span> for <code>dialog</code> elements, given an element
<var>element</var>, an element <var>invoker</var>, and a <code
data-x="attr-button-command">command</code> attribute <var>command</var>, are:</p>
<ol>
<li><p>If <var>element</var> is in the <span
data-x="popover-showing-state">popover showing</span> state, then return.</p></li>
<li>
<p>If <var>command</var> is in the <span data-x="attr-button-command-close-state">Close</span>
state and <var>element</var> has an <code data-x="attr-dialog-open">open</code> attribute:</p>
<ol>
<li><p>Let <var>value</var> be <var>invoker</var>'s <span
data-x="concept-fe-value">value</span>.</p></li>
<li><p><span>Close the dialog</span> <var>element</var> with <var>value</var>.</p></li>
</ol>
</li>
<li><p>If <var>command</var> is the <span
data-x="attr-button-command-show-modal-state">Show Modal</span> state and <var>element</var> does
not have an <code data-x="attr-dialog-open">open</code> attribute, then
<span>show a modal dialog</span> given <var>element</var>.</p></li>
</ol>
<div class="example">
<p>The following buttons use <code data-x="attr-button-commandfor">commandfor</code> to open and
close a "confirm" <code>dialog</code> as modal when activated:</p>
<pre><code class="html"><button type=button
commandfor="the-dialog"
command="show-modal">
Delete
</button>
<dialog id="the-dialog">
<form action="/delete" method="POST">
<button type="submit">
Delete
</button>
<button commandfor="the-dialog"
command="close">
Cancel
</button>
</form>
</dialog>
</code></pre>
</div>
<p>When a <code>dialog</code> element <var>subject</var> is to be <dfn data-x="close the
dialog">closed</dfn>, with null or a string <var>result</var>, run these steps:</p>
<ol>
<li><p>If <var>subject</var> does not have an <code data-x="attr-dialog-open">open</code>
attribute, then return.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-beforetoggle">beforetoggle</code>, using <code>ToggleEvent</code>, with the <code
data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to "<code
data-x="">open</code>" and the <code data-x="dom-ToggleEvent-newState">newState</code> attribute
initialized to "<code data-x="">closed</code>" at <var>subject</var>.</p></li>
<li><p>If <var>subject</var> does not have an <code data-x="attr-dialog-open">open</code>
attribute, then return.</p></li>
<li><p><span>Queue a dialog toggle event task</span> given <var>subject</var>, "<code
data-x="">open</code>", and "<code data-x="">closed</code>".</p></li>
<li><p>Remove <var>subject</var>'s <code data-x="attr-dialog-open">open</code>
attribute.</p></li>
<li><p>If <span>is modal</span> of <var>subject</var> is true, then <span>request an
element to be removed from the top layer</span> given <var>subject</var>.</p></li>
<li><p>Let <var>wasModal</var> be the value of <var>subject</var>'s <span>is
modal</span> flag.</p></li>
<li><p>Set <span>is modal</span> of <var>subject</var> to false.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>subject</var> from <var>subject</var>'s
<span>node document</span>'s <span>open dialogs list</span>.</p></li>
<li><p>If <var>result</var> is not null, then set the <code
data-x="dom-dialog-returnValue">returnValue</code> attribute to <var>result</var>.</p></li>
<li><p>Set the <span>request close return value</span> to null.</p></li>
<li>
<p>If <var>subject</var>'s <span>previously focused element</span> is not null, then:</p>
<ol>
<li><p>Let <var>element</var> be <var>subject</var>'s <span>previously focused
element</span>.</p></li>
<li><p>Set <var>subject</var>'s <span>previously focused element</span> to null.</p></li>
<li><p>If <var>subject</var>'s <span>node document</span>'s <span>focused area of the
document</span>'s <span>DOM anchor</span> is a <span>shadow-including inclusive
descendant</span> of <var>subject</var>, or <var>wasModal</var> is true, then run the
<span>focusing steps</span> for <var>element</var>; the viewport should not be scrolled by
doing this step.</p></li>
</ol>
</li>
<li><p><span>Queue an element task</span> on the <span>user interaction task source</span> given the
<var>subject</var> element to <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-close">close</code> at <var>subject</var>.</p></li>
<li>
<p>If <var>subject</var>'s <span data-x="dialog-close-watcher">close watcher</span> is not null,
then:</p>
<ol>
<li><p><span data-x="close-watcher-destroy">Destroy</span> <var>subject</var>'s <span
data-x="dialog-close-watcher">close watcher</span>.</p></li>
<li><p>Set <var>subject</var>'s <span data-x="dialog-close-watcher">close watcher</span> to
null.</p></li>
</ol>
</li>
</ol>
</div>
<p>To <dfn>queue a dialog toggle event task</dfn> given a <code>dialog</code> element
<var>element</var>, a string <var>oldState</var>, and a string <var>newState</var>:
<ol>
<li>
<p>If <var>element</var>'s <span>dialog toggle task tracker</span> is not null, then:</p>
<ol>
<li><p>Set <var>oldState</var> to <var>element</var>'s <span>dialog toggle task
tracker</span>'s <span data-x="toggle-task-old-state">old state</span>.</p></li>
<li><p>Remove <var>element</var>'s <span>dialog toggle task tracker</span>'s <span
data-x="toggle-task-task">task</span> from its <span>task queue</span>.</p></li>
<li><p>Set <var>element</var>'s <span>dialog toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li>
<p><span>Queue an element task</span> given the <span>DOM manipulation task source</span> and
<var>element</var> to run the following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-toggle">toggle</code> at <var>element</var>, using <code>ToggleEvent</code>, with
the <code data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to
<var>oldState</var> and the <code data-x="dom-ToggleEvent-newState">newState</code> attribute
initialized to <var>newState</var>.</p></li>
<li><p>Set <var>element</var>'s <span>dialog toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li><p>Set <var>element</var>'s <span>dialog toggle task tracker</span> to a struct with <span
data-x="toggle-task-task">task</span> set to the just-queued <span
data-x="concept-task">task</span> and <span data-x="toggle-task-old-state">old state</span> set
to <var>oldState</var>.</p></li>
</ol>
<p>To retrieve a dialog's <dfn>computed closed-by state</dfn>, given a <code>dialog</code>
<var>dialog</var>:
<ol>
<li>
<p>If the state of <var>dialog</var>'s <code data-x="attr-dialog-closedby">closedby</code>
attribute is <span data-x="attr-dialog-closedby-auto-state">Auto</span>:</p>
<ol>
<li><p>If <var>dialog</var>'s <span>is modal</span> is true, then return <span
data-x="attr-dialog-closedby-closerequest-state">Close Request</span>.</p></li>
<li><p>Return <span data-x="attr-dialog-closedby-none-state">None</span>.</p></li>
</ol>
</li>
<li><p>Return the state of <var>dialog</var>'s <code
data-x="attr-dialog-closedby">closedby</code> attribute.</p></li>
</ol>
<p>The <dfn>dialog focusing steps</dfn>, given a <code>dialog</code> element <var>subject</var>,
are as follows:</p>
<ol>
<li><p>If the <span>allow focus steps</span> given <var>subject</var>'s <span>node
document</span> return false, then return.</p></li>
<li><p>Let <var>control</var> be null.</p></li>
<li><p>If <var>subject</var> has the <code data-x="attr-fe-autofocus">autofocus</code>
attribute, then set <var>control</var> to <var>subject</var>.</p></li>
<li><p>If <var>control</var> is null, then set <var>control</var> to the <span>focus
delegate</span> of <var>subject</var>.</p></li>
<li><p>If <var>control</var> is null, then set <var>control</var> to <var>subject</var>.</p></li>
<li>
<p>Run the <span>focusing steps</span> for <var>control</var>.</p>
<p class="note">If <var>control</var> is not <span>focusable</span>, this will do nothing. This
would only happen if subject had no focus delegate, and the user agent decided that
<code>dialog</code> elements were not generally focusable. In that case, any <a
href="#note-dialog-plus-focus-fixup">earlier modifications</a> to the <span>focused area of the
document</span> will apply.</p>
</li>
<li><p>Let <var>topDocument</var> be <var>control</var>'s <span>node navigable</span>'s <span
data-x="nav-top">top-level traversable</span>'s <span data-x="nav-document">active
document</span>.</p></li>
<li><p>If <var>control</var>'s <span>node document</span>'s <span
data-x="concept-document-origin">origin</span> is not the <span data-x="same origin">same</span>
as the <span data-x="concept-document-origin">origin</span> of <var>topDocument</var>, then
return.</p></li>
<li><p><span data-x="list empty">Empty</span> <var>topDocument</var>'s
<span>autofocus candidates</span>.</p></li>
<li><p>Set <var>topDocument</var>'s <span>autofocus processed flag</span> to true.</p></li>
</ol>
<h4><dfn>Dialog light dismiss</dfn></h4>
<p class="note">"Light dismiss" means that clicking outside of a <code>dialog</code> element whose <code
data-x="attr-dialog-closedby">closedby</code> attribute is in the <span
data-x="attr-dialog-closedby-any-state">Any</span> state will close the <code>dialog</code> element. This
is in addition to how such <code>dialog</code>s respond to <span data-x="close request">close requests</span>.</p>
<p>To <dfn>light dismiss open dialogs</dfn>, given a <code>PointerEvent</code> <var>event</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <code
data-x="dom-Event-isTrusted">isTrusted</code> attribute is true.</p></li>
<li><p>Let <var>document</var> be <var>event</var>'s <span
data-x="concept-event-target">target</span>'s <span>node document</span>.</p></li>
<li><p>If <var>document</var>'s <span>open dialogs list</span> is <span
data-x="list is empty">empty</span>, then return.</p></li>
<li><p>Let <var>ancestor</var> be the result of running <span>nearest clicked dialog</span>
given <var>event</var>.</p></li>
<li><p>If <var>event</var>'s <code data-x="dom-Event-type">type</code> is
"<code data-x="event-pointerdown">pointerdown</code>", then set <var>document</var>'s
<span>dialog pointerdown target</span> to <var>ancestor</var>.</p></li>
<li>
<p>If <var>event</var>'s <code data-x="dom-Event-type">type</code> is
"<code data-x="event-pointerup">pointerup</code>", then:</p>
<ol>
<li><p>Let <var>sameTarget</var> be true if <var>ancestor</var> is <var>document</var>'s
<span>dialog pointerdown target</span>.</p></li>
<li><p>Set <var>document</var>'s <span>dialog pointerdown target</span> to null.</p></li>
<li><p>If <var>sameTarget</var> is false, then return.</p></li>
<li><p>Let <var>topmostDialog</var> be the last element of <var>document</var>'s <span>open
dialogs list</span>.</p></li>
<li><p>If <var>ancestor</var> is <var>topmostDialog</var>, then return.</p></li>
<li><p>If <var>topmostDialog</var>'s <span>computed closed-by state</span> is not <span
data-x="attr-dialog-closedby-any-state">Any</span>, then return.</p></li>
<li><p><span>Assert</span>: <var>topmostDialog</var>'s <span
data-x="dialog-close-watcher">close watcher</span> is not null.</p></li>
<li><p><span data-x="close-watcher-request-close">Request to close</span>
<var>topmostDialog</var>'s <span data-x="dialog-close-watcher">close watcher</span> with
false.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>run light dismiss activities</dfn>, given a <code>PointerEvent</code>
<var>event</var>:</p>
<ol>
<li><p>Run <span>light dismiss open popovers</span> with <var>event</var>.</p></li>
<li><p>Run <span>light dismiss open dialogs</span> with <var>event</var>.</p></li>
</ol>
<p class="XXX"><span>Run light dismiss activities</span> will be called by the <a
href="https://github.com/w3c/pointerevents/pull/460">Pointer Events spec</a> when the user clicks
or touches anywhere on the page.</p>
<p>To find the <dfn>nearest clicked dialog</dfn>, given a <code>PointerEvent</code>
<var>event</var>:</p>
<ol>
<li><p>Let <var>target</var> be <var>event</var>'s <span
data-x="concept-event-target">target</span>.</p></li>
<li><p>If <var>target</var> is a <code>dialog</code> element, <var>target</var> has an <code
data-x="attr-dialog-open">open</code> attribute, <var>target</var>'s <span>is modal</span> is
true, and <var>event</var>'s <code data-x="mouseevent-clientx">clientX</code> and
<code data-x="mouseevent-clienty">clientY</code> are outside the bounds of <var>target</var>,
then return null.
<p class="note">The check for <code data-x="mouseevent-clientx">clientX</code> and <code
data-x="mouseevent-clienty">clientY</code> is because a pointer event that hits the <code
data-x="">::backdrop</code> pseudo element of a dialog will result in <var>event</var> having a
target of the dialog element itself.</p>
<li><p>Let <var>currentNode</var> be <var>target</var>.</p></li>
<li>
<p>While <var>currentNode</var> is not null:</p>
<ol>
<li><p>If <var>currentNode</var> is a <code>dialog</code> element and <var>currentNode</var>
has an <code data-x="attr-dialog-open">open</code> attribute, then return
<var>currentNode</var>.</p></li>
<li><p>Set <var>currentNode</var> to <var>currentNode</var>'s parent in the <span>flat
tree</span>.</p></li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<h3 split-filename="scripting">Scripting</h3>
<p>Scripts allow authors to add interactivity to their documents.</p>
<p>Authors are encouraged to use declarative alternatives to scripting where possible, as
declarative mechanisms are often more maintainable, and many users disable scripting.</p>
<div class="example">
<p>For example, instead of using a script to show or hide a section to show more details, the
<code>details</code> element could be used.</p>
</div>
<p>Authors are also encouraged to make their applications degrade gracefully in the absence of
scripting support.</p>
<div class="example">
<p>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.</p>
</div>
<h4 id="the-script-element">The <dfn
id="script" element><code>script</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span data-x="script-supporting elements">Script-supporting element</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>metadata content</span> is expected.</dd>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dd>Where <span>script-supporting elements</span> are expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>If there is no <code data-x="attr-script-src">src</code>
attribute, depends on the value of the <code
data-x="attr-script-type">type</code> attribute, but must match
<span>script content restrictions</span>.</dd>
<dd>If there <em>is</em> a <code data-x="attr-script-src">src</code>
attribute, the element must be either empty or contain only
<span>script documentation</span> that also matches <span>script
content restrictions</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-script-src">src</code></dd>
<dd><code data-x="attr-script-type">type</code></dd>
<dd><code data-x="attr-script-nomodule">nomodule</code></dd>
<dd><code data-x="attr-script-async">async</code></dd>
<dd><code data-x="attr-script-defer">defer</code></dd>
<dd><code data-x="attr-script-crossorigin">crossorigin</code></dd>
<dd><code data-x="attr-script-integrity">integrity</code></dd>
<dd><code data-x="attr-script-referrerpolicy">referrerpolicy</code></dd>
<dd><code data-x="attr-script-blocking">blocking</code></dd>
<dd><code data-x="attr-script-fetchpriority">fetchpriority</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-script">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-script">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLScriptElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute USVString <span data-x="dom-script-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-type">type</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-script-noModule">noModule</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-script-async">async</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-script-defer">defer</span>;
[<span>CEReactions</span>] attribute DOMString? <span data-x="dom-script-crossOrigin">crossOrigin</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-text">text</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-integrity">integrity</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-referrerPolicy">referrerPolicy</span>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-script-blocking">blocking</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-fetchPriority">fetchPriority</span>;
static boolean <span data-x="dom-script-supports">supports</span>(DOMString type);
// <a href="#HTMLScriptElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLScriptElement</code>.</dd>
</dl>
<p>The <code>script</code> element allows authors to include dynamic script and data blocks in
their documents. The element does not <span data-x="represents">represent</span> content for the
user.</p>
<p>The <dfn element-attr for="script"><code data-x="attr-script-type">type</code></dfn> attribute
allows customization of the type of script represented:</p>
<ul>
<li><p>Omitting the attribute, setting it to the empty string, or setting it to a
<span>JavaScript MIME type essence match</span>, means that the script is a <span>classic
script</span>, to be interpreted according to the JavaScript <i
data-x="js-prod-Script">Script</i> top-level production. Classic scripts are affected by the
<code data-x="attr-script-async">async</code> and <code data-x="attr-script-defer">defer</code>
attributes, but only when the <code data-x="attr-script-src">src</code> attribute is set.
Authors should omit the <code data-x="attr-script-type">type</code> attribute instead of
redundantly setting it.</p></li>
<li><p>Setting the attribute to an <span>ASCII case-insensitive</span> match for "<code
data-x="">module</code>" means that the script is a <span>JavaScript module script</span>, to
be interpreted according to the JavaScript <i data-x="js-prod-Module">Module</i> top-level
production. Module scripts are not affected by the <code
data-x="attr-script-defer">defer</code> attribute, but are affected by the <code
data-x="attr-script-async">async</code> attribute (regardless of the state of the <code
data-x="attr-script-src">src</code> attribute).</p></li>
<li><p>Setting the attribute to an <span>ASCII case-insensitive</span> match for "<code
data-x="">importmap</code>" means that the script is an <span>import map</span>, containing
JSON that will be used to control the behavior of <span data-x="resolve a module
specifier">module specifier resolution</span>. Import maps can only be inline, i.e., the <code
data-x="attr-script-src">src</code> attribute and most other attributes are meaningless and not
to be used with them.</p></li>
<li><p>Setting the attribute to any other value means that the script is a <dfn>data
block</dfn>, which is not processed. None of the <code>script</code> attributes (except <code
data-x="attr-script-type">type</code> itself) have any effect on data blocks. Authors must use
a <span>valid MIME type string</span> that is not a <span>JavaScript MIME type essence
match</span> to denote data blocks.</p></li>
</ul>
<p class="note">The requirement that <span data-x="data block">data blocks</span>
<!--non-normative-->must be denoted using a <span>valid MIME type string</span> is in place to
avoid potential future collisions. If this specification ever adds additional types of
<span data-x="concept-script">script</span>, they will be triggered by setting the <code
data-x="attr-script-type">type</code> attribute to something which is not a MIME type, like how
the "<code data-x="">module</code>" value denotes <span data-x="module script">module
scripts</span>. 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.</p>
<p><span data-x="classic script">Classic scripts</span> and <span
data-x="JavaScript module script">JavaScript module scripts</span> can be embedded inline, or be
imported from an external file using the <dfn for="script" element-attr><code
data-x="attr-script-src">src</code></dfn> attribute, which if specified gives the <span>URL</span>
of the external script resource to use. If <code data-x="attr-script-src">src</code> is specified,
it must be a <span>valid non-empty URL potentially surrounded by spaces</span>.</p>
<p>The contents of inline <code>script</code> elements, or the external script resource, must
conform with the requirements of the JavaScript specification's <i
data-x="js-prod-Script">Script</i> or <i data-x="js-prod-Module">Module</i> productions, for <span
data-x="classic script">classic scripts</span> and <span data-x="JavaScript module
script">JavaScript module scripts</span> respectively. <ref>JAVASCRIPT</ref></p>
<p>The contents of the external script resource for <span data-x="CSS module script">CSS module
scripts</span> must conform to the requirements of the CSS specification. <ref>CSS</ref></p>
<p>The contents of the external script resource for <span data-x="JSON module script">JSON module
scripts</span> must conform to the requirements of the JSON specification. <ref>JSON</ref></p>
<p>The contents of inline <code>script</code> elements for <span data-x="import map">import
maps</span> must conform with the <span>import map authoring requirements</span>.</p>
<p>For <span>import map</span> <code>script</code> elements, the <code
data-x="attr-script-src">src</code>, <code data-x="attr-script-async">async</code>, <code
data-x="attr-script-nomodule">nomodule</code>, <code data-x="attr-script-defer">defer</code>,
<code data-x="attr-script-crossorigin">crossorigin</code>, <code
data-x="attr-script-integrity">integrity</code>, and <code
data-x="attr-script-referrerpolicy">referrerpolicy</code> attributes must not be specified.</p>
<p>A document must not have more than one <span>import map</span> <code>script</code> element.</p>
<p>When used to include <span data-x="data block">data blocks</span>, the data must be embedded
inline, the format of the data must be given using the <code data-x="attr-script-type">type</code>
attribute, and the contents of the <code>script</code> element must conform to the requirements
defined for the format used. The <code data-x="attr-script-src">src</code>, <code
data-x="attr-script-async">async</code>, <code data-x="attr-script-nomodule">nomodule</code>,
<code data-x="attr-script-defer">defer</code>, <code
data-x="attr-script-crossorigin">crossorigin</code>, <code
data-x="attr-script-integrity">integrity</code>, <code
data-x="attr-script-referrerpolicy">referrerpolicy</code>, and <code
data-x="attr-script-fetchpriority">fetchpriority</code> attributes must not be specified.</p>
<p>The <dfn element-attr for="script"><code data-x="attr-script-nomodule">nomodule</code></dfn>
attribute is a <span>boolean attribute</span> that prevents a script from being executed in user
agents that support <span data-x="module script">module scripts</span>. This allows selective
execution of <span data-x="module script">module scripts</span> in modern user agents and <span
data-x="classic script">classic scripts</span> in older user agents, <a
href="#script-nomodule-example">as shown below</a>. The <code
data-x="attr-script-nomodule">nomodule</code> attribute must not be specified on <span
data-x="module script">module scripts</span> (and will be ignored if it is).</p>
<p>The <dfn element-attr for="script"><code data-x="attr-script-async">async</code></dfn> and
<dfn element-attr for="script"><code data-x="attr-script-defer">defer</code></dfn> attributes are
<span data-x="boolean attribute">boolean attributes</span> that indicate how the script should be
evaluated. <span data-x="classic script">Classic scripts</span> may specify <code
data-x="attr-script-defer">defer</code> or <code data-x="attr-script-async">async</code>, but must
not specify either unless the <code data-x="attr-script-src">src</code> attribute is present.
<span data-x="module script">Module scripts</span> may specify the <code
data-x="attr-script-async">async</code> attribute, but must not specify the <code
data-x="attr-script-defer">defer</code> attribute.</p>
<p>There are several possible modes that can be selected using these attributes, and depending on
the script's type.</p>
<p>For <span data-x="classic script">classic scripts</span>, if the <code
data-x="attr-script-async">async</code> attribute is present, then the classic script will be
fetched <span>in parallel</span> to parsing and evaluated as soon as it is available (potentially
before parsing completes). If the <code data-x="attr-script-async">async</code> attribute is not
present but the <code data-x="attr-script-defer">defer</code> attribute is present, then the
classic script will be fetched <span>in parallel</span> 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.</p>
<p>For <span data-x="module script">module scripts</span>, if the <code
data-x="attr-script-async">async</code> attribute is present, then the module script and all its
dependencies will be fetched <span>in parallel</span> 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 <span>in parallel</span> to parsing and
evaluated when the page has finished parsing. (The <code data-x="attr-script-defer">defer</code>
attribute has no effect on module scripts.)</p>
<p>This is all summarized in the following schematic diagram:</p>
<p><img src="/images/asyncdefer.svg" style="width: 80%; min-width: 820px;" alt="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." class="darkmode-aware"></p>
<p class="note">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 <code>script</code> <a href="#scriptTag">start</a> and <a
href="#scriptEndTag">end</a> tags in HTML, <a href="#scriptForeignEndTag">in foreign content</a>,
and <a href="#scriptTagXML">in XML</a>, the rules for the <code
data-x="dom-document-write">document.write()</code> method, the handling of <a
href="#scripting">scripting</a>, etc.</p>
<p class="note">When inserted using the <code data-x="dom-document-write">document.write()</code>
method, <code>script</code> elements <a href="#document-written-scripts-intervention">usually</a>
execute (typically blocking further script execution or HTML parsing). When inserted using the
<code data-x="dom-element-innerHTML">innerHTML</code> and <code
data-x="dom-element-outerHTML">outerHTML</code> attributes, they do not execute at all.</p>
<p>The <code data-x="attr-script-defer">defer</code> attribute may be specified even if the <code
data-x="attr-script-async">async</code> attribute is specified, to cause legacy web browsers that
only support <code data-x="attr-script-defer">defer</code> (and not <code
data-x="attr-script-async">async</code>) to fall back to the <code
data-x="attr-script-defer">defer</code> behavior instead of the blocking behavior that
is the default.</p>
<p>The <dfn element-attr for="script"><code
data-x="attr-script-crossorigin">crossorigin</code></dfn> attribute is a <span>CORS settings
attribute</span>. For <span data-x="classic script">classic scripts</span>, it controls whether
error information will be exposed, when the script is obtained from other <span
data-x="origin">origins</span>. For <span data-x="module script">module scripts</span>, it
controls the <span data-x="concept-request-credentials-mode">credentials mode</span> used for
cross-origin requests.</p>
<p class="note">Unlike <span data-x="classic script">classic scripts</span>, <span
data-x="module script">module scripts</span> require the use of the <span
data-x="CORS protocol">CORS protocol</span> for cross-origin fetching.</p>
<p>The <dfn for="script" element-attr><code data-x="attr-script-integrity">integrity</code></dfn>
attribute represents the <span data-x="concept-request-integrity-metadata">integrity
metadata</span> for requests which this element is responsible for. The value is text. The <code
data-x="attr-script-integrity">integrity</code> attribute must not be specified when the <code
data-x="attr-script-src">src</code> attribute is not specified. <ref>SRI</ref></p>
<p>The <dfn element-attr for="script"><code
data-x="attr-script-referrerpolicy">referrerpolicy</code></dfn> attribute is a <span>referrer
policy attribute</span>. Its purpose is to set the <span>referrer policy</span> used when <span
data-x="concept-fetch">fetching</span> the script, as well as any scripts imported from it.
<ref>REFERRERPOLICY</ref></p>
<div class="example">
<p>An example of a <code>script</code> element's referrer policy being used when fetching
imported scripts but not other subresources:</p>
<pre><code class="html"><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></code></pre>
</div>
<p>The <dfn element-attr for="script"><code data-x="attr-script-blocking">blocking</code></dfn>
attribute is a <span>blocking attribute</span>.</p>
<p>The <dfn element-attr for="script"><code
data-x="attr-script-fetchpriority">fetchpriority</code></dfn> attribute is a
<span>fetch priority attribute</span>. Its purpose is to set the <span
data-x="concept-request-priority">priority</span> used when <span
data-x="concept-fetch">fetching</span> the script.</p>
<p>Changing the <code data-x="attr-script-src">src</code>, <code
data-x="attr-script-type">type</code>, <code data-x="attr-script-nomodule">nomodule</code>, <code
data-x="attr-script-async">async</code>, <code data-x="attr-script-defer">defer</code>, <code
data-x="attr-script-crossorigin">crossorigin</code>, <code
data-x="attr-script-integrity">integrity</code>, <code
data-x="attr-script-referrerpolicy">referrerpolicy</code>, and <code
data-x="attr-script-fetchpriority">fetchpriority</code> attributes dynamically has no direct
effect; these attributes are only used at specific times described below.</p> <!-- by implication,
changes to the base URL also have no effect -->
<div w-nodev>
<p>The IDL attributes <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-src">src</code></dfn>, <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-type">type</code></dfn>, <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-defer">defer</code></dfn>, <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-integrity">integrity</code></dfn>, and <dfn attribute
for="HTMLScriptElement"><code data-x="dom-script-blocking">blocking</code></dfn>, must each
<span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-referrerPolicy">referrerPolicy</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-script-referrerpolicy">referrerpolicy</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-fetchPriority">fetchPriority</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-script-fetchpriority">fetchpriority</code>
content attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-crossOrigin">crossOrigin</code></dfn> IDL attribute must <span>reflect</span>
the <code data-x="attr-script-crossorigin">crossorigin</code> content attribute, <span>limited to
only known values</span>.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-noModule">noModule</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-script-nomodule">nomodule</code> content attribute.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code data-x="dom-script-async">async</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="script-force-async">force async</span> is true, then
return true.</p></li>
<li><p>If <span>this</span>'s <code data-x="attr-script-async">async</code> content attribute is
present, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>The <code data-x="dom-script-async">async</code> setter steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <span data-x="script-force-async">force async</span> to
false.</p></li>
<li><p>If the given value is true, then set <span>this</span>'s <code
data-x="attr-script-async">async</code> content attribute to the empty string.</p></li>
<li><p>Otherwise, remove <span>this</span>'s <code data-x="attr-script-async">async</code>
content attribute.</p></li>
</ol>
</div>
<dl class="domintro">
<dt><code data-x=""><var>script</var>.<span subdfn data-x="dom-script-text">text</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>child text content</span> of the element.</p>
<p>Can be set, to replace the element's children with the given value.</p>
</dd>
<dt><code data-x=""><code>HTMLScriptElement</code>.<span subdfn data-x="dom-script-supports">supports</span>(<var>type</var>)</code></dt>
<dd>
<p>Returns true if the given <var>type</var> is a script type supported by the user agent. The
possible script types in this specification are "<code data-x="">classic</code>", "<code
data-x="">module</code>", and "<code data-x="">importmap</code>", but others might be added in
the future.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLScriptElement"><code data-x="dom-script-text">text</code></dfn>
attribute's getter must return this <code>script</code> element's <span>child text
content</span>.</p>
<p>The <code data-x="dom-script-text">text</code> attribute's setter must <span>string replace
all</span> with the given value within this <code>script</code> element.</p>
</div>
<div w-nodev>
<p>The <dfn method for="HTMLScriptElement"><code
data-x="dom-script-supports">supports(<var>type</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <var>type</var> <span>is</span> "<code data-x="">classic</code>", then return
true.</p></li>
<li><p>If <var>type</var> <span>is</span> "<code data-x="">module</code>", then return
true.</p></li>
<li><p>If <var>type</var> <span>is</span> "<code data-x="">importmap</code>", then return
true.</p></li>
<li><p>Return false.</p></li>
</ol>
</div>
<p class="note">The <var>type</var> argument has to exactly match these values; we do not
perform an <span>ASCII case-insensitive</span> match. This is different from how <code
data-x="attr-script-type">type</code> content attribute values are treated, and how
<code>DOMTokenList</code>'s <code data-x="dom-DOMTokenList-supports">supports()</code> method
works, but it aligns with the <code>WorkerType</code> enumeration used in the <code
data-x="dom-Worker">Worker()</code> constructor.</p>
<div class="example">
<p>In this example, two <code>script</code> elements are used. One embeds an external
<span>classic script</span>, and the other includes some data as a <span>data block</span>.</p>
<pre><code class="html"><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></code></pre>
<p>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.</p>
</div>
<div class="example">
<p>The following sample shows how a <code>script</code> element can be used to define a function
that is then used by other parts of the document, as part of a <span>classic script</span>. It
also shows how a <code>script</code> element can be used to invoke script while the document is
being parsed, in this case to initialize the form's output.</p>
<pre><code class="html"><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></code></pre>
</div>
<div class="example" id="script-type-module-example-1">
<p>The following sample shows how a <code>script</code> element can be used to include an
external <span>JavaScript module script</span>.
<pre><code class="html"><script type="module" src="app.mjs"></script></code></pre>
<p>This module, and all its dependencies (expressed through JavaScript <code
data-x="">import</code> 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
<code data-x="">app.mjs</code> will be evaluated.</p>
<p>Additionally, if code from another <code>script</code> element in the same <code>Window</code>
imports the module from <code data-x="">app.mjs</code> (e.g. via <code data-x="">import
"./app.mjs";</code>), then the same <span>JavaScript module script</span> created by the
former <code>script</code> element will be imported.</p>
</div>
<div class="example" id="script-nomodule-example">
<p>This example shows how to include a <span>JavaScript module script</span> for modern user
agents, and a <span>classic script</span> for older user agents:</p>
<pre><code class="html"><script type="module" src="app.mjs"></script>
<script nomodule defer src="classic-app-bundle.js"></script></code></pre>
<p>In modern user agents that support <span data-x="JavaScript module script">JavaScript module
scripts</span>, the <code>script</code> element with the <code
data-x="attr-script-nomodule">nomodule</code> attribute will be ignored, and the
<code>script</code> element with a <code data-x="attr-script-type">type</code> of "<code
data-x="">module</code>" will be fetched and evaluated (as a <span>JavaScript module
script</span>). Conversely, older user agents will ignore the <code>script</code> element with a
<code data-x="attr-script-type">type</code> of "<code data-x="">module</code>", as that is an
unknown script type for them — but they will have no problem fetching and evaluating the other
<code>script</code> element (as a <span>classic script</span>), since they do not implement the
<code data-x="attr-script-nomodule">nomodule</code> attribute.</p>
</div>
<div class="example" id="script-type-module-example-2">
<p>The following sample shows how a <code>script</code> element can be used to write an inline
<span>JavaScript module script</span> 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):
<ref>XKCD1288</ref></p>
<pre><code class="html"><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></code></pre>
<p>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 <span>global object</span>. Also note that no matter
where this <code>script</code> element appears in the document, it will not be evaluated until
both document parsing has complete and its dependency (<code data-x="">dom-utils.mjs</code>) has
been fetched and evaluated.</p>
</div>
<div class="example" id="json-module-script-example">
<p>The following sample shows how a <span>JSON module script</span> can be imported from inside
a <span>JavaScript module script</span>:</p>
<pre><code class="html" data-x=""><script type="module">
import peopleInSpace from "http://api.open-notify.org/astros.json" with { 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></code></pre>
<p>MIME type checking for module scripts is strict. In order for the fetch of the <span>JSON
module script</span> to succeed, the HTTP response must have a <span>JSON MIME type</span>, for
example <code data-x="">Content-Type: text/json</code>. On the other hand, if the <code
data-x="">with { type: "json" }</code> part of the statement is omitted, it is assumed that the
intent is to import a <span>JavaScript module script</span>, and the fetch will fail if the HTTP
response has a MIME type that is not a <span>JavaScript MIME type</span>.</p>
</div>
<div w-nodev>
<h5 id="script-processing-model">Processing model</h5>
<p>A <code>script</code> element has several associated pieces of state.</p>
<p>A <code>script</code> element has a <dfn>parser document</dfn>, which is either null or a
<code>Document</code>, initially null. It is set by the <span>HTML parser</span> and the
<span>XML parser</span> on <code>script</code> elements they insert, and affects the processing
of those elements. <code>script</code> elements with non-null <span data-x="parser
document">parser documents</span> are known as <dfn export
for="script">parser-inserted</dfn>.</p>
<p>A <code>script</code> element has a <dfn>preparation-time document</dfn>, which is either null
or a <code>Document</code>, initially null. It is used to prevent scripts that move between
documents during <span data-x="prepare the script element">preparation</span> from <span
data-x="execute the script element">executing</span>.</p>
<p id="non-blocking">A <code>script</code> element has a <dfn data-x="script-force-async">force
async</dfn> boolean, initially true. It is set to false by the <span>HTML parser</span> and the
<span>XML parser</span> on <code>script</code> elements they insert, and when the element gets an
<code data-x="attr-script-async">async</code> content attribute added.</p>
<p>A <code>script</code> element has a <dfn data-x="concept-script-external">from an external
file</dfn> boolean, initially false. It is determined when the script is <span data-x="prepare
the script element">prepared</span>, based on the <code data-x="attr-script-src">src</code>
attribute of the element at that time.</p>
<p>A <code>script</code> element has a <dfn>ready to be parser-executed</dfn> boolean, initially
false. This is used only used for elements that are also <span>parser-inserted</span>, to let the
parser know when to execute the script.</p>
<p>A <code>script</code> element has an <dfn>already started</dfn> boolean, initially false.</p>
<p>A <code>script</code> element has a <dfn data-x="concept-script-delay-load">delaying the
load event</dfn> boolean, initially false.</p>
<p>A <code>script</code> element has a <dfn data-x="concept-script-type">type</dfn>, which is
either null, "<code data-x="">classic</code>", "<code data-x="">module</code>", or "<code
data-x="">importmap</code>", initially null. It is determined when the element is <span
data-x="prepare the script element">prepared</span>, based on the <code
data-x="attr-script-type">type</code> attribute of the element at that time.</p>
<p id="concept-script-script">A <code>script</code> element has a <dfn
data-x="concept-script-result">result</dfn>, which is either "<code
data-x="">uninitialized</code>", null (representing an error), a <span
data-x="concept-script">script</span>, or an <span>import map parse result</span>. It is
initially "<code data-x="">uninitialized</code>".</p>
<p id="the-script-is-ready">A <code>script</code> element has <dfn>steps to run when the result
is ready</dfn>, which are a series of steps or null, initially null. To <dfn>mark as ready</dfn> a
<code>script</code> element <var>el</var> given a <span
data-x="concept-script">script</span>, <span>import map parse result</span>, or null
<var>result</var>:</p>
<ol>
<li><p>Set <var>el</var>'s <span data-x="concept-script-result">result</span> to
<var>result</var>.</p></li>
<li><p>If <var>el</var>'s <span>steps to run when the result is ready</span> are not null, then
run them.</p></li>
<!-- This is not strictly needed but seems like good hygiene. -->
<li><p>Set <var>el</var>'s <span>steps to run when the result is ready</span> to null.</p></li>
<li><p>Set <var>el</var>'s <span data-x="concept-script-delay-load">delaying the load
event</span> to false.</p></li>
</ol>
<hr>
<p>A <code>script</code> element <var>el</var> is <span>implicitly potentially
render-blocking</span> if <var>el</var>'s <span data-x="concept-script-type">type</span> is
"<code data-x="">classic</code>", <var>el</var> is <span>parser-inserted</span>, and
<var>el</var> does not have an <code data-x="attr-script-async">async</code> or <code
data-x="attr-script-defer">defer</code> attribute.</p>
<p>The <span data-x="concept-node-clone-ext">cloning steps</span> for <code>script</code>
elements given <var>node</var>, <var>copy</var>, and <var>subtree</var> are to set
<var>copy</var>'s <span>already started</span> to <var>node</var>'s <span>already
started</span>.</p>
<p>When an <code data-x="attr-script-async">async</code> attribute is added to a
<code>script</code> element <var>el</var>, the user agent must set <var>el</var>'s
<span data-x="script-force-async">force async</span> to false.</p>
<!-- There's no need to set it to true it when the attribute is removed since you can't have the
attribute present and force async = true at the same time. -->
<p>Whenever a <code>script</code> element <var>el</var>'s <span
data-x="concept-script-delay-load">delaying the load event</span> is true, the user agent must
<span>delay the load event</span> of <var>el</var>'s <span>preparation-time document</span>.</p>
<hr>
<p>The <code>script</code> <span>HTML element post-connection steps</span>, given
<var>insertedNode</var>, are:</p>
<ol>
<li>
<p>If <var>insertedNode</var> is not <span>connected</span>, then return.</p>
<div class="example">
<p>This can happen in the case where an earlier-inserted <code>script</code> removes a
later-inserted <code>script</code>. For instance:</p>
<pre><code class="html"><script>
const script1 = document.createElement('script');
script1.innerText = `
document.querySelector('#script2').remove();
`;
const script2 = document.createElement('script');
script2.id = 'script2';
script2.textContent = `console.log('script#2 running')`;
document.body.append(script1, script2);
</script></code></pre>
<p>Nothing is printed to the console in this example. By the time the <span>HTML element
post-connection steps</span> run for the first <code>script</code> that was atomically inserted
by <code data-x="dom-Node-append">append()</code>, it can observe that the second
<code>script</code> is already <span>connected</span> to the DOM. It removes the second
<code>script</code>, so that by the time <em>its</em> <span>HTML element post-connection
steps</span> run, it is no longer <span>connected</span>, and does not get <span
data-x="prepare the script element">prepared</span>.</p>
</div>
</li>
<li><p>If <var>insertedNode</var> is <span>parser-inserted</span>, then return.</p></li>
<li><p><span>Prepare the script element</span> given <var>insertedNode</var>.</p></li>
</ol>
<p>The <code>script</code> <span>children changed steps</span> are:</p>
<ol>
<li><p>Run the <code>script</code> <span>HTML element post-connection steps</span>, given the
<code>script</code> element.</p></li>
</ol>
<div class="example">
<p>This has an interesting implication on the execution order of a <code>script</code> element
and any newly-inserted child <code>script</code> elements. Consider the following snippet:</p>
<pre><code class="html"><script id=outer-script></script>
<script>
const outerScript = document.querySelector('#outer-script');
const start = new Text('console.log(1);');
const innerScript = document.createElement('script');
innerScript.textContent = `console.log('inner script executing')`;
const end = new Text('console.log(2);');
outerScript.append(start, innerScript, end);
// Logs:
// 1
// 2
// inner script executing
</script></code></pre>
<p>By the time the second script block executes, the <code data-x="">outer-script</code> has
already been <span data-x="prepare the script element">prepared</span>, but because it is empty,
it did not execute and therefore is not marked as <span>already started</span>. The atomic
insertion of the <code>Text</code> nodes and nested <code>script</code> element have the
following effects:</p>
<ol>
<li><p>All three child nodes get atomically inserted as children of <code
data-x="">outer-script</code>; all of their <span data-x="concept-node-insert-ext">insertion
steps</span> run, which have no observable consequences in this case.</p></li>
<li><p>The <code data-x="">outer-script</code>'s <span>children changed steps</span> run, which
<span data-x="prepare the script element">prepares</span> that script; because its body is now
non-empty, this executes the contents of the two <code>Text</code> nodes, in order.</p></li>
<li><p>The <code>script</code> <span>HTML element post-connection steps</span> finally run for
<code data-x="">innerScript</code>, causing its body to execute.</p></li>
</ol>
</div>
<p>The following <span data-x="concept-element-attributes-change-ext">attribute change
steps</span>, given <var>element</var>, <var>localName</var>, <var>oldValue</var>,
<var>value</var>, and <var>namespace</var>, are used for all <code>script</code> elements:</p>
<ol>
<li><p>If <var>namespace</var> is not null, then return.</p></li>
<li><p>If <var>localName</var> is <code data-x="attr-script-src">src</code>, then run the
<code>script</code> <span>HTML element post-connection steps</span>, given
<var>element</var>.</p></li>
</ol>
<p id="prepare-a-script">To <dfn>prepare the script element</dfn> given a <code>script</code>
element <var>el</var>:</p>
<ol>
<li><p>If <var>el</var>'s <span>already started</span> is true, then return.</p></li>
<li><p>Let <var>parser document</var> be <var>el</var>'s <span>parser document</span>.</p></li>
<li>
<p>Set <var>el</var>'s <span>parser document</span> to null.</p>
<p class="note">This is done so that if parser-inserted <code>script</code> 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.</p>
</li>
<li>
<p>If <var>parser document</var> is non-null and <var>el</var> does not have an <code
data-x="attr-script-async">async</code> attribute, then set <var>el</var>'s <span
data-x="script-force-async">force async</span> to true.</p>
<p class="note">This is done so that if a parser-inserted <code>script</code> 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 <code
data-x="attr-script-async">async</code> attribute isn't set.</p>
</li>
<li><p>Let <var>source text</var> be <var>el</var>'s <span>child text content</span>.</p></li>
<li id="script-processing-empty"><p>If <var>el</var> has no <code
data-x="attr-script-src">src</code> attribute, and <var>source text</var> is the empty string,
then return.</p></li>
<li><p>If <var>el</var> is not <span>connected</span>, then return.</p></li>
<li id="script-processing-prepare">
<p>If any of the following are true:</p>
<ul>
<li><p><var>el</var> has a <code data-x="attr-script-type">type</code> attribute whose value is
the empty string;</p></li>
<li><p><var>el</var> has no <code data-x="attr-script-type">type</code> attribute but it has a
<code data-x="attr-script-language">language</code> attribute and <em>that</em> attribute's
value is the empty string; or</p></li>
<li><p><var>el</var> has neither a <code data-x="attr-script-type">type</code> attribute nor a
<code data-x="attr-script-language">language</code> attribute,</p></li>
</ul>
<p>then let <var>the script block's type string</var> for this <code>script</code> element be
"<code data-x="">text/javascript</code>".</p>
<p>Otherwise, if <var>el</var> has a <code data-x="attr-script-type">type</code> attribute, then
let <var>the script block's type string</var> be the value of that attribute with <span
data-x="strip leading and trailing ASCII whitespace">leading and trailing ASCII whitespace
stripped</span>.</p>
<p>Otherwise, <var>el</var> has a non-empty <code data-x="attr-script-language">language</code>
attribute; let <var>the script block's type string</var> be the concatenation of "<code
data-x="">text/</code>" and the value of <var>el</var>'s <code
data-x="attr-script-language">language</code> attribute.</p>
<!-- user agents already support, e.g., type="text/javascript1.3", so we don't have to support
that separately. -->
<p class="note">The <code data-x="attr-script-language">language</code> attribute is never
conforming, and is always ignored if there is a <code data-x="attr-script-type">type</code>
attribute present.</p>
</li>
<li><p>If <var>the script block's type string</var> is a <span>JavaScript MIME type essence
match</span>, then set <var>el</var>'s <span data-x="concept-script-type">type</span> to "<code
data-x="">classic</code>".</p></li>
<li><p>Otherwise, if <var>the script block's type string</var> is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">module</code>", then set
<var>el</var>'s <span data-x="concept-script-type">type</span> to "<code
data-x="">module</code>".</p></li>
<li><p>Otherwise, if <var>the script block's type string</var> is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">importmap</code>", then set
<var>el</var>'s <span data-x="concept-script-type">type</span> to "<code
data-x="">importmap</code>".</p></li>
<li><p>Otherwise, return. (No script is executed, and <var>el</var>'s <span
data-x="concept-script-type">type</span> is left as null.)</p></li>
<li><p>If <var>parser document</var> is non-null, then set <var>el</var>'s <span>parser
document</span> back to <var>parser document</var> and set <var>el</var>'s <span
data-x="script-force-async">force async</span> to false.</p></li>
<li id="script-processing-start"><p>Set <var>el</var>'s <span>already started</span> to
true.</p></li>
<li><p>Set <var>el</var>'s <span>preparation-time document</span> to its <span>node
document</span>.</p>
<li><p>If <var>parser document</var> is non-null, and <var>parser document</var> is not equal to
<var>el</var>'s <span>preparation-time document</span>, then return.</p></li>
<li id="script-processing-noscript"> <p>If <span data-x="concept-n-noscript">scripting is
disabled</span> for <var>el</var>, then return.</p>
<p class="note">The definition of <span data-x="concept-n-noscript">scripting is
disabled</span> means that, amongst others, the following scripts will not execute: scripts in
<code>XMLHttpRequest</code>'s <code data-x="dom-XMLHttpRequest-responseXML">responseXML</code>
documents, scripts in <code>DOMParser</code>-created documents, scripts in documents created by
<code>XSLTProcessor</code>'s <code
data-x="dom-XSLTProcessor-transformToDocument">transformToDocument</code> feature, and scripts
that are first inserted by a script into a <code>Document</code> that was created using the
<code data-x="dom-DOMImplementation-createDocument">createDocument()</code> API. <ref>XHR</ref>
<ref>DOMPARSING</ref> <ref>XSLTP</ref> <ref>DOM</ref></p>
</li>
<li>
<p>If <var>el</var> has a <code data-x="attr-script-nomodule">nomodule</code> content attribute
and its <span data-x="concept-script-type">type</span> is "<code data-x="">classic</code>",
then return.</p>
<p class="note">This means specifying <code data-x="attr-script-nomodule">nomodule</code> on a
<span>module script</span> has no effect; the algorithm continues onward.</p>
</li>
<li id="script-processing-csp"><p>If <var>el</var> does not have a <code
data-x="attr-script-src">src</code> content attribute, and the <span>Should element's inline
behavior be blocked by Content Security Policy?</span> algorithm returns "<code
data-x="">Blocked</code>" when given <var>el</var>, "<code data-x="">script</code>", and
<var>source text</var>, then return. <ref>CSP</ref></p></li>
<li id="script-processing-for">
<p>If <var>el</var> has an <code data-x="attr-script-event">event</code> attribute and a <code
data-x="attr-script-for">for</code> attribute, and <var>el</var>'s <span
data-x="concept-script-type">type</span> is "<code data-x="">classic</code>", then:</p>
<ol>
<li><p>Let <var>for</var> be the value of <var>el</var>'s <code
data-x="attr-script-for">for</code> attribute.</p></li>
<li><p>Let <var>event</var> be the value of <var>el</var>'s <code
data-x="attr-script-event">event</code> attribute.</p></li>
<li><p><span>Strip leading and trailing ASCII whitespace</span> from <var>event</var> and
<var>for</var>.</p></li>
<li><p>If <var>for</var> is not an <span>ASCII case-insensitive</span> match for the string
"<code data-x="">window</code>", then return.</p></li>
<li><p>If <var>event</var> is not an <span>ASCII case-insensitive</span> match for either the
string "<code data-x="">onload</code>" or the string "<code data-x="">onload()</code>", then
return.</p></li>
</ol>
</li>
<li id="script-processing-encoding">
<p>If <var>el</var> has a <code data-x="attr-script-charset">charset</code> attribute, then let
<var>encoding</var> be the result of <span>getting an encoding</span> from the value of the
<code data-x="attr-script-charset">charset</code> attribute.</p>
<p>If <var>el</var> does not have a <code data-x="attr-script-charset">charset</code>
attribute, or if <span>getting an encoding</span> failed, then let <var>encoding</var> be
<var>el</var>'s <span>node document</span>'s <span data-x="document's character encoding">the
encoding</span>.</p>
<p class="note">If <var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">module</code>", this encoding will be ignored.</p>
</li>
<li><p>Let <var>classic script CORS setting</var> be the current state of <var>el</var>'s <code
data-x="attr-script-crossorigin">crossorigin</code> content attribute.</p></li>
<li><p>Let <var>module script credentials mode</var> be the <span>CORS settings attribute
credentials mode</span> for <var>el</var>'s <code
data-x="attr-script-crossorigin">crossorigin</code> content attribute.</p>
<li><p>Let <var>cryptographic nonce</var> be <var>el</var>'s <span>[[CryptographicNonce]]</span>
internal slot's value.</p></li>
<li>
<p>If <var>el</var> has an <code data-x="attr-script-integrity">integrity</code> attribute,
then let <var>integrity metadata</var> be that attribute's value.</p>
<p>Otherwise, let <var>integrity metadata</var> be the empty string.</p>
</li>
<li><p>Let <var>referrer policy</var> be the current state of <var>el</var>'s <code
data-x="attr-script-referrerpolicy">referrerpolicy</code> content attribute.</p></li>
<li><p>Let <var>fetch priority</var> be the current state of <var>el</var>'s <code
data-x="attr-script-fetchpriority">fetchpriority</code> content attribute.</p></li>
<li><p>Let <var>parser metadata</var> be "<code data-x="">parser-inserted</code>" if
<var>el</var> is <span>parser-inserted</span>, and "<code data-x="">not-parser-inserted</code>"
otherwise.</p></li>
<li><p>Let <var>options</var> be a <span>script fetch options</span> whose <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is <var>cryptographic
nonce</var>, <span data-x="concept-script-fetch-options-integrity">integrity metadata</span> is
<var>integrity metadata</var>, <span data-x="concept-script-fetch-options-parser">parser
metadata</span> is <var>parser metadata</var>, <span
data-x="concept-script-fetch-options-credentials">credentials mode</span> is <var>module script
credentials mode</var>, <span data-x="concept-script-fetch-options-referrer-policy">referrer
policy</span> is <var>referrer policy</var>, and <span
data-x="concept-script-fetch-options-fetch-priority">fetch priority</span> is <var>fetch
priority</var>.</p></li>
<li><p>Let <var>settings object</var> be <var>el</var>'s <span>node document</span>'s
<span>relevant settings object</span>.</p></li>
<li id="script-processing-src-prepare">
<p>If <var>el</var> has a <code data-x="attr-script-src">src</code> content attribute, then:</p>
<ol>
<li>
<p>If <var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">importmap</code>", then <span>queue an element task</span> on the <span>DOM
manipulation task source</span> given <var>el</var> to <span data-x="concept-event-fire">fire
an event</span> named <code data-x="event-error">error</code> at <var>el</var>, and
return.</p>
<p class="note">External import map scripts are not currently supported. See <a
href="https://github.com/WICG/import-maps/issues/235">WICG/import-maps issue #235</a> for
discussions on adding support.</p>
</li>
<li><p>Let <var>src</var> be the value of <var>el</var>'s <code
data-x="attr-script-src">src</code> attribute.</p></li>
<li><p>If <var>src</var> is the empty string, then <span>queue an element task</span> on the
<span>DOM manipulation task source</span> given <var>el</var> to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
at <var>el</var>, and return.</p></li>
<li><p>Set <var>el</var>'s <span data-x="concept-script-external">from an external file</span>
to true.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given
<var>src</var>, relative to <var>el</var>'s <span>node document</span>.</p></li>
<li><p>If <var>url</var> is failure, then <span>queue an element task</span> on the <span>DOM
manipulation task source</span> given <var>el</var> to <span data-x="concept-event-fire">fire
an event</span> named <code data-x="event-error">error</code> at <var>el</var>, and
return.</p></li>
<li><p>If <var>el</var> is <span>potentially render-blocking</span>, then <span>block
rendering</span> on <var>el</var>.</p></li>
<li><p>Set <var>el</var>'s <span data-x="concept-script-delay-load">delaying the load
event</span> to true.</p></li>
<li><p>If <var>el</var> is currently <span>render-blocking</span>, then set
<var>options</var>'s <span data-x="concept-script-fetch-options-render-blocking">
render-blocking</span> to true.</p></li>
<li>
<p>Let <var>onComplete</var> given <var>result</var> be the following steps:</p>
<ol>
<li><p><span>Mark as ready</span> <var>el</var> given <var>result</var>.</p></li>
</ol>
</li>
<li>
<p>Switch on <var>el</var>'s <span data-x="concept-script-type">type</span>:</p>
<dl class="switch">
<dt>"<code data-x="">classic</code>"</dt>
<dd>
<p><span>Fetch a classic script</span> given <var>url</var>, <var>settings object</var>,
<var>options</var>, <var>classic script CORS setting</var>, <var>encoding</var>, and
<var>onComplete</var>.</p>
</dd>
<dt>"<code data-x="">module</code>"</dt>
<dd>
<p>If <var>el</var> does not have an <code data-x="attr-script-integrity">integrity</code>
attribute, then set <var>options</var>'s <span
data-x="concept-script-fetch-options-integrity">integrity metadata</span> to the result of
<span>resolving a module integrity metadata</span> with <var>url</var> and <var>settings
object</var>.</p>
<p><span>Fetch an external module script graph</span> given <var>url</var>, <var>settings
object</var>, <var>options</var>, and <var>onComplete</var>.</p>
</dd>
</dl>
<p>For performance reasons, user agents may start fetching the classic script or module graph
(as defined above) as soon as the <code data-x="attr-script-src">src</code> attribute is set,
instead, in the hope that <var>el</var> will become connected (and that the <code
data-x="attr-script-crossorigin">crossorigin</code> attribute won't change value in the
meantime). Either way, once <var>el</var> <span>becomes connected</span>, the load must have
started as described in this step. If the UA performs such prefetching, but <var>el</var>
never becomes connected, or the <code data-x="attr-script-src">src</code> attribute is
dynamically changed, <!-- or the base URL is dynamically changed,--> or the <code
data-x="attr-script-crossorigin">crossorigin</code> attribute is dynamically changed, then the
user agent will not execute the script so obtained, and the fetching process will have been
effectively wasted.</p>
</li>
</ol>
</li>
<li id="establish-script-block-source">
<p>If <var>el</var> does not have a <code data-x="attr-script-src">src</code> content
attribute:</p>
<ol>
<li><p>Let <var>base URL</var> be <var>el</var>'s <span>node document</span>'s <span>document
base URL</span>.</p></li>
<li>
<p>Switch on <var>el</var>'s <span data-x="concept-script-type">type</span>:</p>
<dl class="switch">
<dt>"<code data-x="">classic</code>"</dt>
<dd>
<ol>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> using
<var>source text</var>, <var>settings object</var>, <var>base URL</var>, and
<var>options</var>.</p></li>
<li><p><span>Mark as ready</span> <var>el</var> given <var>script</var>.</p></li>
</ol>
</dd>
<dt>"<code data-x="">module</code>"</dt>
<dd>
<ol>
<li><p>Set <var>el</var>'s <span data-x="concept-script-delay-load">delaying the load
event</span> to true.</p></li>
<li>
<p>If <var>el</var> is <span>potentially render-blocking</span>, then:</p>
<ol>
<li><p><span>Block rendering</span> on <var>el</var>.</p></li>
<li><p>Set <var>options</var>'s <span
data-x="concept-script-fetch-options-render-blocking">render-blocking</span> to
true.</p></li>
</ol>
<li>
<p><span>Fetch an inline module script graph</span>, given <var>source text</var>,
<var>base URL</var>, <var>settings object</var>, <var>options</var>, and with the
following steps given <var>result</var>:</p>
<ol>
<li>
<p><span>Queue an element task</span> on the <span>networking task source</span>
given <var>el</var> to perform the following steps:</p>
<ol>
<li><p><span>Mark as ready</span> <var>el</var> given <var>result</var>.</p></li>
</ol>
<p class="note">Queueing a task here means that, even if the inline module script has
no dependencies or synchronously results in a parse error, we won't proceed to
<span>execute the script element</span> synchronously.</p>
</li>
</ol>
</li>
</ol>
</dd>
<dt>"<code data-x="">importmap</code>"</dt>
<dd>
<ol>
<li><p>Let <var>result</var> be the result of <span data-x="create an import map parse
result">creating an import map parse result</span> given <var>source text</var> and
<var>base URL</var>.</p></li>
<li><p><span>Mark as ready</span> <var>el</var> given <var>result</var>.</p></li>
</ol>
</dd>
</dl>
</li>
</ol>
</li>
<li>
<p>If <var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">classic</code>" and <var>el</var> has a <code data-x="attr-script-src">src</code>
attribute, or <var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">module</code>":</p>
<ol>
<li><p><span>Assert</span>: <var>el</var>'s <span data-x="concept-script-result">result</span>
is "<code data-x="">uninitialized</code>".</p></li>
<li id="script-processing-src">
<p id="script-processing-module-async">If <var>el</var> has an <code
data-x="attr-script-async">async</code> attribute or <var>el</var>'s <span
data-x="script-force-async">force async</span> is true:</p>
<ol>
<li><p>Let <var>scripts</var> be <var>el</var>'s <span>preparation-time document</span>'s
<span>set of scripts that will execute as soon as possible</span>.</p></li>
<li><p><span data-x="set append">Append</span> <var>el</var> to <var>scripts</var>.</p></li>
<li>
<p>Set <var>el</var>'s <span>steps to run when the result is ready</span> to the
following:</p>
<ol>
<li><p><span>Execute the script element</span> <var>el</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>el</var> from
<var>scripts</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li id="script-processing-src-sync">
<p id="script-processing-module-noasync">Otherwise, if <var>el</var> is not
<span>parser-inserted</span>:</p>
<ol>
<li><p>Let <var>scripts</var> be <var>el</var>'s <span>preparation-time document</span>'s
<span>list of scripts that will execute in order as soon as possible</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>el</var> to <var>scripts</var>.</p></li>
<li>
<p>Set <var>el</var>'s <span>steps to run when the result is ready</span> to the
following:</p>
<ol>
<li><p>If <var>scripts</var>[0] is not <var>el</var>, then abort these steps.</p></li>
<li>
<p>While <var>scripts</var> is not empty, and <var>scripts</var>[0]'s <span
data-x="concept-script-result">result</span> is not "<code
data-x="">uninitialized</code>":</p>
<ol>
<li><p><span>Execute the script element</span> <var>scripts</var>[0].</p></li>
<li><p><span data-x="list remove">Remove</span> <var>scripts</var>[0].</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li id="script-processing-defer">
<p id="script-processing-module-noasync-parser-inserted">Otherwise, if <var>el</var> has a
<code data-x="attr-script-defer">defer</code> attribute or <var>el</var>'s <span
data-x="concept-script-type">type</span> is "<code data-x="">module</code>":</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>el</var> to its <span>parser
document</span>'s <span>list of scripts that will execute when the document has finished
parsing</span>.</p></li>
<li><p>Set <var>el</var>'s <span>steps to run when the result is ready</span> to the
following: set <var>el</var>'s <span>ready to be parser-executed</span> to true. (The parser
will handle executing the script.)</p></li>
</ol>
</li>
<li id="script-processing-parser-inserted">
<p>Otherwise:</p>
<ol>
<li><p>Set <var>el</var>'s <span>parser document</span>'s <span>pending parsing-blocking
script</span> to <var>el</var>.</p></li>
<li><p><span>Block rendering</span> on <var>el</var>.</p></li>
<li><p>Set <var>el</var>'s <span>steps to run when the result is ready</span> to the
following: set <var>el</var>'s <span>ready to be parser-executed</span> to true. (The parser
will handle executing the script.)</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>el</var>'s <span data-x="concept-script-result">result</span>
is <em>not</em> "<code data-x="">uninitialized</code>".</p></li>
<li id="script-processing-style-delayed">
<p>If all of the following are true:</p>
<ul>
<li><var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">classic</code>";</li>
<li><var>el</var> is <span>parser-inserted</span>;</li>
<li><var>el</var>'s <span>parser document</span> <span>has a style sheet that is blocking
scripts</span>; and</li>
<li>either the parser that created <var>el</var> is an <span>XML parser</span>, or it's an
<span>HTML parser</span> whose <span>script nesting level</span> is not greater than
one,</li>
</ul>
<p>then:</p>
<ol>
<li><p>Set <var>el</var>'s <span>parser document</span>'s <span>pending parsing-blocking
script</span> to <var>el</var>.</p></li>
<li><p>Set <var>el</var>'s <span>ready to be parser-executed</span> to true. (The parser
will handle executing the script.)</p></li>
</ol>
</li>
<li id="script-processing-inline"><p>Otherwise, <span>immediately</span> <span>execute the
script element</span> <var>el</var>, even if other scripts are already executing.</p></li>
</ol>
</li>
</ol>
<p>Each <code>Document</code> has a <dfn>pending parsing-blocking script</dfn>, which is a
<code>script</code> element or null, initially null.</p>
<p>Each <code>Document</code> has a <dfn>set of scripts that will execute as soon as
possible</dfn>, which is a <span>set</span> of <code>script</code> elements, initially empty.</p>
<p>Each <code>Document</code> has a <dfn>list of scripts that will execute in order as soon as
possible</dfn>, which is a <span>list</span> of <code>script</code> elements, initially
empty.</p>
<p>Each <code>Document</code> has a <dfn>list of scripts that will execute when the document has
finished parsing</dfn>, which is a <span>list</span> of <code>script</code> elements, initially
empty.</p>
<p class="note">If a <code>script</code> element that blocks a parser gets moved to another
<code>Document</code> 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 <span>pending parsing-blocking script</span> because the
original <code>Document</code> <span>has a style sheet that is blocking scripts</span> when it was
parsed, but then the script is moved to another <code>Document</code> 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).</p>
<!-- also (and this would be worth testing): the way the spec is written, if you do not have a
style sheet that is blocking scripts, then you parse a <script src>, then while waiting for the
script to load you insert an external style sheet, the script will delay until the sheet is
loaded, because there's just a binary "are style sheets blocking scripts" state, things aren't
defined in terms of which style sheets are blocking which scripts -->
<p id="execute-the-script-block">To <dfn>execute the script element</dfn> given a
<code>script</code> element <var>el</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>el</var>'s <span>node document</span>.</p></li>
<li><p>If <var>el</var>'s <span>preparation-time document</span> is not equal to
<var>document</var>, then return.</p></li>
<li><p><span>Unblock rendering</span> on <var>el</var>.</p></li>
<li><p>If <var>el</var>'s <span data-x="concept-script-result">result</span> is null, then <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
at <var>el</var>, and return.</p></li>
<li><p>If <var>el</var>'s <span data-x="concept-script-external">from an external file</span> is
true, or <var>el</var>'s <span data-x="concept-script-type">type</span> is "<code
data-x="">module</code>", then increment <var>document</var>'s <span>ignore-destructive-writes
counter</span>.</p></li>
<li>
<p>Switch on <var>el</var>'s <span data-x="concept-script-type">type</span>:</p>
<dl class="switch">
<dt>"<code data-x="">classic</code>"</dt>
<dd>
<ol>
<li><p>Let <var>oldCurrentScript</var> be the value to which <var>document</var>'s <code
data-x="dom-document-currentScript">currentScript</code> object was most recently
set.</p></li>
<li>
<p>If <var>el</var>'s <span>root</span> is <em>not</em> a <span>shadow root</span>, then
set <var>document</var>'s <code data-x="dom-document-currentScript">currentScript</code>
attribute to <var>el</var>. Otherwise, set it to null.</p>
<p class="note">This does not use the <span>in a document tree</span> check, as
<var>el</var> could have been removed from the document prior to execution, and in that
scenario <code data-x="dom-document-currentScript">currentScript</code> still needs to
point to it.</p>
</li>
<li><p><span data-x="run a classic script">Run the classic script</span> given by
<var>el</var>'s <span data-x="concept-script-result">result</span>.</p></li>
<li><p>Set <var>document</var>'s <code
data-x="dom-document-currentScript">currentScript</code> attribute to
<var>oldCurrentScript</var>.</p></li>
</ol>
</dd>
<dt>"<code data-x="">module</code>"</dt>
<dd>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <code
data-x="dom-document-currentScript">currentScript</code> attribute is null.</p></li>
<li><p><span data-x="run a module script">Run the module script</span> given by
<var>el</var>'s <span data-x="concept-script-result">result</span>.</p></li>
</ol>
</dd>
<dt>"<code data-x="">importmap</code>"</dt>
<dd>
<ol>
<li><p><span>Register an import map</span> given <var>el</var>'s <span>relevant global
object</span> and <var>el</var>'s <span
data-x="concept-script-result">result</span>.</p></li>
</ol>
</dd>
</dl>
</li>
<li><p>Decrement the <span>ignore-destructive-writes counter</span> of <var>document</var>, if
it was incremented in the earlier step.</p></li>
<li><p>If <var>el</var>'s <span data-x="concept-script-external">from an external file</span> is
true, then <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-load">load</code> at <var>el</var>.</p></li>
</ol>
</div>
<h5 id="scriptingLanguages">Scripting languages</h5>
<p w-nodev>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 <code>script</code> element.</p>
<p>Servers should use <code>text/javascript</code> for JavaScript resources, in accordance with
<cite>Updates to ECMAScript Media Types</cite>. Servers should not use other
<span data-x="JavaScript MIME type">JavaScript MIME types</span> for JavaScript resources, and
must not use non-<span data-x="JavaScript MIME type">JavaScript MIME types</span>.
<ref>RFC9239</ref></p>
<div w-nodev>
<p>For external JavaScript resources, MIME type parameters in `<code>Content-Type</code>` headers
are generally ignored. (In some cases the `<code data-x="">charset</code>` parameter has an
effect.) However, for the <code>script</code> element's <code
data-x="attr-script-type">type</code> attribute they are significant; it uses the <span>JavaScript
MIME type essence match</span> concept.</p>
<p class="note">For example, scripts with their <code data-x="attr-script-type">type</code>
attribute set to "<code data-x="">text/javascript; charset=utf-8</code>" will not be
evaluated, even though that is a valid <span>JavaScript MIME type</span> when parsed.</p>
<p>Furthermore, again for external JavaScript resources, special considerations apply around
`<code>Content-Type</code>` header processing as detailed in the <span>prepare the script
element</span> algorithm and <cite>Fetch</cite>. <ref>FETCH</ref>
</div>
<h5><dfn data-x="script content restrictions">Restrictions for contents of <code>script</code> elements</dfn></h5>
<p class="note">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 "<code
data-x=""><!--</code>" as "<code data-x="">\x3C!--</code>", "<code
data-x=""><script</code>" as "<code data-x="">\x3Cscript</code>", and "<code
data-x=""></script</code>" as "<code data-x="">\x3C/script</code>" 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
<code>script</code> blocks in HTML is a strange and exotic practice that acts unintuitively in the
face of these sequences.</p>
<p>The <code>script</code> element's <span>descendant text content</span> must match the <code
data-x="">script</code> production in the following ABNF, the character set for which is Unicode.
<ref>ABNF</ref></p>
<pre><code data-x="" class="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 (>)</code></pre>
<p>When a <code>script</code> element contains <span>script documentation</span>, there are
further restrictions on the contents of the element, as described in the section below.</p>
<div class="example">
<p>The following script illustrates this issue. Suppose you have a script that contains a string,
as in:</p>
<pre><code class="js">const example = 'Consider this string: <!-- <script>';
console.log(example);</code></pre>
<p>If one were to put this string directly in a <code>script</code> block, it would violate the
restrictions above:</p>
<pre><code class="html"><script>
const example = 'Consider this string: <!-- <script>';
console.log(example);
</script></code></pre>
<p>The bigger problem, though, and the reason why it would violate those restrictions, is that
actually the script would get parsed weirdly: <em>the script block above is not terminated</em>.
That is, what looks like a "<code data-x=""></script></code>" end tag in this snippet is
actually still part of the <code>script</code> 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:</p>
<pre><code class="html"><script><mark>
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...
</mark></script></code></pre>
<p>What is going on here is that for legacy reasons, "<code data-x=""><!--</code>" and "<code
data-x=""><script</code>" strings in <code>script</code> elements in HTML need to be balanced
in order for the parser to consider closing the block.</p>
<p>By escaping the problematic strings as mentioned at the top of this section, the problem is
avoided entirely:</p>
<pre><code class="html"><script><mark>
// Note: `\x3C` is an escape sequence for `<`.
const example = 'Consider this string: \x3C!-- \x3Cscript>';
console.log(example);
</mark></script>
<!-- this is just a comment between script blocks -->
<script><mark>
... // this is a new script block
</mark></script></code></pre>
<p>It is possible for these sequences to naturally occur in script expressions, as in the
following examples:</p>
<pre><code class="js">if (x<!--y) { ... }
if ( player<script ) { ... }</code></pre>
<p>In such cases the characters cannot be escaped, but the expressions can be rewritten so that
the sequences don't occur, as in:</p>
<pre><code class="js">if (x < !--y) { ... }
if (!--y > x) { ... }
if (!(--y) > x) { ... }
if (player < script) { ... }
if (script > player) { ... }</code></pre>
<p>Doing this also avoids a different pitfall as well: for related historical reasons, the string
"<!--" in <span data-x="classic script">classic scripts</span> is actually treated as a line
comment start, just like "//".</p>
</div>
<h5><dfn data-x="script documentation">Inline documentation for external scripts</dfn></h5>
<p>If a <code>script</code> element's <code data-x="attr-script-src">src</code> attribute is
specified, then the contents of the <code>script</code> element, if any, must be such that the
value of the <code data-x="dom-script-text">text</code> IDL attribute, which is derived from the
element's contents, matches the <code data-x="">documentation</code> production in the following
ABNF, the character set for which is Unicode. <ref>ABNF</ref></p>
<pre><code data-x="" class="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 <span>scalar value</span> other than U+000A LINE FEED (LF)
not-star = %x0000-0029 / %x002B-10FFFF
; a <span>scalar value</span> other than U+002A ASTERISK (*)
not-slash = %x0000-002E / %x0030-10FFFF
; a <span>scalar value</span> other than U+002F SOLIDUS (/)</code></pre>
<p class="note">This corresponds to putting the contents of the element in JavaScript
comments.</p>
<p class="note">This requirement is in addition to the earlier restrictions on the syntax of
contents of <code>script</code> elements.</p>
<div class="example">
<p>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
<code data-x="attr-script-src">src</code> attribute.</p>
<pre><code class="html"><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></code></pre>
</div>
<div w-nodev>
<h5 id="scriptTagXSLT">Interaction of <code>script</code> elements and XSLT</h5>
<!-- NON-NORMATIVE SECTION -->
<p>This specification does not define how XSLT interacts with the <code>script</code> element.
However, in the absence of another specification actually defining this, here are some guidelines
for implementers, based on existing implementations:</p>
<ul>
<li><p>When an XSLT transformation program is triggered by an <code
data-x=""><?xml-stylesheet?></code> processing instruction and the browser implements a
direct-to-DOM transformation, <code>script</code> elements created by the XSLT processor need to
have its <span>parser document</span> set correctly, and run in document order (modulo scripts
marked <code data-x="attr-script-defer">defer</code> or <code
data-x="attr-script-async">async</code>), <span>immediately</span>, as the transformation is
occurring.</p></li>
<li><p>The <code>XSLTProcessor</code> <code
data-x="dom-XSLTProcessor-transformToDocument">transformToDocument()</code> method adds elements
to a <code>Document</code> object with a null <span data-x="concept-document-bc">browsing
context</span>, and, accordingly, any <code>script</code> elements they create need to have
their <span>already started</span> set to true in the <span>prepare the script element</span>
algorithm and never get executed (<span data-x="concept-environment-noscript">scripting is
disabled</span>). Such <code>script</code> elements still need to have their <span>parser
document</span> set, though, such that their <code data-x="dom-script-async">async</code> IDL
attribute will return false in the absence of an <code data-x="attr-script-async">async</code>
content attribute.</p></li>
<li><p>The <code>XSLTProcessor</code> <code
data-x="dom-XSLTProcessor-transformToFragment">transformToFragment()</code> method needs to
create a fragment that is equivalent to one built manually by creating the elements using <code
data-x="dom-document-createElementNS">document.createElementNS()</code>. For instance, it needs
to create <code>script</code> elements with null <span>parser document</span> and with their
<span>already started</span> set to false, so that they will execute when the fragment is
inserted into a document.</p></li>
</ul>
<p>The main distinction between the first two cases and the last case is that the first two
operate on <code>Document</code>s and the last operates on a fragment.</p>
</div>
<h4>The <dfn element><code>noscript</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>In a <code>head</code> element of an <span data-x="HTML documents">HTML document</span>, if there are no ancestor <code>noscript</code> elements.</dd>
<dd>Where <span>phrasing content</span> is expected in <span>HTML documents</span>, if there are no ancestor <code>noscript</code> elements.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>When <span data-x="concept-n-noscript">scripting is disabled</span>, in a <code>head</code> element: in any order, zero or more <code>link</code> elements, zero or more <code>style</code> elements, and zero or more <code>meta</code> elements.</dd>
<dd>When <span data-x="concept-n-noscript">scripting is disabled</span>, not in a <code>head</code> element: <span>transparent</span>, but there must be no <code>noscript</code> element descendants.</dd>
<dd>Otherwise: text that conforms to the requirements given in the prose.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-noscript">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-noscript">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLElement</code>.</dd>
</dl>
<p>The <code>noscript</code> element <span>represents</span> nothing if <span
data-x="concept-n-script">scripting is enabled</span>, and <span>represents</span> its children if
<span data-x="concept-n-noscript">scripting is disabled</span>. 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.</p>
<p>When used in <span>HTML documents</span>, the allowed content model is as follows:</p>
<dl>
<dt>In a <code>head</code> element, if <span data-x="concept-n-noscript">scripting is
disabled</span> for the <code>noscript</code> element</dt>
<dd><p>The <code>noscript</code> element must contain only <code>link</code>, <code>style</code>,
and <code>meta</code> elements.</p></dd>
<dt>In a <code>head</code> element, if <span data-x="concept-n-script">scripting is enabled</span>
for the <code>noscript</code> element</dt>
<dd><p>The <code>noscript</code> element must contain only text, except that invoking the
<span>HTML fragment parsing algorithm</span> <!-- (which disables <script> execution) --> with
the <code>noscript</code> element as the <var data-x="concept-frag-parse-context">context</var>
element and the text contents as the <var>input</var> must result in a list of nodes
that consists only of <code>link</code>, <code>style</code>, and <code>meta</code> elements that
would be conforming if they were children of the <code>noscript</code> element, and no <span
data-x="parse error">parse errors</span>.</p></dd>
<dt>Outside of <code>head</code> elements, if <span data-x="concept-n-noscript">scripting is
disabled</span> for the <code>noscript</code> element</dt>
<dd><p>The <code>noscript</code> element's content model is <span>transparent</span>, with the
additional restriction that a <code>noscript</code> element must not have a <code>noscript</code>
element as an ancestor (that is, <code>noscript</code> can't be nested).</p></dd>
<dt>Outside of <code>head</code> elements, if <span data-x="concept-n-script">scripting is
enabled</span> for the <code>noscript</code> element</dt>
<dd>
<p>The <code>noscript</code> element must contain only text, except that the text must be such
that running the following algorithm results in a conforming document with no
<code>noscript</code> elements and no <code>script</code> elements, and such that no step in the
algorithm throws an exception or causes an <span>HTML parser</span> to flag a <span>parse
error</span>:</p>
<!-- the possible exception is from the outerHTML setter -->
<ol>
<li>Remove every <code>script</code> element from the document.</li>
<li>Make a list of every <code>noscript</code> element in the document. For every
<code>noscript</code> element in that list, perform the following steps:
<ol>
<li>Let <var>s</var> be the <span>child text content</span> of the <code>noscript</code>
element.</li>
<li>Set the <code data-x="dom-element-outerHTML">outerHTML</code> attribute of the
<code>noscript</code> element to the value of <var>s</var>. (This, as a side-effect, causes
the <code>noscript</code> element to be removed from the document.)</li>
</ol>
</li>
</ol>
</dd>
</dl>
<p class="note">All these contortions are required because, for historical reasons, the
<code>noscript</code> element is handled differently by the <span>HTML parser</span> based on
whether <span data-x="scripting flag">scripting was enabled or not</span> when the parser was
invoked.</p>
<p>The <code>noscript</code> element must not be used in <span>XML documents</span>.</p>
<p class="note">The <code>noscript</code> element is only effective in <span>the HTML
syntax</span>, it has no effect in <span>the XML syntax</span>. 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.</p>
<div w-nodev>
<p>The <code>noscript</code> element has no other requirements. In particular, children of the
<code>noscript</code> element are not exempt from <span>form submission</span>, scripting, and so
forth, even when <span data-x="concept-n-script">scripting is enabled</span> for the element.</p>
</div>
<div class="example">
<p>In the following example, a <code>noscript</code> element is
used to provide fallback for a script.</p>
<pre><code class="html"><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></code></pre>
<p>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.</p>
<p>The <code>noscript</code> 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 <code>noscript</code>, 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:</p>
<pre><code class="html"><form action="calcSquare.php">
<p>
<label for=x>Number</label>:
<input id="x" name="x" type="number">
</p>
<strong><input id="submit" type=submit value="Calculate Square"></strong>
<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;
};
<strong> var submit = document.getElementById('submit');
submit.parentNode.removeChild(submit);</strong>
</script>
</form></code></pre>
<p>The above technique is also useful in <span>XML documents</span>, since <code>noscript</code>
is not allowed there.</p>
</div>
<h4 id="the-template-element">The <dfn element><code>template</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Metadata content</span>.</dd>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span data-x="script-supporting elements">Script-supporting element</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>metadata content</span> is expected.</dd>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dd>Where <span>script-supporting elements</span> are expected.</dd>
<dd>As a child of a <code>colgroup</code> element that doesn't have a <code data-x="attr-colgroup-span">span</code> attribute.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span data-x="concept-content-nothing">Nothing</span> (for clarification, <a href="#template-example">see example</a>).</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-template-shadowrootmode">shadowrootmode</code></dd>
<dd><code data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code></dd>
<dd><code data-x="attr-template-shadowrootclonable">shadowrootclonable</code></dd>
<dd><code data-x="attr-template-shadowrootserializable">shadowrootserializable</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-template">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-template">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
readonly attribute <span>DocumentFragment</span> <span data-x="dom-template-content">content</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-template-shadowrootmode">shadowRootMode</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-template-shadowrootdelegatesfocus">shadowRootDelegatesFocus</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-template-shadowrootclonable">shadowRootClonable</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-template-shadowRootSerializable">shadowRootSerializable</span>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTemplateElement</code>.</dd>
</dl>
<p>The <code>template</code> element is used to declare fragments of HTML that can be cloned and
inserted in the document by script.</p>
<p>In a rendering, the <code>template</code> element <span>represents</span> nothing.</p>
<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootmode">shadowrootmode</code></dfn> content attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="template/shadowrootmode"><code data-x="attr-shadowrootmode-open">open</code></dfn>
<td><dfn data-x="attr-shadowrootmode-open-state">open</dfn>
<td>The template element represents an open declarative shadow root.
<tr>
<td><dfn attr-value for="template/shadowrootmode"><code data-x="attr-shadowrootmode-closed">closed</code></dfn>
<td><dfn data-x="attr-shadowrootmode-closed-state">closed</dfn>
<td>The template element represents a closed declarative shadow root.
</table>
<p>The <code data-x="attr-template-shadowrootmode">shadowrootmode</code> attribute's <i
data-x="invalid value default">invalid value default</i> and <i data-x="missing value
default">missing value default</i> are both the <dfn
data-x="attr-shadowrootmode-none-state">none</dfn> state.</p>
<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code></dfn> content
attribute is a <span>boolean attribute</span>.</p>
<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootclonable">shadowrootclonable</code></dfn> content attribute is a
<span>boolean attribute</span>.</p>
<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootserializable">shadowrootserializable</code></dfn> content
attribute is a <span>boolean attribute</span>.</p>
<p>The <span>template contents</span> of a <code>template</code> element <a
href="#template-syntax">are not children of the element itself</a>.</p>
<p class="note">It is also possible, as a result of DOM manipulation, for a <code>template</code>
element to contain <code>Text</code> nodes and element nodes; however, having any is a violation
of the <code>template</code> element's content model, since its content model is defined as <span
data-x="concept-content-nothing">nothing</span>.</p>
<div class="example" id="template-example">
<p>For example, consider the following document:</p>
<!-- https://www.quora.com/Homework-Question-How-do-I-write-a-program-that-produces-the-following-output-1 -->
<pre><code class="html"><!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></code></pre>
<p>The <code>p</code> element in the <code>template</code> is <em>not</em> a child of the
<code>template</code> in the DOM; it is a child of the <code>DocumentFragment</code> returned by
the <code>template</code> element's <code data-x="dom-template-content">content</code> IDL
attribute.</p>
<p>If the script were to call <code data-x="dom-node-appendchild">appendChild()</code> on the
<code>template</code> element, that would add a child to the <code>template</code> element (as
for any other element); however, doing so is a violation of the <code>template</code> element's
content model.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>template</var>.<span subdfn data-x="dom-template-content">content</span></code></dt>
<dd><p>Returns the <span>template contents</span> (a <code>DocumentFragment</code>).</p></dd>
</dl>
<div w-nodev>
<p>Each <code>template</code> element has an associated <code>DocumentFragment</code> object that
is its <dfn>template contents</dfn>. The <span>template contents</span> have <a
href="#no-browsing-context">no conformance requirements</a>. When a <code>template</code> element
is created, the user agent must run the following steps to establish the <span>template
contents</span>:</p>
<ol>
<li><p>Let <var>doc</var> be the <code>template</code> element's <span>node document</span>'s <span>appropriate template contents owner
document</span>.</p></li>
<li><p>Create a <code>DocumentFragment</code> object whose <span>node document</span> is
<var>doc</var> and <span data-x="concept-DocumentFragment-host">host</span> is the
<code>template</code> element.</p></li>
<li><p>Set the <code>template</code> element's <span>template contents</span> to the newly
created <code>DocumentFragment</code> object.</p></li>
</ol>
<p>A <code>Document</code> <var>doc</var>'s <dfn>appropriate template contents owner
document</dfn> is the <code>Document</code> returned by the following algorithm:</p>
<ol>
<li>
<p>If <var>doc</var> is not a <code>Document</code> created by this algorithm, then:</p>
<ol>
<li>
<p>If <var>doc</var> does not yet have an <dfn>associated inert template document</dfn>,
then:</p>
<ol>
<li><p>Let <var>new doc</var> be a new <code>Document</code> (whose <span
data-x="concept-document-bc">browsing context</span> is null). This is "a
<code>Document</code> created by this algorithm" for the purposes of the step above.</p></li>
<li><p>If <var>doc</var> is an <span data-x="HTML documents">HTML document</span>, mark
<var>new doc</var> as an <span data-x="HTML documents">HTML document</span>
also.</p></li>
<li><p>Let <var>doc</var>'s <span>associated inert template document</span> be <var>new doc</var>.</p></li>
</ol>
</li>
<li><p>Set <var>doc</var> to <var>doc</var>'s <span>associated inert
template document</span>.</p></li>
</ol>
<p class="note">Each <code>Document</code> not created by this algorithm thus gets a single
<code>Document</code> to act as its proxy for owning the <span>template contents</span> of all
its <code>template</code> elements, so that they aren't in a <span>browsing context</span> and
thus remain inert (e.g. scripts do not run). Meanwhile, <code>template</code> elements inside
<code>Document</code> objects that <em>are</em> created by this algorithm just reuse the same
<code>Document</code> owner for their contents.</p>
</li>
<li><p>Return <var>doc</var>.</p></li>
</ol>
<p id="template-adopting-steps">The <span data-x="concept-node-adopt-ext">adopting steps</span>
(with <var>node</var> and <var>oldDocument</var> as parameters) for <code>template</code> elements
are the following:</p>
<ol>
<li>
<p>Let <var>doc</var> be <var>node</var>'s <span>node document</span>'s
<span>appropriate template contents owner document</span>.</p>
<p class="note"><var>node</var>'s <span>node document</span> is the <code>Document</code> object
that <var>node</var> was just adopted <em>into</em>.</p>
</li>
<li><p><span data-x="concept-node-adopt">Adopt</span> <var>node</var>'s
<span>template contents</span> (a <code>DocumentFragment</code> object) into <var>doc</var>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-content">content</code></dfn> getter steps are to return
<code>template</code>'s <span>template contents</span>, if the <span>template contents</span> is
not a <code>ShadowRoot</code> node; otherwise null.</p>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-shadowrootmode">shadowRootMode</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-template-shadowrootmode">shadowrootmode</code> content
attribute, <span>limited to only known values</span>.</p>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-shadowrootdelegatesfocus">shadowRootDelegatesFocus</code></dfn> IDL attribute
must <span>reflect</span> the <code
data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-shadowrootclonable">shadowRootClonable</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-template-shadowrootclonable">shadowrootclonable</code>
content attribute.</p>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-shadowRootSerializable">shadowRootSerializable</code></dfn> IDL attribute
must <span>reflect</span> the <code
data-x="attr-template-shadowrootserializable">shadowrootserializable</code> content attribute.</p>
<hr>
<p>The <span data-x="concept-node-clone-ext">cloning steps</span> for <code>template</code>
elements given <var>node</var>, <var>copy</var>, and <var>subtree</var> are:</p>
<ol>
<li><p>If <var>subtree</var> is false, then return.</p></li>
<li><p>For each <var>child</var> of <var>node</var>'s <span>template contents</span>'s <span
data-x="concept-tree-child">children</span>, in <span>tree order</span>: <span
data-x="concept-node-clone">clone a node</span> given <var>child</var> with <span
data-x="concept-node-clone-document"><i>document</i></span> set to <var>copy</var>'s
<span>template contents</span>'s <span>node document</span>, <span
data-x="concept-node-clone-subtree"><i>subtree</i></span> set to true, and <span
data-x="concept-node-clone-parent"><i>parent</i></span> set to <var>copy</var>'s <span>template
contents</span>.</p></li>
</ol>
</div>
<div class="example">
<p>In this example, a script populates a table four-column with data from a data structure, using
a <code>template</code> to provide the element structure instead of manually generating the
structure from markup.</p>
<pre><code class="html"><!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></code></pre>
<p>This example uses <code data-x="dom-node-cloneNode">cloneNode()</code> on the
<code>template</code>'s contents; it could equivalently have used <code
data-x="dom-Document-importNode">document.importNode()</code>, which does the same thing. The
only difference between these two APIs is when the <span>node document</span> is updated: with
<code data-x="dom-node-cloneNode">cloneNode()</code> it is updated when the nodes are appended
with <code data-x="dom-node-appendChild">appendChild()</code>, with <code
data-x="dom-Document-importNode">document.importNode()</code> it is updated when the nodes are
cloned.</p>
</div>
<div w-nodev>
<h5 id="template-XSLT-XPath">Interaction of <code>template</code> elements with XSLT and XPath</h5>
<!-- NON-NORMATIVE SECTION -->
<p>This specification does not define how XSLT and XPath interact with the <code>template</code>
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:</p>
<ul>
<li><p>An XSLT processor based on an XML parser that acts <span data-x="xml parser">as described
in this specification</span> needs to act as if <code>template</code> elements contain as
descendants their <span>template contents</span> for the purposes of the transform.</p></li>
<li><p>An XSLT processor that outputs a DOM needs to ensure that nodes that would go into a
<code>template</code> element are instead placed into the element's <span>template
contents</span>.</p></li>
<li><p>XPath evaluation using the XPath DOM API when applied to a <code>Document</code> parsed
using the <span>HTML parser</span> or the <span>XML parser</span> described in this specification
needs to ignore <span>template contents</span>.</p>
</ul>
</div>
<h4 id="the-slot-element">The <dfn element><code>slot</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span></dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-slot-name">name</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-slot">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-slot">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLSlotElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-slot-name">name</span>;
sequence<Node> <span data-x="dom-slot-assignedNodes">assignedNodes</span>(optional <span>AssignedNodesOptions</span> options = {});
sequence<Element> <span data-x="dom-slot-assignedElements">assignedElements</span>(optional <span>AssignedNodesOptions</span> options = {});
undefined <span data-x="dom-slot-assign">assign</span>((<span>Element</span> or <span>Text</span>)... nodes);
};
dictionary <dfn dictionary>AssignedNodesOptions</dfn> {
boolean <dfn dict-member for="AssignedNodeOptions" data-x="dom-AssignedNodesOptions-flatten">flatten</dfn> = false;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLSlotElement</code>.</dd>
</dl>
<p>The <code>slot</code> element defines a <span data-x="concept-slot">slot</span>. It is
typically used in a <span>shadow tree</span>. A <code>slot</code> element <span>represents</span>
its <span>assigned nodes</span>, if any, and its contents otherwise.</p>
<p>The <dfn element-attr for="slot" data-x="attr-slot-name"><code>name</code></dfn> content
attribute may contain any string value. It represents a <span data-x="concept-slot">slot</span>'s
<span data-x="slot-name">name</span>.</p>
<p class="note">The <code data-x="attr-slot-name">name</code> attribute is used to <span
data-x="assign a slot">assign slots</span> to other elements: a <code>slot</code> element with a
<code data-x="attr-slot-name">name</code> attribute creates a named <span
data-x="concept-slot">slot</span> to which any element is <span data-x="assign a
slot">assigned</span> if that element has a <code data-x="attr-slot">slot</code> attribute whose
value matches that <code data-x="attr-slot-name">name</code> attribute's value, and the
<code>slot</code> element is a child of the <span>shadow tree</span> whose <span>root</span>'s
<span data-x="concept-DocumentFragment-host">host</span> has that corresponding <code
data-x="attr-slot">slot</code> attribute value.</p>
<dl class="domintro">
<dt><code data-x=""><var>slot</var>.<span subdfn data-x="dom-slot-name">name</span></code></dt>
<dd>Can be used to get and set <var>slot</var>'s <span data-x="slot-name">name</span>.</dd>
<dt><code data-x=""><var>slot</var>.<span subdfn data-x="dom-slot-assignedNodes">assignedNodes</span>()</code></dt>
<dd>Returns <var>slot</var>'s <span>assigned nodes</span>.</dd>
<dt><code data-x=""><var>slot</var>.<span data-x="dom-slot-assignedNodes">assignedNodes</span>({ flatten: true })</code></dt>
<dd>Returns <var>slot</var>'s <span>assigned nodes</span>, if any, and <var>slot</var>'s children
otherwise, and does the same for any <code>slot</code> elements encountered therein, recursively,
until there are no <code>slot</code> elements left.</dd>
<dt><code data-x=""><var>slot</var>.<span subdfn data-x="dom-slot-assignedElements">assignedElements</span>()</code></dt>
<dd>Returns <var>slot</var>'s <span>assigned nodes</span>, limited to elements.</dd>
<dt><code data-x=""><var>slot</var>.<span data-x="dom-slot-assignedElements">assignedElements</span>({ flatten: true })</code></dt>
<dd>Returns the same as <code data-x="dom-slot-assignedNodes">assignedNodes({ flatten: true
})</code>, limited to elements.</dd>
<dt><code data-x=""><var>slot</var>.<span data-x="dom-slot-assign">assign</span>(...<var>nodes</var>)</code></dt>
<dd><p>Sets <var>slot</var>'s <span>manually assigned nodes</span> to the given
<var>nodes</var>.</p></dd>
</dl>
<p>The <dfn attribute for="HTMLSlotElement" data-x="dom-slot-name"><code>name</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>
<p>The <code>slot</code> element has <dfn export for="HTMLSlotElement">manually assigned
nodes</dfn>, which is an <span data-x="set">ordered set</span> of <span
data-x="slottable">slottables</span> set by <code data-x="dom-slot-assign">assign()</code>.
This set is initially empty.</p>
<p class="note">The <span>manually assigned nodes</span> set can be implemented using weak
references to the <span data-x="slottable">slottables</span>, because this set is not
directly accessible from script.</p>
<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assignedNodes"><code>assignedNodes(<var>options</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>If <var>options</var>["<code data-x="dom-AssignedNodesOptions-flatten">flatten</code>"] is
false, then return <span>this</span>'s <span>assigned nodes</span>.</p></li>
<li><p>Return the result of <span>finding flattened slottables</span> with
<span>this</span>.</p></li>
</ol>
<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assignedElements"><code>assignedElements(<var>options</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>If <var>options</var>["<code data-x="dom-AssignedNodesOptions-flatten">flatten</code>"] is
false, then return <span>this</span>'s <span>assigned nodes</span>, filtered to contain only
<code>Element</code> nodes.</p></li>
<li><p>Return the result of <span>finding flattened slottables</span> with <span>this</span>,
filtered to contain only <code>Element</code> nodes.</p></li>
</ol>
<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assign"><code>assign(...<var>nodes</var>)</code></dfn> method steps are:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <var>node</var> of <span>this</span>'s
<span>manually assigned nodes</span>, set <var>node</var>'s <span>manual slot assignment</span>
to null.</p></li>
<li><p>Let <var>nodesSet</var> be a new <span data-x="set">ordered set</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>node</var> of <var>nodes</var>:</p>
<ol>
<li><p>If <var>node</var>'s <span>manual slot assignment</span> refers to a <span>slot</span>,
then remove <var>node</var> from that <span>slot</span>'s
<span>manually assigned nodes</span>.</p></li>
<li><p>Set <var>node</var>'s <span>manual slot assignment</span> to <span>this</span>.</p></li>
<li><p><span data-x="set append">Append</span> <var>node</var> to <var>nodesSet</var>.</p></li>
</ol>
</li>
<li><p>Set <span>this</span>'s <span>manually assigned nodes</span> to
<var>nodesSet</var>.</p></li>
<li><p>Run <span>assign slottables for a tree</span> for <span>this</span>'s
<span>root</span>.</p></li>
</ol>
<h4 split-filename="canvas">The <dfn id="canvas" element><code>canvas</code></dfn> element</h4>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Embedded content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>embedded content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>, but with no <span>interactive content</span> descendants except
for <code>a</code> elements, <code>img</code> elements with
<code data-x="attr-hyperlink-usemap">usemap</code> attributes, <code>button</code> elements,
<code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute are in
the <span data-x="attr-input-type-checkbox">Checkbox</span> or <span
data-x="attr-input-type-radio">Radio Button</span> states, <code>input</code> elements that are
<span data-x="concept-button">buttons</span>, and <code>select</code> elements with a <code
data-x="attr-select-multiple">multiple</code> attribute or a <span
data-x="concept-select-size">display size</span> greater than 1.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-canvas-width">width</code></dd>
<dd><code data-x="attr-canvas-height">height</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-canvas">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-canvas">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">typedef (<span>CanvasRenderingContext2D</span> or <span>ImageBitmapRenderingContext</span> or <span>WebGLRenderingContext</span> or <span>WebGL2RenderingContext</span> or <span>GPUCanvasContext</span>) <dfn typedef>RenderingContext</dfn>;
[Exposed=Window]
interface <dfn interface>HTMLCanvasElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-canvas-width">width</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-canvas-height">height</span>;
<span>RenderingContext</span>? <span data-x="dom-canvas-getContext">getContext</span>(DOMString contextId, optional any options = null);
USVString <span data-x="dom-canvas-toDataURL">toDataURL</span>(optional DOMString type = "image/png", optional any quality);
undefined <span data-x="dom-canvas-toBlob">toBlob</span>(<span>BlobCallback</span> _callback, optional DOMString type = "image/png", optional any quality);
<span>OffscreenCanvas</span> <span data-x="dom-canvas-transferControlToOffscreen">transferControlToOffscreen</span>();
};
callback <dfn callback>BlobCallback</dfn> = undefined (<span>Blob</span>? blob);</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLCanvasElement</code>.</dd>
</dl>
<p>The <code>canvas</code> element provides scripts with a resolution-dependent bitmap canvas,
which can be used for rendering graphs, game graphics, art, or other visual images on the fly.</p>
<p>Authors should not use the <code>canvas</code> element in a document when a more suitable
element is available. For example, it is inappropriate to use a <code>canvas</code> element to
render a page heading: if the desired presentation of the heading is graphically intense, it
should be marked up using appropriate elements (typically <code>h1</code>) and then styled using
CSS and supporting technologies such as <span data-x="shadow tree">shadow trees</span>.</p>
<p>When authors use the <code>canvas</code> element, they must also provide content that, when
presented to the user, conveys essentially the same function or purpose as the
<code>canvas</code>'s bitmap. This content may be placed as content of the <code>canvas</code>
element. The contents of the <code>canvas</code> element, if any, are the element's <span>fallback
content</span>.</p>
<hr>
<p>In interactive visual media, if <span data-x="concept-n-script">scripting is enabled</span> for
the <code>canvas</code> element, and if support for <code>canvas</code> elements has been enabled,
then the <code>canvas</code> element <span>represents</span> <span>embedded content</span>
consisting of a dynamically created image, the element's bitmap.</p>
<p>In non-interactive, static, visual media, if the <code>canvas</code> element has been
previously associated with a rendering context (e.g. if the page was viewed in an interactive
visual medium and is now being printed, or if some script that ran during the page layout process
painted on the element), then the <code>canvas</code> element <span>represents</span>
<span>embedded content</span> with the element's current bitmap and size. Otherwise, the element
represents its <span>fallback content</span> instead.</p>
<p>In non-visual media, and in visual media if <span data-x="concept-n-noscript">scripting is
disabled</span> for the <code>canvas</code> element or if support for <code>canvas</code> elements
has been disabled, the <code>canvas</code> element <span>represents</span> its <span>fallback
content</span> instead.</p>
<!-- CANVAS-FOCUS-FALLBACK -->
<p>When a <code>canvas</code> element <span>represents</span> <span>embedded content</span>, the
user can still focus descendants of the <code>canvas</code> element (in the <span>fallback
content</span>). When an element is <span>focused</span>, it is the target of keyboard interaction
events (even though the element itself is not visible). This allows authors to make an interactive
canvas keyboard-accessible: authors should have a one-to-one mapping of interactive regions to <i
data-x="focusable area">focusable areas</i> in the <span>fallback content</span>. (Focus has no
effect on mouse interaction events.) <ref>UIEVENTS</ref></p> <!-- user
interaction spec integration point -->
<p>An element whose nearest <code>canvas</code> element ancestor is <span>being rendered</span>
and <span>represents</span> <span>embedded content</span> is an element that is <dfn>being used as
relevant canvas fallback content</dfn>.</p>
<hr>
<p>The <code>canvas</code> element has two attributes to control the size of the element's bitmap:
<dfn element-attr for="canvas"><code data-x="attr-canvas-width">width</code></dfn> and <dfn
element-attr for="canvas"><code data-x="attr-canvas-height">height</code></dfn>. These attributes,
when specified, must have values that are <span data-x="valid non-negative integer">valid
non-negative integers</span>. <span w-nodev>The <span>rules for parsing non-negative
integers</span> must be used to <dfn data-x="obtain-numeric-values">obtain their numeric
values</dfn>. If an attribute is missing, or if parsing its value returns an error, then the
default value must be used instead.</span> The <code data-x="attr-canvas-width">width</code>
attribute defaults to 300, and the <code data-x="attr-canvas-height">height</code> attribute
defaults to 150.</p>
<p>When setting the value of the <code data-x="attr-canvas-width">width</code> or <code
data-x="attr-canvas-height">height</code> attribute, if the <span
data-x="concept-canvas-context-mode">context mode</span> of the <code>canvas</code>
element is set to <span data-x="concept-canvas-placeholder">placeholder</span>, the
user agent must throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>
and leave the attribute's value unchanged.</p>
<p>The <span>natural dimensions</span> of the <code>canvas</code> element when it
<span>represents</span> <span>embedded content</span> are equal to the dimensions of the
element's bitmap.</p>
<p>The user agent must use a square pixel density consisting of one pixel of image data per
coordinate space unit for the bitmaps of a <code>canvas</code> and its rendering contexts.</p>
<p class="note">A <code>canvas</code> element can be sized arbitrarily by a style sheet, its
bitmap is then subject to the <span>'object-fit'</span> CSS property.</p>
<div w-nodev>
<hr>
<p>The bitmaps of <code>canvas</code> elements, the bitmaps of <code>ImageBitmap</code> objects,
as well as some of the bitmaps of rendering contexts, such as those described in the sections on
the <code>CanvasRenderingContext2D</code>, <code>OffscreenCanvasRenderingContext2D</code>, and
<code>ImageBitmapRenderingContext</code> objects below, have an <dfn
data-x="concept-canvas-origin-clean">origin-clean</dfn> flag, which can be set to true or false.
Initially, when the <code>canvas</code> element or <code>ImageBitmap</code> object is created, its
bitmap's <span data-x="concept-canvas-origin-clean">origin-clean</span> flag must be set to
true.</p>
<p>A <code>canvas</code> element can have a rendering context bound to it. Initially, it does not
have a bound rendering context. To keep track of whether it has a rendering context or not, and
what kind of rendering context it is, a <code>canvas</code> also has a <dfn
data-x="concept-canvas-context-mode">canvas context mode</dfn>, which is initially <dfn
data-x="concept-canvas-none">none</dfn> but can be changed to either <dfn
data-x="concept-canvas-placeholder">placeholder</dfn>, <dfn
data-x="concept-canvas-2d">2d</dfn>, <dfn
data-x="concept-canvas-bitmaprenderer">bitmaprenderer</dfn>, <dfn
data-x="concept-canvas-webgl">webgl</dfn>, <dfn
data-x="concept-canvas-webgl2">webgl2</dfn>, or <dfn
data-x="concept-canvas-webgpu">webgpu</dfn> by algorithms defined in this specification.</p>
<p>When its <span data-x="concept-canvas-context-mode">canvas context mode</span> is <span
data-x="concept-canvas-none">none</span>, a <code>canvas</code> element has no rendering context,
and its bitmap must be <span>transparent black</span> with a <span>natural width</span> equal
to <span data-x="obtain-numeric-values">the numeric value</span> of the element's <code
data-x="attr-canvas-width">width</code> attribute and a <span>natural height</span> equal to
<span data-x="obtain-numeric-values">the numeric value</span> of the element's <code
data-x="attr-canvas-height">height</code> attribute, those values being interpreted in <span
data-x="'px'">CSS pixels</span>, and being updated as the attributes are set, changed, or
removed.</p>
<p>When its <span data-x="concept-canvas-context-mode">canvas context mode</span> is <span
data-x="concept-canvas-placeholder">placeholder</span>, a <code>canvas</code> element has no
rendering context. It serves as a placeholder for an <code>OffscreenCanvas</code> object, and
the content of the <code>canvas</code> element is updated by the <code>OffscreenCanvas</code>
object's rendering context.</p>
<p>When a <code>canvas</code> element represents <span>embedded content</span>, it provides a
<span>paint source</span> whose width is the element's <span>natural width</span>, whose height
is the element's <span>natural height</span>, and whose appearance is the element's bitmap.</p>
<p>Whenever the <code data-x="attr-canvas-width">width</code> and <code
data-x="attr-canvas-height">height</code> content attributes are set, removed, changed, or
redundantly set to the value they already have, then the user agent must perform the action
from the row of the following table that corresponds to the <code>canvas</code> element's <span
data-x="concept-canvas-context-mode">context mode</span>.</p>
<table>
<thead>
<tr>
<th>
<p><span data-x="concept-canvas-context-mode">Context Mode</span></p>
<th>
<p>Action</p>
<tbody>
<tr>
<th>
<p><span data-x="concept-canvas-2d">2d</span></p>
<td>
<p>Follow the steps to <span data-x="concept-canvas-set-bitmap-dimensions">set bitmap
dimensions</span> to <span data-x="obtain-numeric-values">the numeric values</span>
of the <code data-x="attr-canvas-width">width</code> and <code
data-x="attr-canvas-height">height</code> content attributes.</p>
<tr>
<th>
<p><span data-x="concept-canvas-webgl">webgl</span> or <span
data-x="concept-canvas-webgl2">webgl2</span></p>
<td>
<p>Follow the behavior defined in the WebGL specifications. <ref>WEBGL</ref></p>
<tr>
<th>
<p><span data-x="concept-canvas-webgpu">webgpu</span></p>
<td>
<p>Follow the behavior defined in <cite>WebGPU</cite>. <ref>WEBGPU</ref></p>
<tr>
<th>
<p><span data-x="concept-canvas-bitmaprenderer">bitmaprenderer</span></p>
<td>
<p>If the context's <span data-x="concept-ImageBitmapRenderingContext-bitmap-mode">bitmap
mode</span> is set to <span data-x="concept-ImageBitmapRenderingContext-blank">blank</span>,
run the steps to <span>set an <code>ImageBitmapRenderingContext</code>'s output bitmap</span>,
passing the <code>canvas</code> element's rendering context.</p>
<tr>
<th>
<p><span data-x="concept-canvas-placeholder">placeholder</span></p>
<td>
<p>Do nothing.</p>
<tr>
<th>
<p><span data-x="concept-canvas-none">none</span></p>
<td>
<p>Do nothing.</p>
</table>
<p>The <dfn attribute for="HTMLCanvasElement"><code data-x="dom-canvas-width">width</code></dfn>
and <dfn attribute for="HTMLCanvasElement"><code data-x="dom-canvas-height">height</code></dfn>
IDL attributes must <span>reflect</span> the respective content attributes of the same name, with
the same defaults.</p>
</div>
<hr>
<dl class="domintro">
<dt><code data-x=""><var>context</var> = <var>canvas</var>.<span subdfn data-x="dom-canvas-getContext">getContext</span>(<var>contextId</var> [, <var>options</var> ])</code></dt>
<dd>
<p>Returns an object that exposes an API for drawing on the canvas. <var>contextId</var>
specifies the desired API: "<code data-x="canvas-context-2d">2d</code>", "<code
data-x="canvas-context-bitmaprenderer">bitmaprenderer</code>", "<code
data-x="canvas-context-webgl">webgl</code>", "<code
data-x="canvas-context-webgl2">webgl2</code>", or "<code
data-x="canvas-context-webgpu">webgpu</code>". <var>options</var> is handled by that API.</p>
<p>This specification defines the "<code data-x="canvas-context-2d">2d</code>" and "<code
data-x="canvas-context-bitmaprenderer">bitmaprenderer</code>" contexts below. The WebGL
specifications define the "<code data-x="canvas-context-webgl">webgl</code>" and "<code
data-x="canvas-context-webgl2">webgl2</code>" contexts. <cite>WebGPU</cite> defines the "<code
data-x="canvas-context-webgpu">webgpu</code>" context. <ref>WEBGL</ref> <ref>WEBGPU</ref></p>
<p>Returns null if <var>contextId</var> is not supported, or if the canvas has already been
initialized with another context type (e.g., trying to get a "<code
data-x="canvas-context-2d">2d</code>" context after getting a "<code
data-x="canvas-context-webgl">webgl</code>" context).</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLCanvasElement"><code
data-x="dom-canvas-getContext">getContext(<var>contextId</var>, <var>options</var>)</code></dfn>
method of the <code>canvas</code> element, when invoked, must run these steps:
<ol>
<li><p>If <var>options</var> is not an <span data-x="idl-object">object</span>, then set
<var>options</var> to null.</p></li>
<li><p>Set <var>options</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>options</var> to a JavaScript value.</p></li>
<li>
<p>Run the steps in the cell of the following table whose column header matches this
<code>canvas</code> element's <span data-x="concept-canvas-context-mode">canvas context
mode</span> and whose row header matches <var>contextId</var>:</p>
<table>
<thead>
<tr>
<td>
<th><span data-x="concept-canvas-none">none</span>
<th><span data-x="concept-canvas-2d">2d</span>
<th><span data-x="concept-canvas-bitmaprenderer">bitmaprenderer</span>
<th><span data-x="concept-canvas-webgl">webgl</span> or <span
data-x="concept-canvas-webgl2">webgl2</span>
<th><span data-x="concept-canvas-webgpu">webgpu</span>
<th><span data-x="concept-canvas-placeholder">placeholder</span>
<tbody>
<tr>
<th>"<dfn><code data-x="canvas-context-2d">2d</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of running the <span>2D context
creation algorithm</span> given <span>this</span> and <var>options</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-canvas-context-mode">context
mode</span> to <span data-x="concept-canvas-2d">2d</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="canvas-context-bitmaprenderer">bitmaprenderer</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of running the
<span><code>ImageBitmapRenderingContext</code> creation algorithm</span> given
<span>this</span> and <var>options</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-canvas-context-mode">context
mode</span> to <span
data-x="concept-canvas-bitmaprenderer">bitmaprenderer</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="canvas-context-webgl">webgl</code></dfn>" or "<dfn><code
data-x="canvas-context-webgl2">webgl2</code></dfn>", if the user agent supports the WebGL
feature in its current configuration
<td>
<ol>
<li><p>Let <var>context</var> be the result of following the instructions given in
the WebGL specifications' <i>Context Creation</i> sections. <ref>WEBGL</ref></p></li>
<li><p>If <var>context</var> is null, then return null; otherwise set <span>this</span>'s
<span data-x="concept-canvas-context-mode">context mode</span> to <span
data-x="concept-canvas-webgl">webgl</span> or <span
data-x="concept-canvas-webgl2">webgl2</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return null.
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="canvas-context-webgpu">webgpu</code></dfn>", if the user
agent supports the WebGPU feature in its current configuration
<td>
<ol>
<li><p>Let <var>context</var> be the result of following the instructions given
in <cite>WebGPU</cite>'s <a
href="https://gpuweb.github.io/gpuweb/#canvas-rendering">Canvas Rendering</a>
section. <ref>WEBGPU</ref></p></li>
<li><p>If <var>context</var> is null, then return null; otherwise set
<span>this</span>'s <span data-x="concept-canvas-context-mode">context mode</span> to
<span data-x="concept-canvas-webgpu">webgpu</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>An unsupported value*
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
</table>
<p class="tablenote"><small>* For example, the "<code
data-x="canvas-context-webgl">webgl</code>" or "<code
data-x="canvas-context-webgl2">webgl2</code>" value in the case of a user agent having exhausted
the graphics hardware's abilities and having no software fallback implementation.</small></p>
</li>
</ol>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>url</var> = <var>canvas</var>.<span subdfn data-x="dom-canvas-toDataURL">toDataURL</span>([ <var>type</var> [, <var>quality</var> ] ])</code></dt>
<dd>
<p>Returns a <span data-x="data protocol"><code>data:</code> URL</span> for the image in the
canvas.</p>
<p>The first argument, if provided, controls the type of the image to be returned (e.g. PNG or
JPEG). The default is "<code>image/png</code>"; that type is also used if the given type isn't
supported. The second argument applies if the type is an image format that supports variable
quality (such as "<code>image/jpeg</code>"), and is a number in the range 0.0 to 1.0 inclusive
indicating the desired quality level for the resulting image.</p>
<p>When trying to use types other than "<code>image/png</code>", authors can check if the image
was really returned in the requested format by checking to see if the returned string starts
with one of the exact strings "<code data-x="">data:image/png,</code>" or "<code
data-x="">data:image/png;</code>". If it does, the image is PNG, and thus the requested type was
not supported. (The one exception to this is if the canvas has either no height or no width, in
which case the result might simply be "<code data-x="">data:,</code>".)</p>
</dd>
<dt><code data-x=""><var>canvas</var>.<span subdfn data-x="dom-canvas-toBlob">toBlob</span>(<var>callback</var> [, <var>type</var> [, quality ] ])</code></dt>
<dd>
<p>Creates a <code>Blob</code> object representing a file containing the image in the canvas,
and invokes a callback with a handle to that object.</p>
<p>The second argument, if provided, controls the type of the image to be returned (e.g. PNG or
JPEG). The default is "<code>image/png</code>"; that type is also used if the given type isn't
supported. The third argument applies if the type is an image format that supports variable
quality (such as "<code>image/jpeg</code>"), and is a number in the range 0.0 to 1.0 inclusive
indicating the desired quality level for the resulting image.</p>
</dd>
<dt><code data-x=""><var>canvas</var>.<span subdfn data-x="dom-canvas-transferControlToOffscreen">transferControlToOffscreen</span>()</code></dt>
<dd>
<p>Returns a newly created <code>OffscreenCanvas</code> object that uses the
<code>canvas</code> element as a placeholder. Once the <code>canvas</code> element has become a
placeholder for an <code>OffscreenCanvas</code> object, its natural size can no longer be
changed, and it cannot have a rendering context. The content of the placeholder canvas is
updated on the <code>OffscreenCanvas</code>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>update the rendering</span>
steps.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="HTMLCanvasElement"><code
data-x="dom-canvas-toDataURL">toDataURL(<var>type</var>, <var>quality</var>)</code></dfn> method,
when invoked, must run these steps:</p>
<ol>
<li><p>If this <code>canvas</code> element's bitmap's <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag is set to false, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p>
<li><p>If this <code>canvas</code> element's bitmap has no pixels (i.e. either its horizontal
dimension or its vertical dimension is zero) then return the string "<code
data-x="">data:,</code>". (This is the shortest <span data-x="data
protocol"><code>data:</code> URL</span>; it represents the empty string in a <code
data-x="">text/plain</code> resource.)</p></li>
<li><p>Let <var>file</var> be <span data-x="a serialization of the bitmap as a file">a
serialization of this <code>canvas</code> element's bitmap as a file</span>, passing
<var>type</var> and <var>quality</var> if given.</p></li>
<li><p>If <var>file</var> is null then return "<code data-x="">data:,</code>".</p></li>
<li><p>Return a <span data-x="data protocol"><code>data:</code> URL</span> representing
<var>file</var>. <ref>RFC2397</ref></p>
<!-- should we explicitly require the URL to be base64-encoded and not have any parameters, to
ensure the same exact URL is generated in each browser? -->
</ol>
<p>The <dfn method for="HTMLCanvasElement"><code
data-x="dom-canvas-toBlob">toBlob(<var>callback</var>, <var>type</var>,
<var>quality</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If this <code>canvas</code> element's bitmap's <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag is set to false, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>result</var> be null.</p></li>
<li><p>If this <code>canvas</code> element's bitmap has pixels (i.e., neither its horizontal
dimension nor its vertical dimension is zero), then set <var>result</var> to a copy of this
<code>canvas</code> element's bitmap.
<li>
<p>Run these steps <span>in parallel</span>:</p>
<ol>
<li><p>If <var>result</var> is non-null, then set <var>result</var> to <span data-x="a
serialization of the bitmap as a file">a serialization of <var>result</var> as a file</span>
with <var>type</var> and <var>quality</var> if given.</p></li>
<li>
<p><span>Queue an element task</span> on the
<!--en-GB--><dfn id="canvas-blob-serialisation-task-source">canvas blob serialization task
source</dfn> given the <code>canvas</code> element to run these steps:</p>
<ol>
<li><p>If <var>result</var> is non-null, then set <var>result</var> to a new
<code>Blob</code> object, created in the <span data-x="concept-relevant-realm">relevant
realm</span> of this <code>canvas</code> element, representing <var>result</var>.
<ref>FILEAPI</ref></p></li>
<li><p><span data-x="es-invoking-callback-functions">Invoke</span> <var>callback</var> with
« <var>result</var> » and "<code data-x="">report</code>".</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p>The <dfn method for="HTMLCanvasElement"><code
data-x="dom-canvas-transferControlToOffscreen">transferControlToOffscreen()</code></dfn> method,
when invoked, must run these steps:</p>
<ol>
<li><p>If this <code>canvas</code> element's <span data-x="concept-canvas-context-mode">context
mode</span> is not set to <span data-x="concept-canvas-none">none</span>, throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>offscreenCanvas</var> be a new <code>OffscreenCanvas</code> object with its
width and height equal to the values of the <code data-x="attr-canvas-width">width</code>
and <code data-x="attr-canvas-height">height</code> content attributes of this
<code>canvas</code> element.</p></li>
<li><p>Set the <var>offscreenCanvas</var>'s <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>
to a weak reference to this <code>canvas</code> element.</p></li>
<li><p>Set this <code>canvas</code> element's <span data-x="concept-canvas-context-mode">context
mode</span> to <span data-x="concept-canvas-placeholder">placeholder</span>.</p></li>
<li><p>Set the <var>offscreenCanvas</var>'s <span
data-x="offscreencanvas-inherited-lang">inherited language</span> to the
<span>language</span> of this <code>canvas</code> element.</p></li>
<li><p>Set the <var>offscreenCanvas</var>'s <span
data-x="offscreencanvas-inherited-direction">inherited direction</span> to the <span
data-x="the directionality">directionality</span> of this <code>canvas</code> element.</p></li>
<li><p>Return <var>offscreenCanvas</var>.</p></li>
</ol>
</div>
<h5 id="2dcontext">The 2D rendering context</h5>
<!-- v2: we're on v5. suggestions for subsequent versions are marked v6, v7, v8. -->
<pre><code class="idl">typedef (<span>HTMLImageElement</span> or
<span>SVGImageElement</span>) <dfn typedef>HTMLOrSVGImageElement</dfn>;
typedef (<span>HTMLOrSVGImageElement</span> or
<span>HTMLVideoElement</span> or
<span>HTMLCanvasElement</span> or
<span>ImageBitmap</span> or
<span>OffscreenCanvas</span> or
<span>VideoFrame</span>) <dfn typedef>CanvasImageSource</dfn>;
enum <dfn enum>PredefinedColorSpace</dfn> { "<span data-x="dom-PredefinedColorSpace-srgb">srgb</span>", "<span data-x="dom-PredefinedColorSpace-display-p3">display-p3</span>" };
enum <dfn enum>CanvasColorType</dfn> { "<span data-x="dom-CanvasColorType-unorm8">unorm8</span>", "<span data-x="dom-CanvasColorType-float16">float16</span>" };
enum <dfn enum>CanvasFillRule</dfn> { "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>", "<span data-x="dom-context-2d-fillRule-evenodd">evenodd</span>" };
dictionary <dfn dictionary>CanvasRenderingContext2DSettings</dfn> {
boolean <span data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</span> = true;
boolean <span data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</span> = false;
<span>PredefinedColorSpace</span> <span data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</span> = "<span data-x="dom-PredefinedColorSpace-srgb">srgb</span>";
<span>CanvasColorType</span> <span data-x="dom-CanvasRenderingContext2DSettings-colorType">colorType</span> = "<span data-x="dom-CanvasColorType-unorm8">unorm8</span>";
boolean <span data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</span> = false;
};
enum <dfn enum>ImageSmoothingQuality</dfn> { "<span data-x="dom-context-2d-imageSmoothingQuality-low">low</span>", "<span data-x="dom-context-2d-imageSmoothingQuality-medium">medium</span>", "<span data-x="dom-context-2d-imageSmoothingQuality-high">high</span>" };
[Exposed=Window]
interface <dfn interface>CanvasRenderingContext2D</dfn> {
// back-reference to the canvas
readonly attribute <span>HTMLCanvasElement</span> <span data-x="dom-context-2d-canvas">canvas</span>;
};
<span>CanvasRenderingContext2D</span> includes <span>CanvasSettings</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasState</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasTransform</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasCompositing</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasImageSmoothing</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasFillStrokeStyles</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasShadowStyles</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasFilters</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasRect</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasDrawPath</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasUserInterface</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasText</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasDrawImage</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasImageData</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasPathDrawingStyles</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasTextDrawingStyles</span>;
<span>CanvasRenderingContext2D</span> includes <span>CanvasPath</span>;
interface mixin <dfn interface>CanvasSettings</dfn> {
// settings
<span>CanvasRenderingContext2DSettings</span> <span data-x="dom-context-2d-canvas-getcontextattributes">getContextAttributes</span>();
};
interface mixin <dfn interface>CanvasState</dfn> {
// state
undefined <span data-x="dom-context-2d-save">save</span>(); // push state on state stack
undefined <span data-x="dom-context-2d-restore">restore</span>(); // pop state stack and restore state
undefined <span data-x="dom-context-2d-reset">reset</span>(); // <span>reset the rendering context to its default state</span>
boolean <span data-x="dom-context-2d-isContextLost">isContextLost</span>(); // return whether context is lost
};
interface mixin <dfn interface>CanvasTransform</dfn> {
// transformations (default transform is the identity matrix)
undefined <span data-x="dom-context-2d-scale">scale</span>(unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-rotate">rotate</span>(unrestricted double angle);
undefined <span data-x="dom-context-2d-translate">translate</span>(unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-transform">transform</span>(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
[NewObject] <span>DOMMatrix</span> <span data-x="dom-context-2d-getTransform">getTransform</span>();
undefined <span data-x="dom-context-2d-setTransform">setTransform</span>(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
undefined <span data-x="dom-context-2d-setTransform-matrix">setTransform</span>(optional <span>DOMMatrix2DInit</span> transform = {});
undefined <span data-x="dom-context-2d-resetTransform">resetTransform</span>();
<!--
// v7 we've also received requests (though not many so far) for:
undefined skew(...); // is this common enough that one can't just use setTransform()?
undefined reflect(...); and undefined mirror(...); // aren't negative values in scale() sufficient for these?
-->
};
interface mixin <dfn interface>CanvasCompositing</dfn> {
// compositing
attribute unrestricted double <span data-x="dom-context-2d-globalAlpha">globalAlpha</span>; // (default 1.0)
attribute DOMString <span data-x="dom-context-2d-globalCompositeOperation">globalCompositeOperation</span>; // (default "source-over")
};
interface mixin <dfn interface>CanvasImageSmoothing</dfn> {
// image smoothing
attribute boolean <span data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</span>; // (default true)
attribute <span>ImageSmoothingQuality</span> <span data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</span>; // (default low)
<!--
// v7 we've also received requests for:
- turning off antialiasing to avoid seams when patterns are painted next to each other
- might be better to overdraw?
- might be better to just draw at a higher res then downsample, like for 3d?
- nested layers
- the ability to composite an entire set of drawing operations with one shadow all at once
https://lists.w3.org/Archives/Public/public-whatwg-archive/2008Aug/0024.html
-->
};
interface mixin <dfn interface>CanvasFillStrokeStyles</dfn> {
// colors and styles (see also the <span>CanvasPathDrawingStyles</span> and <span>CanvasTextDrawingStyles</span> interfaces)
attribute (DOMString or CanvasGradient or CanvasPattern) <span data-x="dom-context-2d-strokeStyle">strokeStyle</span>; // (default black)
attribute (DOMString or CanvasGradient or CanvasPattern) <span data-x="dom-context-2d-fillStyle">fillStyle</span>; // (default black)
<span>CanvasGradient</span> <span data-x="dom-context-2d-createLinearGradient">createLinearGradient</span>(double x0, double y0, double x1, double y1);
<span>CanvasGradient</span> <span data-x="dom-context-2d-createRadialGradient">createRadialGradient</span>(double x0, double y0, double r0, double x1, double y1, double r1);
<span>CanvasGradient</span> <span data-x="dom-context-2d-createConicGradient">createConicGradient</span>(double startAngle, double x, double y);
<span>CanvasPattern</span>? <span data-x="dom-context-2d-createPattern">createPattern</span>(<span>CanvasImageSource</span> image, [<span>LegacyNullToEmptyString</span>] DOMString repetition);
<!--
// v8 we received one request from Ralf Richard G&oml;bel for a new kind of pattern: a hatch.
// basically it would be a series of dash styles, angles, line widths, and offsets
-->
};
interface mixin <dfn interface>CanvasShadowStyles</dfn> {
// shadows
attribute unrestricted double <span data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</span>; // (default 0)
attribute unrestricted double <span data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</span>; // (default 0)
attribute unrestricted double <span data-x="dom-context-2d-shadowBlur">shadowBlur</span>; // (default 0)
attribute DOMString <span data-x="dom-context-2d-shadowColor">shadowColor</span>; // (default <span>transparent black</span>)
};
interface mixin <dfn interface>CanvasFilters</dfn> {
// filters
attribute DOMString <span data-x="dom-context-2d-filter">filter</span>; // (default "none")
};
interface mixin <dfn interface>CanvasRect</dfn> {
// rects
undefined <span data-x="dom-context-2d-clearRect">clearRect</span>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
undefined <span data-x="dom-context-2d-fillRect">fillRect</span>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
undefined <span data-x="dom-context-2d-strokeRect">strokeRect</span>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
};
interface mixin <dfn interface>CanvasDrawPath</dfn> {
// path API (see also <span>CanvasPath</span>)
undefined <span data-x="dom-context-2d-beginPath">beginPath</span>();
undefined <span data-x="dom-context-2d-fill">fill</span>(optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
undefined <span data-x="dom-context-2d-fill-path">fill</span>(<span>Path2D</span> path, optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
undefined <span data-x="dom-context-2d-stroke">stroke</span>();
undefined <span data-x="dom-context-2d-stroke-path">stroke</span>(<span>Path2D</span> path);
undefined <span data-x="dom-context-2d-clip">clip</span>(optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
undefined <span data-x="dom-context-2d-clip-path">clip</span>(<span>Path2D</span> path, optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
boolean <span data-x="dom-context-2d-isPointInPath">isPointInPath</span>(unrestricted double x, unrestricted double y, optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
boolean <span data-x="dom-context-2d-isPointInPath-path">isPointInPath</span>(<span>Path2D</span> path, unrestricted double x, unrestricted double y, optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>");
boolean <span data-x="dom-context-2d-isPointInStroke">isPointInStroke</span>(unrestricted double x, unrestricted double y);
boolean <span data-x="dom-context-2d-isPointInStroke-path">isPointInStroke</span>(<span>Path2D</span> path, unrestricted double x, unrestricted double y);
};
interface mixin <dfn interface>CanvasUserInterface</dfn> {
undefined <span data-x="dom-context-2d-drawFocusIfNeeded">drawFocusIfNeeded</span>(<span>Element</span> element);
undefined <span data-x="dom-context-2d-drawFocusIfNeeded-path-element">drawFocusIfNeeded</span>(<span>Path2D</span> path, <span>Element</span> element);
};
interface mixin <dfn interface>CanvasText</dfn> {
// text (see also the <span>CanvasPathDrawingStyles</span> and <span>CanvasTextDrawingStyles</span> interfaces)
undefined <span data-x="dom-context-2d-fillText">fillText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
undefined <span data-x="dom-context-2d-strokeText">strokeText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
<span>TextMetrics</span> <span data-x="dom-context-2d-measureText">measureText</span>(DOMString text);
};
interface mixin <dfn interface>CanvasDrawImage</dfn> {
// drawing images
undefined <span data-x="dom-context-2d-drawImage">drawImage</span>(<span>CanvasImageSource</span> image, unrestricted double dx, unrestricted double dy);
undefined <span data-x="dom-context-2d-drawImage">drawImage</span>(<span>CanvasImageSource</span> image, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
undefined <span data-x="dom-context-2d-drawImage">drawImage</span>(<span>CanvasImageSource</span> image, unrestricted double sx, unrestricted double sy, unrestricted double sw, unrestricted double sh, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
};
interface mixin <dfn interface>CanvasImageData</dfn> {
// <span>pixel manipulation</span>
<span>ImageData</span> <span data-x="dom-context-2d-createImageData">createImageData</span>([EnforceRange] long sw, [EnforceRange] long sh, optional <span>ImageDataSettings</span> settings = {});
<span>ImageData</span> <span data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<span>ImageData</span> imageData);
<span>ImageData</span> <span data-x="dom-context-2d-getImageData">getImageData</span>([EnforceRange] long sx, [EnforceRange] long sy, [EnforceRange] long sw, [EnforceRange] long sh, optional <span>ImageDataSettings</span> settings = {});
undefined <span data-x="dom-context-2d-putImageData-short">putImageData</span>(<span>ImageData</span> imageData, [EnforceRange] long dx, [EnforceRange] long dy);
undefined <span data-x="dom-context-2d-putImageData">putImageData</span>(<span>ImageData</span> imageData, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
};
enum <dfn enum>CanvasLineCap</dfn> { "butt", "round", "square" };
enum <dfn enum>CanvasLineJoin</dfn> { "round", "bevel", "miter" };
enum <dfn enum>CanvasTextAlign</dfn> { "<span data-x="dom-context-2d-textalign-start">start</span>", "<span data-x="dom-context-2d-textalign-end">end</span>", "<span data-x="dom-context-2d-textalign-left">left</span>", "<span data-x="dom-context-2d-textalign-right">right</span>", "<span data-x="dom-context-2d-textalign-center">center</span>" };
enum <dfn enum>CanvasTextBaseline</dfn> { "<span data-x="dom-context-2d-textbaseline-top">top</span>", "<span data-x="dom-context-2d-textbaseline-hanging">hanging</span>", "<span data-x="dom-context-2d-textbaseline-middle">middle</span>", "<span data-x="dom-context-2d-textbaseline-alphabetic">alphabetic</span>", "<span data-x="dom-context-2d-textbaseline-ideographic">ideographic</span>", "<span data-x="dom-context-2d-textbaseline-bottom">bottom</span>" };
enum <dfn enum>CanvasDirection</dfn> { "<span data-x="dom-context-2d-direction-ltr">ltr</span>", "<span data-x="dom-context-2d-direction-rtl">rtl</span>", "<span data-x="dom-context-2d-direction-inherit">inherit</span>" };
enum <dfn enum>CanvasFontKerning</dfn> { "<span data-x="dom-context-2d-fontkerning-auto">auto</span>", "<span data-x="dom-context-2d-fontkerning-normal">normal</span>", "<span data-x="dom-context-2d-fontkerning-none">none</span>" };
enum <dfn enum>CanvasFontStretch</dfn> { "<span data-x="dom-context-2d-fontstretch-ultra-condensed">ultra-condensed</span>", "<span data-x="dom-context-2d-fontstretch-extra-condensed">extra-condensed</span>", "<span data-x="dom-context-2d-fontstretch-condensed">condensed</span>", "<span data-x="dom-context-2d-fontstretch-semi-condensed">semi-condensed</span>", "<span data-x="dom-context-2d-fontstretch-normal">normal</span>", "<span data-x="dom-context-2d-fontstretch-semi-expanded">semi-expanded</span>", "<span data-x="dom-context-2d-fontstretch-expanded">expanded</span>", "<span data-x="dom-context-2d-fontstretch-extra-expanded">extra-expanded</span>", "<span data-x="dom-context-2d-fontstretch-ultra-expanded">ultra-expanded</span>" };
enum <dfn enum>CanvasFontVariantCaps</dfn> { "<span data-x="dom-context-2d-fontvariantcaps-normal">normal</span>", "<span data-x="dom-context-2d-fontvariantcaps-small-caps">small-caps</span>", "<span data-x="dom-context-2d-fontvariantcaps-all-small-caps">all-small-caps</span>", "<span data-x="dom-context-2d-fontvariantcaps-petite-caps">petite-caps</span>", "<span data-x="dom-context-2d-fontvariantcaps-all-petite-caps">all-petite-caps</span>", "<span data-x="dom-context-2d-fontvariantcaps-unicase">unicase</span>", "<span data-x="dom-context-2d-fontvariantcaps-titling-caps">titling-caps</span>" };
enum <dfn enum>CanvasTextRendering</dfn> { "<span data-x="dom-context-2d-textRendering-auto">auto</span>", "<span data-x="dom-context-2d-textRendering-optimizeSpeed">optimizeSpeed</span>", "<span data-x="dom-context-2d-textRendering-optimizeLegibility">optimizeLegibility</span>", "<span data-x="dom-context-2d-textRendering-geometricPrecision">geometricPrecision</span>" };
interface mixin <dfn interface>CanvasPathDrawingStyles</dfn> {
// line caps/joins
attribute unrestricted double <span data-x="dom-context-2d-lineWidth">lineWidth</span>; // (default 1)
attribute <span>CanvasLineCap</span> <span data-x="dom-context-2d-lineCap">lineCap</span>; // (default "butt")
attribute <span>CanvasLineJoin</span> <span data-x="dom-context-2d-lineJoin">lineJoin</span>; // (default "miter")
attribute unrestricted double <span data-x="dom-context-2d-miterLimit">miterLimit</span>; // (default 10)
// dashed lines
undefined <span data-x="dom-context-2d-setLineDash">setLineDash</span>(sequence<unrestricted double> segments); // default empty
sequence<unrestricted double> <span data-x="dom-context-2d-getLineDash">getLineDash</span>();
attribute unrestricted double <span data-x="dom-context-2d-lineDashOffset">lineDashOffset</span>;
};
interface mixin <dfn interface>CanvasTextDrawingStyles</dfn> {
// text
attribute DOMString <span data-x="dom-context-2d-lang">lang</span>; // (default: "inherit")
attribute DOMString <span data-x="dom-context-2d-font">font</span>; // (default 10px sans-serif)
attribute <span>CanvasTextAlign</span> <span data-x="dom-context-2d-textAlign">textAlign</span>; // (default: "start")
attribute <span>CanvasTextBaseline</span> <span data-x="dom-context-2d-textBaseline">textBaseline</span>; // (default: "alphabetic")
attribute <span>CanvasDirection</span> <span data-x="dom-context-2d-direction">direction</span>; // (default: "inherit")
attribute DOMString <span data-x="dom-context-2d-letterSpacing">letterSpacing</span>; // (default: "0px")
attribute <span>CanvasFontKerning</span> <span data-x="dom-context-2d-fontKerning">fontKerning</span>; // (default: "auto")
attribute <span>CanvasFontStretch</span> <span data-x="dom-context-2d-fontStretch">fontStretch</span>; // (default: "normal")
attribute <span>CanvasFontVariantCaps</span> <span data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</span>; // (default: "normal")
attribute <span>CanvasTextRendering</span> <span data-x="dom-context-2d-textRendering">textRendering</span>; // (default: "auto")
attribute DOMString <span data-x="dom-context-2d-wordSpacing">wordSpacing</span>; // (default: "0px")
};
interface mixin <dfn interface>CanvasPath</dfn> {
// shared path API methods
undefined <span data-x="dom-context-2d-closePath">closePath</span>();
undefined <span data-x="dom-context-2d-moveTo">moveTo</span>(unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-lineTo">lineTo</span>(unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-quadraticCurveTo">quadraticCurveTo</span>(unrestricted double cpx, unrestricted double cpy, unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-bezierCurveTo">bezierCurveTo</span>(unrestricted double cp1x, unrestricted double cp1y, unrestricted double cp2x, unrestricted double cp2y, unrestricted double x, unrestricted double y);
undefined <span data-x="dom-context-2d-arcTo">arcTo</span>(unrestricted double x1, unrestricted double y1, unrestricted double x2, unrestricted double y2, unrestricted double radius); <!-- see ARC-ORDER note below -->
undefined <span data-x="dom-context-2d-rect">rect</span>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
undefined <span data-x="dom-context-2d-roundRect">roundRect</span>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h, optional (unrestricted double or <span>DOMPointInit</span> or sequence<(unrestricted double or <span>DOMPointInit</span>)>) radii = 0);
undefined <span data-x="dom-context-2d-arc">arc</span>(unrestricted double x, unrestricted double y, unrestricted double radius, unrestricted double startAngle, unrestricted double endAngle, optional boolean counterclockwise = false); <!-- see ARC-ORDER note below -->
undefined <span data-x="dom-context-2d-ellipse">ellipse</span>(unrestricted double x, unrestricted double y, unrestricted double radiusX, unrestricted double radiusY, unrestricted double rotation, unrestricted double startAngle, unrestricted double endAngle, optional boolean counterclockwise = false); <!-- see ARC-ORDER note below -->
};
[Exposed=(Window,Worker)]
interface <dfn interface>CanvasGradient</dfn> {
// opaque object
undefined <span data-x="dom-canvasgradient-addColorStop">addColorStop</span>(double offset, DOMString color);
};
[Exposed=(Window,Worker)]
interface <dfn interface>CanvasPattern</dfn> {
// opaque object
undefined <span data-x="dom-canvaspattern-setTransform">setTransform</span>(optional <span>DOMMatrix2DInit</span> transform = {});
};
[Exposed=(Window,Worker)]
interface <dfn interface>TextMetrics</dfn> {
// x-direction
readonly attribute double <span data-x="dom-textmetrics-width">width</span>; // advance width
readonly attribute double <span data-x="dom-textmetrics-actualBoundingBoxLeft">actualBoundingBoxLeft</span>;
readonly attribute double <span data-x="dom-textmetrics-actualBoundingBoxRight">actualBoundingBoxRight</span>;
// y-direction
readonly attribute double <span data-x="dom-textmetrics-fontBoundingBoxAscent">fontBoundingBoxAscent</span>;
readonly attribute double <span data-x="dom-textmetrics-fontBoundingBoxDescent">fontBoundingBoxDescent</span>;
readonly attribute double <span data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</span>;
readonly attribute double <span data-x="dom-textmetrics-actualBoundingBoxDescent">actualBoundingBoxDescent</span>;
readonly attribute double <span data-x="dom-textmetrics-emHeightAscent">emHeightAscent</span>;
readonly attribute double <span data-x="dom-textmetrics-emHeightDescent">emHeightDescent</span>;
readonly attribute double <span data-x="dom-textmetrics-hangingBaseline">hangingBaseline</span>;
readonly attribute double <span data-x="dom-textmetrics-alphabeticBaseline">alphabeticBaseline</span>;
readonly attribute double <span data-x="dom-textmetrics-ideographicBaseline">ideographicBaseline</span>;
};
dictionary <dfn dictionary>ImageDataSettings</dfn> {
<span>PredefinedColorSpace</span> <span data-x="dom-PredefinedColorSpace-srgb">colorSpace</span>;
};
[Exposed=(Window,Worker),
<span>Serializable</span>]
interface <dfn interface>ImageData</dfn> {
<span data-x="dom-imagedata">constructor</span>(unsigned long sw, unsigned long sh, optional <span>ImageDataSettings</span> settings = {});
<span data-x="dom-imagedata-with-data">constructor</span>(<span data-x="idl-Uint8ClampedArray">Uint8ClampedArray</span> data, unsigned long sw, optional unsigned long sh, optional <span>ImageDataSettings</span> settings = {});
readonly attribute unsigned long <span data-x="dom-imagedata-width">width</span>;
readonly attribute unsigned long <span data-x="dom-imagedata-height">height</span>;
readonly attribute <span data-x="idl-Uint8ClampedArray">Uint8ClampedArray</span> <span data-x="dom-imagedata-data">data</span>;
readonly attribute <span>PredefinedColorSpace</span> <span data-x="dom-imagedata-colorSpace">colorSpace</span>;
};
[Exposed=(Window,Worker)]
interface <dfn interface>Path2D</dfn> {
<span data-x="dom-Path2D">constructor</span>(optional (<span>Path2D</span> or DOMString) path);
undefined <span data-x="dom-Path2D-addPath">addPath</span>(<span>Path2D</span> path, optional <span>DOMMatrix2DInit</span> transform = {});
};
<span>Path2D</span> includes <span>CanvasPath</span>;</code></pre>
<!-- ARC-ORDER note (see above):
some demos rely on the precise order of the arc() and arcTo()
methods, see https://bugzilla.mozilla.org/show_bug.cgi?id=623437
for an example, and its duplicates for more -->
<p class="note" w-nodev>To maintain compatibility with existing web content, user agents need to
enumerate methods defined in <code>CanvasUserInterface</code> immediately after the <code
data-x="dom-context-2d-stroke">stroke()</code> method on <code>CanvasRenderingContext2D</code>
objects.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var> = <var>canvas</var>.<span data-x="dom-canvas-getContext">getContext</span>('2d' [, { [ <span data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</span>: true ] [, <span data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</span>: false ] [, <span data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</span>: 'srgb'] [, <span data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</span>: false ]} ])</code></dt>
<dd>
<p>Returns a <code>CanvasRenderingContext2D</code> object that is permanently bound to a
particular <code>canvas</code> element.</p>
<p>If the <code data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</code> member is
false, then the context is forced to always be opaque.</p>
<p>If the <code
data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code> member is
true, then the context might be <span
data-x="concept-canvas-desynchronized">desynchronized</span>.</p>
<p>The <code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code> member
specifies the <span data-x="concept-canvas-color-space">color space</span> of the rendering
context.</p>
<p>The <code data-x="dom-CanvasRenderingContext2DSettings-colorType">colorType</code> member
specifies the <span data-x="concept-canvas-color-type">color type</span> of the rendering
context.</p>
<p>If the <code
data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>
member is true, then the context is marked for <span
data-x="concept-canvas-will-read-frequently">readback optimization</span>.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-canvas">canvas</span></code></dt>
<dd><p>Returns the <code>canvas</code> element.</p></dd>
<dt><code data-x=""><var>attributes</var> = <var>context</var>.<span data-x="dom-context-2d-canvas-getcontextattributes">getContextAttributes</span>()</code></dt>
<dd>
<p>Returns an object whose:</p>
<ul>
<li><code data-x="concept-canvas-alpha">alpha</code> member is true if the context has an alpha
component that is not 1.0; otherwise false.</li>
<li><code data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code>
member is true if the context can be <span data-x="concept-canvas-desynchronized">desynchronized</span>.</li>
<li><code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code> member is
a string indicating the context's <span data-x="concept-canvas-color-space">color
space</span>.</li>
<li><code data-x="dom-CanvasRenderingContext2DSettings-colorType">colorType</code> member is
a string indicating the context's <span data-x="concept-canvas-color-type">color
type</span>.</li>
<li><code data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>
member is true if the context is marked for <span data-x="concept-canvas-will-read-frequently">readback
optimization</span>.</li>
</ul>
</dd>
</dl>
<div w-nodev>
<hr>
<p>The <code>CanvasRenderingContext2D</code> 2D rendering context represents a flat linear
Cartesian surface whose origin (0,0) is at the top left corner, with the coordinate space having
<var>x</var> values increasing when going right, and <var>y</var> values increasing when going
down. The <var>x</var>-coordinate of the right-most edge is equal to the width of the rendering
context's <span>output bitmap</span> in <span data-x="'px'">CSS pixels</span>; similarly, the
<var>y</var>-coordinate of the bottom-most edge is equal to the height of the rendering context's
<span>output bitmap</span> in <span data-x="'px'">CSS pixels</span>.</p>
<p>The size of the coordinate space does not necessarily represent the size of the actual bitmaps
that the user agent will use internally or during rendering. On high-definition displays, for
instance, the user agent may internally use bitmaps with four device pixels per unit in the
coordinate space, so that the rendering remains at high quality throughout. Anti-aliasing can
similarly be implemented using oversampling with bitmaps of a higher resolution than the final
image on the display.</p>
<div class="example">
<p>Using <span data-x="'px'">CSS pixels</span> to describe the size of a rendering context's
<span>output bitmap</span> does not mean that when rendered the canvas will cover an equivalent
area in <span data-x="'px'">CSS pixels</span>. <span data-x="'px'">CSS pixels</span> are reused
for ease of integration with CSS features, such as text layout.</p>
<p>In other words, the <code>canvas</code> element below's rendering context has a 200x200
<span>output bitmap</span> (which internally uses <span data-x="'px'">CSS pixels</span> as a
unit for ease of integration with CSS) and is rendered as 100x100 <span data-x="'px'">CSS
pixels</span>:
<pre><code class="html"><canvas width=200 height=200 style=width:100px;height:100px></code></pre>
</div>
<hr>
<p>The <dfn>2D context creation algorithm</dfn>, which is passed a <var>target</var> (a
<code>canvas</code> element) and <var>options</var>, consists of running these steps:</p>
<ol>
<li><p>Let <var>settings</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>options</var> to the dictionary type
<code>CanvasRenderingContext2DSettings</code>. (This can throw an exception.).</p></li>
<li><p>Let <var>context</var> be a new <code>CanvasRenderingContext2D</code> object.</p></li>
<li><p>Initialize <var>context</var>'s <code data-x="dom-context-2d-canvas">canvas</code>
attribute to point to <var>target</var>.</p></li>
<li><p>Set <var>context</var>'s <span>output bitmap</span> to the same bitmap as
<var>target</var>'s bitmap (so that they are shared).</p></li>
<li><p><span data-x="concept-canvas-set-bitmap-dimensions">Set bitmap dimensions</span> to
<span data-x="obtain-numeric-values">the numeric values</span> of <var>target</var>'s <code
data-x="attr-canvas-width">width</code> and <code data-x="attr-canvas-height">height</code>
content attributes.</p></li>
<li><p>Run the <span data-x="canvas-setting-init-bitmap">canvas settings output bitmap
initialization algorithm</span>, given <var>context</var> and <var>settings</var>.</li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<hr>
<p>When the user agent is to <dfn data-x="concept-canvas-set-bitmap-dimensions">set bitmap
dimensions</dfn> to <var>width</var> and <var>height</var>, it must run these steps:</p>
<ol>
<li><p><span>Reset the rendering context to its default state</span>.</p></li>
<li><p>Resize the <span>output bitmap</span> to the new <var>width</var> and
<var>height</var>.</p></li>
<li><p>Let <var>canvas</var> be the <code>canvas</code> element to which the rendering
context's <code data-x="dom-context-2d-canvas">canvas</code> attribute was initialized.</p></li>
<li><p>If <span data-x="obtain-numeric-values">the numeric value</span> of
<var>canvas</var>'s <code data-x="attr-canvas-width">width</code> content
attribute differs from <var>width</var>, then set <var>canvas</var>'s <code
data-x="attr-canvas-width">width</code> content attribute to the shortest possible string
representing <var>width</var> as a <span>valid non-negative integer</span>.</p></li>
<li><p>If <span data-x="obtain-numeric-values">the numeric value</span> of
<var>canvas</var>'s <code data-x="attr-canvas-height">height</code> content
attribute differs from <var>height</var>, then set <var>canvas</var>'s <code
data-x="attr-canvas-height">height</code> content attribute to the shortest possible string
representing <var>height</var> as a <span>valid non-negative integer</span>.</p></li>
</ol>
<div class="example">
<p>Only one square appears to be drawn in the following example:</p>
<pre><code class="js">// canvas is a reference to a <canvas> element
var context = canvas.getContext('2d');
context.fillRect(0,0,50,50);
canvas.setAttribute('width', '300'); // clears the canvas
context.fillRect(0,100,50,50);
canvas.width = canvas.width; // clears the canvas
context.fillRect(100,0,50,50); // only this square remains</code></pre>
</div>
<hr>
<p>The <dfn attribute for="CanvasRenderingContext2D"><code
data-x="dom-context-2d-canvas">canvas</code></dfn> attribute must return the value it was
initialized to when the object was created.</p>
</div>
<hr>
<p>The <code>PredefinedColorSpace</code> enumeration is used to specify the <span
data-x="concept-canvas-color-space">color space</span> of the canvas's backing store.</p>
<p>The "<dfn enum-value for="PredefinedColorSpace"><code
data-x="dom-PredefinedColorSpace-srgb">srgb</code></dfn>" value indicates the <span>'srgb'</span>
color space.</p>
<p>The "<dfn enum-value for="PredefinedColorSpace"><code
data-x="dom-PredefinedColorSpace-display-p3">display-p3</code></dfn>" value indicates the
<span>'display-p3'</span> color space.</p>
<p class="note">The algorithm for converting between color spaces can be found in the
<span>Converting Colors</span> section of <cite>CSS Color</cite>. <ref>CSSCOLOR</ref></p>
<hr>
<p>The <code>CanvasColorType</code> enumeration is used to specify the <span
data-x="concept-canvas-color-type">color type</span> of the canvas's backing store.</p>
<p>The "<dfn enum-value for="CanvasColorType"><code
data-x="dom-CanvasColorType-unorm8">unorm8</code></dfn>" value indicates that the type
for all color components is 8-bit unsigned normalized.</p>
<p>The "<dfn enum-value for="CanvasColorType"><code
data-x="dom-CanvasColorType-float16">float16</code></dfn>" value indicates that the type
for all color components is 16-bit floating point.</p>
<hr>
<p>The <code>CanvasFillRule</code> enumeration is used to select the <dfn>fill rule</dfn>
algorithm by which to determine if a point is inside or outside a path.</p>
<p>The "<dfn enum-value for="CanvasFillRule"><code
data-x="dom-context-2d-fillRule-nonzero">nonzero</code></dfn>" value indicates the nonzero winding
rule, wherein
a point is considered to be outside a shape if the number of times a half-infinite straight
line drawn from that point crosses the shape's path going in one direction is equal to the
number of times it crosses the path going in the other direction.
</p>
<p>The "<dfn enum-value for="CanvasFillRule"><code
data-x="dom-context-2d-fillRule-evenodd">evenodd</code></dfn>" value indicates the even-odd rule,
wherein
a point is considered to be outside a shape if the number of times a half-infinite straight
line drawn from that point crosses the shape's path is even.
</p>
<p>If a point is not outside a shape, it is inside the shape.</p>
<hr>
<p>The <code>ImageSmoothingQuality</code> enumeration is used to express a preference for the
interpolation quality to use when smoothing images.</p>
<p>The "<dfn enum-value for="ImageSmoothingQuality"><code
data-x="dom-context-2d-imageSmoothingQuality-low">low</code></dfn>" value indicates a preference
for a low level of image interpolation quality. Low-quality image interpolation may be more
computationally efficient than higher settings.</p>
<p>The "<dfn enum-value for="ImageSmoothingQuality"><code
data-x="dom-context-2d-imageSmoothingQuality-medium">medium</code></dfn>" value indicates a
preference for a medium level of image interpolation quality.</p>
<p>The "<dfn enum-value for="ImageSmoothingQuality"><code
data-x="dom-context-2d-imageSmoothingQuality-high">high</code></dfn>" value indicates a preference
for a high level of image interpolation quality. High-quality image interpolation may be more
computationally expensive than lower settings.</p>
<p class="note">Bilinear scaling is an example of a relatively fast, lower-quality image-smoothing
algorithm. Bicubic or Lanczos scaling are examples of image-smoothing algorithms that produce
higher-quality output. This specification does not mandate that specific interpolation algorithms
be used.</p>
<h6>Implementation notes</h6>
<!-- NON-NORMATIVE SECTION -->
<p>The <span>output bitmap</span>, when it is not directly displayed by the user agent,
implementations can, instead of updating this bitmap, merely remember the sequence of drawing
operations that have been applied to it until such time as the bitmap's actual data is needed
(for example because of a call to <code data-x="dom-context-2d-drawImage">drawImage()</code>, or
the <code data-x="dom-createImageBitmap">createImageBitmap()</code> factory method). In many
cases, this will be more memory efficient.</p>
<p>The bitmap of a <code>canvas</code> element is the one bitmap that's pretty much always going
to be needed in practice. The <span>output bitmap</span> of a rendering context, when it has one,
is always just an alias to a <code>canvas</code> element's bitmap.</p>
<p>Additional bitmaps are sometimes needed, e.g. to enable fast drawing when the canvas is being
painted at a different size than its <span data-x="natural dimensions">natural size</span>,
or to enable double buffering so that graphics updates, like page scrolling for example, can be
processed concurrently while canvas draw commands are being executed.</p>
<h6>The canvas settings</h6>
<p>A <code>CanvasSettings</code> object has an <dfn>output bitmap</dfn> that is initialized when
the object is created.</p>
<p>The <span>output bitmap</span> has an <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag, which can be set to true or false.
Initially, when one of these bitmaps is created, its <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag must be set to true.</p>
<p>The <code>CanvasSettings</code> object also has an <dfn
data-x="concept-canvas-alpha">alpha</dfn> boolean. When a <code>CanvasSettings</code> object's
<span data-x="concept-canvas-alpha">alpha</span> is false, then its alpha component must be fixed
to 1.0 (fully opaque) for all pixels, and attempts to change the alpha component of any pixel must
be silently ignored.</p>
<p class="note">Thus, the bitmap of such a context starts off as <span>opaque black</span> instead
of <span>transparent black</span>; <code data-x="dom-context-2d-clearRect">clearRect()</code>
always results in <span>opaque black</span> pixels, every fourth byte from <code
data-x="dom-context-2d-getImageData">getImageData()</code> is always 255, the <code
data-x="dom-context-2d-putImageData">putImageData()</code> method effectively ignores every fourth
byte in its input, and so on. However, the alpha component of styles and images drawn onto the
canvas are still honoured up to the point where they would impact the <span>output bitmap</span>'s
alpha component; for instance, drawing a 50% transparent white square on a freshly created
<span>output bitmap</span> with its <span data-x="concept-canvas-alpha">alpha</span> set to false
will result in a fully-opaque gray square.</p>
<p>The <code>CanvasSettings</code> object also has a <dfn
data-x="concept-canvas-desynchronized">desynchronized</dfn> boolean. When a
<code>CanvasSettings</code> object's <span
data-x="concept-canvas-desynchronized">desynchronized</span> is true, then the user agent may
optimize the rendering of the canvas to reduce the latency, as measured from input events to
rasterization, by desynchronizing the canvas paint cycle from the event loop, bypassing the
ordinary user agent rendering algorithm, or both. Insofar as this mode involves bypassing the
usual paint mechanisms, rasterization, or both, it might introduce visible tearing artifacts.</p>
<p class="note">The user agent usually renders on a buffer which is not being displayed, quickly
swapping it and the one being scanned out for presentation; the former buffer is called back
buffer and the latter <i>front buffer</i>. A popular technique for reducing latency is called
front buffer rendering, also known as <i>single buffer</i> rendering, where rendering happens in
parallel and racily with the scanning out process. This technique reduces the latency at the price
of potentially introducing tearing artifacts and can be used to implement in total or part of the
<span data-x="concept-canvas-desynchronized">desynchronized</span> boolean.
<ref>MULTIPLEBUFFERING</ref></p>
<p class="note">The <span data-x="concept-canvas-desynchronized">desynchronized</span> boolean can
be useful when implementing certain kinds of applications, such as drawing applications, where the
latency between input and rasterization is critical.</p>
<p>The <code>CanvasSettings</code> object also has a <dfn
data-x="concept-canvas-will-read-frequently">will read frequently</dfn> boolean. When a
<code>CanvasSettings</code> object's <span data-x="concept-canvas-will-read-frequently">will read
frequently</span> is true, the user agent may optimize the canvas for readback operations.</p>
<p class="note">On most devices the user agent needs to decide whether to store the canvas's
<span>output bitmap</span> on the GPU (this is also called "hardware accelerated"), or on the CPU
(also called "software"). Most rendering operations are more performant for accelerated canvases,
with the major exception being readback with <code
data-x="dom-context-2d-getImageData">getImageData()</code>, <code
data-x="dom-canvas-toDataURL">toDataURL()</code>, or <code
data-x="dom-canvas-toBlob">toBlob()</code>. <code>CanvasSettings</code> objects with <span
data-x="concept-canvas-will-read-frequently">will read frequently</span> equal to true tell the
user agent that the webpage is likely to perform many readback operations and that it is
advantageous to use a software canvas.</p>
<p>The <code>CanvasSettings</code> object also has a <dfn
data-x="concept-canvas-color-space">color space</dfn> setting of type
<code>PredefinedColorSpace</code>. The <code>CanvasSettings</code> object's <span
data-x="concept-canvas-color-space">color space</span> indicates the color space for the
<span>output bitmap</span>.</p>
<p>The <code>CanvasSettings</code> object also has a <dfn
data-x="concept-canvas-color-type">color type</dfn> setting of type
<code>CanvasColorType</code>. The <code>CanvasSettings</code> object's <span
data-x="concept-canvas-color-type">color type</span> indicates the data type of the
color and alpha components of the pixels of the <span>output bitmap</span>.</p>
<p>To <dfn data-x="canvas-setting-init-bitmap">initialize a <code>CanvasSettings</code> output
bitmap</dfn>, given a <code>CanvasSettings</code> <var>context</var> and a
<code>CanvasRenderingContext2DSettings</code> <var>settings</var>:</p>
<ol>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-alpha">alpha</span> to
<var>settings</var>["<dfn dict-member for="CanvasRenderingContext2DSettings"><code
data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</code></dfn>"].</p></li>
<li><p>Set <var>context</var>'s <span
data-x="concept-canvas-desynchronized">desynchronized</span> to <var>settings</var>["<dfn
dict-member for="CanvasRenderingContext2DSettings"><code
data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code></dfn>"].</p></li>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-color-space">color space</span> to
<var>settings</var>["<dfn dict-member for="CanvasRenderingContext2DSettings"><code
data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code></dfn>"].</p></li>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-color-type">color type</span> to
<var>settings</var>["<dfn dict-member for="CanvasRenderingContext2DSettings"><code
data-x="dom-CanvasRenderingContext2DSettings-colorType">colorType</code></dfn>"].</p></li>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-will-read-frequently">will read
frequently</span> to <var>settings</var>["<dfn dict-member
for="CanvasRenderingContext2DSettings"><code
data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code></dfn>"].</p></li>
</ol>
<p>The <dfn method for="CanvasSettings"><code
data-x="dom-context-2d-canvas-getcontextattributes">getContextAttributes()</code></dfn> method
steps are to return «[ "<code data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</code>" →
<span>this</span>'s <span data-x="concept-canvas-alpha">alpha</span>, "<code
data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code>" →
<span>this</span>'s <span data-x="concept-canvas-desynchronized">desynchronized</span>, "<code
data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code>" → <span>this</span>'s
<span data-x="concept-canvas-color-space">color space</span>, "<code
data-x="dom-CanvasRenderingContext2DSettings-colorType">colorType</code>" → <span>this</span>'s
<span data-x="concept-canvas-color-type">color type</span>, "<code
data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>" →
<span>this</span>'s <span data-x="concept-canvas-will-read-frequently">will read frequently</span>
]».</p>
<h6>The canvas state</h6>
<p>Objects that implement the <code>CanvasState</code> interface maintain a stack of drawing
states. <dfn data-x="drawing state">Drawing states</dfn> consist of:</p>
<ul>
<li><p>The current <span data-x="dom-context-2d-transformation">transformation
matrix</span>.</p></li>
<li><p>The current <span>clipping region</span>.</p></li>
<li><p>The current <span data-x="concept-CanvasTextDrawingStyles-letter-spacing">letter
spacing</span>, <span data-x="concept-CanvasTextDrawingStyles-word-spacing">word spacing</span>,
<span data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span>, <span
data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</span>, <span
data-x="concept-canvas-current-filter">filter</span>, <span
data-x="concept-canvas-global-alpha">global alpha</span>, <span data-x="current compositing and
blending operator">compositing and blending operator</span>, and <span
data-x="concept-CanvasShadowStyles-shadow-color">shadow color</span>.</p></li>
<li><p>The current values of the following attributes: <code
data-x="dom-context-2d-lineWidth">lineWidth</code>, <code
data-x="dom-context-2d-lineCap">lineCap</code>, <code
data-x="dom-context-2d-lineJoin">lineJoin</code>, <code
data-x="dom-context-2d-miterLimit">miterLimit</code>, <code
data-x="dom-context-2d-lineDashOffset">lineDashOffset</code>, <code
data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</code>, <code
data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</code>, <code
data-x="dom-context-2d-shadowBlur">shadowBlur</code>, <code
data-x="dom-context-2d-lang">lang</code>, <code
data-x="dom-context-2d-font">font</code>, <code
data-x="dom-context-2d-textAlign">textAlign</code>, <code
data-x="dom-context-2d-textBaseline">textBaseline</code>, <code
data-x="dom-context-2d-direction">direction</code>, <code
data-x="dom-context-2d-fontKerning">fontKerning</code>, <code
data-x="dom-context-2d-fontStretch">fontStretch</code>, <code
data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</code>, <code
data-x="dom-context-2d-textRendering">textRendering</code>, <code
data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code>, <code
data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</code>.</p></li>
<li><p>The current <span>dash list</span>.</p></li>
</ul>
<p class="note">The rendering context's bitmaps are not part of the drawing state, as they
depend on whether and how the rendering context is bound to a <code>canvas</code> element.</p>
<p>Objects that implement the <code>CanvasState</code> mixin have a <dfn
data-x="concept-canvas-context-lost">context lost</dfn> boolean, that is initialized to false
when the object is created. The <span data-x="concept-canvas-context-lost">context lost</span>
value is updated in the <span>context lost steps</span>.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-save">save</span>()</code></dt>
<dd><p>Pushes the current state onto the stack.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-restore">restore</span>()</code></dt>
<dd><p>Pops the top state on the stack, restoring the context to that state.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-reset">reset</span>()</code></dt>
<dd><p>Resets the rendering context, which includes the backing buffer, the drawing state stack,
path, and styles.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-isContextLost">isContextLost</span>()</code></dt>
<dd><p>Returns true if the rendering context was lost. Context loss can occur due to driver
crashes, running out of memory, etc. In these cases, the canvas loses its backing storage and
takes steps to <span>reset the rendering context to its default state</span>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasState"><code data-x="dom-context-2d-save">save()</code></dfn> method
steps are to push a copy of the current drawing state onto the drawing state stack.</p>
<p>The <dfn method for="CanvasState"><code data-x="dom-context-2d-restore">restore()</code></dfn>
method steps are to pop the top entry in the drawing state stack, and reset the drawing state it
describes. If there is no saved state, then the method must do nothing.</p>
<p>The <dfn method for="CanvasState"><code data-x="dom-context-2d-reset">reset()</code></dfn>
method steps are to <span>reset the rendering context to its default state</span>.</p>
<p>To <dfn>reset the rendering context to its default state</dfn>:</p>
<ol>
<li><p>Clear canvas's bitmap to <span>transparent black</span>.</p></li>
<li><p>Empty the list of subpaths in context's <span>current default path</span>.</p></li>
<li><p>Clear the context's drawing state stack.</p></li>
<li><p>Reset everything that <span>drawing state</span> consists of to their initial
values.</p></li>
</ol>
<p>The <dfn method for="CanvasState"><code
data-x="dom-context-2d-isContextLost">isContextLost()</code></dfn> method steps are to return
<span>this</span>'s <span data-x="concept-canvas-context-lost">context lost</span>.</p>
</div>
<h6>Line styles</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lineWidth">lineWidth</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lineWidth">lineWidth</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current line width.</p>
<p>Can be set, to change the line width. Values that are not finite values greater than zero are
ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lineCap">lineCap</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lineCap">lineCap</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current line cap style.</p>
<p>Can be set, to change the line cap style.</p>
<p>The possible line cap styles are "<code data-x="">butt</code>", "<code
data-x="">round</code>", and "<code data-x="">square</code>". Other values are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lineJoin">lineJoin</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lineJoin">lineJoin</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current line join style.</p>
<p>Can be set, to change the line join style.</p>
<p>The possible line join styles are "<code data-x="">bevel</code>", "<code
data-x="">round</code>", and "<code data-x="">miter</code>". Other values are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-miterLimit">miterLimit</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-miterLimit">miterLimit</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current miter limit ratio.</p>
<p>Can be set, to change the miter limit ratio. Values that are not finite values greater than
zero are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-setLineDash">setLineDash</span>(<var>segments</var>)</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-setLineDash">setLineDash</span>(<var>segments</var>)</code></dt>
<dd>
<p>Sets the current line dash pattern (as used when stroking). The argument is a list of
distances for which to alternately have the line on and the line off.</p>
</dd>
<dt><code data-x=""><var>segments</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-getLineDash">getLineDash</span>()</code></dt>
<dt><code data-x=""><var>segments</var> = <var>styles</var>.<span data-x="dom-context-2d-getLineDash">getLineDash</span>()</code></dt>
<dd>
<p>Returns a copy of the current line dash pattern. The array returned will always have an even
number of entries (i.e. the pattern is normalized).</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lineDashOffset">lineDashOffset</span></code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lineDashOffset">lineDashOffset</span></code></dt>
<dd>
<p>Returns the phase offset (in the same units as the line dash pattern).</p>
<p>Can be set, to change the phase offset. Values that are not finite values are ignored.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasPathDrawingStyles</code> interface have attributes and
methods (defined in this section) that control how lines are treated by the object.</p>
<p>The <dfn attribute for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-lineWidth">lineWidth</code></dfn> attribute gives the width of lines, in
coordinate space units. On getting, it must return the current value. On setting, zero, negative,
infinite, and NaN values must be ignored, leaving the value unchanged; other values must change
the current value to the new value.</p>
<p>When the object implementing the <code>CanvasPathDrawingStyles</code> interface is created, the
<code data-x="dom-context-2d-lineWidth">lineWidth</code> attribute must initially have the value
1.0.</p>
<hr>
<p>The <dfn attribute for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-lineCap">lineCap</code></dfn> attribute defines the type of endings that
UAs will place on the end of lines. The three valid values are "<code data-x="">butt</code>",
"<code data-x="">round</code>", and "<code data-x="">square</code>".</p>
<p>On getting, it must return the current value. On setting, the current value must be changed
to the new value.</p>
<p>When the object implementing the <code>CanvasPathDrawingStyles</code> interface is created, the
<code data-x="dom-context-2d-lineCap">lineCap</code> attribute must initially have the value
"<code data-x="">butt</code>".</p>
<hr>
<p>The <dfn attribute for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-lineJoin">lineJoin</code></dfn> attribute defines the type of corners that
UAs will place where two lines meet. The three valid values are "<code data-x="">bevel</code>",
"<code data-x="">round</code>", and "<code data-x="">miter</code>".</p>
<p>On getting, it must return the current value. On setting, the current value must be changed
to the new value.</p>
<p>When the object implementing the <code>CanvasPathDrawingStyles</code> interface is created, the
<code data-x="dom-context-2d-lineJoin">lineJoin</code> attribute must initially have the value
"<code data-x="">miter</code>".</p>
<hr>
<p>When the <code data-x="dom-context-2d-lineJoin">lineJoin</code> attribute has the value "<code
data-x="">miter</code>", strokes use the miter limit ratio to decide how to render joins. The
miter limit ratio can be explicitly set using the <dfn attribute
for="CanvasPathDrawingStyles"><code data-x="dom-context-2d-miterLimit">miterLimit</code></dfn>
attribute. On getting, it must return the current value. On setting, zero, negative, infinite, and
NaN values must be ignored, leaving the value unchanged; other values must change the current
value to the new value.</p>
<!-- values less than 1.0 are equivalent to 1.0, since it's compared against a ratio that can't be
less than 1.0 -->
<p>When the object implementing the <code>CanvasPathDrawingStyles</code> interface is created, the
<code data-x="dom-context-2d-miterLimit">miterLimit</code> attribute must initially have the value
10.0.</p>
<hr>
<p>Each <code>CanvasPathDrawingStyles</code> object has a <dfn>dash list</dfn>, which is either
empty or consists of an even number of non-negative numbers. Initially, the <span>dash list</span>
must be empty.</p>
<p>The <dfn method for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-setLineDash">setLineDash(<var>segments</var>)</code></dfn> method, when invoked, must run
these steps:</p>
<ol>
<li><p>If any value in <var>segments</var> is not finite (e.g. an Infinity or a NaN value), or
if any value is negative (less than zero), then return (without throwing an exception;
user agents could show a message on a developer console, though, as that would be helpful for
debugging).</p></li>
<li><p>If the number of elements in <var>segments</var> is odd, then let <var>segments</var>
be the concatenation of two copies of <var>segments</var>.</p></li>
<li><p>Let the object's <span>dash list</span> be <var>segments</var>.</p></li>
</ol>
<p>When the <dfn method for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-getLineDash">getLineDash()</code></dfn> method is invoked, it must return a
sequence whose values are the values of the object's <span>dash list</span>, in the same
order.</p>
<p>It is sometimes useful to change the "phase" of the dash pattern, e.g. to achieve a "marching
ants" effect. The phase can be set using the <dfn attribute for="CanvasPathDrawingStyles"><code
data-x="dom-context-2d-lineDashOffset">lineDashOffset</code></dfn> attribute. On getting, it must
return the current value. On setting, infinite and NaN values must be ignored, leaving the value
unchanged; other values must change the current value to the new value.</p>
<p>When the object implementing the <code>CanvasPathDrawingStyles</code> interface is created, the
<code data-x="dom-context-2d-lineDashOffset">lineDashOffset</code> attribute must initially have
the value 0.0.</p>
<hr>
<p>When a user agent is to <dfn>trace a path</dfn>, given an object <var>style</var>
that implements the <code>CanvasPathDrawingStyles</code> interface, it must run the following
algorithm. This algorithm returns a new <span data-x="concept-path">path</span>.</p>
<ol>
<li><p>Let <var>path</var> be a copy of the path being traced.</p></li>
<!-- PATH SANITIZATION -->
<li><p>Prune all zero-length <span>line segments</span> from <var>path</var>.</p></li>
<li><p>Remove from <var>path</var> any subpaths containing no lines (i.e. subpaths with
just one point).</p></li>
<li><p>Replace each point in each subpath of <var>path</var> other than the first point
and the last point of each subpath by a <i>join</i> that joins the line leading to that point to
the line leading out of that point, such that the subpaths all consist of two points (a starting
point with a line leading out of it, and an ending point with a line leading into it), one or
more lines (connecting the points and the joins), and zero or more joins (each connecting one
line to another), connected together such that each subpath is a series of one or more lines with
a join between each one and a point on each end.</p></li>
<li><p>Add a straight closing line to each closed subpath in <var>path</var> connecting
the last point and the first point of that subpath; change the last point to a join (from the
previously last line to the newly added closing line), and change the first point to a join (from
the newly added closing line to the first line).</p>
<li><p>If <var>style</var>'s <span>dash list</span> is empty, then jump to the step
labeled <i>convert</i>.</p></li>
<!-- DASHING -->
<li><p>Let <var>pattern width</var> be the concatenation of all the entries of
<var>style</var>'s <span>dash list</span>, in coordinate space units.</p>
<li><p>For each subpath <var>subpath</var> in <var>path</var>, run the
following substeps. These substeps mutate the subpaths in <var>path</var> <i>in
vivo</i>.</p>
<ol>
<li><p>Let <var>subpath width</var> be the length of all the lines of <var>subpath</var>, in coordinate space units.</p>
<li><p>Let <var>offset</var> be the value of <var>style</var>'s <code
data-x="dom-context-2d-lineDashOffset">lineDashOffset</code>, in coordinate space
units.</p></li>
<li>
<p>While <var>offset</var> is greater than <var>pattern width</var>,
decrement it by <var>pattern width</var>.</p>
<p>While <var>offset</var> is less than zero, increment it by <var>pattern
width</var>.</p>
</li>
<li><p>Define <var>L</var> to be a linear coordinate line defined along all lines in
<var>subpath</var>, such that the start of the first line in the subpath is defined
as coordinate 0, and the end of the last line in the subpath is defined as coordinate <var>subpath width</var>.</p></li>
<li><p>Let <var>position</var> be zero minus <var>offset</var>.</p></li>
<li><p>Let <var>index</var> be 0.</p></li>
<li><p>Let <var>current state</var> be <i>off</i> (the other states being <i>on</i>
and <i>zero-on</i>).</p></li>
<li><p><i>Dash on</i>: Let <var>segment length</var> be
the value of <var>style</var>'s <span>dash
list</span>'s <var>index</var>th entry.</p></li>
<li><p>Increment <var>position</var> by <var>segment length</var>.</p></li>
<li><p>If <var>position</var> is greater than <var>subpath width</var>,
then end these substeps for this subpath and start them again for the next subpath; if there
are no more subpaths, then jump to the step labeled <i>convert</i> instead.</p></li>
<li><p>If <var>segment length</var> is nonzero, then let <var>current state</var> be
<i>on</i>.</p></li>
<li><p>Increment <var>index</var> by one.</p></li>
<li><p><i>Dash off<!-- labeled for consistency only --></i>: Let <var>segment
length</var> be the value of <var>style</var>'s <span>dash list</span>'s <var>index</var>th entry.</p></li>
<li><p>Let <var>start</var> be the offset <var>position</var> on <var>L</var>.</p></li>
<li><p>Increment <var>position</var> by <var>segment length</var>.</p></li>
<li><p>If <var>position</var> is less than zero, then jump to the step labeled
<i>post-cut</i>.</p></li> <!-- start and end both before zero -->
<li><p>If <var>start</var> is less than zero, then let <var>start</var> be
zero.</p></li> <!-- end will be (at or) after zero -->
<li><p>If <var>position</var> is greater than <var>subpath width</var>,
then let <var>end</var> be the offset <var>subpath width</var> on <var>L</var>. Otherwise, let <var>end</var> be the offset <var>position</var> on <var>L</var>.</p></li>
<li>
<p>Jump to the first appropriate step:</p>
<dl class="switch">
<dt>If <var>segment length</var> is zero and <var>current state</var> is
<i>off</i></dt>
<dd>
<p>Do nothing, just continue to the next step.</p>
</dd>
<dt>If <var>current state</var> is <i>off</i></dt>
<dd>
<p>Cut the line on which <var>end</var> finds itself short at <var>end</var> and place a point there, cutting in two the subpath that it was in;
remove all line segments, joins, points, and subpaths that are between <var>start</var> and <var>end</var>; and finally place a single point at <var>start</var> with no lines connecting to it.</p>
<p>The point has a <i>directionality</i> for the purposes of drawing line caps (see below).
The directionality is the direction that the original line had at that point (i.e. when <var>L</var> was defined above).</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>Cut the line on which <var>start</var> finds itself into two at <var>start</var> and place a point there, cutting in two the subpath that it was in, and
similarly cut the line on which <var>end</var> finds itself short at <var>end</var> and place a point there, cutting in two the subpath that <em>it</em> was in,
and then remove all line segments, joins, points, and subpaths that are between <var>start</var> and <var>end</var>.</p>
<p>If <var>start</var> and <var>end</var> are the same point, then this
results in just the line being cut in two and two points being inserted there, with nothing
being removed, unless a join also happens to be at that point, in which case the join must
be removed.</p>
</dd>
</dl>
</li>
<li><p><i>Post-cut</i>: If <var>position</var> is greater than <var>subpath width</var>, then jump to the step labeled <i>convert</i>.</p></li>
<li><p>Increment <var>index</var> by one. If it is equal to the number of entries in
<var>style</var>'s <span>dash list</span>, then let <var>index</var> be
0.</p></li>
<li><p>Return to the step labeled <i>dash on</i>.</p></li>
</ol>
</li>
<!-- STROKING -->
<li>
<p><i>Convert</i>: This is the step that converts the path to a new path that represents its
stroke.</p>
<p>Create a new <span data-x="concept-path">path</span> that describes the edge of the areas
that would be covered if a straight line of length equal to <var>style</var>'s
<code data-x="dom-context-2d-lineWidth">lineWidth</code> was swept along each subpath in <var>path</var> while being kept at an angle such that the line is orthogonal to the path
being swept, replacing each point with the end cap necessary to satisfy <var>style</var>'s <code data-x="dom-context-2d-lineCap">lineCap</code> attribute as
described previously and elaborated below, and replacing each join with the join necessary to
satisfy <var>style</var>'s <code data-x="dom-context-2d-lineJoin">lineJoin</code>
type, as defined below.</p>
<p><strong>Caps</strong>: Each point has a flat edge perpendicular to the direction of the line
coming out of it. This is then augmented according to the value of <var>style</var>'s <code data-x="dom-context-2d-lineCap">lineCap</code>. The "<code
data-x="">butt</code>" value means that no additional line cap is added. The "<code
data-x="">round</code>" value means that a semi-circle with the diameter equal to
<var>style</var>'s <code data-x="dom-context-2d-lineWidth">lineWidth</code> width must
additionally be placed on to the line coming out of each point. The "<code
data-x="">square</code>" value means that a rectangle with the length of <var>style</var>'s <code data-x="dom-context-2d-lineWidth">lineWidth</code> width and the
width of half <var>style</var>'s <code
data-x="dom-context-2d-lineWidth">lineWidth</code> width, placed flat against the edge
perpendicular to the direction of the line coming out of the point, must be added at each
point.</p>
<p>Points with no lines coming out of them must have two caps placed back-to-back as if it was
really two points connected to each other by an infinitesimally short straight line in the
direction of the point's <i>directionality</i> (as defined above).</p>
<p><strong>Joins</strong>: In addition to the point where a join occurs, two additional points
are relevant to each join, one for each line: the two corners found half the line width away
from the join point, one perpendicular to each line, each on the side furthest from the other
line.</p>
<p>A triangle connecting these two opposite corners with a straight line, with the third point
of the triangle being the join point, must be added at all joins. The <code
data-x="dom-context-2d-lineJoin">lineJoin</code> attribute controls whether anything else is
rendered. The three aforementioned values have the following meanings:</p>
<p>The "<code data-x="">bevel</code>" value means that this is all that is rendered at
joins.</p>
<p>The "<code data-x="">round</code>" value means that an arc connecting the two aforementioned
corners of the join, abutting (and not overlapping) the aforementioned triangle, with the
diameter equal to the line width and the origin at the point of the join, must be added at
joins.</p>
<p>The "<code data-x="">miter</code>" value means that a second triangle must (if it can given
the miter length) be added at the join, with one line being the line between the two
aforementioned corners, abutting the first triangle, and the other two being continuations of
the outside edges of the two joining lines, as long as required to intersect without going over
the miter length.</p>
<p>The miter length is the distance from the point where the join occurs to the intersection of
the line edges on the outside of the join. The miter limit ratio is the maximum allowed ratio of
the miter length to half the line width. If the miter length would cause the miter limit ratio
(as set by <var>style</var>'s <code
data-x="dom-context-2d-miterLimit">miterLimit</code> attribute) to be exceeded, then this second
triangle must not be added.</p> <!-- the actual ratio can't possibly be less than 1.0 -->
<!-- here's a nice demo of the miter:
c.clearRect(0, 0, 640, 480);
c.beginPath();
c.moveTo((new Date()/100) % 600, 100);
c.lineTo(300, 300);
c.lineTo(500, 300);
c.lineWidth = 50;
c.miterLimit = 10000;
c.strokeStyle = 'silver'
c.stroke();
c.miterLimit = 0.0001;
c.strokeStyle = 'black'
c.stroke();
c.lineWidth = 1;
c.strokeStyle = 'red'
c.stroke();
-->
<p>The subpaths in the newly created path must be oriented such that for any point, the number
of times a half-infinite straight line drawn from that point crosses a subpath is even if and
only if the number of times a half-infinite straight line drawn from that same point crosses a
subpath going in one direction is equal to the number of times it crosses a subpath going in the
other direction.</p>
</li>
<li><p>Return the newly created path.</p></li>
</ol>
<!--v6: Another request has been for hairline width lines, that remain hairline width with
transform. ack Shaun Morris. -->
</div>
<h6>Text styles</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lang">lang</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lang">lang</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current language setting.</p>
<p>Can be set to a BCP 47 language tag, the empty string, or "<code
data-x="dom-context-2d-lang-inherit">inherit</code>", to change the language used when
resolving fonts. "<code data-x="dom-context-2d-lang-inherit">inherit</code>" takes the language
from the <code>canvas</code> element's language, or the associated <span>document
element</span> when there is no <code>canvas</code> element.</p>
<p>The default is "<code data-x="dom-context-2d-lang-inherit">inherit</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-font">font</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-font">font</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current font settings.</p>
<p>Can be set, to change the font. The syntax is the same as for the CSS <span>'font'</span>
property; values that cannot be parsed as CSS font values are ignored. The default is "10px
sans-serif".</p>
<p>Relative keywords and lengths are computed relative to the font of the <code>canvas</code>
element.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-textAlign">textAlign</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-textAlign">textAlign</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current text alignment settings.</p>
<p>Can be set, to change the alignment. The possible values are and their meanings are given
below. Other values are ignored. The default is "<code data-x="">start</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-textBaseline">textBaseline</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-textBaseline">textBaseline</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current baseline alignment settings.</p>
<p>Can be set, to change the baseline alignment. The possible values and their meanings are
given below. Other values are ignored. The default is "<code
data-x="dom-context-2d-textBaseline-alphabetic">alphabetic</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-direction">direction</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-direction">direction</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current directionality.</p>
<p>Can be set, to change the directionality. The possible values and their meanings are given
below. Other values are ignored. The default is "<code
data-x="dom-context-2d-direction-inherit">inherit</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-letterSpacing">letterSpacing</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-letterSpacing">letterSpacing</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current spacing between characters in the text.</p>
<p>Can be set, to change spacing between characters. Values that cannot be parsed as a CSS
<span><length></span> are ignored. The default is "<code data-x="">0px</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fontKerning">fontKerning</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-fontKerning">fontKerning</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current font kerning settings.</p>
<p>Can be set, to change the font kerning. The possible values and their meanings are given
below. Other values are ignored. The default is "<code
data-x="dom-context-2d-fontKerning-auto">auto</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fontStretch">fontStretch</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-fontStretch">fontStretch</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current font stretch settings.</p>
<p>Can be set, to change the font stretch. The possible values and their meanings are given
below. Other values are ignored. The default is "<code
data-x="dom-context-2d-fontStretch-normal">normal</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current font variant caps settings.</p>
<p>Can be set, to change the font variant caps. The possible values and their meanings are given
below. Other values are ignored. The default is "<code
data-x="dom-context-2d-fontVariantCaps-normal">normal</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-textRendering">textRendering</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-textRendering">textRendering</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current text rendering settings.</p>
<p>Can be set, to change the text rendering. The possible values and their meanings are given
below. Other values are ignored. The default is "<code
data-x="dom-context-2d-textRendering-auto">auto</code>".</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-wordSpacing">wordSpacing</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-wordSpacing">wordSpacing</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current spacing between words in the text.</p>
<p>Can be set, to change spacing between words. Values that cannot be parsed as a CSS
<span><length></span> are ignored. The default is "<code data-x="">0px</code>".</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasTextDrawingStyles</code> interface have attributes
(defined in this section) that control how text is laid out (rasterized or outlined) by the
object. Such objects can also have a <dfn>font style source object</dfn>. For
<code>CanvasRenderingContext2D</code> objects, this is the <code>canvas</code> element given by
the value of the context's <code data-x="dom-context-2d-canvas">canvas</code> attribute. For
<code>OffscreenCanvasRenderingContext2D</code> objects, this is the <span>associated
<code>OffscreenCanvas</code> object</span>.</p>
<p>Font resolution for the <span>font style source object</span> requires a <span>font
source</span>. This is determined for a given <var>object</var> implementing
<code>CanvasTextDrawingStyles</code> by the following steps: <ref>CSSFONTLOAD</ref></p>
<ol>
<li><p>If <var>object</var>'s <span>font style source object</span> is a <code>canvas</code>
element, return the element's <span>node document</span>.</p></li>
<li>
<p>Otherwise, <var>object</var>'s <span>font style source object</span> is an
<code>OffscreenCanvas</code> object:</p>
<ol>
<li><p>Let <var>global</var> be <var>object</var>'s <span>relevant global
object</span>.</p></li>
<li><p>If <var>global</var> is a <code>Window</code> object, then return <var>global</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p><span>Assert</span>: <var>global</var> implements
<code>WorkerGlobalScope</code>.</p></li>
<li><p>Return <var>global</var>.</p></li>
</ol>
</li>
</ol>
<div class="example">
<p>This is an example of font resolution with a regular <code>canvas</code> element with ID <code
data-x="">c1</code>.</p>
<pre><code class="js">const font = new FontFace("MyCanvasFont", "url(mycanvasfont.ttf)");
documents.fonts.add(font);
const context = document.getElementById("c1").getContext("2d");
document.fonts.ready.then(function() {
context.font = "64px MyCanvasFont";
context.fillText("hello", 0, 0);
});</code></pre>
<p>In this example, the canvas will display text using <code data-x="">mycanvasfont.ttf</code> as
its font.</p>
</div>
<div class="example">
<p>This is an example of how font resolution can happen using <code>OffscreenCanvas</code>.
Assuming a <code>canvas</code> element with ID <code data-x="">c2</code> which is transferred to
a worker like so:</p>
<pre><code class="js">const offscreenCanvas = document.getElementById("c2").transferControlToOffscreen();
worker.postMessage(offscreenCanvas, [offscreenCanvas]);</code></pre>
<p>Then, in the worker:</p>
<pre><code class="js">self.onmessage = function(ev) {
const transferredCanvas = ev.data;
const context = transferredCanvas.getContext("2d");
const font = new FontFace("MyFont", "url(myfont.ttf)");
self.fonts.add(font);
self.fonts.ready.then(function() {
context.font = "64px MyFont";
context.fillText("hello", 0, 0);
});
};</code></pre>
<p>In this example, the canvas will display a text using <code data-x="">myfont.ttf</code>.
Notice that the font is only loaded inside the worker, and not in the document context.</p>
</div>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-font">font</code></dfn> IDL attribute, on setting, must be <span
data-x="parse something according to a CSS grammar">parsed as a CSS <'font'> value</span> (but
without supporting property-independent style sheet syntax like 'inherit'), and the resulting font
must be assigned to the context, with the <span>'line-height'</span> component forced to 'normal',
with the <span>'font-size'</span> component converted to <span data-x="'px'">CSS pixels</span>,
and with system fonts being computed to explicit values. If the new value is syntactically
incorrect (including using property-independent style sheet syntax like 'inherit' or 'initial'),
then it must be ignored, without assigning a new font value. <ref>CSS</ref></p>
<p>Font family names must be interpreted in the context of the <span>font style source
object</span> when the font is to be used; any fonts embedded using <code
data-x="">@font-face</code> or loaded using <code>FontFace</code> objects that are visible to the
<span>font style source object</span> must therefore be available once they are loaded. (Each <span>font style source
object</span> has a <span>font source</span>, which determines what fonts are available.) If a font
is used before it is fully loaded, or if the <span>font style source object</span> does not have
that font in scope at the time the font is to be used, then it must be treated as if it was an
unknown font, falling back to another as described by the relevant CSS specifications.
<ref>CSSFONTS</ref> <ref>CSSFONTLOAD</ref></p>
<p>On getting, the <code data-x="dom-context-2d-font">font</code> attribute must return the <span
data-x="serializing a CSS value">serialized form</span> of the current font of the context (with
no <span>'line-height'</span> component). <ref>CSSOM</ref></p>
<div class="example">
<p>For example, after the following statement:</p>
<pre><code class="js">context.font = 'italic 400 12px/2 Unknown Font, sans-serif';</code></pre>
<p>...the expression <code data-x="">context.font</code> would evaluate to the string "<code
data-x="">italic 12px "Unknown Font", sans-serif</code>". The "400"
font-weight doesn't appear because that is the default value. The line-height doesn't appear
because it is forced to "normal", the default value.</p>
</div>
<p>When the object implementing the <code>CanvasTextDrawingStyles</code> interface is created, the
font of the context must be set to 10px sans-serif. When the <span>'font-size'</span> component is
set to lengths using percentages, <span>'em'</span> or <span>'ex'</span> units, or the 'larger' or
'smaller' keywords, these must be interpreted relative to the <span>computed value</span> of the
<span>'font-size'</span> property of the <span>font style source object</span> at the time that
the attribute is set, if it is an element. When the <span>'font-weight'</span> component is set to
the relative values 'bolder' and 'lighter', these must be interpreted relative to the
<span>computed value</span> of the <span>'font-weight'</span> property of the <span>font style
source object</span> at the time that the attribute is set, if it is an element. If the <span
data-x="computed value">computed values</span> are undefined for a particular case (e.g. because
the <span>font style source object</span> is not an element or is not <span>being
rendered</span>), then the relative keywords must be interpreted relative to the normal-weight
10px sans-serif default.</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-textAlign">textAlign</code></dfn> IDL attribute, on getting, must return
the current value. On setting, the current value must be changed to the new value. When the object
implementing the <code>CanvasTextDrawingStyles</code> interface is created, the <code
data-x="dom-context-2d-textAlign">textAlign</code> attribute must initially have the value <code
data-x="dom-context-2d-textAlign-start">start</code>.</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-textBaseline">textBaseline</code></dfn> IDL attribute, on getting, must
return the current value. On setting, the current value must be changed to the new value. When the
object implementing the <code>CanvasTextDrawingStyles</code> interface is created, the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute must initially have the value
<code data-x="dom-context-2d-textBaseline-alphabetic">alphabetic</code>.</p>
<p>Objects that implement the <code>CanvasTextDrawingStyles</code> interface have an associated
<dfn data-x="concept-CanvasTextDrawingStyles-language">language</dfn> value used to localize font
rendering. Valid values are a BCP 47 language tag, the empty string, or "<dfn
data-x="dom-context-2d-lang-inherit">inherit</dfn>" where the language comes from the
<code>canvas</code> element's language, or the associated <span>document element</span> when there
is no <code>canvas</code> element. Initially, the <span
data-x="concept-CanvasTextDrawingStyles-language">language</span> must be "<code
data-x="dom-context-2d-lang-inherit">inherit</code>".</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles" data-x="dom-context-2d-lang"><code
data-x="dom-context-2d-lang">lang</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-CanvasTextDrawingStyles-language">language</span>.</p>
<p>The <code data-x="dom-context-2d-lang">lang</code> setter steps are to set <span>this</span>'s
<span data-x="concept-CanvasTextDrawingStyles-language">language</span> to the given value.</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-direction">direction</code></dfn> IDL attribute, on getting, must return
the current value. On setting, the current value must be changed to the new value. When the object
implementing the <code>CanvasTextDrawingStyles</code> interface is created, the <code
data-x="dom-context-2d-direction">direction</code> attribute must initially have the value "<code
data-x="dom-context-2d-direction-inherit">inherit</code>".</p>
<p>Objects that implement the <code>CanvasTextDrawingStyles</code> interface have attributes that
control the spacing between letters and words. Such objects have associated <dfn
data-x="concept-CanvasTextDrawingStyles-letter-spacing">letter spacing</dfn> and <dfn
data-x="concept-CanvasTextDrawingStyles-word-spacing">word spacing</dfn> values, which are CSS
<span><length></span> values. Initially, both must be the result of <span data-x="parse
something according to a CSS grammar">parsing</span> "<code data-x="">0px</code>" as a CSS
<span><length></span>.</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"
data-x="dom-context-2d-letterSpacing"><code>letterSpacing</code></dfn> getter steps are to return
the <span data-x="serializing a CSS value">serialized form</span> of <span>this</span>'s <span
data-x="concept-CanvasTextDrawingStyles-letter-spacing">letter spacing</span>.</p>
<p>The <code data-x="dom-context-2d-letterSpacing">letterSpacing</code> setter steps are:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span data-x="parse something according to a CSS
grammar">parsing</span> the given value as a CSS <span><length></span>.</p></li>
<li><p>If <var>parsed</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span
data-x="concept-CanvasTextDrawingStyles-letter-spacing">letter spacing</span> to
<var>parsed</var>.</p></li>
</ol>
<p>The <dfn attribute for="CanvasTextDrawingStyles"
data-x="dom-context-2d-wordSpacing"><code>wordSpacing</code></dfn> getter steps are to return the
<span data-x="serializing a CSS value">serialized form</span> of <span>this</span>'s <span
data-x="concept-CanvasTextDrawingStyles-word-spacing">word spacing</span>.</p>
<p>The <code data-x="dom-context-2d-wordSpacing">wordSpacing</code> setter steps are:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span data-x="parse something according to a CSS
grammar">parsing</span> the given value as a CSS <span><length></span>.</p></li>
<li><p>If <var>parsed</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-CanvasTextDrawingStyles-word-spacing">word
spacing</span> to <var>parsed</var>.</p></li>
</ol>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-fontKerning">fontKerning</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code>CanvasTextDrawingStyles</code> interface is created,
the <code data-x="dom-context-2d-fontKerning">fontKerning</code> attribute must
initially have the value "<code data-x="dom-context-2d-fontkerning-auto">auto</code>".</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-fontStretch">fontStretch</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code>CanvasTextDrawingStyles</code> interface is created,
the <code data-x="dom-context-2d-fontStretch">fontStretch</code> attribute must
initially have the value "<code data-x="dom-context-2d-fontStretch-normal">normal</code>".</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code>CanvasTextDrawingStyles</code> interface is created,
the <code data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</code> attribute must
initially have the value "<code data-x="dom-context-2d-fontVariantCaps-normal">normal</code>".</p>
<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-textRendering">textRendering</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code>CanvasTextDrawingStyles</code> interface is created,
the <code data-x="dom-context-2d-textRendering">textRendering</code> attribute must
initially have the value "<code data-x="dom-context-2d-textRendering-auto">auto</code>".</p>
</div>
<p>The <code data-x="dom-context-2d-textAlign">textAlign</code> attribute's allowed keywords are
as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasTextAlign"><code data-x="dom-context-2d-textAlign-start">start</code></dfn>
<dd><p>Align to the start edge of the text (left side in left-to-right text, right side in
right-to-left text).</p></dd>
<dt><dfn enum-value for="CanvasTextAlign"><code data-x="dom-context-2d-textAlign-end">end</code></dfn>
<dd><p>Align to the end edge of the text (right side in left-to-right text, left side in
right-to-left text).</p></dd>
<dt><dfn enum-value for="CanvasTextAlign"><code data-x="dom-context-2d-textAlign-left">left</code></dfn>
<dd><p>Align to the left.</p></dd>
<dt><dfn enum-value for="CanvasTextAlign"><code data-x="dom-context-2d-textAlign-right">right</code></dfn>
<dd><p>Align to the right.</p></dd>
<dt><dfn enum-value for="CanvasTextAlign"><code data-x="dom-context-2d-textAlign-center">center</code></dfn>
<dd><p>Align to the center.</p></dd>
</dl>
<p>The <code data-x="dom-context-2d-textBaseline">textBaseline</code>
attribute's allowed keywords correspond to alignment points in the
font:</p>
<p><img src="/images/baselines.png" width="738" height="300" alt="The em-over baseline is roughly at the top of the glyphs in a font, the hanging baseline is where some glyphs like आ are anchored, the middle is half-way between the em-over and em-under baselines, the alphabetic baseline is where characters like Á, ÿ, f, and Ω are anchored, the ideographic-under baseline is where glyphs like 私 and 達 are anchored, and the em-under baseline is roughly at the bottom of the glyphs in a font. The top and bottom of the bounding box can be far from these baselines, due to glyphs extending far outside em-over and em-under baselines."></p>
<p>The keywords map to these alignment points as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-top">top</code></dfn>
<dd>The <span>em-over baseline</span></dd>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-hanging">hanging</code></dfn>
<dd>The <span>hanging baseline</span></dd>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-middle">middle</code></dfn>
<dd>Halfway between the <span>em-over baseline</span> and the <span>em-under baseline</span></dd>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-alphabetic">alphabetic</code></dfn>
<dd>The <span>alphabetic baseline</span></dd>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-ideographic">ideographic</code></dfn>
<dd>The <span>ideographic-under baseline</span></dd>
<dt><dfn enum-value for="CanvasTextBaseline"><code data-x="dom-context-2d-textBaseline-bottom">bottom</code></dfn>
<dd>The <span>em-under baseline</span></dd>
</dl>
<p>The <code data-x="dom-context-2d-direction">direction</code> attribute's allowed keywords are
as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasDirection"><code data-x="dom-context-2d-direction-ltr">ltr</code></dfn>
<dd><p>Treat input to the <span>text preparation algorithm</span> as left-to-right text.</p></dd>
<dt><dfn enum-value for="CanvasDirection"><code data-x="dom-context-2d-direction-rtl">rtl</code></dfn>
<dd><p>Treat input to the <span>text preparation algorithm</span> as right-to-left text.</p></dd>
<dt><dfn enum-value for="CanvasDirection"><code data-x="dom-context-2d-direction-inherit">inherit</code></dfn>
<dd><p>Use the process in the <span>text preparation algorithm</span> to obtain the text
direction from the <code>canvas</code> element, <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>, or
<span>document element</span>.</p></dd>
</dl>
<p>The <code data-x="dom-context-2d-fontKerning">fontKerning</code> attribute's allowed keywords
are as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasFontKerning"><code data-x="dom-context-2d-fontkerning-auto">auto</code></dfn>
<dd><p>Kerning is applied at the discretion of the user agent.</p></dd>
<dt><dfn enum-value for="CanvasFontKerning"><code data-x="dom-context-2d-fontkerning-normal">normal</code></dfn>
<dd><p>Kerning is applied.</p></dd>
<dt><dfn enum-value for="CanvasFontKerning"><code data-x="dom-context-2d-fontkerning-none">none</code></dfn>
<dd><p>Kerning is not applied.</p></dd>
</dl>
<p>The <code data-x="dom-context-2d-fontStretch">fontStretch</code> attribute's allowed keywords
are as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-ultra-condensed">ultra-condensed</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'ultra-condensed'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-extra-condensed">extra-condensed</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'extra-condensed'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-condensed">condensed</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'condensed'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-semi-condensed">semi-condensed</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'semi-condensed'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-normal">normal</code></dfn>
<dd><p>The default setting, where width of the glyphs is at 100%.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-semi-expanded">semi-expanded</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'semi-expanded'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-expanded">expanded</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'expanded'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-extra-expanded">extra-expanded</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'extra-expanded'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontStretch"><code data-x="dom-context-2d-fontstretch-ultra-expanded">ultra-expanded</code></dfn>
<dd><p>Same as CSS <span>'font-stretch'</span> <span>'ultra-expanded'</span> setting.</p></dd>
</dl>
<p>The <code data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</code> attribute's allowed
keywords are as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-normal">normal</code></dfn>
<dd><p>None of the features listed below are enabled.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-small-caps">small-caps</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'small-caps'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-all-small-caps">all-small-caps</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'all-small-caps'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-petite-caps">petite-caps</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'petite-caps'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-all-petite-caps">all-petite-caps</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'all-petite-caps'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-unicase">unicase</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'unicase'</span> setting.</p></dd>
<dt><dfn enum-value for="CanvasFontVariantCaps"><code data-x="dom-context-2d-fontvariantcaps-titling-caps">titling-caps</code></dfn>
<dd><p>Same as CSS <span>'font-variant-caps'</span> <span>'titling-caps'</span> setting.</p></dd>
</dl>
<p>The <code data-x="dom-context-2d-textRendering">textRendering</code> attribute's allowed
keywords are as follows:</p>
<dl>
<dt><dfn enum-value for="CanvasTextRendering"><code data-x="dom-context-2d-textRendering-auto">auto</code></dfn>
<dd><p>Same as 'auto' in <span>SVG text-rendering</span> property.</p></dd>
<dt><dfn enum-value for="CanvasTextRendering"><code data-x="dom-context-2d-textRendering-optimizeSpeed">optimizeSpeed</code></dfn>
<dd><p>Same as 'optimizeSpeed' in <span>SVG text-rendering</span> property.</p></dd>
<dt><dfn enum-value for="CanvasTextRendering"><code data-x="dom-context-2d-textRendering-optimizeLegibility">optimizeLegibility</code></dfn>
<dd><p>Same as 'optimizeLegibility' in <span>SVG text-rendering</span> property.</p></dd>
<dt><dfn enum-value for="CanvasTextRendering"><code data-x="dom-context-2d-textRendering-geometricPrecision">geometricPrecision</code></dfn>
<dd><p>Same as 'geometricPrecision' in <span>SVG text-rendering</span> property.</p></dd>
</dl>
<p>The <dfn>text preparation algorithm</dfn> is as follows. It takes as input a string <var>text</var>,
a <code>CanvasTextDrawingStyles</code> object <var>target</var>, and an optional length
<var>maxWidth</var>. It returns an array of glyph shapes, each positioned on a common coordinate
space, a <var>physical alignment</var> whose value is one of <i>left</i>, <i>right</i>, and
<i>center</i>, and an <span>inline box</span>. (Most callers of this algorithm ignore the
<var>physical alignment</var> and the <span>inline box</span>.)</p>
<ol>
<li><p>If <var>maxWidth</var> was provided but is less than or equal to zero or equal to NaN,
then return an empty array.</p></li>
<li><p>Replace all <span>ASCII whitespace</span> in <var>text</var> with U+0020 SPACE
characters.</p></li>
<li><p>Let <var>font</var> be the current font of <var>target</var>, as given
by that object's <code data-x="dom-context-2d-font">font</code> attribute.</p></li>
<li><p>Let <var>language</var> be the <var>target</var>'s <span
data-x="concept-CanvasTextDrawingStyles-language">language</span>.</p></li>
<li>
<p>If <var>language</var> is "<code data-x="dom-context-2d-lang-inherit">inherit</code>":</p>
<ol>
<li><p>Let <var>sourceObject</var> be <var>object</var>'s <span>font style source
object</span></p></li>
<li><p>If <var>sourceObject</var> is a <code>canvas</code>
element, then set <var>language</var> to the <var>sourceObject</var>'s
<span data-x="language">language</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Assert: <var>sourceObject</var> is an <code>OffscreenCanvas</code> object.</p></li>
<li><p>Set <var>language</var> to the <var>sourceObject</var>'s
<span data-x="offscreencanvas-inherited-lang">inherited language</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If <var>language</var> is the empty string, then set <var>language</var> to
<span data-x="concept-explicitly-unknown">explicitly unknown</span>.</p></li>
<li>
<p>Apply the appropriate step from the following list to determine the value of
<var>direction</var>:</p>
<dl class="switch">
<dt>If the <var>target</var> object's <code
data-x="dom-context-2d-direction">direction</code> attribute has the value "<code
data-x="dom-context-2d-direction-ltr">ltr</code>"</dt>
<dd>Let <var>direction</var> be '<span data-x="concept-ltr">ltr</span>'.</dd>
<dt>If the <var>target</var> object's <code
data-x="dom-context-2d-direction">direction</code> attribute has the value "<code
data-x="dom-context-2d-direction-rtl">rtl</code>"</dt>
<dd>Let <var>direction</var> be '<span data-x="concept-rtl">rtl</span>'.</dd>
<dt>If the <var>target</var> object's <code
data-x="dom-context-2d-direction">direction</code> attribute has the value "<code
data-x="dom-context-2d-direction-inherit">inherit</code>"</dt>
<dd>
<ol>
<li><p>Let <var>sourceObject</var> be <var>object</var>'s <span>font style source
object</span></p></li>
<li><p>If <var>sourceObject</var> is a <code>canvas</code>
element, then let <var>direction</var> be <var>sourceObject</var>'s
<span data-x="the directionality">directionality</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Assert: <var>sourceObject</var> is an <code>OffscreenCanvas</code> object.</p></li>
<li><p>Let <var>direction</var> be <var>sourceObject</var>'s
<span data-x="offscreencanvas-inherited-direction">inherited direction</span>.</p></li>
</ol>
</li>
</ol>
</dd>
</dl>
</li>
<li>
<p>Form a hypothetical infinitely-wide CSS <span>line box</span> containing a single
<span>inline box</span> containing the text <var>text</var>, with the CSS
<span>content language</span> set to <var>language</var>, and with its CSS properties set as
follows:</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Source</th>
</tr>
</thead>
<tbody>
<tr>
<td><span>'direction'</span></td>
<td><var>direction</var></td>
</tr>
<tr>
<td><span>'font'</span></td>
<td><var>font</var></td>
</tr>
<tr>
<td><span>'font-kerning'</span></td>
<td><var>target</var>'s <code data-x="dom-context-2d-fontKerning">fontKerning</code></td>
</tr>
<tr>
<td><span>'font-stretch'</span></td>
<td><var>target</var>'s <code data-x="dom-context-2d-fontStretch">fontStretch</code></td>
</tr>
<tr>
<td><span>'font-variant-caps'</span></td>
<td><var>target</var>'s <code data-x="dom-context-2d-fontVariantCaps">fontVariantCaps</code></td>
</tr>
<tr>
<td><span>'letter-spacing'</span></td>
<td><var>target</var>'s <span data-x="concept-CanvasTextDrawingStyles-letter-spacing">letter spacing</span></td>
</tr>
<tr>
<td><span>SVG text-rendering</span></td>
<td><var>target</var>'s <code data-x="dom-context-2d-textRendering">textRendering</code></td>
</tr>
<tr>
<td><span>'white-space'</span></td>
<td>'pre'</td>
</tr>
<tr>
<td><span>'word-spacing'</span></td>
<td><var>target</var>'s <span data-x="concept-CanvasTextDrawingStyles-word-spacing">word spacing</span></td>
</tr>
</tbody>
</table>
<p>and with all other properties set to their initial values.</p>
</li>
<!-- if you insert a step here, make sure to adjust the next step's final words -->
<li><p>If <var>maxWidth</var> was provided and the hypothetical width of the
<span>inline box</span> in the hypothetical <span>line box</span> is greater than
<var>maxWidth</var> <span data-x="'px'">CSS pixels</span>, then change <var>font</var> to have a
more condensed font (if one is available or if a reasonably readable one can be synthesized by
applying a horizontal scale factor to the font) or a smaller font, and return to the previous
step.</p></li>
<li>
<p>The <var>anchor point</var> is a point on the <span>inline box</span>, and the <var>physical
alignment</var> is one of the values <i>left</i>, <i>right</i>, and <i>center</i>. These
variables are determined by the <code data-x="dom-context-2d-textAlign">textAlign</code> and
<code data-x="dom-context-2d-textBaseline">textBaseline</code> values as follows:</p>
<p>Horizontal position:</p>
<dl>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-left">left</code></dt>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-start">start</code> and <var>direction</var> is
'ltr'</dt>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-end">end</code> and <var>direction</var> is 'rtl'</dt>
<dd>Let the <var>anchor point</var>'s horizontal position be the left edge of the
<span>inline box</span>, and let <var>physical alignment</var> be <i>left</i>.</dd>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-right">right</code></dt>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-end">end</code> and <var>direction</var> is 'ltr'</dt>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-start">start</code> and <var>direction</var> is
'rtl'</dt>
<dd>Let the <var>anchor point</var>'s horizontal position be the right edge of the
<span>inline box</span>, and let <var>physical alignment</var> be <i>right</i>.</dd>
<dt>If <code data-x="dom-context-2d-textAlign">textAlign</code> is <code
data-x="dom-context-2d-textAlign-center">center</code></dt>
<dd>Let the <var>anchor point</var>'s horizontal position be half way between the left
and right edges of the <span>inline box</span>, and let <var>physical alignment</var> be
<i>center</i>.</dd>
</dl>
<p>Vertical position:</p>
<dl>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-top">top</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be the top of the em box of
the <span>first available font</span> of the <span>inline box</span>.</dd>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-hanging">hanging</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be the <span>hanging baseline</span> of
the <span>first available font</span> of the <span>inline box</span>.</dd>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-middle">middle</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be half way between the bottom
and the top of the em box of the <span>first available font</span> of the <span>inline
box</span>.</dd>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-alphabetic">alphabetic</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be the <span>alphabetic baseline</span>
of the <span>first available font</span> of the <span>inline box</span>.</dd>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-ideographic">ideographic</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be the <span>ideographic-under
baseline</span> of the <span>first available font</span> of the <span>inline box</span>.</dd>
<dt>If <code data-x="dom-context-2d-textBaseline">textBaseline</code> is <code
data-x="dom-context-2d-textBaseline-bottom">bottom</code></dt>
<dd>Let the <var>anchor point</var>'s vertical position be the bottom of the em box of
the <span>first available font</span> of the <span>inline box</span>.</dd>
</dl>
</li>
<li>
<p>Let <var>result</var> be an array constructed by iterating over each glyph in the
<span>inline box</span> from left to right (if any), adding to the array, for each glyph, the
shape of the glyph as it is in the <span>inline box</span>, positioned on a coordinate space
using <span data-x="'px'">CSS pixels</span> with its origin at the <var>anchor
point</var>.</p>
</li>
<li><p>Return <var>result</var>, <var>physical alignment</var>, and the inline
box.</p></li>
</ol>
<h6>Building paths</h6>
<p>Objects that implement the <code>CanvasPath</code> interface have a <span
data-x="concept-path">path</span>. A <dfn data-x="concept-path">path</dfn> has a list of zero or
more subpaths. Each subpath consists of a list of one or more points, connected by straight or
curved <dfn>line segments</dfn>, and a flag indicating whether the subpath is closed or not. A
closed subpath is one where the last point of the subpath is connected to the first point of the
subpath by a straight line. Subpaths with only one point are ignored when painting the path.</p>
<p><span data-x="concept-path">Paths</span> have a <dfn>need new subpath</dfn> flag. When this
flag is set, certain APIs create a new subpath rather than extending the previous one. When a
<span data-x="concept-path">path</span> is created, its <span>need new subpath</span> flag must be
set.</p>
<p>When an object implementing the <code>CanvasPath</code> interface is created, its <span
data-x="concept-path">path</span> must be initialized to zero subpaths.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-moveTo">moveTo</span>(<var>x</var>, <var>y</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-moveTo">moveTo</span>(<var>x</var>, <var>y</var>)</code></dt>
<dd><p>Creates a new subpath with the given point.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-closePath">closePath</span>()</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-closePath">closePath</span>()</code></dt>
<dd>
<p>Marks the current subpath as closed, and starts a new subpath with a point the same as the
start and end of the newly closed subpath.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lineTo">lineTo</span>(<var>x</var>, <var>y</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-lineTo">lineTo</span>(<var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Adds the given point to the current subpath, connected to the previous one by a straight
line.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-quadraticCurveTo">quadraticCurveTo</span>(<var>cpx</var>, <var>cpy</var>, <var>x</var>, <var>y</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-quadraticCurveTo">quadraticCurveTo</span>(<var>cpx</var>, <var>cpy</var>, <var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Adds the given point to the current subpath, connected to the previous one by a quadratic
Bézier curve with the given control point.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-bezierCurveTo">bezierCurveTo</span>(<var>cp1x</var>, <var>cp1y</var>, <var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-bezierCurveTo">bezierCurveTo</span>(<var>cp1x</var>, <var>cp1y</var>, <var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Adds the given point to the current subpath, connected to the previous one by a cubic Bézier
curve with the given control points.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-arcTo">arcTo</span>(<var>x1</var>, <var>y1</var>, <var>x2</var>, <var>y2</var>, <var>radius</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-arcTo">arcTo</span>(<var>x1</var>, <var>y1</var>, <var>x2</var>, <var>y2</var>, <var>radius</var>)</code></dt>
<dd>
<p>Adds an arc with the given control points and radius to the current subpath, connected to the
previous point by a straight line.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the given
radius is negative.</p>
<figure class="diagrams">
<!-- if anyone wants to try writing alternative text for these,
be my guest. I can't work out how to describe them. -->
<img src="/images/arcTo1.png" alt="" width="357" height="254">
<img src="/images/arcTo2.png" alt="" width="468" height="310">
<img src="/images/arcTo3.png" alt="" width="513" height="233">
</figure>
<!--
c.clearRect(0, 0, 640, 480);
c.save();
try {
var x0 = 150;
var y0 = 100;
var x1 = 375;
var y1 = 100;
var x2 = x1;
var y2 = 250;
var r = 50;
var bottom = 210;
var center = 100;
var fontSize = 16;
var margin = 50;
var dotHalfSize = 5;
// (also update the label positions at the bottom)
// ========
function extendLine(xa,ya,xb,yb) {
var dx = xb-xa;
var dy = yb-ya;
var theta = Math.atan2(dx,dy);
var extX = margin * Math.sin(theta);
var extY = margin * Math.cos(theta);
c.beginPath();
c.moveTo(xa-extX,ya-extY);
c.lineTo(xb+extX,yb+extY);
c.stroke();
}
function dot(x,y,s) {
c.beginPath();
c.arc(x,y,dotHalfSize,0,Math.PI*2);
c.fill();
c.textAlign = 'left';
c.textBaseline = 'top';
c.fillText(s,x+dotHalfSize,y);
}
c.font = fontSize + 'px Gill Sans';
c.fillStyle = 'black';
c.lineWidth = 1;
c.strokeStyle = 'red';
extendLine(x0,y0,x1,y1);
extendLine(x1,y1,x2,y2);
c.lineWidth = 1;
c.strokeStyle = 'silver';
c.beginPath();
c.moveTo(x0,y0);
// based on https://lists.freedesktop.org/archives/cairo/2005-August/004801.html
var angle0, angle1, angle2, angled;
var xc, yc, dc;
angle0 = Math.atan2(y0 - y1, x0 - x1);
angle2 = Math.atan2(y2 - y1, x2 - x1);
angle1 = (angle0 + angle2) / 2;
angled = angle2 - angle0;
if (angled > Math.PI || (angled < 0 && angled > -Math.PI)) {
angle1 += Math.PI;
angled = 2 * Math.PI - angled;
angle0 += Math.PI*2;
angle2 -= Math.PI*2;
} else {
angle0 -= Math.PI*2;
angle2 += Math.PI*2;
}
dc = r / Math.sin (angled / 2);
yc = Math.sin(angle1);
xc = Math.cos(angle1);
xc = x1 + xc * dc;
yc = y1 + yc * dc;
c.lineWidth = 1;
c.strokeStyle = 'blue';
c.beginPath();
c.moveTo(xc,yc);
c.arc(xc,yc,r, Math.PI*3/4, Math.PI*(3/4));
c.stroke();
c.beginPath();
c.strokeStyle = 'silver';
c.arc(xc,yc,r, Math.PI*3/4,Math.PI*(2+3/4));
c.stroke();
c.save();
try {
c.translate(xc, yc);
c.rotate(-Math.PI/4);
c.textAlign = 'center';
c.textBaseline = 'top';
c.fillText("radius", -r/2, 0);
} finally {
c.restore();
}
c.lineWidth = 15;
c.lineCap = 'round';
c.strokeStyle = 'rgba(20,200,40,0.8)';
c.beginPath();
c.moveTo(x0,y0);
c.arcTo(x1,y1,x2,y2,r);
c.stroke();
dot(x0,y0, "x\u2080,y\u2080");
dot(x1,y1, "x\u2081,y\u2081");
dot(x2,y2, "x\u2082,y\u2082");
dot(xc,yc, '');
c.textAlign = 'left';
c.textBaseline = 'alphabetic';
var L = 0;
function print(s) {
c.fillText(s, center, bottom+L*fontSize*1.3);
L += 1;
}
print('// the thick line corresponds to:');
print('context.moveTo(x\u2080, y\u2080)');
print('context.arcTo(x\u2081, y\u2081, x\u2082, y\u2082, radius)');
print('context.stroke()');
c.fillStyle = 'green';
c.fillText("\u25be initial line", 160, 70);
c.textAlign = 'right';
c.fillText("arc \u25b8", x1-25, 115);
} finally {
c.restore();
}
-->
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-arc">arc</span>(<var>x</var>, <var>y</var>, <var>radius</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>counterclockwise</var> ])</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-arc">arc</span>(<var>x</var>, <var>y</var>, <var>radius</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>counterclockwise</var> ])</code></dt>
<dd>
<p>Adds points to the subpath such that the arc described by the circumference of the circle
described by the arguments, starting at the given start angle and ending at the given end angle,
going in the given direction (defaulting to clockwise), is added to the path, connected to the
previous point by a straight line.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the given
radius is negative.</p>
<figure class="diagrams">
<!-- if anyone wants to try writing alternative text for this, be my guest. I can't work out how to describe it. -->
<img src="/images/arc1.png" alt="" width="590" height="255">
</figure>
<!--
c.clearRect(0, 0, 640, 480);
c.save();
try {
var x0 = 50;
var y0 = 200;
var x = 255;
var y = 150;
var radius = 100;
var startAngle = 2.0;
var endAngle = 5.7;
var direction = false;
var bottom = 110;
var center = 380;
var fontSize = 16;
var margin = 50;
var dotHalfSize = 5;
var arrowHead = 5;
// (also update the label positions at the bottom)
// ========
function dot(x,y,s) {
c.beginPath();
c.arc(x,y,dotHalfSize,0,Math.PI*2);
c.fill();
c.textAlign = 'center';
c.textBaseline = 'top';
c.fillText(s,x,y+dotHalfSize);
}
function arc(x, y, r, sA, eA, d, fr, s) {
c.lineWidth = 1;
c.strokeStyle = 'red';
c.beginPath();
c.arc(x, y, r, sA, eA, d);
c.stroke();
c.save();
c.translate(x, y);
c.rotate(eA);
c.beginPath();
c.moveTo(r-arrowHead, d?arrowHead:-arrowHead);
c.lineTo(r, 0);
c.lineTo(r+arrowHead, d?arrowHead:-arrowHead);
c.stroke();
c.strokeStyle = 'silver';
c.beginPath();
c.moveTo(0, 0);
c.lineTo(fr, 0);
c.stroke();
c.restore();
c.fillStyle = 'black';
if (eA<Math.PI) {
c.save();
c.translate(x, y);
c.rotate(sA+(eA-sA)/2-Math.PI/2);
c.translate(0, r);
c.rotate(-(sA+(eA-sA)/2-Math.PI/2));
c.beginPath();
c.textAlign = 'center';
c.textBaseline = 'bottom';
c.fillText(s + ' ',0,0);
c.restore();
} else {
c.save();
c.beginPath();
c.textAlign = 'left';
c.textBaseline = 'middle';
c.fillText(' ' + s,x-r,y);
c.restore();
}
}
function radial(x, y, length, rotation, s) {
c.lineWidth = 1;
c.strokeStyle = 'blue';
c.save();
c.translate(x, y);
c.rotate(rotation);
c.beginPath();
c.moveTo(0, 0);
c.lineTo(length, 0);
c.stroke();
c.textAlign = 'center';
c.textBaseline = 'bottom';
c.fillStyle = 'black';
c.fillText(s,length/2,0);
c.restore();
}
c.font = fontSize + 'px Gill Sans';
// construction lines
c.lineWidth = 1;
c.strokeStyle = 'silver';
// circle
c.beginPath();
c.arc(x, y, radius, 0, 2*Math.PI);
c.stroke();
// angles
arc(x, y, radius/10+2*radius/3, 0, startAngle, false, radius, '\u03B1');
arc(x, y, radius/10+radius/3, 0, endAngle, false, radius, '\u03B2');
// radii
radial(x, y, radius, 0, 'radius');
// the line
c.lineWidth = 15;
c.lineCap = 'round';
c.strokeStyle = 'rgba(20,200,40,0.8)';
c.beginPath();
c.moveTo(x0,y0);
c.arc(x,y,radius,startAngle,endAngle,direction);
c.stroke();
dot(x0,y0, "x\u2080,y\u2080");
dot(x,y, "x,y");
c.textAlign = 'left';
c.textBaseline = 'alphabetic';
var L = 0;
function print(s) {
c.fillText(s, center, bottom+L*fontSize*1.3);
L += 1;
}
print('// the thick line corresponds to:');
print('context.moveTo(x\u2080, y\u2080)');
print('context.arc(x, y, radius, \u03B1, \u03B2)');
print('context.stroke()');
c.fillStyle = 'green';
c.textBaseline = 'top';
c.fillText("initial line \u25b4", x0+20, y0+fontSize*2);
c.textAlign = 'right';
c.textBaseline = 'middle';
c.fillText("arc \u25b8", x-radius-15, y);
} finally {
c.restore();
}
-->
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-ellipse">ellipse</span>(<var>x</var>, <var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>counterclockwise</var>])</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-ellipse">ellipse</span>(<var>x</var>, <var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>counterclockwise</var>])</code></dt>
<dd>
<p>Adds points to the subpath such that the arc described by the circumference of the ellipse
described by the arguments, starting at the given start angle and ending at the given end angle,
going in the given direction (defaulting to clockwise), is added to the path, connected to the
previous point by a straight line.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the given
radius is negative.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-rect">rect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-rect">rect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</code></dt>
<dd><p>Adds a new closed subpath to the path, representing the given rectangle.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-roundRect">roundRect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>, <var>radii</var>)</code></dt>
<dt><code data-x=""><var>path</var>.<span data-x="dom-context-2d-roundRect">roundRect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>, <var>radii</var>)</code></dt>
<dd>
<p>Adds a new closed subpath to the path representing the given rounded rectangle.
<var>radii</var> is either a list of radii or a single radius representing the corners of the
rectangle in pixels. If a list is provided, the number and order of these radii function in the
same way as the CSS <span>'border-radius'</span> property. A single radius behaves the same way
as a list with a single element.</p>
<p>If <var>w</var> and <var>h</var> are both greater than or equal to 0, or if both are smaller
than 0, then the path is drawn clockwise. Otherwise, it is drawn counterclockwise.</p>
<p>When <var>w</var> is negative, the rounded rectangle is flipped horizontally, which means
that the radius values that normally apply to the left corners are used on the right and vice
versa. Similarly, when <var>h</var> is negative, the rounded rect is flipped vertically.</p>
<p>When a value <var>r</var> in <var>radii</var> is a number, the corresponding corner(s) are
drawn as circular arcs of radius <var>r</var>.</p>
<p>When a value <var>r</var> in <var>radii</var> is an object with <code data-x="">{ x, y
}</code> properties, the corresponding corner(s) are drawn as elliptical arcs whose <var>x</var>
and <var>y</var> radii are equal to <var>r.x</var> and <var>r.y</var>, respectively.</p>
<p>When the sum of the <var>radii</var> of two corners of the same edge is greater than the
length of the edge, all the <var>radii</var> of the rounded rectangle are scaled by a factor of
length / (<var>r1</var> + <var>r2</var>). If multiple edges have this property, the scale factor
of the edge with the smallest scale factor is used. This is consistent with CSS behavior.</p>
<p>Throws a <code data-x="js-RangeError">RangeError</code> if <var>radii</var> is a list whose
size is not one, two, three, or four.</p>
<p>Throws a <code data-x="js-RangeError">RangeError</code> if a value in <var>radii</var> is a
negative number, or is an <code data-x="">{ x, y }</code> object whose <code data-x="">x</code>
or <code data-x="">y</code> properties are negative numbers.</p>
<!-- Consider adding this useful information to all the methods which behave this way: -->
<!--
<p>If any of <var>x</var>, <var>y</var>, <var>width</var> or <var>height</var> are non-finite
numbers, or if a value in <var>radii</var> is a non-finite number, or if a value in
<var>radii</var> is an <code data-x="">{ x, y }</code> object whose <code data-x="">x</code> or
<code data-x="">y</code> properties are non-finite numbers, then the method aborts without
throwing an exception and without adding anything to the current path.</p>
-->
</dd>
</dl>
<div w-nodev>
<p>The following methods allow authors to manipulate the <span data-x="concept-path">paths</span>
of objects implementing the <code>CanvasPath</code> interface.</p>
<p>For objects implementing the <code>CanvasDrawPath</code> and <code>CanvasTransform</code>
interfaces, the points passed to the methods, and the resulting lines added to <span>current
default path</span> by these methods, must be transformed according to the <span
data-x="dom-context-2d-transformation">current transformation matrix</span> before being added to
the path.</p>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-moveTo">moveTo(<var>x</var>,
<var>y</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If either of the arguments are infinite or NaN, then return.</p></li>
<li><p>Create a new subpath with the specified point as its first (and only) point.</p></li>
</ol>
<p>When the user agent is to <dfn>ensure there is a subpath</dfn> for a coordinate (<var>x</var>,
<var>y</var>) on a <span data-x="concept-path">path</span>, the user agent must check to see if
the <span data-x="concept-path">path</span> has its <span>need new subpath</span> flag set. If it
does, then the user agent must create a new subpath with the point (<var>x</var>, <var>y</var>) as
its first (and only) point, as if the <code data-x="dom-context-2d-moveTo">moveTo()</code> method
had been called, and must then unset the <span data-x="concept-path">path</span>'s <span>need new
subpath</span> flag.</p>
<p>The <dfn method for="CanvasPath"><code
data-x="dom-context-2d-closePath">closePath()</code></dfn> method, when invoked, must do nothing
if the object's path has no subpaths. Otherwise, it must mark the last subpath as closed, create a
new subpath whose first point is the same as the previous subpath's first point, and finally add
this new subpath to the path.</p>
<p class="note">If the last subpath had more than one point in its list of points, then this is
equivalent to adding a straight line connecting the last point back to the first point of the last
subpath, thus "closing" the subpath.</p>
<hr>
<p>New points and the lines connecting them are added to subpaths using the methods described
below. In all cases, the methods only modify the last subpath in the object's path.</p>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-lineTo">lineTo(<var>x</var>,
<var>y</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If either of the arguments are infinite or NaN, then return.</p></li>
<li><p>If the object's path has no subpaths, then <span>ensure there is a subpath</span> for
<span data-x="">(<var>x</var>, <var>y</var>)</span>.</p></li>
<li><p>Otherwise, connect the last point in the subpath to the given point (<var>x</var>,
<var>y</var>) using a straight line, and then add the given point (<var>x</var>, <var>y</var>) to
the subpath.</p></li>
</ol>
<p>The <dfn method for="CanvasPath"><code
data-x="dom-context-2d-quadraticCurveTo">quadraticCurveTo(<var>cpx</var>, <var>cpy</var>,
<var>x</var>, <var>y</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p><span>Ensure there is a subpath</span> for <span data-x="">(<var>cpx</var>,
<var>cpy</var>)</span></p></li>
<li><p>Connect the last point in the subpath to the given point (<var>x</var>, <var>y</var>)
using a quadratic Bézier curve with control point (<var>cpx</var>, <var>cpy</var>).
<ref>BEZIER</ref></p></li>
<li><p>Add the given point (<var>x</var>, <var>y</var>) to the subpath.</p></li>
</ol>
<p>The <dfn method for="CanvasPath"><code
data-x="dom-context-2d-bezierCurveTo">bezierCurveTo(<var>cp1x</var>, <var>cp1y</var>,
<var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</code></dfn> method, when invoked,
must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p><span>Ensure there is a subpath</span> for <span data-x="">(<var>cp1x</var>,
<var>cp1y</var>)</span>.</p></li>
<li><p>Connect the last point in the subpath to the given point (<var>x</var>, <var>y</var>)
using a cubic Bézier curve with control points (<var>cp1x</var>, <var>cp1y</var>) and
(<var>cp2x</var>, <var>cp2y</var>). <ref>BEZIER</ref></p></li>
<li><p>Add the point (<var>x</var>, <var>y</var>) to the subpath.</p></li>
</ol>
<hr>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-arcTo">arcTo(<var>x1</var>,
<var>y1</var>, <var>x2</var>, <var>y2</var>, <var>radius</var>)</code></dfn> method, when invoked,
must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p><span>Ensure there is a subpath</span> for <span data-x="">(<var>x1</var>,
<var>y1</var>)</span>.</p></li>
<li><p>If <var>radius</var> is negative, then throw an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let the point (<var>x0</var>, <var>y0</var>) be the last point in the subpath, transformed
by the inverse of the <span data-x="dom-context-2d-transformation">current transformation
matrix</span> (so that it is in the same coordinate system as the points passed to the
method).</p></li>
<li><p>If the point (<var>x0</var>, <var>y0</var>) is equal to the point (<var>x1</var>,
<var>y1</var>), or if the point (<var>x1</var>, <var>y1</var>) is equal to the point
(<var>x2</var>, <var>y2</var>), or if <var>radius</var> is zero, then add the point
(<var>x1</var>, <var>y1</var>) to the subpath, and connect that point to the previous point
(<var>x0</var>, <var>y0</var>) by a straight line.</p></li>
<li><p>Otherwise, if the points (<var>x0</var>, <var>y0</var>), (<var>x1</var>, <var>y1</var>),
and (<var>x2</var>, <var>y2</var>) all lie on a single straight line, then add the point
(<var>x1</var>, <var>y1</var>) to the subpath, and connect that point to the previous point
(<var>x0</var>, <var>y0</var>) by a straight line.</p></li>
<li><p>Otherwise, let <var>The Arc</var> be the shortest arc given by circumference of the circle
that has radius <var>radius</var>, and that has one point tangent to the half-infinite line that
crosses the point (<var>x0</var>, <var>y0</var>) and ends at the point (<var>x1</var>,
<var>y1</var>), and that has a different point tangent to the half-infinite line that ends at the
point (<var>x1</var>, <var>y1</var>) and crosses the point (<var>x2</var>, <var>y2</var>). The
points at which this circle touches these two lines are called the start and end tangent points
respectively. Connect the point (<var>x0</var>, <var>y0</var>) to the start tangent point by a
straight line, adding the start tangent point to the subpath, and then connect the start tangent
point to the end tangent point by <var>The Arc</var>, adding the end tangent point to the
subpath.</p></li>
</ol>
<hr>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-arc">arc(<var>x</var>,
<var>y</var>, <var>radius</var>, <var>startAngle</var>, <var>endAngle</var>,
<var>counterclockwise</var>)</code></dfn> method, when invoked, must run the <span>ellipse method
steps</span> with this, <var>x</var>, <var>y</var>, <var>radius</var>, <var>radius</var>, 0,
<var>startAngle</var>, <var>endAngle</var>, and <var>counterclockwise</var>.</p>
<p class="note">This makes it equivalent to <code data-x="dom-context-2d-ellipse">ellipse()</code>
except that both radii are equal and <var>rotation</var> is 0.</p>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-ellipse">ellipse(<var>x</var>,
<var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>,
<var>endAngle</var>, <var>counterclockwise</var>)</code></dfn> method, when invoked, must run the
<span>ellipse method steps</span> with this, <var>x</var>, <var>y</var>, <var>radiusX</var>,
<var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var>, and
<var>counterclockwise</var>.</p>
<p>The <dfn>determine the point on an ellipse steps</dfn>, given <var>ellipse</var>, and
<var>angle</var>, are:</p>
<ol>
<li><p>Let <var>eccentricCircle</var> be the circle that shares its origin with
<var>ellipse</var>, with a radius equal to the semi-major axis of <var>ellipse</var>.</p></li>
<li><p>Let <var>outerPoint</var> be the point on <var>eccentricCircle</var>'s circumference at
<var>angle</var> measured in radians clockwise from <var>ellipse</var>'s semi-major
axis.</p></li>
<li><p>Let <var>chord</var> be the line perpendicular to <var>ellipse</var>'s major axis between
this axis and <var>outerPoint</var>.</p></li>
<li><p>Return the point on <var>chord</var> that crosses <var>ellipse</var>'s
circumference.</p></li>
</ol>
<p>The <dfn>ellipse method steps</dfn>, given <var>canvasPath</var>, <var>x</var>, <var>y</var>,
<var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>,
<var>endAngle</var>, and <var>counterclockwise</var>, are:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>If either <var>radiusX</var> or <var>radiusY</var> are negative, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>canvasPath</var>'s path has any subpaths, then add a straight line from the last
point in the subpath to the start point of the arc.</p></li>
<li>
<p>Add the start and end points of the arc to the subpath, and connect them with an arc. The
arc and its start and end points are defined as follows:</p>
<p>Consider an ellipse that has its origin at (<var>x</var>, <var>y</var>), that has a
major-axis radius <var>radiusX</var> and a minor-axis radius <var>radiusY</var>, and that is
rotated about its origin such that its semi-major axis is inclined <var>rotation</var> radians
clockwise from the x-axis.</p>
<p>If <var>counterclockwise</var> is false and <span data-x=""><var>endAngle</var> −
<var>startAngle</var></span> is greater than or equal to <span data-x="">2π</span>, or, if
<var>counterclockwise</var> is <em>true</em> and <span data-x=""><var>startAngle</var> −
<var>endAngle</var></span> is greater than or equal to <span data-x="">2π</span>, then the
arc is the whole circumference of this ellipse, and both the start point and the end point are
the result of running the <span>determine the point on an ellipse steps</span> given this
ellipse and <var>startAngle</var>.</p>
<p>Otherwise, the start point is the result of running the <span>determine the point on an
ellipse steps</span> given this ellipse and <var>startAngle</var>, the end point is the result
of running the <span>determine the point on an ellipse steps</span> given this ellipse and
<var>endAngle</var>, and the arc is the path along the circumference of this ellipse from the
start point to the end point, going counterclockwise if <var>counterclockwise</var> is true,
and clockwise otherwise. Since the points are on the ellipse, as opposed to being simply angles
from zero, the arc can never cover an angle greater than <span data-x="">2π</span>
radians.</p>
<p class="note">Even if the arc covers the entire circumference of the ellipse and there are no
other points in the subpath, the path is not closed unless the <code
data-x="dom-context-2d-closePath">closePath()</code> method is appropriately invoked.</p>
</li>
</ol>
<hr>
<p>The <dfn method for="CanvasPath"><code data-x="dom-context-2d-rect">rect(<var>x</var>,
<var>y</var>, <var>w</var>, <var>h</var>)</code></dfn> method, when invoked, must run these
steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>Create a new subpath containing just the four points (<var>x</var>, <var>y</var>),
(<var>x</var>+<var>w</var>, <var>y</var>), (<var>x</var>+<var>w</var>,
<var>y</var>+<var>h</var>), (<var>x</var>, <var>y</var>+<var>h</var>), in that order, with those
four points connected by straight lines.</p></li>
<li><p>Mark the subpath as closed.</p></li>
<li><p>Create a new subpath with the point (<var>x</var>, <var>y</var>) as the only point in the
subpath.</p></li>
</ol>
<p>The <dfn method for="CanvasPath"><code
data-x="dom-context-2d-roundRect">roundRect(<var>x</var>, <var>y</var>, <var>w</var>,
<var>h</var>, <var>radii</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If any of <var>x</var>, <var>y</var>, <var>w</var>, or <var>h</var> are infinite or NaN,
then return.</p></li>
<li><p>If <var>radii</var> is an <code data-x="idl-unrestricted-double">unrestricted
double</code> or <code>DOMPointInit</code>, then set <var>radii</var> to « <var>radii</var>
».</p></li>
<li><p>If <var>radii</var> is not a list of size one, two, three, or four, then throw a <code
data-x="js-RangeError">RangeError</code>.</p></li>
<li><p>Let <var>normalizedRadii</var> be an empty list.</p></li>
<li>
<p>For each <var>radius</var> of <var>radii</var>:</p>
<ol>
<li>
<p>If <var>radius</var> is a <code>DOMPointInit</code>:</p>
<ol>
<li><p>If <var>radius</var>["<code data-x="DOMPointInit-x">x</code>"] or
<var>radius</var>["<code data-x="DOMPointInit-y">y</code>"] is infinite or NaN, then
return.</p></li>
<li><p>If <var>radius</var>["<code data-x="DOMPointInit-x">x</code>"] or
<var>radius</var>["<code data-x="DOMPointInit-y">y</code>"] is negative, then throw a <code
data-x="js-RangeError">RangeError</code>.</p></li>
<li><p>Otherwise, append <var>radius</var> to <var>normalizedRadii</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>radius</var> is a <code data-x="idl-unrestricted-double">unrestricted
double</code>:</p>
<ol>
<li><p>If <var>radius</var> is infinite or NaN, then return.</p></li>
<li><p>If <var>radius</var> is negative, then throw a <code
data-x="js-RangeError">RangeError</code>.</p></li>
<li><p>Otherwise, append «[ "<code data-x="DOMPointInit-x">x</code>" → <var>radius</var>,
"<code data-x="DOMPointInit-x">y</code>" → <var>radius</var> ]» to
<var>normalizedRadii</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>upperLeft</var>, <var>upperRight</var>, <var>lowerRight</var>, and
<var>lowerLeft</var> be null.</p></li>
<li><p>If <var>normalizedRadii</var>'s size is 4, then set <var>upperLeft</var> to
<var>normalizedRadii</var>[0], set <var>upperRight</var> to <var>normalizedRadii</var>[1], set
<var>lowerRight</var> to <var>normalizedRadii</var>[2], and set <var>lowerLeft</var> to
<var>normalizedRadii</var>[3].</p></li>
<li><p>If <var>normalizedRadii</var>'s size is 3, then set <var>upperLeft</var> to
<var>normalizedRadii</var>[0], set <var>upperRight</var> and <var>lowerLeft</var> to
<var>normalizedRadii</var>[1], and set <var>lowerRight</var> to
<var>normalizedRadii</var>[2].</p></li>
<li><p>If <var>normalizedRadii</var>'s size is 2, then set <var>upperLeft</var> and
<var>lowerRight</var> to <var>normalizedRadii</var>[0] and set <var>upperRight</var> and
<var>lowerLeft</var> to <var>normalizedRadii</var>[1].</p></li>
<li><p>If <var>normalizedRadii</var>'s size is 1, then set <var>upperLeft</var>,
<var>upperRight</var>, <var>lowerRight</var>, and <var>lowerLeft</var> to
<var>normalizedRadii</var>[0].</p></li>
<li>
<p>Corner curves must not overlap. Scale all radii to prevent this:</p>
<ol>
<li><p>Let <var>top</var> be <var>upperLeft</var>["<code data-x="DOMPointInit-x">x</code>"] +
<var>upperRight</var>["<code data-x="DOMPointInit-x">x</code>"].</p></li>
<li><p>Let <var>right</var> be <var>upperRight</var>["<code
data-x="DOMPointInit-y">y</code>"] + <var>lowerRight</var>["<code
data-x="DOMPointInit-y">y</code>"].</p></li>
<li><p>Let <var>bottom</var> be <var>lowerRight</var>["<code
data-x="DOMPointInit-x">x</code>"] + <var>lowerLeft</var>["<code
data-x="DOMPointInit-x">x</code>"].</p></li>
<li><p>Let <var>left</var> be <var>upperLeft</var>["<code data-x="DOMPointInit-y">y</code>"]
+ <var>lowerLeft</var>["<code data-x="DOMPointInit-y">y</code>"].</p></li>
<li><p>Let <var>scale</var> be the minimum value of the ratios <var>w</var> / <var>top</var>,
<var>h</var> / <var>right</var>, <var>w</var> / <var>bottom</var>, <var>h</var> /
<var>left</var>.</p></li>
<li><p>If <var>scale</var> is less than 1, then set the <code data-x="DOMPointInit-x">x</code>
and <code data-x="DOMPointInit-y">y</code> members of <var>upperLeft</var>,
<var>upperRight</var>, <var>lowerLeft</var>, and <var>lowerRight</var> to their current values
multiplied by <var>scale</var>.</p></li>
</ol>
</li>
<li>
<p>Create a new subpath:</p>
<ol>
<li><p>Move to the point (<var>x</var> + <var>upperLeft</var>["<code
data-x="DOMPointInit-x">x</code>"], <var>y</var>).</p></li>
<li><p>Draw a straight line to the point (<var>x</var> + <var>w</var> −
<var>upperRight</var>["<code data-x="DOMPointInit-x">x</code>"], <var>y</var>).</p></li>
<li><p>Draw an arc to the point (<var>x</var> + <var>w</var>, <var>y</var> +
<var>upperRight</var>["<code data-x="DOMPointInit-y">y</code>"]).</p></li>
<li><p>Draw a straight line to the point (<var>x</var> + <var>w</var>, <var>y</var> +
<var>h</var> − <var>lowerRight</var>["<code data-x="DOMPointInit-y">y</code>"]).</p></li>
<li><p>Draw an arc to the point (<var>x</var> + <var>w</var> −
<var>lowerRight</var>["<code data-x="DOMPointInit-x">x</code>"], <var>y</var> +
<var>h</var>).</p></li>
<li><p>Draw a straight line to the point (<var>x</var> + <var>lowerLeft</var>["<code
data-x="DOMPointInit-x">x</code>"], <var>y</var> + <var>h</var>).</p></li>
<li><p>Draw an arc to the point (<var>x</var>, <var>y</var> + <var>h</var> −
<var>lowerLeft</var>["<code data-x="DOMPointInit-y">y</code>"]).</p></li>
<li><p>Draw a straight line to the point (<var>x</var>, <var>y</var> +
<var>upperLeft</var>["<code data-x="DOMPointInit-y">y</code>"]).</p></li>
<li><p>Draw an arc to the point (<var>x</var> + <var>upperLeft</var>["<code
data-x="DOMPointInit-x">x</code>"], <var>y</var>).</p></li>
</ol>
</li>
<li><p>Mark the subpath as closed.</p></li>
<li><p>Create a new subpath with the point (<var>x</var>, <var>y</var>) as the only point in the
subpath.</p></li>
</ol>
<p class="note">This is designed to behave similarly to the CSS <span
data-x="'border-radius'">'border-radius'</span> property.</p>
<!-- v6 feature request:
* points as a primitive shape
http://home.comcast.net/~urbanjost/canvas/vogle4.html
-->
</div>
<h6><code>Path2D</code> objects</h6>
<p><code>Path2D</code> objects can be used to declare paths that are then later used on
objects implementing the <code>CanvasDrawPath</code> interface. In addition to many of the APIs
described in earlier sections, <code>Path2D</code> objects have methods to combine paths, and to
add text to paths.</p>
<dl class="domintro">
<dt><code data-x=""><var>path</var> = new <span subdfn data-x="dom-Path2D">Path2D</span>()</code></dt>
<dd><p>Creates a new empty <code>Path2D</code> object.</p></dd>
<dt><code data-x=""><var>path</var> = new <span data-x="dom-Path2D">Path2D</span>(<var>path</var>)</code></dt>
<dd>
<p>When <var>path</var> is a <code>Path2D</code> object, returns a copy.</p>
<p>When <var>path</var> is a string, creates the path described by the argument, interpreted as
SVG path data. <ref>SVG</ref>
</p></dd>
<dt><code data-x=""><var>path</var>.<span subdfn data-x="dom-Path2D-addPath">addPath</span>(<var>path</var> [, <var>transform</var> ])</code></dt>
<dd><p>Adds to the path the path given by the argument.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn constructor for="Path2D"><code
data-x="dom-Path2D">Path2D(<var>path</var>)</code></dfn> constructor, when invoked, must run these
steps:</p>
<ol>
<li><p>Let <var>output</var> be a new <code>Path2D</code> object.</p></li>
<li><p>If <var>path</var> is not given, then return <var>output</var>.</p></li>
<li><p>If <var>path</var> is a <code>Path2D</code> object, then add all subpaths of
<var>path</var> to <var>output</var> and return <var>output</var>. (In other words, it returns a
copy of the argument.)</p></li>
<li>
<p>Let <var>svgPath</var> be the result of parsing and interpreting <var>path</var> according to
<cite>SVG 2</cite>'s rules for path data. <ref>SVG</ref></p>
<p class="note">The resulting path could be empty. SVG defines error handling rules for parsing
and applying path data.</p>
</li>
<li><p>Let (<var>x</var>, <var>y</var>) be the last point in <var>svgPath</var>.</p></li>
<li><p>Add all the subpaths, if any, from <var>svgPath</var> to <var>output</var>.</p></li>
<li><p>Create a new subpath in <var>output</var> with (<var>x</var>, <var>y</var>) as the only
point in the subpath.</p></li>
<li><p>Return <var>output</var>.</p></li>
</ol>
<hr>
<p>The <dfn method for="Path2D"><code data-x="dom-Path2D-addPath">addPath(<var>path</var>,
<var>transform</var>)</code></dfn> method, when invoked on a <code>Path2D</code> object
<var>a</var>, must run these steps:</p>
<ol>
<li><p>If the <code>Path2D</code> object <var>path</var> has no subpaths, then return.</p></li>
<li><p>Let <var>matrix</var> be the result of <span data-x="create a DOMMatrix from a 2D
dictionary">creating a <code>DOMMatrix</code> from the 2D dictionary</span>
<var>transform</var>.</p></li>
<li><p>If one or more of <var>matrix</var>'s <span>m11 element</span>, <span>m12 element</span>,
<span>m21 element</span>, <span>m22 element</span>, <span>m41 element</span>, or <span>m42
element</span> are infinite or NaN, then return.</p></li>
<li><p>Create a copy of all the subpaths in <var>path</var>. Let this copy be known as
<var>c</var>.</p></li>
<li><p>Transform all the coordinates and lines in <var>c</var> by the transform matrix
<var>matrix</var>.</p></li>
<li><p>Let (<var>x</var>, <var>y</var>) be the last point in the last subpath
of <var>c</var>.</p></li>
<li><p>Add all the subpaths in <var>c</var> to <var>a</var>.</p></li>
<li><p>Create a new subpath in <var>a</var> with (<var>x</var>, <var>y</var>) as the only point
in the subpath.</p></li>
</ol>
</div>
<h6><dfn data-x="dom-context-2d-transformation">Transformations</dfn></h6>
<p>Objects that implement the <code>CanvasTransform</code> interface have a <dfn>current
transformation matrix</dfn>, as well as methods (described in this section) to manipulate it. When
an object implementing the <code>CanvasTransform</code> interface is created, its transformation
matrix must be initialized to the identity matrix.</p>
<p>The <span>current transformation matrix</span> is applied to coordinates when creating the
<span>current default path</span>, and when painting text, shapes, and <code>Path2D</code>
objects, on objects implementing the <code>CanvasTransform</code> interface.</p>
<!-- conformance criteria for actual drawing are described in the various sections below -->
<div w-nodev>
<p>The transformations must be performed in reverse order.</p>
<p class="note">For instance, if a scale transformation that doubles the width is applied to the
canvas, followed by a rotation transformation that rotates drawing operations by a quarter turn,
and a rectangle twice as wide as it is tall is then drawn on the canvas, the actual result will be
a square.</p> <!-- q.v. https://goo.gl/5RLrN -->
</div>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-scale">scale</span>(<var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> to apply a scaling transformation with
the given characteristics.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-rotate">rotate</span>(<var>angle</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> to apply a rotation transformation
with the given characteristics. The angle is in radians.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-translate">translate</span>(<var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> to apply a translation transformation
with the given characteristics.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-transform">transform</span>(<var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> to apply the matrix given by the
arguments as described below.</p>
</dd>
<dt><code data-x=""><var>matrix</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-getTransform">getTransform</span>()</code></dt>
<dd>
<p>Returns a copy of the <span>current transformation matrix</span>, as a newly created
<code>DOMMatrix</code> object.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-setTransform">setTransform</span>(<var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> <em>to</em> the matrix given by the
arguments as described below.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-setTransform-matrix">setTransform</span>(<var>transform</var>)</code></dt>
<dd>
<p>Changes the <span>current transformation matrix</span> <em>to</em> the matrix represented by
the passed <code>DOMMatrix2DInit</code> dictionary.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-resetTransform">resetTransform</span>()</code></dt>
<dd><p>Changes the <span>current transformation matrix</span> to the identity matrix.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasTransform"><code data-x="dom-context-2d-scale">scale(<var>x</var>,
<var>y</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If either of the arguments are infinite or NaN, then return.</p></li>
<li><p>Add the scaling transformation described by the arguments to the <span>current
transformation matrix</span>. The <var>x</var> argument represents the scale factor in the
horizontal direction and the <var>y</var> argument represents the scale factor in the vertical
direction. The factors are multiples.</p></li>
</ol>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-rotate">rotate(<var>angle</var>)</code></dfn> method, when invoked, must
run these steps:</p>
<ol>
<li><p>If <var>angle</var> is infinite or NaN, then return.</p></li>
<li><p>Add the rotation transformation described by the argument to the <span>current
transformation matrix</span>. The <var>angle</var> argument represents a clockwise rotation angle
expressed in radians.</p></li>
</ol>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-translate">translate(<var>x</var>, <var>y</var>)</code></dfn> method, when
invoked, must run these steps:</p>
<ol>
<li><p>If either of the arguments are infinite or NaN, then return.</p></li>
<li><p>Add the translation transformation described by the arguments to the <span>current
transformation matrix</span>. The <var>x</var> argument represents the translation distance in
the horizontal direction and the <var>y</var> argument represents the translation distance in the
vertical direction. The arguments are in coordinate space units.</p></li>
</ol>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-transform">transform(<var>a</var>, <var>b</var>, <var>c</var>,
<var>d</var>, <var>e</var>, <var>f</var>)</code></dfn> method, when invoked, must run these
steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li>
<p>Replace the <span>current transformation matrix</span> with the result of <span
data-x="matrix multiplication">multiplying</span> the <span>current transformation matrix</span>
with the matrix described by:</p>
<table class="matrix">
<tr>
<td><var>a</var></td>
<td><var>c</var></td>
<td><var>e</var></td>
</tr>
<tr>
<td><var>b</var></td>
<td><var>d</var></td>
<td><var>f</var></td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
</table>
</li>
</ol>
</div>
<p class="note">The arguments <var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>,
<var>e</var>, and <var>f</var> are sometimes called <var>m11</var>, <var>m12</var>,
<var>m21</var>, <var>m22</var>, <var>dx</var>, and <var>dy</var> or <var>m11</var>,
<var>m21</var>, <var>m12</var>, <var>m22</var>, <var>dx</var>, and <var>dy</var>. Care ought to be
taken in particular with the order of the second and third arguments (<var>b</var> and
<var>c</var>) as their order varies from API to API and APIs sometimes use the notation
<var>m12</var>/<var>m21</var> and sometimes <var>m21</var>/<var>m12</var> for those positions.</p>
<div w-nodev>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-getTransform">getTransform()</code></dfn> method, when invoked, must return
a newly created <code>DOMMatrix</code> representing a copy of the <span>current transformation
matrix</span> matrix of the context.</p>
<p class="note">This returned object is not live, so updating it will not affect the
<span>current transformation matrix</span>, and updating the <span>current transformation
matrix</span> will not affect an already returned <code>DOMMatrix</code>.</p>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-setTransform">setTransform(<var>a</var>, <var>b</var>, <var>c</var>,
<var>d</var>, <var>e</var>, <var>f</var>)</code></dfn> method, when invoked, must run these
steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li>
<p>Reset the <span>current transformation matrix</span> to the matrix described by:</p>
<table class="matrix">
<tr>
<td><var>a</var></td>
<td><var>c</var></td>
<td><var>e</var></td>
</tr>
<tr>
<td><var>b</var></td>
<td><var>d</var></td>
<td><var>f</var></td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
</table>
</li>
</ol>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-setTransform-matrix">setTransform(<var>transform</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol>
<li><p>Let <var>matrix</var> be the result of <span data-x="create a DOMMatrix from a 2D
dictionary">creating a <code>DOMMatrix</code> from the 2D dictionary</span>
<var>transform</var>.</p>
<li><p>If one or more of <var>matrix</var>'s <span>m11 element</span>, <span>m12 element</span>,
<span>m21 element</span>, <span>m22 element</span>, <span>m41 element</span>, or <span>m42
element</span> are infinite or NaN, then return.</p></li>
<li><p>Reset the <span>current transformation matrix</span> to <var>matrix</var>.</p></li>
</ol>
<p>The <dfn method for="CanvasTransform"><code
data-x="dom-context-2d-resetTransform">resetTransform()</code></dfn> method, when invoked, must
reset the <span>current transformation matrix</span> to the identity matrix.</p>
</div>
<div class="note">
<p>Given a matrix of the form created by the <code
data-x="dom-context-2d-transform">transform()</code> and <code
data-x="dom-context-2d-setTransform">setTransform()</code> methods, i.e.,</p>
<table class="matrix">
<tr>
<td><var>a</var></td>
<td><var>c</var></td>
<td><var>e</var></td>
</tr>
<tr>
<td><var>b</var></td>
<td><var>d</var></td>
<td><var>f</var></td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
</table>
<p>the resulting transformed coordinates after transform matrix multiplication will be</p>
<p class="equations">
<var>x</var><sub>new</sub> = <var>a</var> <var>x</var> + <var>c</var> <var>y</var> + <var>e</var><br>
<var>y</var><sub>new</sub> = <var>b</var> <var>x</var> + <var>d</var> <var>y</var> + <var>f</var>
</p>
</div>
<h6>Image sources for 2D rendering contexts</h6>
<p>Some methods on the <code>CanvasDrawImage</code> and <code>CanvasFillStrokeStyles</code>
interfaces take the union type <code>CanvasImageSource</code> as an argument.</p>
<p>This union type allows objects implementing any of the following interfaces to be used as image
sources:</p>
<ul>
<li><code>HTMLOrSVGImageElement</code> (<code>img</code> or <span>SVG <code>image</code></span>
elements)</li>
<li><code>HTMLVideoElement</code> (<code>video</code> elements)</li>
<li><code>HTMLCanvasElement</code> (<code>canvas</code> elements)</li>
<li><code>OffscreenCanvas</code></li>
<li><code>ImageBitmap</code></li>
<li><code>VideoFrame</code></li>
</ul>
<p class="note">Although not formally specified as such, <span>SVG <code>image</code></span>
elements are expected to be implemented nearly identical to <code>img</code> elements. That is,
<span>SVG <code>image</code></span> elements share the fundamental concepts and features of
<code>img</code> elements.</p>
<p class="note">The <code>ImageBitmap</code> interface can be created from a number of other
image-representing types, including <code>ImageData</code>.</p>
<p>To <dfn>check the usability of the <var>image</var> argument</dfn>, where <var>image</var>
is a <code>CanvasImageSource</code> object, run these steps:</p>
<ol>
<li>
<p>Switch on <var>image</var>:</p>
<dl class="switch">
<dt><code>HTMLOrSVGImageElement</code></dt>
<dd>
<p>If <var>image</var>'s <span>current request</span>'s <span
data-x="img-req-state">state</span> is <span data-x="img-error">broken</span>, then
throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
<p>If <var>image</var> is not <span data-x="img-good">fully decodable</span>,
then return <i>bad</i>.</p>
<p>If <var>image</var> has a <span>natural width</span> or <span>natural height</span>
(or both) equal to zero, then return <i>bad</i>.</p> <!--
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2567 -->
</dd>
<dt><code>HTMLVideoElement</code></dt>
<dd><p>If <var>image</var>'s <code data-x="dom-media-readyState">readyState</code>
attribute is either <code data-x="dom-media-HAVE_NOTHING">HAVE_NOTHING</code> or <code
data-x="dom-media-HAVE_METADATA">HAVE_METADATA</code>, then return <i>bad</i>.</p></dd>
<dt><code>HTMLCanvasElement</code></dt>
<dt><code>OffscreenCanvas</code></dt>
<dd><p>If <var>image</var> has either a horizontal dimension or a vertical dimension
equal to zero, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></dd>
<dt><code>ImageBitmap</code></dt>
<dt><code>VideoFrame</code></dt>
<dd><p>If <var>image</var>'s <span>[[Detached]]</span> internal slot value
is set to true, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></dd>
</dl>
</li>
<li>
<p>Return <i>good</i>.</p>
</li>
</ol>
<p>When a <code>CanvasImageSource</code> object represents an <code>HTMLOrSVGImageElement</code>,
the element's image must be used as the source image.</p>
<p>Specifically, when a <code>CanvasImageSource</code> object represents an animated image in an
<code>HTMLOrSVGImageElement</code>, the user agent must use the default image of the animation
(the one that the format defines is to be used when animation is not supported or is disabled),
or, if there is no such image, the first frame of the animation, when rendering the image for
<code>CanvasRenderingContext2D</code> APIs.</p>
<p>When a <code>CanvasImageSource</code> object represents an <code>HTMLVideoElement</code>, then
the frame at the <span>current playback position</span> when the method with the argument is
invoked must be used as the source image when rendering the image for
<code>CanvasRenderingContext2D</code> APIs, and the source image's dimensions must be the <span
data-x="concept-video-natural-width">natural width</span> and <span
data-x="concept-video-natural-height">natural height</span> of the <span>media resource</span>
(i.e., after any aspect-ratio correction has been applied).</p>
<p>When a <code>CanvasImageSource</code> object represents an <code>HTMLCanvasElement</code>, the
element's bitmap must be used as the source image.</p>
<p>When a <code>CanvasImageSource</code> object represents an element that is <span>being
rendered</span> and that element has been resized, the original image data of the source image
must be used, not the image as it is rendered (e.g. <code data-x="attr-dim-width">width</code> and
<code data-x="attr-dim-height">height</code> attributes on the source element have no effect on how
the object is interpreted when rendering the image for <code>CanvasRenderingContext2D</code>
APIs).</p>
<p>When a <code>CanvasImageSource</code> object represents an <code>ImageBitmap</code>, the
object's bitmap image data must be used as the source image.</p>
<p>When a <code>CanvasImageSource</code> object represents an <code>OffscreenCanvas</code>, the
object's bitmap must be used as the source image.</p>
<p>When a <code>CanvasImageSource</code> object represents a <code>VideoFrame</code>, the object's
pixel data must be used as the source image, and the source image's dimensions must be the
object's <span>[[display width]]</span> and <span>[[display height]]</span>.</p>
<p>An object <var>image</var> <dfn id=the-image-argument-is-not-origin-clean>is not
origin-clean</dfn> if, switching on <var>image</var>'s type:</p>
<dl class=switch>
<dt><code>HTMLOrSVGImageElement</code>
<dd><p><var>image</var>'s <span>current request</span>'s <span data-x="img-req-data">image
data</span> is <span>CORS-cross-origin</span>.</p></dd>
<dt><code>HTMLVideoElement</code>
<dd><p><var>image</var>'s <span>media data</span> is <span>CORS-cross-origin</span>.</p></dd>
<dt><code>HTMLCanvasElement</code>
<dt><code>ImageBitmap</code>
<dt><code>OffscreenCanvas</code>
<dd><p><var>image</var>'s bitmap's <span data-x="concept-canvas-origin-clean">origin-clean</span>
flag is false.</p></dd>
</dl>
<h6>Fill and stroke styles</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fillStyle">fillStyle</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current style used for filling shapes.</p>
<p>Can be set, to change the <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</span>.</p>
<p>The style can be either a string containing a CSS color, or a <code>CanvasGradient</code> or
<code>CanvasPattern</code> object. Invalid values are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-strokeStyle">strokeStyle</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current style used for stroking shapes.</p>
<p>Can be set, to change the <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style.</span></p>
<p>The style can be either a string containing a CSS color, or a <code>CanvasGradient</code> or
<code>CanvasPattern</code> object. Invalid values are ignored.</p>
</dd>
</dl>
<div w-nodev>
<!-- v6 feature requests:
* Getting and setting colors by component to bypass the CSS value parsing.
Either:
context.fillStyle.red += 1;
Or:
var array = context.fillStyle;
array[1] += 1;
context.fillStyle = array;
* A more performant way of setting colors in general, e.g.:
context.setFillColor(r,g,b,a) // already supported by webkit
Or:
context.fillStyle = 0xRRGGBBAA; // set a 32bit int directly
-->
<p>Objects that implement the <code>CanvasFillStrokeStyles</code> interface have attributes and
methods (defined in this section) that control how shapes are treated by the object.</p>
<p>Such objects have associated <dfn data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</dfn> and <dfn data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</dfn>
values, which are either CSS colors, <code>CanvasPattern</code>s, or <code>CanvasGradient</code>s.
Initially, both must be the result of <span data-x="parse a CSS <color> value">parsing</span>
the string "<code data-x="">#000000</code>".</p>
<p>When the value is a CSS color, it must not be affected by the transformation matrix when used
to draw on bitmaps.</p> <!-- so singular matrices don't affect solid color fillStyles -->
<p class="note">When set to a <code>CanvasPattern</code> or <code>CanvasGradient</code> object,
changes made to the object after the assignment do affect subsequent stroking or filling of
shapes.</p>
<p>The <dfn attribute for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-fillStyle">fillStyle</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</span> is a CSS color, then return the <span data-x="serialize a CSS <color>
value">serialization</span> of that color with <span data-x="HTML-compatible serialization is
requested">HTML-compatible serialization requested</span>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</span>.</p></li>
</ol>
<p>The <code data-x="dom-context-2d-fillStyle">fillStyle</code> setter steps are:</p>
<ol>
<li>
<p>If the given value is a string, then:</p>
<ol>
<li><p>Let <var>context</var> be <span>this</span>'s <code
data-x="dom-context-2d-canvas">canvas</code> attribute's value, if that is an element;
otherwise null.</p></li>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> the given value with <var>context</var> if non-null.</p></li>
<li><p>If <var>parsedValue</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</span> to <var>parsedValue</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>If the given value is a <code>CanvasPattern</code> object that is marked as <span
data-x="concept-canvas-pattern-not-origin-clean">not origin-clean</span>, then set
<span>this</span>'s <span data-x="concept-canvas-origin-clean">origin-clean</span> flag to
false.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill
style</span> to the given value.</p></li>
</ol>
<p>The <dfn attribute for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-strokeStyle">strokeStyle</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span> is a CSS color, then return the <span data-x="serialize a CSS <color>
value">serialization</span> of that color with <span data-x="HTML-compatible serialization is
requested">HTML-compatible serialization requested</span>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span>.</p></li>
</ol>
<p>The <code data-x="dom-context-2d-strokeStyle">strokeStyle</code> setter steps are:</p>
<ol>
<li>
<p>If the given value is a string, then:</p>
<ol>
<li><p>Let <var>context</var> be <span>this</span>'s <code
data-x="dom-context-2d-canvas">canvas</code> attribute's value, if that is an element;
otherwise null.</p></li>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> the given value with <var>context</var> if non-null.</p></li>
<li><p>If <var>parsedValue</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</span> to
<var>parsedValue</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>If the given value is a <code>CanvasPattern</code> object that is marked as <span
data-x="concept-canvas-pattern-not-origin-clean">not origin-clean</span>, then set
<span>this</span>'s <span data-x="concept-canvas-origin-clean">origin-clean</span> flag to
false.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span> to the given value.</p></li>
</ol>
</div>
<hr>
<p>There are three types of gradients, linear gradients, radial gradients, and conic gradients,
represented by objects implementing the opaque <code>CanvasGradient</code> interface.</p>
<p id="interpolation">Once a gradient has been created (see below), stops are placed along it to
define how the colors are distributed along the gradient. <span w-nodev>The color of the
gradient at each stop is the color specified for that stop. Between each such stop, the colors and
the alpha component must be linearly interpolated over the RGBA space without premultiplying the
alpha value to find the color to use at that offset. Before the first stop, the color must be the
color of the first stop. After the last stop, the color must be the color of the last stop. When
there are no stops, the gradient is <span>transparent black</span>.</span></p>
<dl class="domintro">
<dt><code data-x=""><var>gradient</var>.<span subdfn data-x="dom-canvasgradient-addColorStop">addColorStop</span>(<var>offset</var>, <var>color</var>)</code></dt>
<dd>
<p>Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset
at one end of the gradient, 1.0 is the offset at the other end.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the offset
is out of range. Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if
the color cannot be parsed.</p>
</dd>
<dt><code data-x=""><var>gradient</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createLinearGradient">createLinearGradient</span>(<var>x0</var>, <var>y0</var>, <var>x1</var>, <var>y1</var>)</code></dt>
<dd>
<p>Returns a <code>CanvasGradient</code> object that represents a linear gradient that paints
along the line given by the coordinates represented by the arguments.</p>
</dd>
<dt><code data-x=""><var>gradient</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createRadialGradient">createRadialGradient</span>(<var>x0</var>, <var>y0</var>, <var>r0</var>, <var>x1</var>, <var>y1</var>, <var>r1</var>)</code></dt>
<dd>
<p>Returns a <code>CanvasGradient</code> object that represents a radial gradient that paints
along the cone given by the circles represented by the arguments.</p>
<p>If either of the radii are negative, throws an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code> exception.</p>
</dd>
<dt><code data-x=""><var>gradient</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createConicGradient">createConicGradient</span>(<var>startAngle</var>, <var>x</var>, <var>y</var>)</code></dt>
<dd><p>Returns a <code>CanvasGradient</code> object that represents a conic gradient that paints
clockwise along the rotation around the center represented by the arguments.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasGradient"><code
data-x="dom-canvasgradient-addColorStop">addColorStop(<var>offset</var>,
<var>color</var>)</code></dfn> method on the <code>CanvasGradient</code>, when invoked, must run
these steps:</p>
<ol>
<li><p>If the <var>offset</var> is less than 0 or greater than 1, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>Let <var>parsed color</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> <var>color</var>.</p>
<p class="note">No element is passed to the parser because <code>CanvasGradient</code> objects
are <code>canvas</code>-neutral — a <code>CanvasGradient</code> object created by one
<code>canvas</code> can be used by another, and there is therefore no way to know which is the
"element in question" at the time that the color is specified.</p>
</li>
<li><p>If <var>parsed color</var> is failure, throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li>
<p>Place a new stop on the gradient, at offset <var>offset</var> relative to the whole gradient,
and with the color <var>parsed color</var>.</p>
<p>If multiple stops are added at the same offset on a gradient, then they must be placed in the
order added, with the first one closest to the start of the gradient, and each subsequent one
infinitesimally further along towards the end point (in effect causing all but the first and
last stop added at each point to be ignored).</p>
</li>
</ol>
<p>The <dfn method for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-createLinearGradient">createLinearGradient(<var>x0</var>, <var>y0</var>,
<var>x1</var>, <var>y1</var>)</code></dfn> method takes four arguments that represent the start
point (<var>x0</var>, <var>y0</var>) and end point (<var>x1</var>, <var>y1</var>) of the gradient.
The method, when invoked, must return a linear <code>CanvasGradient</code> initialized with the
specified line.</p>
<p>Linear gradients must be rendered such that all points on a line perpendicular to the line that
crosses the start and end points have the color at the point where those two lines cross (with the
colors coming from the <a href="#interpolation">interpolation and extrapolation</a> described
above). The points in the linear gradient must be transformed as described by the <span
data-x="dom-context-2d-transformation">current transformation matrix</span> when rendering.</p>
<p>If <var>x0</var> = <var>x1</var> and <span
data-x=""><var>y0</var> = <var>y1</var></span>, then the linear
gradient must paint nothing.</p>
<p>The <dfn method for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-createRadialGradient">createRadialGradient(<var>x0</var>, <var>y0</var>,
<var>r0</var>, <var>x1</var>, <var>y1</var>, <var>r1</var>)</code></dfn> method takes six
arguments, the first three representing the start circle with origin (<var>x0</var>,
<var>y0</var>) and radius <var>r0</var>, and the last three representing the end circle with
origin (<var>x1</var>, <var>y1</var>) and radius <var>r1</var>. The values are in coordinate space
units. If either of <var>r0</var> or <var>r1</var> are negative, then an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> must be thrown. Otherwise,
the method, when invoked, must return a radial <code>CanvasGradient</code> initialized with the
two specified circles.</p>
<p>Radial gradients must be rendered by following these steps:</p>
<ol>
<li><p>If <var>x<sub>0</sub></var> = <var>x<sub>1</sub></var> and <var>y<sub>0</sub></var> = <var>y<sub>1</sub></var> and <var>r<sub>0</sub></var> = <var>r<sub>1</sub></var>, then the radial gradient must
paint nothing. Return.</p></li>
<li>
<p>Let <span data-x="">x(<var>ω</var>) = (<var>x<sub>1</sub></var>-<var>x<sub>0</sub></var>)<var>ω</var> + <var>x<sub>0</sub></var></span></p>
<p>Let <span data-x="">y(<var>ω</var>) = (<var>y<sub>1</sub></var>-<var>y<sub>0</sub></var>)<var>ω</var> + <var>y<sub>0</sub></var></span></p>
<p>Let <span data-x="">r(<var>ω</var>) = (<var>r<sub>1</sub></var>-<var>r<sub>0</sub></var>)<var>ω</var> + <var>r<sub>0</sub></var></span></p>
<p>Let the color at <var>ω</var> be the color at that position on the gradient
(with the colors coming from the <a href="#interpolation">interpolation and extrapolation</a>
described above).</p>
</li>
<li><p>For all values of <var>ω</var> where <span data-x="">r(<var>ω</var>) > 0</span>, starting with the value of <var>ω</var> nearest to positive infinity and ending with the value of <var>ω</var> nearest to negative infinity, draw the circumference of the circle with
radius <span data-x="">r(<var>ω</var>)</span> at position (<span data-x="">x(<var>ω</var>)</span>, <span data-x="">y(<var>ω</var>)</span>), with the
color at <var>ω</var>, but only painting on the parts of the bitmap that have not
yet been painted on by earlier circles in this step for this rendering of the gradient.</p></li>
</ol>
<p class="note">This effectively creates a cone, touched by the two circles defined in the
creation of the gradient, with the part of the cone before the start circle (0.0) using the color
of the first offset, the part of the cone after the end circle (1.0) using the color of the last
offset, and areas outside the cone untouched by the gradient (<span>transparent black</span>).</p>
<p>The resulting radial gradient must then be transformed as described by the <span
data-x="dom-context-2d-transformation">current transformation matrix</span> when rendering.</p>
<p>The <dfn method for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-createConicGradient">createConicGradient(<var>startAngle</var>,
<var>x</var>, <var>y</var>)</code></dfn> method takes three arguments, the first argument,
<var>startAngle</var>, represents the angle in radians at which the gradient begins, and the last
two arguments, (<var>x</var>, <var>y</var>), represent the center of the gradient in <span
data-x="'px'">CSS pixels</span>. The method, when invoked, must return a conic
<code>CanvasGradient</code> initialized with the specified center and angle.</p>
<p>It follows the same rendering rule as CSS <span>'conic-gradient'</span> and it is
equivalent to CSS 'conic-gradient(from <var>adjustedStartAngle</var>rad at
<var>x</var>px <var>y</var>px, <var>angularColorStopList</var>)'. Here:</p>
<ul>
<li><p><var>adjustedStartAngle</var> is given by <var>startAngle</var> + π/2;</p></li>
<li><p><var>angularColorStopList</var> is given by the color stops that have been added to the
<code>CanvasGradient</code> using <code
data-x="dom-canvasgradient-addColorStop">addColorStop()</code>, with the color stop offsets
interpreted as percentages.</p></li>
</ul>
<p>Gradients must be painted only where the relevant stroking or filling effects requires that
they be drawn.</p>
</div>
<hr>
<p>Patterns are represented by objects implementing the opaque <code>CanvasPattern</code>
interface.</p>
<dl class="domintro">
<dt><code data-x=""><var>pattern</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createPattern">createPattern</span>(<var>image</var>, <var>repetition</var>)</code></dt>
<dd>
<p>Returns a <code>CanvasPattern</code> object that uses the given image and repeats in the
direction(s) given by the <var>repetition</var> argument.</p>
<p>The allowed values for <var>repetition</var> are <code data-x="">repeat</code> (both
directions), <code data-x="">repeat-x</code> (horizontal only), <code data-x="">repeat-y</code>
(vertical only), and <code data-x="">no-repeat</code> (neither). If the <var>repetition</var>
argument is empty, the value <code data-x="">repeat</code> is used.</p>
<p>If the image isn't yet fully decoded, then nothing is drawn. If the image is a canvas with no
data, throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
</dd>
<dt><code data-x=""><var>pattern</var>.<span subdfn data-x="dom-canvaspattern-setTransform">setTransform</span>(<var>transform</var>)</code></dt>
<dd>
<p>Sets the transformation matrix that will be used when rendering the pattern during a fill or
stroke painting operation.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasFillStrokeStyles"><code
data-x="dom-context-2d-createPattern">createPattern(<var>image</var>,
<var>repetition</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>Let <var>usability</var> be the result of <span data-x="check the usability of the image
argument">checking the usability of</span> <var>image</var>.</p></li>
<li><p>If <var>usability</var> is <i>bad</i>, then return null.</p></li>
<li><p><span>Assert</span>: <var>usability</var> is <i>good</i>.</p></li>
<li><p>If <var>repetition</var> is the empty string, then set it to "<code
data-x="">repeat</code>".</p>
<li><p>If <var>repetition</var> is not <span>identical to</span> one of "<code
data-x="">repeat</code>", "<code data-x="">repeat-x</code>", "<code data-x="">repeat-y</code>",
or "<code data-x="">no-repeat</code>", then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>pattern</var> be a new <code>CanvasPattern</code> object with the image
<var>image</var> and the repetition behavior given by <var>repetition</var>.</p></li>
<li><p>If <var>image</var> <span>is not origin-clean</span>, then mark <var>pattern</var> as <dfn
data-x="concept-canvas-pattern-not-origin-clean">not origin-clean</dfn>.</p></li>
<li><p>Return <var>pattern</var>.</p></li>
</ol>
<p>Modifying the <var>image</var> used when creating a <code>CanvasPattern</code> object
after calling the <code data-x="dom-context-2d-createPattern">createPattern()</code> method must
not affect the pattern(s) rendered by the <code>CanvasPattern</code> object.</p>
<p>Patterns have a transformation matrix, which controls how the pattern is used when it is
painted. Initially, a pattern's transformation matrix must be the identity matrix.</p>
<p>The <dfn method for="CanvasPattern"><code
data-x="dom-canvaspattern-setTransform">setTransform(<var>transform</var>)</code></dfn> method,
when invoked, must run these steps:</p>
<ol>
<li><p>Let <var>matrix</var> be the result of <span data-x="create a DOMMatrix from a 2D
dictionary">creating a <code>DOMMatrix</code> from the 2D dictionary</span>
<var>transform</var>.</p>
<li><p>If one or more of <var>matrix</var>'s <span>m11 element</span>, <span>m12 element</span>,
<span>m21 element</span>, <span>m22 element</span>, <span>m41 element</span>, or <span>m42
element</span> are infinite or NaN, then return.</p></li>
<li><p>Reset the pattern's transformation matrix to <var>matrix</var>.</p></li>
</ol>
<p>When a pattern is to be rendered within an area, the user agent must run the following steps to
determine what is rendered:</p>
<ol>
<li><p>Create an infinite <span>transparent black</span> bitmap.</p></li>
<li>
<p>Place a copy of the image on the bitmap, anchored such that its top left corner is at the
origin of the coordinate space, with one coordinate space unit per <span data-x="'px'">CSS
pixel</span> of the image, then place repeated copies of this image horizontally to the left and
right, if the repetition behavior is "<code data-x="">repeat-x</code>", or vertically up and
down, if the repetition behavior is "<code data-x="">repeat-y</code>", or in all four
directions all over the bitmap, if the repetition behavior is "<code
data-x="">repeat</code>".</p>
<p>If the original image data is a bitmap image, then the value painted at a point in the area
of the repetitions is computed by filtering the original image data. When scaling up, if the
<code data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code> attribute is
set to false, then the image must be rendered using nearest-neighbor interpolation. Otherwise,
the user agent may use any filtering algorithm (for example bilinear interpolation or
nearest-neighbor). User agents which support multiple filtering algorithms may use the value of
the <code data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</code> attribute
to guide the choice of filtering algorithm. When such a filtering algorithm requires a pixel
value from outside the original image data, it must instead use the value from wrapping the
pixel's coordinates to the original image's dimensions. (That is, the filter uses 'repeat'
behavior, regardless of the value of the pattern's repetition behavior.)</p> <!-- drawImage()
has similar paragraphs with different rules -->
</li>
<li><p>Transform the resulting bitmap according to the pattern's transformation matrix.</p></li>
<li><p>Transform the resulting bitmap again, this time according to the <span
data-x="dom-context-2d-transformation">current transformation matrix</span>.</p></li>
<li><p>Replace any part of the image outside the area in which the pattern is to be rendered with
<span>transparent black</span>.</p></li>
<li><p>The resulting bitmap is what is to be rendered, with the same origin and same
scale.</p></li>
</ol>
<hr>
<p>If a radial gradient or repeated pattern is used when the transformation matrix is singular,
then the resulting style must be <span>transparent black</span> (otherwise the gradient or pattern
would be collapsed to a point or line, leaving the other pixels undefined). Linear gradients and
solid colors always define all points even with singular transformation matrices.</p>
</div>
<h6>Drawing rectangles to the bitmap</h6>
<p>Objects that implement the <code>CanvasRect</code> interface provide the following methods for
immediately drawing rectangles to the bitmap. The methods each take four arguments; the first two
give the <var>x</var> and <var>y</var> coordinates of the top left of the rectangle, and the
second two give the width <var>w</var> and height <var>h</var> of the rectangle, respectively.</p>
<div w-nodev>
<p>The <span data-x="dom-context-2d-transformation">current transformation matrix</span> must be
applied to the following four coordinates, which form the path that must then be closed to get the
specified rectangle: <span data-x="">(<var>x</var>, <var>y</var>)</span>, <span
data-x="">(<var>x</var>+<var>w</var>, <var>y</var>)</span>, <span data-x="">(<var>x</var>+<var>w</var>, <var>y</var>+<var>h</var>)</span>, <span data-x="">(<var>x</var>, <var>y</var>+<var>h</var>)</span>.</p>
<p>Shapes are painted without affecting the <span>current default path</span>, and are subject to
the <span>clipping region</span>, and, with the exception of <code
data-x="dom-context-2d-clearRect">clearRect()</code>, also <span data-x="shadows">shadow
effects</span>, <span data-x="concept-canvas-global-alpha">global alpha</span>, and the
<span>current compositing and blending operator</span>.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-clearRect">clearRect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</code></dt>
<dd><p>Clears all pixels on the bitmap in the given rectangle to <span>transparent
black</span>.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fillRect">fillRect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</code></dt>
<dd><p>Paints the given rectangle onto the bitmap, using the current fill style.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-strokeRect">strokeRect</span>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</code></dt>
<dd>
<p>Paints the box that outlines the given rectangle onto the bitmap, using the current stroke
style.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasRect"><code
data-x="dom-context-2d-clearRect">clearRect(<var>x</var>, <var>y</var>, <var>w</var>,
<var>h</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>Let <var>pixels</var> be the set of pixels in the specified rectangle that also
intersect the current <span>clipping region</span>.</p></li>
<li><p>Clear the pixels in <var>pixels</var> to a <span>transparent black</span>, erasing any
previous image.</p></li>
</ol>
<p class="note">If either height or width are zero, this method has no effect, since the set of
pixels would be empty.</p>
<p>The <dfn method for="CanvasRect"><code data-x="dom-context-2d-fillRect">fillRect(<var>x</var>,
<var>y</var>, <var>w</var>, <var>h</var>)</code></dfn> method, when invoked, must run these
steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>If either <var>w</var> or <var>h</var> are zero, then return.</p></li>
<li><p>Paint the specified rectangular area using <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span>.</p></li>
</ol>
<p>The <dfn method for="CanvasRect"><code
data-x="dom-context-2d-strokeRect">strokeRect(<var>x</var>, <var>y</var>, <var>w</var>,
<var>h</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>Take the result of <span data-x="trace a path">tracing the path</span> described below,
using the <code>CanvasPathDrawingStyles</code> interface's line styles, and fill it with
<span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span>.</p></li>
</ol>
<p>If both <var>w</var> and <var>h</var> are zero, the path has a single subpath
with just one point (<var>x</var>, <var>y</var>), and no lines, and this method
thus has no effect (the <span>trace a path</span> algorithm returns an empty path in that
case).</p>
<p>If just one of either <var>w</var> or <var>h</var> is zero, then the path has
a single subpath consisting of two points, with coordinates (<var>x</var>, <var>y</var>) and (<var>x</var>+<var>w</var>, <var>y</var>+<var>h</var>), in that order, connected by a single straight line.</p>
<p>Otherwise, the path has a single subpath consisting of four points, with coordinates (<span
data-x=""><var>x</var></span>, <var>y</var>), (<span
data-x=""><var>x</var>+<var>w</var></span>, <var>y</var>), (<var>x</var>+<var>w</var>,
<var>y</var>+<var>h</var>), and (<var>x</var>, <var>y</var>+<var>h</var>),
connected to each other in that order by straight lines.</p>
</div>
<h6>Drawing text to the bitmap</h6>
<dl class="domintro" id="text-0">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fillText">fillText</span>(<var>text</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ])</code></dt>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-strokeText">strokeText</span>(<var>text</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ])</code></dt>
<dd>
<p>Fills or strokes (respectively) the given text at the given position. If a maximum width is
provided, the text will be scaled to fit that width if necessary.</p>
</dd>
<dt><code data-x=""><var>metrics</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-measureText">measureText</span>(<var>text</var>)</code></dt>
<dd>
<p>Returns a <code>TextMetrics</code> object with the metrics of the given text in the current
font.</p>
</dd>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-width">width</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-actualBoundingBoxLeft">actualBoundingBoxLeft</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-actualBoundingBoxRight">actualBoundingBoxRight</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-fontBoundingBoxAscent">fontBoundingBoxAscent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-fontBoundingBoxDescent">fontBoundingBoxDescent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-actualBoundingBoxDescent">actualBoundingBoxDescent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-emHeightAscent">emHeightAscent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-emHeightDescent">emHeightDescent</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-hangingBaseline">hangingBaseline</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-alphabeticBaseline">alphabeticBaseline</span></code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-ideographicBaseline">ideographicBaseline</span></code></dt>
<dd><p>Returns the measurement described below.</p></dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasText</code> interface provide the following methods for
rendering text.</p>
<p>The <dfn method for="CanvasText"><code
data-x="dom-context-2d-fillText">fillText(<var>text</var>, <var>x</var>, <var>y</var>,
<var>maxWidth</var>)</code></dfn> and <dfn method for="CanvasText"><code
data-x="dom-context-2d-strokeText">strokeText(<var>text</var>, <var>x</var>, <var>y</var>,
<var>maxWidth</var>)</code></dfn> methods render the given
<var>text</var> at the given (<var>x</var>, <var>y</var>) coordinates ensuring that the text isn't
wider than <var>maxWidth</var> if specified, using the current <code
data-x="dom-context-2d-font">font</code>, <code
data-x="dom-context-2d-textAlign">textAlign</code>, and <code
data-x="dom-context-2d-textBaseline">textBaseline</code> values. Specifically, when the methods
are invoked, the user agent must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>Run the <span>text preparation algorithm</span>, passing it <var>text</var>, the object
implementing the <code>CanvasText</code> interface, and, if the <var>maxWidth</var> argument was
provided, that argument. Let <var>glyphs</var> be the result.</p>
<li><p>Move all the shapes in <var>glyphs</var> to the right by <var>x</var>
<span data-x="'px'">CSS pixels</span> and down by <var>y</var> <span data-x="'px'">CSS
pixels</span>.</p></li>
<li>
<p>Paint the shapes given in <var>glyphs</var>, as transformed by the <span
data-x="dom-context-2d-transformation">current transformation matrix</span>, with each <span
data-x="'px'">CSS pixel</span> in the coordinate space of <var>glyphs</var> mapped to one
coordinate space unit.</p>
<p>For <code data-x="dom-context-2d-fillText">fillText()</code>, <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span> must be applied to the
shapes and <span>this</span>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span> must be ignored. For <code data-x="dom-context-2d-strokeText">strokeText()</code>,
the reverse holds: <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</span> must be applied to the
result of <span data-x="trace a path">tracing</span> the shapes using the object implementing
the <code>CanvasText</code> interface for the line styles, and <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span> must be ignored.</p>
<p>These shapes are painted without affecting the current path, and are subject to <span
data-x="shadows">shadow effects</span>, <span data-x="concept-canvas-global-alpha">global
alpha</span>, the <span>clipping region</span>, and the <span>current compositing and blending
operator</span>.</p>
</li>
</ol>
<p>
<!--INSERT TRACKING-->
The <dfn method for="CanvasText"><code
data-x="dom-context-2d-measureText">measureText(<var>text</var>)</code></dfn> method steps are to
run the <span>text preparation algorithm</span>, passing it <var>text</var> and the object
implementing the <code>CanvasText</code> interface, and then using the returned <span>inline
box</span> must return a new <code>TextMetrics</code> object with members behaving as described in
the following list: <ref>CSS</ref></p>
</div>
<dl>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-width">width</code></dfn>
attribute</dt>
<dd><p>The width of that <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>. (The
text's advance width.)</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-actualBoundingBoxLeft">actualBoundingBoxLeft</code></dfn> attribute</dt>
<dd>
<p>The distance parallel to the baseline from the alignment point given by the <code
data-x="dom-context-2d-textAlign">textAlign</code> attribute to the left side of the bounding
rectangle of the given text, in <span data-x="'px'">CSS pixels</span>; positive numbers
indicating a distance going left from the given alignment point.
<p class="note">The sum of this value and the next (<code
data-x="dom-textmetrics-actualBoundingBoxRight">actualBoundingBoxRight</code>) can be wider than
the width of the <span>inline box</span> (<code data-x="dom-textmetrics-width">width</code>), in
particular with slanted fonts where characters overhang their advance width.</p>
</dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-actualBoundingBoxRight">actualBoundingBoxRight</code></dfn> attribute</dt>
<dd>
<p>The distance parallel to the baseline from the alignment point given by the <code
data-x="dom-context-2d-textAlign">textAlign</code> attribute to the right side of the bounding
rectangle of the given text, in <span data-x="'px'">CSS pixels</span>; positive numbers
indicating a distance going right from the given alignment point.</p>
</dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-fontBoundingBoxAscent">fontBoundingBoxAscent</code></dfn> attribute</dt>
<dd>
<p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>ascent
metric</span> of the <span>first available font</span>, in <span data-x="'px'">CSS
pixels</span>; positive numbers indicating a distance going up from the given baseline.</p>
<p class="note">This value and the next are useful when rendering a background that have to have
a consistent height even if the exact text being rendered changes. The <code
data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</code> attribute (and
its corresponding attribute for the descent) are useful when drawing a bounding box around
specific text.</p>
</dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-fontBoundingBoxDescent">fontBoundingBoxDescent</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>descent
metric</span> of the <span>first available font</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating a distance going down from the given baseline.</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</code></dfn> attribute</dt>
<dd>
<p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the top of the bounding
rectangle of the given text, in <span data-x="'px'">CSS pixels</span>; positive numbers
indicating a distance going up from the given baseline.
<p class="note">This number can vary greatly based on the input text, even if the first font
specified covers all the characters in the input. For example, the <code
data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</code> of a lowercase
"o" from an <span>alphabetic baseline</span> would be less than that of an uppercase "F". The
value can easily be negative; for example, the distance from the top of the em box (<code
data-x="dom-context-2d-textBaseline">textBaseline</code> value "<code
data-x="dom-context-2d-textBaseline-top">top</code>") to the top of the bounding rectangle when
the given text is just a single comma "<code data-x="">,</code>" would likely (unless the font is
quite unusual) be negative.</p>
</dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-actualBoundingBoxDescent">actualBoundingBoxDescent</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the bottom of the bounding
rectangle of the given text, in <span data-x="'px'">CSS pixels</span>; positive numbers
indicating a distance going down from the given baseline.</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-emHeightAscent">emHeightAscent</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>em-over
baseline</span> in the <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating that the given baseline is below the <span>em-over baseline</span>
(so this value will usually be positive). Zero if the given baseline is the <span>em-over
baseline</span>; half the font size if the given baseline is halfway between the <span>em-over
baseline</span> and the <span>em-under baseline</span>.</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-emHeightDescent">emHeightDescent</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>em-under
baseline</span> in the <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating that the given baseline is above the <span>em-under baseline</span>.
(Zero if the given baseline is the <span>em-under baseline</span>.)</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-hangingBaseline">hangingBaseline</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>hanging
baseline</span> of the <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating that the given baseline is below the <span>hanging baseline</span>.
(Zero if the given baseline is the <span>hanging baseline</span>.)</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-alphabeticBaseline">alphabeticBaseline</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>alphabetic
baseline</span> of the <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating that the given baseline is below the <span>alphabetic
baseline</span>. (Zero if the given baseline is the <span>alphabetic baseline</span>.)</p></dd>
<dt><dfn attribute for="TextMetrics"><code data-x="dom-textmetrics-ideographicBaseline">ideographicBaseline</code></dfn> attribute</dt>
<dd><p>The distance from the horizontal line indicated by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the <span>ideographic-under
baseline</span> of the <span>inline box</span>, in <span data-x="'px'">CSS pixels</span>;
positive numbers indicating that the given baseline is below the <span>ideographic-under
baseline</span>. (Zero if the given baseline is the <span>ideographic-under
baseline</span>.)</p></dd>
</dl>
<p class="note">Glyphs rendered using <code data-x="dom-context-2d-fillText">fillText()</code> and
<code data-x="dom-context-2d-strokeText">strokeText()</code> can spill out of the box given by the
font size and the width returned by <code data-x="dom-context-2d-measureText">measureText()</code>
(the text width). Authors are encouraged to use the bounding box values described above if this is
an issue.</p>
<p class="note">A future version of the 2D context API might provide a way to render fragments of
documents, rendered using CSS, straight to the canvas. This would be provided in preference to a
dedicated way of doing multiline layout.</p>
<h6>Drawing paths to the canvas</h6>
<p>Objects that implement the <code>CanvasDrawPath</code> interface have a <dfn>current default
path</dfn>. There is only one <span>current default path</span>, it is not part of the
<span>drawing state</span>. The <span>current default path</span> is a <span
data-x="concept-path">path</span>, as described above.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-beginPath">beginPath</span>()</code></dt>
<dd><p>Resets the <span>current default path</span>.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fill">fill</span>([ <var>fillRule</var> ])</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-fill">fill</span>(<var>path</var> [, <var>fillRule</var> ])</code></dt>
<dd>
<p>Fills the subpaths of the <span>current default path</span> or the given path with the
current fill style, obeying the given fill rule.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-stroke">stroke</span>()</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-stroke">stroke</span>(<var>path</var>)</code></dt>
<dd>
<p>Strokes the subpaths of the <span>current default path</span> or the given path with the
current stroke style.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-clip">clip</span>([ <var>fillRule</var> ])</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-clip">clip</span>(<var>path</var> [, <var>fillRule</var> ])</code></dt>
<dd>
<p>Further constrains the clipping region to the <span>current default path</span> or the given
path, using the given fill rule to determine what points are in the path.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-isPointInPath">isPointInPath</span>(<var>x</var>, <var>y</var> [, <var>fillRule</var> ])</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-isPointInPath">isPointInPath</span>(<var>path</var>, <var>x</var>, <var>y</var> [, <var>fillRule</var> ])</code></dt>
<dd>
<p>Returns true if the given point is in the <span>current default path</span> or the given
path, using the given fill rule to determine what points are in the path.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-isPointInStroke">isPointInStroke</span>(<var>x</var>, <var>y</var>)</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-isPointInStroke">isPointInStroke</span>(<var>path</var>, <var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Returns true if the given point would be in the region covered by the stroke of the
<span>current default path</span> or the given path, given the current stroke style.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-beginPath">beginPath()</code></dfn> method steps are to empty the list of
subpaths in <span>this</span>'s <span>current default path</span> so that it once again has zero
subpaths.</p>
<p>Where the following method definitions use the term <dfn>intended path</dfn> for a
<code>Path2D</code>-or-null <var>path</var>, it means <var>path</var> itself if it is a
<code>Path2D</code> object, or the <span>current default path</span> otherwise.</p>
<p>When the <span>intended path</span> is a <code>Path2D</code> object, the coordinates and lines
of its subpaths must be transformed according to the <span
data-x="dom-context-2d-transformation"> current transformation matrix</span> on the object
implementing the <code>CanvasTransform</code> interface when used by these methods (without
affecting the <code>Path2D</code> object itself). When the intended path is the <span>current
default path</span>, it is not affected by the transform. (This is because transformations
already affect the <span>current default path</span> when it is constructed, so applying it when
it is painted as well would result in a double transformation.)</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-fill">fill(<var>fillRule</var>)</code></dfn> method steps are to run the
<span>fill steps</span> given <span>this</span>, null, and <var>fillRule</var>.</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-fill-path">fill(<var>path</var>, <var>fillRule</var>)</code></dfn> method
steps are to run the <span>fill steps</span> given <span>this</span>, <var>path</var>, and
<var>fillRule</var>.</p>
<p>The <dfn>fill steps</dfn>, given a <code>CanvasDrawPath</code> <var>context</var>, a
<code>Path2D</code>-or-null <var>path</var>, and a <span>fill rule</span> <var>fillRule</var>,
are to fill all the subpaths of the <span>intended path</span> for <var>path</var>, using
<var>context</var>'s <span data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span>,
and using the <span>fill rule</span> indicated by <var>fillRule</var>. Open subpaths must be
implicitly closed when being filled (without affecting the actual subpaths).</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-stroke">stroke()</code></dfn> method steps are to run the <span>stroke
steps</span> given <span>this</span> and null.</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-stroke-path">stroke(<var>path</var>)</code></dfn> method steps are to run
the <span>stroke steps</span> given <span>this</span> and <var>path</var>.</p>
<p>The <dfn>stroke steps</dfn>, given a <code>CanvasDrawPath</code> <var>context</var> and a
<code>Path2D</code>-or-null <var>path</var>, are to <span data-x="trace a path">trace</span> the
<span>intended path</span> for <var>path</var>, using <var>context</var>'s line styles as set by
its <code>CanvasPathDrawingStyles</code> mixin, and then fill the resulting path using
<var>context</var>'s <span data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke
style</span>, using the <span data-x="dom-context-2d-fillRule-nonzero">nonzero winding
rule</span>.</p>
<p class="note">As a result of how the algorithm to <span>trace a path</span> is defined,
overlapping parts of the paths in one stroke operation are treated as if their union was what was
painted.</p>
<p class="note">The stroke <em>style</em> is affected by the transformation during painting, even
if the <span>current default path</span> is used.</p>
<p>Paths, when filled or stroked, must be painted without affecting the <span>current default
path</span> or any <code>Path2D</code> objects, and must be subject to <span
data-x="shadows">shadow effects</span>, <span data-x="concept-canvas-global-alpha">global
alpha</span>, the <span>clipping region</span>, and the <span>current compositing and blending
operator</span>. (The effect of transformations is described above and varies based on which path
is being used.)</p>
<hr>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-clip">clip(<var>fillRule</var>)</code></dfn> method steps are to run the
<span>clip steps</span> given <span>this</span>, null, and <var>fillRule</var>.</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-clip-path">clip(<var>path</var>, <var>fillRule</var>)</code></dfn> method
steps are to run the <span>clip steps</span> given <span>this</span>, <var>path</var>, and
<var>fillRule</var>.</p>
<p>The <dfn>clip steps</dfn>, given a <code>CanvasDrawPath</code> <var>context</var>, a
<code>Path2D</code>-or-null <var>path</var>, and a <span>fill rule</span> <var>fillRule</var>,
are to create a new <dfn>clipping region</dfn> by calculating the intersection of
<var>context</var>'s current clipping region and the area described by the <span>intended
path</span> for <var>path</var>, using the <span>fill rule</span> indicated by
<var>fillRule</var>. Open subpaths must be implicitly closed when computing the clipping region,
without affecting the actual subpaths. The new clipping region replaces the current clipping
region.</p>
<p>When the context is initialized, its current clipping region must be set to the largest
infinite surface (i.e. by default, no clipping occurs).</p>
<!-- v6
Jordan OSETE suggests:
* support ways of extending the clipping region (union instead of intersection)
- also "add", "subtract", "replace", "intersect" and "xor"
- maybe just support creating unions, intersections, and other -ions of paths
-->
<hr>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-isPointInPath">isPointInPath(<var>x</var>, <var>y</var>,
<var>fillRule</var>)</code></dfn> method steps are to return the result of the <span>is point in
path steps</span> given <span>this</span>, null, <var>x</var>, <var>y</var>, and
<var>fillRule</var>.</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-isPointInPath-path">isPointInPath(<var>path</var>, <var>x</var>,
<var>y</var>, <var>fillRule</var>)</code></dfn> method steps are to return the result of the
<span>is point in path steps</span> given <span>this</span>, <var>path</var>, <var>x</var>, <var>y</var>,
and <var>fillRule</var>.</p>
<p>The <dfn>is point in path steps</dfn>, given a <code>CanvasDrawPath</code> <var>context</var>,
a <code>Path2D</code>-or-null <var>path</var>, two numbers <var>x</var> and <var>y</var>, and a
<span>fill rule</span> <var>fillRule</var>, are:</p>
<ol>
<li><p>If <var>x</var> or <var>y</var> are infinite or NaN, then return false.</p></li>
<li><p>If the point given by the <var>x</var> and <var>y</var> coordinates, when treated as
coordinates in the canvas coordinate space unaffected by the current transformation, is inside
the <span>intended path</span> for <var>path</var> as determined by the <span>fill rule</span>
indicated by <var>fillRule</var>, then return true. Open subpaths must be implicitly closed when
computing the area inside the path, without affecting the actual subpaths. Points on the path
itself must be considered to be inside the path.</p></li>
<li><p>Return false.</p></li>
</ol>
<hr>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-isPointInStroke">isPointInStroke(<var>x</var>, <var>y</var>)</code></dfn>
method steps are to return the result of the <span>is point in stroke steps</span> given
<span>this</span>, null, <var>x</var>, and <var>y</var>.</p>
<p>The <dfn method for="CanvasDrawPath"><code
data-x="dom-context-2d-isPointInStroke-path">isPointInStroke(<var>path</var>, <var>x</var>,
<var>y</var>)</code></dfn> method steps are to return the result of the <span>is point in stroke
steps</span> given <span>this</span>, <var>path</var>, <var>x</var>, and <var>y</var>.</p>
<p>The <dfn>is point in stroke steps</dfn>, given a <code>CanvasDrawPath</code>
<var>context</var>, a <code>Path2D</code>-or-null <var>path</var>, and two numbers <var>x</var>
and <var>y</var>, are:</p>
<ol>
<li><p>If <var>x</var> or <var>y</var> are infinite or NaN, then return false.</p></li>
<li><p>If the point given by the <var>x</var> and <var>y</var> coordinates, when treated as
coordinates in the canvas coordinate space unaffected by the current transformation, is inside
the path that results from <span data-x="trace a path">tracing</span> the <span>intended
path</span> for <var>path</var>, using the <span
data-x="dom-context-2d-fillRule-nonzero">nonzero winding rule</span>, and using
<var>context</var>'s line styles as set by its <code>CanvasPathDrawingStyles</code> mixin, then
return true. Points on the resulting path must be considered to be inside the path.</p></li>
<li><p>Return false.</p></li>
</ol>
<hr>
</div>
<div class="example" id="drawCustomFocusRingExample">
<p>This <code>canvas</code> element has a couple of checkboxes. The path-related commands are
highlighted:</p>
<pre><code class="html"><canvas height=400 width=750>
<label><input type=checkbox id=showA> Show As</label>
<label><input type=checkbox id=showB> Show Bs</label>
<!-- ... -->
</canvas>
<script>
function drawCheckbox(context, element, x, y, paint) {
context.save();
context.font = '10px sans-serif';
context.textAlign = 'left';
context.textBaseline = 'middle';
var metrics = context.measureText(element.labels[0].textContent);
if (paint) {
<strong> context.beginPath();
context.strokeStyle = 'black';
context.rect(x-5, y-5, 10, 10);
context.stroke();
</strong> if (element.checked) {
<strong> context.fillStyle = 'black';
context.fill();
</strong> }
context.fillText(element.labels[0].textContent, x+5, y);
}
<strong> context.beginPath();
context.rect(x-7, y-7, 12 + metrics.width+2, 14);
</strong>
context.drawFocusIfNeeded(element);
context.restore();
}
function drawBase() { /* ... */ }
function drawAs() { /* ... */ }
function drawBs() { /* ... */ }
function redraw() {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
context.clearRect(0, 0, canvas.width, canvas.height);
drawCheckbox(context, document.getElementById('showA'), 20, 40, true);
drawCheckbox(context, document.getElementById('showB'), 20, 60, true);
drawBase();
if (document.getElementById('showA').checked)
drawAs();
if (document.getElementById('showB').checked)
drawBs();
}
function processClick(event) {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
var x = event.clientX;
var y = event.clientY;
var node = event.target;
while (node) {
x -= node.offsetLeft - node.scrollLeft;
y -= node.offsetTop - node.scrollTop;
node = node.offsetParent;
}
drawCheckbox(context, document.getElementById('showA'), 20, 40, false);
if (<strong>context.isPointInPath(x, y)</strong>)
document.getElementById('showA').checked = !(document.getElementById('showA').checked);
drawCheckbox(context, document.getElementById('showB'), 20, 60, false);
if (<strong>context.isPointInPath(x, y)</strong>)
document.getElementById('showB').checked = !(document.getElementById('showB').checked);
redraw();
}
document.getElementsByTagName('canvas')[0].addEventListener('focus', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('blur', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('change', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('click', processClick, false);
redraw();
</script></code></pre>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=340 -->
</div>
<h6 id="drawing-focus-rings-and-scrolling-paths-into-view">Drawing focus rings</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-drawFocusIfNeeded">drawFocusIfNeeded</span>(<var>element</var>)</code></dt>
<dd>
<p>If <var>element</var> is <span>focused</span>, draws a focus ring around the <span>current
default path</span>, following the platform conventions for focus rings.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-drawFocusIfNeeded-path-element">drawFocusIfNeeded</span>(<var>path</var>, <var>element</var>)</code></dt>
<dd>
<p>If <var>element</var> is <span>focused</span>, draws a focus ring around <var>path</var>,
following the platform conventions for focus rings.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasUserInterface</code> interface provide the following
methods to draw focus rings.</p>
<p id="dom-context-2d-drawosfocusring">The <dfn method for="CanvasUserInterface"><code
data-x="dom-context-2d-drawFocusIfNeeded">drawFocusIfNeeded(<var>element</var>)</code></dfn>
method steps are to <span>draw focus if needed</span> given <span>this</span>,
<var>element</var>, and <span>this</span>'s <span>current default path</span>.</p>
<!--
This treats a Path2D as a concept-path. Ideally Path2Ds would have an internal slot holding
a concept-path, but for now they don't...
-->
<p>The <dfn method for="CanvasUserInterface"><code
data-x="dom-context-2d-drawFocusIfNeeded-path-element">drawFocusIfNeeded(<var>path</var>,
<var>element</var>)</code></dfn> method steps are to <span>draw focus if needed</span> given
<span>this</span>, <var>element</var>, and <var>path</var>.</p>
<p>To <dfn>draw focus if needed</dfn>, given an object implementing
<code>CanvasUserInterface</code> <var>context</var>, an element <var>element</var>, and a <span
data-x="concept-path">path</span> <var>path</var>:</p>
<ol>
<li><p>If <var>element</var> is not <span>focused</span> or is not a descendant of
<var>context</var>'s <code>canvas</code> element, then return.</p></li>
<li>
<p>Draw a focus ring of the appropriate style along <var>path</var>, following platform
conventions.</p>
<p class="note">Some platforms only draw focus rings around elements that have been focused from
the keyboard, and not those focused from the mouse. Other platforms simply don't draw focus
rings around some elements at all unless relevant accessibility features are enabled. This API
is intended to follow these conventions. User agents that implement distinctions based on the
manner in which the element was focused are encouraged to classify focus driven by the <code
data-x="dom-focus">focus()</code> method based on the kind of user interaction event from which
the call was triggered (if any).</p>
<p>The focus ring should not be subject to the <span data-x="shadows">shadow effects</span>,
the <span data-x="concept-canvas-global-alpha">global alpha</span>, the <span>current
compositing and blending operator</span>, the <span
data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span>, the <span
data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</span>, or any of the members
in the <code>CanvasPathDrawingStyles</code>, <code>CanvasTextDrawingStyles</code> interfaces,
but <em>should</em> be subject to the <span>clipping region</span>. (The effect of
transformations is described above and varies based on which path is being used.)</p>
</li>
<li><p><a href="#inform">Inform the user</a> that the focus is at the location given by the
intended path. User agents may wait until the next time the <span>event loop</span> reaches its
<span>update the rendering</span> step to optionally inform the user.</p></li>
</ol>
<p>User agents should not implicitly close open subpaths in the intended path when drawing the
focus ring.</p>
<p class="note">This might be a moot point, however. For example, if the focus ring is drawn as an
axis-aligned bounding rectangle around the points in the intended path, then whether the subpaths
are closed or not has no effect. This specification intentionally does not specify precisely how
focus rings are to be drawn: user agents are expected to honor their platform's native
conventions.</p>
<p id="inform">"Inform the user", as used in this section, does not imply any persistent state
change. It could mean, for instance, calling a system accessibility API to notify assistive
technologies such as magnification tools so that the user's magnifier moves to the given area of
the canvas. However, it does not associate the path with the element, or provide a region for
tactile feedback, etc.</p>
</div>
<h6>Drawing images</h6>
<p>Objects that implement the <code>CanvasDrawImage</code> interface have the <dfn method
for="CanvasDrawImage"><code data-x="dom-context-2d-drawImage">drawImage()</code></dfn> method to
draw images.</p>
<div w-nodev>
<p>This method can be invoked with three different sets of arguments:</p>
<ul class="brief">
<li><code data-x="">drawImage(<var>image</var>, <var>dx</var>, <var>dy</var>)</code>
<li><code data-x="">drawImage(<var>image</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code>
<li><code data-x="">drawImage(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code>
</ul>
</div>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-drawImage">drawImage</span>(<var>image</var>, <var>dx</var>, <var>dy</var>)</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-drawImage">drawImage</span>(<var>image</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code></dt>
<dt><code data-x=""><var>context</var>.<span data-x="dom-context-2d-drawImage">drawImage</span>(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code></dt>
<dd>
<p>Draws the given image onto the canvas. The arguments are interpreted as follows:</p>
<p><img src="/images/drawImage.png" width="356" height="356" alt="The sx and sy parameters give
the x and y coordinates of the source rectangle; the sw and sh arguments give the width and
height of the source rectangle; the dx and dy give the x and y coordinates of the destination
rectangle; and the dw and dh arguments give the width and height of the destination
rectangle."></p>
<p>If the image isn't yet fully decoded, then nothing is drawn. If the image is a canvas with no
data, throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>When the <code data-x="dom-context-2d-drawImage">drawImage()</code> method is invoked, the user
agent must run these steps:</p>
<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>
<li><p>Let <var>usability</var> be the result of <span data-x="check the usability of the image
argument">checking the usability of <var>image</var></span>.</p></li>
<li><p>If <var>usability</var> is <i>bad</i>, then return (without drawing anything).</p></li>
<li>
<p>Establish the source and destination rectangles as follows:</p>
<p>If not specified, the <var>dw</var> and <var>dh</var> arguments must default to the values of
<var>sw</var> and <var>sh</var>, interpreted such that one <span data-x="'px'">CSS pixel</span>
in the image is treated as one unit in the <span>output bitmap</span>'s coordinate space. If the
<var>sx</var>, <var>sy</var>, <var>sw</var>, and <var>sh</var> arguments are omitted, then they
must default to 0, 0, the image's <span>natural width</span> in image pixels, and the image's
<span>natural height</span> in image pixels, respectively. If the image has no <span>natural
dimensions</span>, then the <i>concrete object size</i> must be used instead, as determined
using the CSS "<a href="https://drafts.csswg.org/css-images/#default-sizing">Concrete Object
Size Resolution</a>" algorithm, with the <i>specified size</i> having neither a definite width
nor height, nor any additional constraints, the object's natural properties being those of the
<var>image</var> argument, and the <span>default object size</span> being the size of the
<span>output bitmap</span>. <ref>CSSIMAGES</ref></p>
<p>The source rectangle is the rectangle whose corners are the four points (<var>sx</var>, <var>sy</var>), (<var>sx</var>+<var>sw</var>, <var>sy</var>), (<var>sx</var>+<var>sw</var>, <var>sy</var>+<var>sh</var>),
(<var>sx</var>, <var>sy</var>+<var>sh</var>).</p>
<p>The destination rectangle is the rectangle whose corners are the four points (<var>dx</var>, <var>dy</var>), (<var>dx</var>+<var>dw</var>, <var>dy</var>), (<var>dx</var>+<var>dw</var>, <var>dy</var>+<var>dh</var>),
(<var>dx</var>, <var>dy</var>+<var>dh</var>).</p>
<p>When the source rectangle is outside the source image, the source rectangle must be clipped
to the source image and the destination rectangle must be clipped in the same proportion.</p>
<p class="note">When the destination rectangle is outside the destination image (the
<span>output bitmap</span>), the pixels that land outside the <span>output bitmap</span> are
discarded, as if the destination was an infinite canvas whose rendering was clipped to the
dimensions of the <span>output bitmap</span>.</p>
</li>
<li><p>If one of the <var>sw</var> or <var>sh</var> arguments is zero, then return. Nothing is
painted.</p></li>
<li>
<p>Paint the region of the <var>image</var> argument specified by the source rectangle
on the region of the rendering context's <span>output bitmap</span> specified by the
destination rectangle, after applying the <span data-x="dom-context-2d-transformation">current
transformation matrix</span> to the destination rectangle.</p>
<p>The image data must be processed in the original direction, even if the dimensions given are
negative. <!-- note: that last sentence has several times been needed to correct people who
suggested that 5,5,-2,-2 was different than 3,3,2,2 --></p>
<p>When scaling up, if the <code
data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code> attribute is set to
true, the user agent should attempt to apply a smoothing algorithm to the image data when it is
scaled. User agents which support multiple filtering algorithms may use the value of the <code
data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</code> attribute to guide
the choice of filtering algorithm when the <code
data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code> attribute is set to
true. Otherwise, the image must be rendered using nearest-neighbor interpolation.</p>
<p class="note">This specification does not define the precise algorithm to use when scaling an
image down, or when scaling an image up when the <code
data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code> attribute is set to
true.</p>
<p class="note">When a <code>canvas</code> element is drawn onto itself, the <span>drawing
model</span> requires the source to be copied before the image is drawn, so it is possible to
copy parts of a <code>canvas</code> element onto overlapping parts of itself.</p>
<p>If the original image data is a bitmap image, then the value painted at a point in the
destination rectangle is computed by filtering the original image data. The user agent may use
any filtering algorithm (for example bilinear interpolation or nearest-neighbor). When the
filtering algorithm requires a pixel value from outside the original image data, it must instead
use the value from the nearest edge pixel. (That is, the filter uses 'clamp-to-edge' behavior.)
When the filtering algorithm requires a pixel value from outside the source rectangle but inside
the original image data, then the value from the original image data must be used.</p>
<!-- see CORE-32111 and:
https://krijnhoetmer.nl/irc-logs/whatwg/20100818#l-737
https://www.w3.org/Bugs/Public/show_bug.cgi?id=10799#c11
-->
<!-- createPattern() has a similar paragraph with different rules -->
<p class="note">Thus, scaling an image in parts or in whole will have the same effect. This does
mean that when sprites coming from a single sprite sheet are to be scaled, adjacent images in
the sprite sheet can interfere. This can be avoided by ensuring each sprite in the sheet is
surrounded by a border of <span>transparent black</span>, or by copying sprites to be scaled
into temporary <code>canvas</code> elements and drawing the scaled sprites from there.</p>
<p>Images are painted without affecting the current path, and are subject to <span
data-x="shadows">shadow effects</span>, <span data-x="concept-canvas-global-alpha">global
alpha</span>, the <span>clipping region</span>, and the <span>current compositing and blending
operator</span>.</p>
</li>
<li><p>If <var>image</var> <span>is not origin-clean</span>, then set the
<code>CanvasRenderingContext2D</code>'s <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag to false.</p></li>
</ol>
</div>
<h6><dfn>Pixel manipulation</dfn></h6>
<dl class="domintro">
<dt><code data-x=""><var>imageData</var> = new <span subdfn data-x="dom-imagedata">ImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
<dd>
<p>Returns an <code>ImageData</code> object with the given dimensions and the color space
indicated by <var>settings</var>. All the pixels in the returned object are <span>transparent
black</span>.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if either of
the width or height arguments are zero.</p>
</dd>
<dt><code data-x=""><var>imageData</var> = new <span subdfn data-x="dom-imagedata-with-data">ImageData</span>(<var>data</var>, <var>sw</var> [, <var>sh</var> [, <var>settings</var> ] ])</code></dt>
<dd>
<p>Returns an <code>ImageData</code> object using the data provided in the <code
data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> argument, interpreted using the given
dimensions and the color space indicated by <var>settings</var>.</p>
<p>As each pixel in the data is represented by four numbers, the length of the data needs to be
a multiple of four times the given width. If the height is provided as well, then the length
needs to be exactly the width times the height times 4.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the given
data and dimensions can't be interpreted consistently, or if either dimension is zero.</p>
</dd>
<dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<var>imageData</var>)</code></dt>
<dd><p>Returns an <code>ImageData</code> object with the same dimensions and color space as the
argument. All the pixels in the returned object are <span>transparent black</span>.</p></dd>
<dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData">createImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
<dd>
<p>Returns an <code>ImageData</code> object with the given dimensions. The color space of the
returned object is the <span data-x="concept-canvas-color-space">color space</span> of
<var>context</var> unless overridden by <var>settings</var>. All the pixels in the returned
object are <span>transparent black</span>.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if either of
the width or height arguments are zero.</p>
</dd>
<dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-getImageData">getImageData</span>(<var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
<dd>
<p>Returns an <code>ImageData</code> object containing the image data for the given rectangle of
the bitmap. The color space of the returned object is the <span
data-x="concept-canvas-color-space">color space</span> of <var>context</var> unless overridden
by <var>settings</var>.</p>
<p>Throws an <span>"<code>IndexSizeError</code>"</span> <code>DOMException</code> if the either
of the width or height arguments are zero.</p>
</dd>
<dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-width">width</span></code></dt>
<dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-height">height</span></code></dt>
<dd><p>Returns the actual dimensions of the data in the <code>ImageData</code> object, in
pixels.</p></dd>
<dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-data">data</span></code></dt>
<dd><p>Returns the one-dimensional array containing the data in RGBA order, as integers in the
range 0 to 255.</p></dd>
<dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-colorSpace">colorSpace</span></code></dt>
<dd><p>Returns the color space of the pixels.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-putImageData">putImageData</span>(<var>imageData</var>, <var>dx</var>, <var>dy</var> [, <var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, <var>dirtyHeight</var> ])</code></dt>
<dd>
<p>Paints the data from the given <code>ImageData</code> object onto the bitmap. If a dirty
rectangle is provided, only the pixels from that rectangle are painted.</p>
<p>The <code data-x="dom-context-2d-globalAlpha">globalAlpha</code> and <code
data-x="dom-context-2d-globalCompositeOperation">globalCompositeOperation</code> properties, as
well as the <span data-x="shadows">shadow attributes</span>, are ignored for the purposes of
this method call; pixels in the canvas are replaced wholesale, with no composition, alpha
blending, no shadows, etc.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
<var>imageData</var> object's <code data-x="dom-imagedata-data">data</code> attribute value's
[[ViewedArrayBuffer]] internal slot is detached.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasImageData</code> interface provide the following methods
for reading and writing pixel data to the bitmap.</p>
<p>The <dfn constructor for="ImageData"><code data-x="dom-imagedata">new ImageData(<var>sw</var>,
<var>sh</var>, <var>settings</var>)</code></dfn> constructor steps are:</p>
<ol>
<li><p>If one or both of <var>sw</var> and <var>sh</var> are zero, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span data-x="Initialize an ImageData object">Initialize</span> <span>this</span> given
<var>sw</var>, <var>sh</var>, and <i><span
data-x="initialize-imagedata-settings">settings</span></i> set to <var>settings</var>.</p></li>
<li><p>Initialize the image data of <span>this</span> to <span>transparent black</span>.</p></li>
</ol>
<p>The <dfn constructor for="ImageData"><code data-x="dom-imagedata-with-data">new
ImageData(<var>data</var>, <var>sw</var>, <var>sh</var>, <var>settings</var>)</code></dfn>
constructor steps are:</p>
<ol>
<li><p>Let <var>length</var> be the number of bytes in <var>data</var>.</p></li>
<li><p>If <var>length</var> is not a nonzero integral multiple of four, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>length</var> be <var>length</var> divided by four.</p>
<li>
<p>If <var>length</var> is not an integral multiple of <var>sw</var>, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p>
<p class="note">At this step, the length is guaranteed to be greater than zero (otherwise the
second step above would have aborted the steps), so if <var>sw</var> is zero, this
step will throw the exception and return.</p>
</li>
<li><p>Let <var>height</var> be <var>length</var> divided by <var>sw</var>.</p></li>
<li><p>If <var>sh</var> was given and its value is not equal to <var>height</var>, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p><span data-x="Initialize an ImageData object">Initialize</span> <span>this</span> given
<var>sw</var>, <var>sh</var>, <i><span
data-x="initialize-imagedata-settings">settings</span></i> set to <var>settings</var>, and
<i><span data-x="initialize-imagedata-source">source</span></i> set to <var>data</var>.</p>
<p class="note">This step does not set <span>this</span>'s data to a copy of <var>data</var>.
It sets it to the actual <code data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> object
passed as <var>data</var>.</p>
</li>
</ol>
<p>The <dfn method for="CanvasImageData"><code
data-x="dom-context-2d-createimagedata">createImageData(<var>sw</var>, <var>sh</var>,
<var>settings</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If one or both of <var>sw</var> and <var>sh</var> are zero, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>newImageData</var> be a <span>new</span> <code>ImageData</code> object.</p></li>
<li><p><span data-x="Initialize an ImageData object">Initialize</span> <var>newImageData</var>
given the absolute magnitude of <var>sw</var>, the absolute magnitude of <var>sh</var>, <i><span
data-x="initialize-imagedata-settings">settings</span></i> set to <var>settings</var>, and
<i><span data-x="initialize-imagedata-defaultcolorspace">defaultColorSpace</span></i> set to
<span>this</span>'s <span data-x="concept-canvas-color-space">color space</span>.</p></li>
<li><p>Initialize the image data of <var>newImageData</var> to <span>transparent
black</span>.</p></li>
<li><p>Return <var>newImageData</var>.</p></li>
</ol>
<p>The <dfn method for="CanvasImageData"><code
data-x="dom-context-2d-createimagedata-imagedata">createImageData(<var>imageData</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>Let <var>newImageData</var> be a <span>new</span> <code>ImageData</code> object.</p></li>
<li><p><span data-x="Initialize an ImageData object">Initialize</span> <var>newImageData</var>
given the value of <var>imageData</var>'s <code data-x="dom-imagedata-width">width</code>
attribute, the value of <var>imageData</var>'s <code data-x="dom-imagedata-height">height</code>
attribute, and <i><span
data-x="initialize-imagedata-defaultcolorspace">defaultColorSpace</span></i> set to the value of
<var>imageData</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code> attribute.</p></li>
<li><p>Initialize the image data of <var>newImageData</var> to <span>transparent
black</span>.</p></li>
<li><p>Return <var>newImageData</var>.</p></li>
</ol>
<p>The <dfn method for="CanvasImageData"><code
data-x="dom-context-2d-getImageData">getImageData(<var>sx</var>, <var>sy</var>, <var>sw</var>,
<var>sh</var>, <var>settings</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If either the <var>sw</var> or <var>sh</var> arguments are zero, then throw an
<span>"<code>IndexSizeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the <code>CanvasRenderingContext2D</code>'s <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag is set to false, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>imageData</var> be a <span>new</span> <code>ImageData</code> object.</p></li>
<li><p><span data-x="Initialize an ImageData object">Initialize</span> <var>imageData</var> given
<var>sw</var>, <var>sh</var>, <i><span
data-x="initialize-imagedata-settings">settings</span></i> set to <var>settings</var>, and
<i><span data-x="initialize-imagedata-defaultcolorspace">defaultColorSpace</span></i> set to
<span>this</span>'s <span data-x="concept-canvas-color-space">color space</span>.</p></li>
<li><p>Let the source rectangle be the rectangle whose corners are the four points
(<var>sx</var>, <var>sy</var>), (<span data-x=""><var>sx</var>+<var>sw</var></span>,
<var>sy</var>), (<span data-x=""><var>sx</var>+<var>sw</var></span>, <span
data-x=""><var>sy</var>+<var>sh</var></span>), (<var>sx</var>,
<var>sy</var>+<var>sh</var>).</p></li>
<li><p>Set the pixel values of <var>imageData</var> to be the pixels of <span>this</span>'s
<span>output bitmap</span> in the area specified by the source rectangle in the bitmap's
coordinate space units, converted from <span>this</span>'s <span
data-x="concept-canvas-color-space">color space</span> to <var>imageData</var>'s <code
data-x="dom-imagedata-colorSpace">colorSpace</code> using <span>'relative-colorimetric'</span>
rendering intent.</p></li>
<li><p>Set the pixels values of <var>imageData</var> for areas of the source rectangle that are
outside of the <span>output bitmap</span> to <span>transparent black</span>.</p></li>
<li><p>Return <var>imageData</var>.</p></li>
</ol>
<p>To <dfn>initialize an <code>ImageData</code> object</dfn> <var>imageData</var>, given a
positive integer number of rows <var>rows</var>, a positive integer number of pixels per row
<var>pixelsPerRow</var>, an optional <code>ImageDataSettings</code> <dfn
data-x="initialize-imagedata-settings"><var>settings</var></dfn>, an optional <code
data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> <dfn
data-x="initialize-imagedata-source"><var>source</var></dfn>, and an optional
<code>PredefinedColorSpace</code> <dfn
data-x="initialize-imagedata-defaultcolorspace"><var>defaultColorSpace</var></dfn>:</p>
<ol>
<li><p>If <var>source</var> was given, then initialize the <dfn attribute for="ImageData"><code
data-x="dom-imagedata-data">data</code></dfn> attribute of <var>imageData</var> to
<var>source</var>.</p></li>
<li>
<p>Otherwise (<var>source</var> was not given), initialize the <code
data-x="dom-imagedata-data">data</code> attribute of <var>imageData</var> to a new <code
data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> object. The <code
data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> object must use a new <span>Canvas
Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span> for its storage, and must have a
zero start offset and a length equal to the length of its storage, in bytes. The <span>Canvas
Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span> must have the correct size to
store <var>rows</var> × <var>pixelsPerRow</var> pixels.</p>
<p>If the <span>Canvas Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span> cannot be
allocated, then rethrow the <code data-x="js-RangeError">RangeError</code> thrown by JavaScript,
and return.</p>
</li>
<li><p>Initialize the <dfn attribute for="ImageData"><code
data-x="dom-imagedata-width">width</code></dfn> attribute of <var>imageData</var> to
<var>pixelsPerRow</var>.</p></li>
<li><p>Initialize the <dfn attribute for="ImageData"><code
data-x="dom-imagedata-height">height</code></dfn> attribute of <var>imageData</var> to
<var>rows</var>.</p></li>
<li><p>If <var>settings</var> was given and <var>settings</var>["<code
data-x="dom-ImageDataSettings-colorSpace">colorSpace</code>"] <span data-x="map
exists">exists</span>, then initialize the <dfn attribute for="ImageData"><code
data-x="dom-imagedata-colorSpace">colorSpace</code></dfn> attribute of <var>imageData</var> to
<var>settings</var>["<dfn dict-member for="ImageDataSettings"><code
data-x="dom-ImageDataSettings-colorSpace">colorSpace</code></dfn>"].</p></li>
<li><p>Otherwise, if <var>defaultColorSpace</var> was given, then initialize the <code
data-x="dom-imagedata-colorSpace">colorSpace</code> attribute of <var>imageData</var> to
<var>defaultColorSpace</var>.</p></li>
<li><p>Otherwise, initialize the <code data-x="dom-imagedata-colorSpace">colorSpace</code>
attribute of <var>imageData</var> to "<span
data-x="dom-PredefinedColorSpace-srgb">srgb</span>".</p></li>
</ol>
<p><code>ImageData</code> objects are <span>serializable objects</span>. Their <span>serialization
steps</span>, given <var>value</var> and <var>serialized</var>, are:</p>
<ol>
<li><p>Set <var>serialized</var>.[[Data]] to the <span>sub-serialization</span> of the value of
<var>value</var>'s <code data-x="dom-imagedata-data">data</code> attribute.</p></li>
<li><p>Set <var>serialized</var>.[[Width]] to the value of <var>value</var>'s <code
data-x="dom-imagedata-width">width</code> attribute.</p></li>
<li><p>Set <var>serialized</var>.[[Height]] to the value of <var>value</var>'s <code
data-x="dom-imagedata-height">height</code> attribute.</p></li>
<li><p>Set <var>serialized</var>.[[ColorSpace]] to the value of <var>value</var>'s <code
data-x="dom-imagedata-colorSpace">colorSpace</code> attribute.</p></li>
</ol>
<p>Their <span>deserialization steps</span>, given <var>serialized</var>, <var>value</var>,
and <var>targetRealm</var>, are:</p>
<ol>
<li><p>Initialize <var>value</var>'s <code data-x="dom-imagedata-data">data</code> attribute
to the <span>sub-deserialization</span> of <var>serialized</var>.[[Data]].</p></li>
<li><p>Initialize <var>value</var>'s <code data-x="dom-imagedata-width">width</code> attribute
to <var>serialized</var>.[[Width]].</p></li>
<li><p>Initialize <var>value</var>'s <code data-x="dom-imagedata-height">height</code> attribute
to <var>serialized</var>.[[Height]].</p></li>
<li><p>Initialize <var>value</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code>
attribute to <var>serialized</var>.[[ColorSpace]].</p></li>
</ol>
<p>A <dfn>Canvas Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></dfn> is an <code
data-x="idl-ArrayBuffer">ArrayBuffer</code> whose data is represented in left-to-right order, row
by row top to bottom, starting with the top left, with each pixel's red, green, blue, and alpha
components being given in that order for each pixel. Each component of each pixel represented in
this array must be in the range 0..255, representing the 8 bit value for that component. The
components must be assigned consecutive indices starting with 0 for the top left pixel's red
component.</p>
<p>The <dfn method for="CanvasImageData"><code
data-x="dom-context-2d-putImageData-short">putImageData(<var>imageData</var>,
<var>dx</var>, <var>dy</var>)</code></dfn> method steps are to
<span data-x="dom-context2d-putImageData-common">put pixels from an
<code>ImageData</code> onto a bitmap</span>, given
<var>imageData</var>, <span>this</span>'s <span>output bitmap</span>,
<var>dx</var>, <var>dy</var>, 0, 0,
<var>imageData</var>'s <code data-x="dom-imagedata-width">width</code>, and
<var>imageData</var>'s <code data-x="dom-imagedata-height">height</code>.</p>
<p>The <dfn method for="CanvasImageData"><code
data-x="dom-context-2d-putImageData">putImageData(<var>imageData</var>,
<var>dx</var>, <var>dy</var>, <var>dirtyX</var>, <var>dirtyY</var>,
<var>dirtyWidth</var>, <var>dirtyHeight</var>)</code></dfn> method steps are to
<span data-x="dom-context2d-putImageData-common">put pixels from an
<code>ImageData</code> onto a bitmap</span>, given
<var>imageData</var>, <span>this</span>'s <span>output bitmap</span>,
<var>dx</var>, <var>dy</var>, <var>dirtyX</var>, <var>dirtyY</var>,
<var>dirtyWidth</var>, and <var>dirtyHeight</var>.</p>
<p>To <dfn data-x="dom-context2d-putImageData-common">put pixels from an <code>ImageData</code>
onto a bitmap</dfn>, given an <code>ImageData</code> <var>imageData</var>,
an <span>output bitmap</span> <var>bitmap</var>, and numbers <var>dx</var>, <var>dy</var>,
<var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, and <var>dirtyHeight</var>:</p>
<ol>
<li><p>Let <var>buffer</var> be <var>imageData</var>'s <code
data-x="dom-imagedata-data">data</code> attribute value's [[ViewedArrayBuffer]] internal
slot.</p></li>
<li><p>If <span>IsDetachedBuffer</span>(<var>buffer</var>) is true, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>If <var>dirtyWidth</var> is negative, then let <var>dirtyX</var> be <span
data-x=""><var>dirtyX</var>+<var>dirtyWidth</var></span>, and let <var>dirtyWidth</var> be equal
to the absolute magnitude of <var>dirtyWidth</var>.</p>
<p>If <var>dirtyHeight</var> is negative, then let <var>dirtyY</var> be <span
data-x=""><var>dirtyY</var>+<var>dirtyHeight</var></span>, and let <var>dirtyHeight</var> be
equal to the absolute magnitude of <var>dirtyHeight</var>.</p>
</li>
<li>
<p>If <var>dirtyX</var> is negative, then let <var>dirtyWidth</var> be <span
data-x=""><var>dirtyWidth</var>+<var>dirtyX</var></span>, and let <var>dirtyX</var> be zero.</p>
<p>If <var>dirtyY</var> is negative, then let <var>dirtyHeight</var> be <span
data-x=""><var>dirtyHeight</var>+<var>dirtyY</var></span>, and let <var>dirtyY</var> be zero.</p>
</li>
<li>
<p>If <var>dirtyX</var>+<var>dirtyWidth</var> is greater than the <code
data-x="dom-imagedata-width">width</code> attribute of the <var>imageData</var> argument, then
let <var>dirtyWidth</var> be the value of that <code data-x="dom-imagedata-width">width</code>
attribute, minus the value of <var>dirtyX</var>.</p>
<p>If <var>dirtyY</var>+<var>dirtyHeight</var> is greater than the <code
data-x="dom-imagedata-height">height</code> attribute of the <var>imageData</var> argument, then
let <var>dirtyHeight</var> be the value of that <code
data-x="dom-imagedata-height">height</code> attribute, minus the value of <var>dirtyY</var>.</p>
</li>
<li>
<p>If, after those changes, either <var>dirtyWidth</var> or <var>dirtyHeight</var> are negative
or zero, then return without affecting any bitmaps.</p>
</li>
<li><p>For all integer values of <var>x</var> and <var>y</var> where <span
data-x=""><var>dirtyX</var> ≤ <var>x</var> < <span
data-x=""><var>dirtyX</var>+<var>dirtyWidth</var></span></span> and <span
data-x=""><var>dirtyY</var> ≤ <var>y</var> < <span
data-x=""><var>dirtyY</var>+<var>dirtyHeight</var></span></span>,
set the pixel with coordinate (<span data-x=""><var>dx</var>+<var>x</var></span>,
<var>dy</var>+<var>y</var>) in <var>bitmap</var> to the color of the pixel at coordinate
(<var>x</var>, <var>y</var>) in the <var>imageData</var> data structure's
<span>Canvas Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span>,
converted from <var>imageData</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code>
to the <span data-x="concept-canvas-color-space">color space</span> of <var>bitmap</var>
using <span>'relative-colorimetric'</span> rendering intent.</p></li>
</ol>
<p class="note">Due to the lossy nature of converting between color spaces and converting to and
from <span data-x="concept-premultiplied-alpha">premultiplied alpha</span> color values, pixels
that have just been set using <code data-x="dom-context-2d-putImageData">putImageData()</code>,
and are not completely opaque, might be returned to an equivalent <code
data-x="dom-context-2d-getImageData">getImageData()</code> as different values.</p>
<p>The current path, <span data-x="dom-context-2d-transformation">transformation matrix</span>,
<span data-x="shadows">shadow attributes</span>, <span data-x="concept-canvas-global-alpha">global
alpha</span>, the <span>clipping region</span>, and <span>current compositing and blending
operator</span> must not affect the methods described in this section.</p>
</div>
<div class="example">
<p>In the following example, the script generates an <code>ImageData</code> object so that it can
draw onto it.</p>
<pre><code class="js">// canvas is a reference to a <canvas> element
var context = canvas.getContext('2d');
// create a blank slate
var data = context.createImageData(canvas.width, canvas.height);
// create some plasma
FillPlasma(data, 'green'); // green plasma
// add a cloud to the plasma
AddCloud(data, data.width/2, data.height/2); // put a cloud in the middle
// paint the plasma+cloud on the canvas
context.putImageData(data, 0, 0);
// support methods
function FillPlasma(data, color) { ... }
function AddCloud(data, x, y) { ... }</code></pre>
</div>
<div class="example">
<p>Here is an example of using <code
data-x="dom-context-2d-getImageData">getImageData()</code> and <code
data-x="dom-context-2d-putImageData">putImageData()</code> to implement an edge detection
filter.</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Edge detection demo</title>
<script>
var image = new Image();
function init() {
image.onload = demo;
image.src = "image.jpeg";
}
function demo() {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
// draw the image onto the canvas
context.drawImage(image, 0, 0);
// get the image data to manipulate
var input = context.getImageData(0, 0, canvas.width, canvas.height);
// get an empty slate to put the data into
var output = context.createImageData(canvas.width, canvas.height);
// alias some variables for convenience
// In this case input.width and input.height
// match canvas.width and canvas.height
// but we'll use the former to keep the code generic.
var w = input.width, h = input.height;
var inputData = input.data;
var outputData = output.data;
// edge detection
for (var y = 1; y < h-1; y += 1) {
for (var x = 1; x < w-1; x += 1) {
for (var c = 0; c < 3; c += 1) {
var i = (y*w + x)*4 + c;
outputData[i] = 127 + -inputData[i - w*4 - 4] - inputData[i - w*4] - inputData[i - w*4 + 4] +
-inputData[i - 4] + 8*inputData[i] - inputData[i + 4] +
-inputData[i + w*4 - 4] - inputData[i + w*4] - inputData[i + w*4 + 4];
}
outputData[(y*w + x)*4 + 3] = 255; // alpha
}
}
// put the image data back after manipulation
context.putImageData(output, 0, 0);
}
</script>
</head>
<body onload="init()">
<canvas></canvas>
</body>
</html></code></pre>
</div>
<div class="example">
<p>Here is an example of color space conversion applied when drawing a solid color and
reading the result back using and <code data-x=
"dom-context-2d-getImageData">getImageData()</code>.</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<title>Color space image data demo</title>
<canvas></canvas>
<script>
const canvas = document.querySelector('canvas');
const context = canvas.getContext('2d', {colorSpace:'display-p3'});
// Draw a red rectangle. Note that the hex color notation
// specifies sRGB colors.
context.fillStyle = "#FF0000";
context.fillRect(0, 0, 64, 64);
// Get the image data.
const pixels = context.getImageData(0, 0, 1, 1);
// This will print 'display-p3', reflecting the default behavior
// of returning image data in the canvas's color space.
console.log(pixels.colorSpace);
// This will print the values 234, 51, and 35, reflecting the
// red fill color, converted to 'display-p3'.
console.log(pixels.data[0]);
console.log(pixels.data[1]);
console.log(pixels.data[2]);
</script></code></pre>
</div>
<h6>Compositing</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-globalAlpha">globalAlpha</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current <span data-x="concept-canvas-global-alpha">global alpha</span> value
applied to rendering operations.</p>
<p>Can be set, to change the <span data-x="concept-canvas-global-alpha">global alpha</span>
value. Values outside of the range 0.0 .. 1.0 are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-globalCompositeOperation">globalCompositeOperation</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <span>current compositing and blending operator</span>, from the values defined
in <cite>Compositing and Blending</cite>. <ref>COMPOSITE</ref></p>
<p>Can be set, to change the <span>current compositing and blending operator</span>. Unknown
values are ignored.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasCompositing</code> interface have a <span
data-x="concept-canvas-global-alpha">global alpha</span> value and a <span>current compositing
and blending operator</span> value that both affect all the drawing operations on this
object.</p>
<!-- conformance criteria for painting are described in the "drawing model" section below -->
<p>The <dfn data-x="concept-canvas-global-alpha">global alpha</dfn> value gives an alpha value
that is applied to shapes and images before they are composited onto the <span>output bitmap</span>.
The value ranges from 0.0 (fully transparent) to 1.0 (no additional transparency). It must
initially have the value 1.0.</p>
<p>The <dfn attribute for="CanvasCompositing"><code
data-x="dom-context-2d-globalAlpha">globalAlpha</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-canvas-global-alpha">global alpha</span>.</p>
<p>The <code data-x="dom-context-2d-globalAlpha">globalAlpha</code> setter steps are:
<ol>
<li><p>If the given value is either infinite, NaN, or not in the range 0.0 to 1.0, then
return.</p></li>
<li><p>Otherwise, set <span>this</span>'s <span data-x="concept-canvas-global-alpha">global
alpha</span> to the given value.</p></li>
</ol>
<p>The <dfn>current compositing and blending operator</dfn> value controls how shapes and images
are drawn onto the <span>output bitmap</span>, once they have had the <span
data-x="concept-canvas-global-alpha">global alpha</span> and the <span>current transformation
matrix</span> applied. Initially, it must be set to "<code
data-x="gcop-source-over">source-over</code>".</p>
<p>The <dfn attribute for="CanvasCompositing"><code
data-x="dom-context-2d-globalCompositeOperation">globalCompositeOperation</code></dfn> getter
steps are to return <span>this</span>'s <span>current compositing and blending
operator</span>.</p>
<p>The <code
data-x="dom-context-2d-globalCompositeOperation">globalCompositeOperation</code> setter steps
are:</p>
<ol>
<li><p>If the given value is not <span>identical to</span> any of the values that the
<span><blend-mode></span> or the <span><composite-mode></span> properties are defined
to take, then return. <ref>COMPOSITE</ref></p></li>
<li><p>Otherwise, set <span>this</span>'s <span>current compositing and blending operator</span>
to the given value.</p></li>
</ol>
</div>
<h6>Image smoothing</h6>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns whether pattern fills and the <code
data-x="dom-context-2d-drawImage">drawImage()</code> method will attempt to smooth images if
their pixels don't line up exactly with the display, when scaling images up.</p>
<p>Can be set, to change whether images are smoothed (true) or not (false).</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current image-smoothing-quality preference.</p>
<p>Can be set, to change the preferred quality of image smoothing. The possible values are
"<code data-x="dom-context-2d-imageSmoothingQuality-low">low</code>", "<code
data-x="dom-context-2d-imageSmoothingQuality-medium">medium</code>" and "<code
data-x="dom-context-2d-imageSmoothingQuality-high">high</code>". Unknown values are ignored.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects that implement the <code>CanvasImageSmoothing</code> interface have attributes that
control how image smoothing is performed.</p>
<p>The <dfn attribute for="CanvasImageSmoothing"><code
data-x="dom-context-2d-imageSmoothingEnabled">imageSmoothingEnabled</code></dfn> attribute, on
getting, must return the last value it was set to. On setting, it must be set to the new value.
When the object implementing the <code>CanvasImageSmoothing</code> interface is created, the
attribute must be set to true.</p>
<p>The <dfn attribute for="CanvasImageSmoothing"><code
data-x="dom-context-2d-imageSmoothingQuality">imageSmoothingQuality</code></dfn> attribute, on
getting, must return the last value it was set to. On setting, it must be set to the new value.
When the object implementing the <code>CanvasImageSmoothing</code> interface is created, the
attribute must be set to "<code data-x="dom-context-2d-imageSmoothingQuality-low">low</code>".</p>
</div>
<h6><dfn>Shadows</dfn></h6>
<p>All drawing operations on an object which implements the <code>CanvasShadowStyles</code>
interface are affected by the four global shadow attributes.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-shadowColor">shadowColor</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current shadow color.</p>
<p>Can be set, to change the shadow color. Values that cannot be parsed as CSS colors are
ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current shadow offset.</p>
<p>Can be set, to change the shadow offset. Values that are not finite numbers are ignored.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-shadowBlur">shadowBlur</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current level of blur applied to shadows.</p>
<p>Can be set, to change the blur level. Values that are not finite numbers greater than or
equal to zero are ignored.</p>
</dd>
</dl>
<div w-nodev>
<p>Objects which implement the <code>CanvasShadowStyles</code> interface have an associated <dfn
data-x="concept-CanvasShadowStyles-shadow-color">shadow color</dfn>, which is a CSS color.
Initially, it must be <span>transparent black</span>.</p>
<p>The <dfn attribute for="CanvasShadowStyles"><code
data-x="dom-context-2d-shadowColor">shadowColor</code></dfn> getter steps are to return the <span
data-x="serialize a CSS <color> value">serialization</span> of <span>this</span>'s <span
data-x="concept-CanvasShadowStyles-shadow-color">shadow color</span> with <span
data-x="HTML-compatible serialization is requested">HTML-compatible serialization
requested</span>.</p>
<p>The <code data-x="dom-context-2d-shadowColor">shadowColor</code> setter steps are:</p>
<ol>
<li><p>Let <var>context</var> be <span>this</span>'s <code
data-x="dom-context-2d-canvas">canvas</code> attribute's value, if that is an element; otherwise
null.</p></li>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="parse a CSS <color>
value">parsing</span> the given value with <var>context</var> if non-null.</p></li>
<li><p>If <var>parsedValue</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-CanvasShadowStyles-shadow-color">shadow
color</span> to <var>parsedValue</var>.</p></li>
</ol>
<p>The <dfn attribute for="CanvasShadowStyles"><code
data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</code></dfn> and <dfn attribute
for="CanvasShadowStyles"><code data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</code></dfn>
attributes specify the distance that the shadow will be offset in the positive horizontal and
positive vertical distance respectively. Their values are in coordinate space units. They are not
affected by the current transformation matrix.</p>
<p>When the context is created, the shadow offset attributes must initially have the value
0.</p>
<p>On getting, they must return their current value. On setting, the attribute being set must be
set to the new value, except if the value is infinite or NaN, in which case the new value must be
ignored.</p>
<p>The <dfn attribute for="CanvasShadowStyles"><code
data-x="dom-context-2d-shadowBlur">shadowBlur</code></dfn> attribute specifies the level of the
blurring effect. (The units do not map to coordinate space units, and are not affected by the
current transformation matrix.)</p>
<p>When the context is created, the <code data-x="dom-context-2d-shadowBlur">shadowBlur</code>
attribute must initially have the value 0.</p>
<p>On getting, the attribute must return its current value. On setting, the attribute must be set
to the new value, except if the value is negative, infinite or NaN, in which case the new value
must be ignored.</p>
<p><dfn data-x="when shadows are drawn">Shadows are only drawn if</dfn> the opacity component of
the alpha component of the <span data-x="concept-CanvasShadowStyles-shadow-color">shadow
color</span> is nonzero and either the <code data-x="dom-context-2d-shadowBlur">shadowBlur</code>
is nonzero, or the <code data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</code> is nonzero, or
the <code data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</code> is nonzero.</p>
<p><span>When shadows are drawn</span>, they must be rendered as follows:</p>
<ol>
<li><p>Let <var>A</var> be an infinite <span>transparent black</span> bitmap on which the source
image for which a shadow is being created has been rendered.</p></li>
<li><p>Let <var>B</var> be an infinite <span>transparent black</span> bitmap, with a coordinate
space and an origin identical to <var>A</var>.</p></li>
<li><p>Copy the alpha component of <var>A</var> to <var>B</var>, offset by <code
data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</code> in the positive <var>x</var>
direction, and <code data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</code> in the positive
<var>y</var> direction.</p></li>
<li>
<p>If <code data-x="dom-context-2d-shadowBlur">shadowBlur</code> is greater than 0:</p>
<ol>
<li><p>Let <var>σ</var> be half the value of <code
data-x="dom-context-2d-shadowBlur">shadowBlur</code>.</p></li>
<li><p>Perform a 2D Gaussian Blur on <var>B</var>, using <var>σ</var>
as the standard deviation.</p> <!-- wish i could find a reference for this --> </li>
</ol>
<p>User agents may limit values of <var>σ</var> to an implementation-specific
maximum value to avoid exceeding hardware limitations during the Gaussian blur operation.</p>
</li>
<li><p>Set the red, green, and blue components of every pixel in <var>B</var> to the
red, green, and blue components (respectively) of the <span
data-x="concept-CanvasShadowStyles-shadow-color">shadow color</span>.</p></li>
<li><p>Multiply the alpha component of every pixel in <var>B</var> by the alpha
component of the <span data-x="concept-CanvasShadowStyles-shadow-color">shadow
color</span>.</p></li>
<li><p>The shadow is in the bitmap <var>B</var>, and is rendered as part of the
<span>drawing model</span> described below.</p></li>
</ol>
</div>
<p>If the <span>current compositing and blending operator</span> is "<code
data-x="gcop-copy">copy</code>", then shadows effectively won't render (since the shape will
overwrite the shadow).</p>
<h6>Filters</h6>
<p>All drawing operations on an object which implements the <code>CanvasFilters</code>
interface are affected by the global <dfn attribute for="CanvasFilters"><code
data-x="dom-context-2d-filter">filter</code></dfn> attribute.</p>
<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-filter">filter</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current filter.</p>
<p>Can be set, to change the filter. Values can either be the string "<code
data-x="">none</code>" or a string parseable as a <span><filter-value-list></span>. Other
values are ignored.</p>
</dd>
</dl>
<div w-nodev>
<p>Such objects have an associated <dfn data-x="concept-canvas-current-filter">current
filter</dfn>, which is a string. Initially the <span
data-x="concept-canvas-current-filter">current filter</span> is set to the string "<code
data-x="">none</code>". Whenever the value of the <span
data-x="concept-canvas-current-filter">current filter</span> is the string "<code
data-x="">none</code>" filters will be disabled for the context.</p>
<p>The <code data-x="dom-context-2d-filter">filter</code> getter steps are to return
<span>this</span>'s <span data-x="concept-canvas-current-filter">current filter</span>.</p>
<p>The <code data-x="dom-context-2d-filter">filter</code> setter steps are:</p>
<ol>
<li><p>If the given value is "<code data-x="">none</code>", then set <span>this</span>'s <span
data-x="concept-canvas-current-filter">current filter</span> to "<code data-x="">none</code>"
and return.</p></li>
<li><p>Let <var>parsedValue</var> be the result of <span data-x="parse something according to a
CSS grammar">parsing</span> the given values as a <span><filter-value-list></span>. If any
property-independent style sheet syntax like 'inherit' or 'initial' is present, then this
parsing must return failure.</p></li>
<li><p>If <var>parsedValue</var> is failure, then return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-canvas-current-filter">current
filter</span> to the given value.</p></li>
</ol>
</div>
<p class="note">Though <code data-x=""><var>context</var>.<code
data-x="dom-context-2d-filter">filter</code> = "<code data-x="">none</code>"</code> will disable
filters for the context, <code data-x=""><var>context</var>.<code
data-x="dom-context-2d-filter">filter</code> = ""</code>, <code
data-x=""><var>context</var>.<code data-x="dom-context-2d-filter">filter</code> = null</code>,
and <code data-x=""><var>context</var>.<code data-x="dom-context-2d-filter">filter</code> =
undefined</code> are all treated as unparseable inputs and the value of the <span
data-x="concept-canvas-current-filter">current filter</span> is left unchanged.</p>
<p>Coordinates used in the value of the <span data-x="concept-canvas-current-filter">current
filter</span> are interpreted such that one pixel is equivalent to one SVG user space unit and to
one canvas coordinate space unit. Filter coordinates are not affected by the <span
data-x="dom-context-2d-transformation">current transformation matrix</span>. The current
transformation matrix affects only the input to the filter. Filters are applied in the
<span>output bitmap</span>'s coordinate space.</p>
<div w-nodev>
<p>When the value of the <span data-x="concept-canvas-current-filter">current filter</span> is a
string parsable as a <span><filter-value-list></span> which defines lengths using
percentages or using <span>'em'</span> or <span>'ex'</span> units, these must be interpreted
relative to the <span>computed value</span> of the <span>'font-size'</span> property of the
<span>font style source object</span> at the time that the attribute is set. If the <span
data-x="computed value">computed values</span> are undefined for a particular case (e.g. because
the <span>font style source object</span> is not an element or is not <span>being
rendered</span>), then the relative keywords must be interpreted relative to the default value of
the <code data-x="dom-context-2d-font">font</code> attribute. The 'larger' and 'smaller' keywords
are not supported.</p>
<p>If the value of the <span data-x="concept-canvas-current-filter">current filter</span> is a
string parseable as a <span><filter-value-list></span> with a reference to an SVG filter in
the same document, and this SVG filter changes, then the changed filter is used for the next draw
operation.</p>
<p>If the value of the <span data-x="concept-canvas-current-filter">current filter</span> is a
string parseable as a <span><filter-value-list></span> with a reference to an SVG filter in
an external resource document and that document is not loaded when a drawing operation is
invoked, then the drawing operation must proceed with no filtering.</p>
</div>
<h6>Working with externally-defined SVG filters</h6>
<!-- NON-NORMATIVE SECTION -->
<p>Since drawing is performed using filter value "<code data-x="">none</code>" until an
externally-defined filter has finished loading, authors might wish to determine whether such a
filter has finished loading before proceeding with a drawing operation. One way to accomplish
this is to load the externally-defined filter elsewhere within the same page in some element that
sends a <code data-x="">load</code> event (for example, an <span>SVG <code>use</code></span>
element), and wait for the <code data-x="">load</code> event to be dispatched.</p>
<div w-nodev>
<h6><dfn>Drawing model</dfn></h6>
<p>When a shape or image is painted, user agents must follow these steps, in the order given (or
act as if they do):</p>
<ol>
<li><p>Render the shape or image onto an infinite <span>transparent black</span> bitmap, creating
image <var>A</var>, as described in the previous sections. For shapes, the current fill, stroke,
and line styles must be honored, and the stroke must itself also be subjected to the current
transformation matrix.</p></li>
<li><p>Multiply the alpha component of every pixel in <var>A</var> by <code
data-x="concept-canvas-global-alpha">global alpha</code>.</p></li>
<li>
<p>When the <span data-x="concept-canvas-current-filter">current filter</span> is set to a
value other than "<code data-x="">none</code>" and all the externally-defined filters it
references, if any, are in documents that are currently loaded, then use image <var>A</var> as
the input to the <span data-x="concept-canvas-current-filter">current filter</span>, creating
image <var>B</var>. If the <span data-x="concept-canvas-current-filter">current filter</span>
is a string parseable as a <span><filter-value-list></span>, then draw using the <span
data-x="concept-canvas-current-filter">current filter</span> in the same manner as SVG.</p>
<p>Otherwise, let <var>B</var> be an alias for <var>A</var>.</p>
</li>
<li><p><span>When shadows are drawn</span>, render the shadow from image <var>B</var>,
using the current shadow styles, creating image <var>C</var>.</p></li>
<li><p><span>When shadows are drawn</span>, composite <var>C</var> within the
<span>clipping region</span> over the current <span>output bitmap</span> using the <span>current
compositing and blending operator</span>.</p></li>
<li><p>Composite <var>B</var> within the <span>clipping region</span> over the current
<span>output bitmap</span> using the <span>current compositing and blending
operator</span>.</p></li>
</ol>
<p>When compositing onto the <span>output bitmap</span>, pixels that would fall outside of the
<span>output bitmap</span> must be discarded.</p>
</div>
<h6>Best practices</h6>
<p>When a canvas is interactive, authors should include <span>focusable</span> elements in the
element's fallback content corresponding to each <span>focusable</span> part of the canvas, as in
the <a href="#drawCustomFocusRingExample">example above</a>.</p>
<p>When rendering focus rings, to ensure that focus rings have the appearance of native focus
rings, authors should use the <code
data-x="dom-context-2d-drawFocusIfNeeded">drawFocusIfNeeded()</code> method, passing it the
element for which a ring is being drawn. This method only draws the focus ring if the element is
<span>focused</span>, so that it can simply be called whenever drawing the element, without
checking whether the element is focused or not first.</p>
<p id="no-text-editing-in-canvas-please">Authors should avoid implementing text editing controls
using the <code>canvas</code> element. Doing so has a large number of disadvantages:</p>
<ul>
<li>Mouse placement of the caret has to be reimplemented.</li>
<li>Keyboard movement of the caret has to be reimplemented (possibly across lines, for multiline
text input).</li>
<li>Scrolling of the text control has to be implemented (horizontally for long lines, vertically
for multiline input).</li>
<li>Native features such as copy-and-paste have to be reimplemented.</li>
<li>Native features such as spell-checking have to be reimplemented.</li>
<li>Native features such as drag-and-drop have to be reimplemented.</li>
<li>Native features such as page-wide text search have to be reimplemented.</li>
<li>Native features specific to the user, for example custom text services, have to be
reimplemented. This is close to impossible since each user might have different services
installed, and there is an unbounded set of possible such services.</li>
<li>Bidirectional text editing has to be reimplemented.</li>
<li>For multiline text editing, line wrapping has to be implemented for all relevant
languages.</li>
<li>Text selection has to be reimplemented.</li>
<li>Dragging of bidirectional text selections has to be reimplemented.</li>
<li>Platform-native keyboard shortcuts have to be reimplemented.</li>
<li>Platform-native input method editors (IMEs) have to be reimplemented.</li>
<li>Undo and redo functionality has to be reimplemented.</li>
<li>Accessibility features such as magnification following the caret or selection have to be
reimplemented.</li>
</ul>
<p>This is a huge amount of work, and authors are most strongly encouraged to avoid doing any of
it by instead using the <code>input</code> element, the <code>textarea</code> element, or the
<code data-x="attr-contenteditable">contenteditable</code> attribute.</p>
<h6>Examples</h6>
<!-- NON-NORMATIVE SECTION -->
<div class="example">
<p>Here is an example of a script that uses canvas to draw <a href="data:text/html;charset=utf-8;base64,PCFET0NUWVBFIEhUTUw%2BDQo8aHRtbCBsYW5nPSJlbiI%2BDQogPGhlYWQ%2BDQogIDx0aXRsZT5QcmV0dHkgR2xvd2luZyBMaW5lczwvdGl0bGU%2BDQogPC9oZWFkPg0KIDxib2R5Pg0KPGNhbnZhcyB3aWR0aD0iODAwIiBoZWlnaHQ9IjQ1MCI%2BPC9jYW52YXM%2BDQo8c2NyaXB0Pg0KDQogdmFyIGNvbnRleHQgPSBkb2N1bWVudC5nZXRFbGVtZW50c0J5VGFnTmFtZSgnY2FudmFzJylbMF0uZ2V0Q29udGV4dCgnMmQnKTsNCg0KIHZhciBsYXN0WCA9IGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKTsNCiB2YXIgbGFzdFkgPSBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpOw0KIHZhciBodWUgPSAwOw0KIGZ1bmN0aW9uIGxpbmUoKSB7DQogICBjb250ZXh0LnNhdmUoKTsNCiAgIGNvbnRleHQudHJhbnNsYXRlKGNvbnRleHQuY2FudmFzLndpZHRoLzIsIGNvbnRleHQuY2FudmFzLmhlaWdodC8yKTsNCiAgIGNvbnRleHQuc2NhbGUoMC45LCAwLjkpOw0KICAgY29udGV4dC50cmFuc2xhdGUoLWNvbnRleHQuY2FudmFzLndpZHRoLzIsIC1jb250ZXh0LmNhbnZhcy5oZWlnaHQvMik7DQogICBjb250ZXh0LmJlZ2luUGF0aCgpOw0KICAgY29udGV4dC5saW5lV2lkdGggPSA1ICsgTWF0aC5yYW5kb20oKSAqIDEwOw0KICAgY29udGV4dC5tb3ZlVG8obGFzdFgsIGxhc3RZKTsNCiAgIGxhc3RYID0gY29udGV4dC5jYW52YXMud2lkdGggKiBNYXRoLnJhbmRvbSgpOw0KICAgbGFzdFkgPSBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpOw0KICAgY29udGV4dC5iZXppZXJDdXJ2ZVRvKGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKSwNCiAgICAgICAgICAgICAgICAgICAgICAgICBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpLA0KICAgICAgICAgICAgICAgICAgICAgICAgIGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKSwNCiAgICAgICAgICAgICAgICAgICAgICAgICBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpLA0KICAgICAgICAgICAgICAgICAgICAgICAgIGxhc3RYLCBsYXN0WSk7DQoNCiAgIGh1ZSA9IGh1ZSArIDEwICogTWF0aC5yYW5kb20oKTsNCiAgIGNvbnRleHQuc3Ryb2tlU3R5bGUgPSAnaHNsKCcgKyBodWUgKyAnLCA1MCUsIDUwJSknOw0KICAgY29udGV4dC5zaGFkb3dDb2xvciA9ICd3aGl0ZSc7DQogICBjb250ZXh0LnNoYWRvd0JsdXIgPSAxMDsNCiAgIGNvbnRleHQuc3Ryb2tlKCk7DQogICBjb250ZXh0LnJlc3RvcmUoKTsNCiB9DQogc2V0SW50ZXJ2YWwobGluZSwgNTApOw0KDQogZnVuY3Rpb24gYmxhbmsoKSB7DQogICBjb250ZXh0LmZpbGxTdHlsZSA9ICdyZ2JhKDAsMCwwLDAuMSknOw0KICAgY29udGV4dC5maWxsUmVjdCgwLCAwLCBjb250ZXh0LmNhbnZhcy53aWR0aCwgY29udGV4dC5jYW52YXMuaGVpZ2h0KTsNCiB9DQogc2V0SW50ZXJ2YWwoYmxhbmssIDQwKTsNCg0KPC9zY3JpcHQ%2BDQogPC9ib2R5Pg0KPC9odG1sPg0K">pretty glowing lines</a>.</p>
<pre><code class="html"><canvas width="800" height="450"></canvas>
<script>
var context = document.getElementsByTagName('canvas')[0].getContext('2d');
var lastX = context.canvas.width * Math.random();
var lastY = context.canvas.height * Math.random();
var hue = 0;
function line() {
context.save();
context.translate(context.canvas.width/2, context.canvas.height/2);
context.scale(0.9, 0.9);
context.translate(-context.canvas.width/2, -context.canvas.height/2);
context.beginPath();
context.lineWidth = 5 + Math.random() * 10;
context.moveTo(lastX, lastY);
lastX = context.canvas.width * Math.random();
lastY = context.canvas.height * Math.random();
context.bezierCurveTo(context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
lastX, lastY);
hue = hue + 10 * Math.random();
context.strokeStyle = 'hsl(' + hue + ', 50%, 50%)';
context.shadowColor = 'white';
context.shadowBlur = 10;
context.stroke();
context.restore();
}
setInterval(line, 50);
function blank() {
context.fillStyle = 'rgba(0,0,0,0.1)';
context.fillRect(0, 0, context.canvas.width, context.canvas.height);
}
setInterval(blank, 40);
</script></code></pre>
</div>
<div class="example">
<p>The 2D rendering context for <code>canvas</code> is often used for sprite-based games. The
following example demonstrates this:</p>
<iframe src="/demos/canvas/blue-robot/index-idle.html" width="396" height="216"></iframe>
<p>Here is the source for this example:</p>
<pre><code class="html">EXAMPLE canvas/blue-robot/index.html</code></pre>
</div>
<h5>The <code>ImageBitmap</code> rendering context</h5>
<h6>Introduction</h6>
<p><code>ImageBitmapRenderingContext</code> is a performance-oriented interface that provides a
low overhead method for displaying the contents of <code>ImageBitmap</code> objects. It uses
transfer semantics to reduce overall memory consumption. It also streamlines performance by
avoiding intermediate compositing, unlike the <code
data-x="dom-context-2d-drawImage">drawImage()</code> method of
<code>CanvasRenderingContext2D</code>.</p>
<p>Using an <code>img</code> element as an intermediate for getting an image resource into a
canvas, for example, would result in two copies of the decoded image existing in memory at the
same time: the <code>img</code> element's copy, and the one in the canvas's backing store. This
memory cost can be prohibitive when dealing with extremely large images. This can be avoided by
using <code>ImageBitmapRenderingContext</code>.</p>
<div class="example">
<p>Using <code>ImageBitmapRenderingContext</code>, here is how to transcode an image to the JPEG
format in a memory- and CPU-efficient way:</p>
<pre><code class="js">createImageBitmap(inputImageBlob).then(image => {
const canvas = document.createElement('canvas');
const context = canvas.getContext('bitmaprenderer');
context.transferFromImageBitmap(image);
canvas.toBlob(outputJPEGBlob => {
// Do something with outputJPEGBlob.
}, 'image/jpeg');
});</code></pre>
</div>
<h6>The <code>ImageBitmapRenderingContext</code> interface</h6>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>ImageBitmapRenderingContext</dfn> {
readonly attribute (<span>HTMLCanvasElement</span> or <span>OffscreenCanvas</span>) <span data-x="dom-ImageBitmapRenderingContext-canvas">canvas</span>;
undefined <span data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap</span>(<span>ImageBitmap</span>? bitmap);
};
dictionary <dfn dictionary>ImageBitmapRenderingContextSettings</dfn> {
boolean <span data-x="dom-ImageBitmapRenderingContextSettings-alpha">alpha</span> = true;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>context</var> = <var>canvas</var>.<span data-x="dom-canvas-getContext">getContext</span>('bitmaprenderer' [, { [ <span data-x="dom-ImageBitmapRenderingContextSettings-alpha">alpha</span>: false ] } ])</code></dt>
<dd>
<p>Returns an <code>ImageBitmapRenderingContext</code> object that is permanently bound to a
particular <code>canvas</code> element.</p>
<p>If the <code data-x="dom-ImageBitmapRenderingContextSettings-alpha">alpha</code> setting is
provided and set to false, then the canvas is forced to always be opaque.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-ImageBitmapRenderingContext-canvas">canvas</span></code></dt>
<dd><p>Returns the <code>canvas</code> element that the context is bound to.</p></dd>
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap</span>(imageBitmap)</code></dt>
<dd>
<p>Transfers the underlying <span data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>
from <var>imageBitmap</var> to <var>context</var>, and the bitmap becomes the contents of the
<code>canvas</code> element to which <var>context</var> is bound.</p>
</dd>
<dt><code data-x=""><var>context</var>.<span data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap</span>(null)</code></dt>
<dd>
<p>Replaces contents of the <code>canvas</code> element to which <var>context</var> is bound
with a <span>transparent black</span> bitmap whose size corresponds to the <code
data-x="attr-canvas-width">width</code> and <code data-x="attr-canvas-height">height</code>
content attributes of the <code>canvas</code> element.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="ImageBitmapRenderingContext"><code
data-x="dom-ImageBitmapRenderingContext-canvas">canvas</code></dfn> attribute must return the
value it was initialized to when the object was created.</p>
<p>An <code>ImageBitmapRenderingContext</code> object has an <dfn
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</dfn>, which is a
reference to <span data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>.</p>
<p>An <code>ImageBitmapRenderingContext</code> object has a <dfn
data-x="concept-ImageBitmapRenderingContext-bitmap-mode">bitmap mode</dfn>, which can be set to
<dfn data-x="concept-ImageBitmapRenderingContext-valid">valid</dfn> or <dfn
data-x="concept-ImageBitmapRenderingContext-blank">blank</dfn>. A value of <span
data-x="concept-ImageBitmapRenderingContext-valid">valid</span> indicates that the context's
<span data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> refers to
<span data-x="concept-ImageBitmap-bitmap-data">bitmap data</span> that was acquired via <code
data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap()</code>.
A value <span data-x="concept-ImageBitmapRenderingContext-blank">blank</span> indicates that the
context's <span data-x="concept-ImageBitmapRenderingContext-output-bitmap">output
bitmap</span> is a default transparent bitmap.</p>
<p>An <code>ImageBitmapRenderingContext</code> object also has an <dfn
data-x="concept-ImageBitmapRenderingContext-alpha">alpha</dfn> flag, which can be set to true or
false. When an <code>ImageBitmapRenderingContext</code> object has its <span
data-x="concept-ImageBitmapRenderingContext-alpha">alpha</span> flag set to false, the contents
of the <code>canvas</code> element to which the context is bound are obtained by
compositing the context's <span
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> onto an
<span>opaque black</span> bitmap of the same size using the <span
data-x="gcop-source-over">source-over</span> compositing operator. If the <span
data-x="concept-ImageBitmapRenderingContext-alpha">alpha</span> flag is set to true, then the
<span data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> is used as
the contents of the <code>canvas</code> element to which the context is bound.
<ref>COMPOSITE</ref></p>
<p class="note">The step of compositing over an <span>opaque black</span> bitmap ought to be
elided whenever equivalent results can be obtained more efficiently by other means.</p>
<hr>
<p>When a user agent is required to <dfn>set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</dfn>, with a <var>context</var> argument that is an
<code>ImageBitmapRenderingContext</code> object and an optional argument <var>bitmap</var> that
refers to <span data-x="concept-imagebitmap-bitmap-data">bitmap data</span>, it must run these
steps:</p>
<ol>
<li><p>If a <var>bitmap</var> argument was not provided, then:</p>
<ol>
<li><p>Set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-bitmap-mode">bitmap mode</span> to <span
data-x="concept-ImageBitmapRenderingContext-blank">blank</span>.</p></li>
<li><p>Let <var>canvas</var> be the <code>canvas</code> element to which <var>context</var>
is bound.</p></li>
<li><p>Set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> to be
<span>transparent black</span> with a <span>natural width</span> equal to <span
data-x="obtain-numeric-values">the numeric value</span> of <var>canvas</var>'s <code
data-x="attr-canvas-width">width</code> attribute and a <span>natural height</span> equal
to <span data-x="obtain-numeric-values">the numeric value</span> of <var>canvas</var>'s
<code data-x="attr-canvas-height">height</code> attribute, those values being interpreted
in <span data-x="'px'">CSS pixels</span>.</p></li>
<li><p>Set the <span
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span>'s <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag to true.</p></li>
</ol>
</li>
<li><p>If a <var>bitmap</var> argument was provided, then:</p>
<ol>
<li><p>Set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-bitmap-mode">bitmap mode</span> to <span
data-x="concept-ImageBitmapRenderingContext-valid">valid</span>.</p></li>
<li>
<p>Set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> to refer
to the same underlying bitmap data as <var>bitmap</var>, without making a copy.</p>
<p class="note">The <span data-x="concept-canvas-origin-clean">origin-clean</span> flag of
<var>bitmap</var> is included in the bitmap data to be referenced by <var>context</var>'s
<span data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span>.</p>
</li>
</ol>
</li>
</ol>
<hr>
<p>The <dfn><code>ImageBitmapRenderingContext</code> creation algorithm</dfn>, which is passed a
<var>target</var> and <var>options</var>, consists of running these steps:</p>
<ol>
<li><p>Let <var>settings</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>options</var> to the dictionary type
<code>ImageBitmapRenderingContextSettings</code>. (This can throw an exception.)</p></li>
<li><p>Let <var>context</var> be a new <code>ImageBitmapRenderingContext</code> object.</p></li>
<li><p>Initialize <var>context</var>'s <code data-x="dom-context-2d-canvas">canvas</code>
attribute to point to <var>target</var>.</p></li>
<li><p>Set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-output-bitmap">output bitmap</span> to the same
bitmap as <var>target</var>'s bitmap (so that they are shared).</p></li>
<li><p>Run the steps to <span>set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</span> with <var>context</var>.</p></li>
<li><p>Initialize <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-alpha">alpha</span> flag to true.
<li>
<p>Process each of the members of <var>settings</var> as follows:</p>
<dl>
<dt><dfn dict-member for="ImageBitmapRenderingContextSettings"><code data-x="dom-ImageBitmapRenderingContextSettings-alpha">alpha</code></dfn></dt>
<dd>If false, then set <var>context</var>'s <span
data-x="concept-ImageBitmapRenderingContext-alpha">alpha</span> flag to false.</dd>
</dl>
</li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<hr>
<p>The <dfn method for="ImageBitmapRenderingContext"><code
data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap(<var>bitmap</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol>
<li><p>Let <var>bitmapContext</var> be the <code>ImageBitmapRenderingContext</code> object on
which the <code
data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap()</code>
method was called.</p></li>
<li><p>If <var>bitmap</var> is null, then run the steps to <span>set an
ImageBitmapRenderingContext's output bitmap</span>, with <var>bitmapContext</var> as the
<var>context</var> argument and no <var>bitmap</var> argument, then return.</p></li>
<li><p>If the value of <var>bitmap</var>'s <span>[[Detached]]</span> internal slot is set to
true, then throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Run the steps to <span>set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</span>, with the <var>context</var> argument equal to <var>bitmapContext</var>, and the
<var>bitmap</var> argument referring to <var>bitmap</var>'s underlying <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>.
<li><p>Set the value of <var>bitmap</var>'s <span>[[Detached]]</span> internal slot to
true.</p></li>
<li><p>Unset <var>bitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span>.</p></li>
</ol>
</div>
<h5>The <code>OffscreenCanvas</code> interface</h5>
<pre><code class="idl">typedef (<span>OffscreenCanvasRenderingContext2D</span> or <span>ImageBitmapRenderingContext</span> or <span>WebGLRenderingContext</span> or <span>WebGL2RenderingContext</span> or <span>GPUCanvasContext</span>) <dfn typedef>OffscreenRenderingContext</dfn>;
dictionary <dfn dictionary>ImageEncodeOptions</dfn> {
DOMString <span data-x="image-encode-options-type">type</span> = "image/png";
unrestricted double <span data-x="image-encode-options-quality">quality</span>;
};
enum <dfn enum>OffscreenRenderingContextId</dfn> { "<span data-x="offscreen-context-type-2d">2d</span>", "<span data-x="offscreen-context-type-bitmaprenderer">bitmaprenderer</span>", "<span data-x="offscreen-context-type-webgl">webgl</span>", "<span data-x="offscreen-context-type-webgl2">webgl2</span>", "<span data-x="offscreen-context-type-webgpu">webgpu</span>" };
[Exposed=(Window,Worker), <span>Transferable</span>]
interface <dfn interface>OffscreenCanvas</dfn> : <span>EventTarget</span> {
<span data-x="dom-OffscreenCanvas">constructor</span>([EnforceRange] unsigned long long width, [EnforceRange] unsigned long long height);
attribute [EnforceRange] unsigned long long <span data-x="dom-OffscreenCanvas-width">width</span>;
attribute [EnforceRange] unsigned long long <span data-x="dom-OffscreenCanvas-height">height</span>;
<span>OffscreenRenderingContext</span>? <span data-x="dom-OffscreenCanvas-getContext">getContext</span>(<span>OffscreenRenderingContextId</span> contextId, optional any options = null);
<span>ImageBitmap</span> <span data-x="dom-OffscreenCanvas-transferToImageBitmap">transferToImageBitmap</span>();
<span data-x="idl-Promise">Promise</span><<span>Blob</span>> <span data-x="dom-OffscreenCanvas-convertToBlob">convertToBlob</span>(optional <span>ImageEncodeOptions</span> options = {});
attribute <span>EventHandler</span> <span data-x="handler-offscreencanvas-oncontextlost">oncontextlost</span>;
attribute <span>EventHandler</span> <span data-x="handler-offscreencanvas-oncontextrestored">oncontextrestored</span>;
};</code></pre>
<p class="note"><code>OffscreenCanvas</code> is an <code>EventTarget</code>, so both
<code>OffscreenCanvasRenderingContext2D</code> and WebGL can fire events at it.
<code>OffscreenCanvasRenderingContext2D</code> can fire <code
data-x="event-contextlost">contextlost</code> and <code
data-x="event-contextrestored">contextrestored</code>, and WebGL can fire <code
data-x="">webglcontextlost</code> and <code data-x="">webglcontextrestored</code>.
<ref>WEBGL</ref></p>
<p><code>OffscreenCanvas</code> objects are used to create rendering contexts, much like an
<code>HTMLCanvasElement</code>, but with no connection to the DOM. This makes it possible to
use canvas rendering contexts in <a href="#workers">workers</a>.</p>
<p>An <code>OffscreenCanvas</code> object may hold a weak reference to a <dfn
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</dfn>, which is
typically in the DOM, whose embedded content is provided by the <code>OffscreenCanvas</code>
object. The bitmap of the <code>OffscreenCanvas</code> object is pushed to the <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span> as part of
the <code>OffscreenCanvas</code>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>update the rendering</span>
steps.</p>
<dl class="domintro">
<dt><code data-x=""><var>offscreenCanvas</var> = new <span subdfn data-x="dom-OffscreenCanvas">OffscreenCanvas</span>(<var>width</var>,
<var>height</var>)</code></dt>
<dd>
<p>Returns a new <code>OffscreenCanvas</code> object that is not linked to a <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>, and whose
bitmap's size is determined by the <var>width</var> and <var>height</var> arguments.</p>
</dd>
<dt><code data-x=""><var>context</var> = <var>offscreenCanvas</var>.<span subdfn data-x="dom-OffscreenCanvas-getContext">getContext</span>(<var>contextId</var> [,
<var>options</var> ])</code></dt>
<dd>
<p>Returns an object that exposes an API for drawing on the <code>OffscreenCanvas</code> object.
<var>contextId</var> specifies the desired API: "<code
data-x="offscreen-context-type-2d">2d</code>", "<code
data-x="offscreen-context-type-bitmaprenderer">bitmaprenderer</code>", "<code
data-x="offscreen-context-type-webgl">webgl</code>", "<code
data-x="offscreen-context-type-webgl2">webgl2</code>", or "<code
data-x="offscreen-context-type-webgpu">webgpu</code>". <var>options</var> is handled by that
API.</p>
<p>This specification defines the "<code data-x="canvas-context-2d">2d</code>" context below,
which is similar but distinct from the "<code data-x="offscreen-context-type-2d">2d</code>"
context that is created from a <code>canvas</code> element. The WebGL specifications define the
"<code data-x="offscreen-context-type-webgl">webgl</code>" and "<code
data-x="offscreen-context-type-webgl2">webgl2</code>" contexts. <cite>WebGPU</cite> defines the
"<code data-x="offscreen-context-type-webgpu">webgpu</code>" context. <ref>WEBGL</ref>
<ref>WEBGPU</ref></p>
<p>Returns null if the canvas has already been initialized with another context type (e.g.,
trying to get a "<code data-x="offscreen-context-type-2d">2d</code>" context after getting a
"<code data-x="offscreen-context-type-webgl">webgl</code>" context).</p>
</dd>
</dl>
<div w-nodev>
<p>An <code>OffscreenCanvas</code> object has an internal <dfn
data-x="offscreencanvas-bitmap">bitmap</dfn> that is initialized when the object
is created. The width and height of the <span data-x="offscreencanvas-bitmap">bitmap</span> are
equal to the values of the <code data-x="dom-OffscreenCanvas-width">width</code> and <code
data-x="dom-OffscreenCanvas-height">height</code> attributes of the <code>OffscreenCanvas</code>
object. Initially, all the bitmap's pixels are <span>transparent black</span>.</p>
<p>An <code>OffscreenCanvas</code> object has an internal <dfn
data-x="offscreencanvas-inherited-lang">inherited language</dfn> and <dfn
data-x="offscreencanvas-inherited-direction">inherited direction</dfn> set when
the <code>OffscreenCanvas</code> is created.</p>
<p>An <code>OffscreenCanvas</code> object can have a rendering context bound to it. Initially,
it does not have a bound rendering context. To keep track of whether it has a rendering context
or not, and what kind of rendering context it is, an <code>OffscreenCanvas</code> object also
has a <dfn data-x="offscreencanvas-context-mode">context mode</dfn>, which is initially <dfn
data-x="offscreencanvas-context-none">none</dfn> but can be changed to either <dfn
data-x="offscreencanvas-context-2d">2d</dfn>, <dfn
data-x="offscreencanvas-context-bitmaprenderer">bitmaprenderer</dfn>, <dfn
data-x="offscreencanvas-context-webgl">webgl</dfn>, <dfn
data-x="offscreencanvas-context-webgl2">webgl2</dfn>, <dfn
data-x="offscreencanvas-context-webgpu">webgpu</dfn>, or <dfn
data-x="offscreencanvas-context-detached">detached</dfn> by algorithms defined in this
specification.</p>
<p>The <dfn constructor for="OffscreenCanvas"><code data-x="dom-OffscreenCanvas">new OffscreenCanvas(<var>width</var>,
<var>height</var>)</code></dfn> constructor steps are:</p>
<ol>
<li><p>Initialize the <span data-x="offscreencanvas-bitmap">bitmap</span> of <span>this</span>
to a rectangular array of <span>transparent black</span> pixels of the dimensions specified
by <var>width</var> and <var>height</var>.</p></li>
<li><p>Initialize the <code data-x="dom-OffscreenCanvas-width">width</code> of <span>this</span>
to <var>width</var>.</p></li>
<li><p>Initialize the <code data-x="dom-OffscreenCanvas-height">height</code> of
<span>this</span> to <var>height</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="offscreencanvas-inherited-lang">inherited
language</span> to <span data-x="concept-explicitly-unknown">explicitly unknown</span>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="offscreencanvas-inherited-direction">inherited
direction</span> to "<code data-x="">ltr</code>".</p></li>
<li><p>Let <var>global</var> be the <span>relevant global object</span> of
<span>this</span>.</p></li>
<li>
<p>If <var>global</var> is a <code>Window</code> object:</p>
<ol>
<li><p>Let <var>element</var> be the <span>document element</span> of <var>global</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li>
<p>If <var>element</var> is not null:</p>
<ol>
<li><p>Set the <span data-x="offscreencanvas-inherited-lang">inherited language</span>
of <span>this</span> to <var>element</var>'s <span
data-x="language">language</span>.</p></li>
<li><p>Set the <span data-x="offscreencanvas-inherited-direction">inherited
direction</span> of <span>this</span> to <var>element</var>'s <span
data-x="the directionality">directionality</span>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p><code>OffscreenCanvas</code> objects are <span data-x="transferable
objects">transferable</span>. Their <span>transfer steps</span>, given <var>value</var> and
<var>dataHolder</var>, are as follows:</p>
<ol>
<li><p>If <var>value</var>'s <span data-x="offscreencanvas-context-mode">context mode</span> is
not equal to <span data-x="offscreencanvas-context-none">none</span>, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <var>value</var>'s <span data-x="offscreencanvas-context-mode">context mode</span> to
<span data-x="offscreencanvas-context-detached">detached</span>.</p></li>
<li><p>Let <var>width</var> and <var>height</var> be the dimensions of <var>value</var>'s <span
data-x="offscreencanvas-bitmap">bitmap</span>.</p></li>
<li><p>Let <var>language</var> and <var>direction</var> be the values of <var>value</var>'s
<span data-x="offscreencanvas-inherited-lang">inherited language</span> and
<span data-x="offscreencanvas-inherited-direction">inherited direction</span>.</p></li>
<li><p>Unset <var>value</var>'s <span data-x="offscreencanvas-bitmap">bitmap</span>.</p></li>
<li><p>Set <var>dataHolder</var>.[[Width]] to <var>width</var> and
<var>dataHolder</var>.[[Height]] to <var>height</var>.</p></li>
<li><p>Set <var>dataHolder</var>.[[Language]] to <var>language</var> and
<var>dataHolder</var>.[[Direction]] to <var>direction</var>.</p></li>
<li><p>Set <var>dataHolder</var>.[[PlaceholderCanvas]] to be a weak reference to
<var>value</var>'s <span data-x="offscreencanvas-placeholder">placeholder <code>canvas</code>
element</span>, if <var>value</var> has one, or null if it does not.</p></li>
</ol>
<p>Their <span>transfer-receiving steps</span>, given <var>dataHolder</var> and <var>value</var>,
are:</p>
<ol>
<li><p>Initialize <var>value</var>'s <span data-x="offscreencanvas-bitmap">bitmap</span> to a
rectangular array of <span>transparent black</span> pixels with width given by
<var>dataHolder</var>.[[Width]] and height given by <var>dataHolder</var>.[[Height]].</p></li>
<li><p>Set <var>value</var>'s <span data-x="offscreencanvas-inherited-lang">inherited
language</span> to <var>dataHolder</var>.[[Language]] and <span
data-x="offscreencanvas-inherited-direction">inherited direction</span> to
<var>dataHolder</var>.[[Direction]].</p></li>
<li><p>If <var>dataHolder</var>.[[PlaceholderCanvas]] is not null, set <var>value</var>'s <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span> to
<var>dataHolder</var>.[[PlaceholderCanvas]] (while maintaining the weak reference
semantics).</p></li>
</ol>
<hr>
<p>The <dfn method for="OffscreenCanvas"><code
data-x="dom-OffscreenCanvas-getContext">getContext(<var>contextId</var>,
<var>options</var>)</code></dfn> method of an <code>OffscreenCanvas</code> object, when invoked,
must run these steps:</p>
<ol>
<li><p>If <var>options</var> is not an <span data-x="idl-object">object</span>, then set
<var>options</var> to null.</p></li>
<li><p>Set <var>options</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>options</var> to a JavaScript value.</p></li>
<li>
<p>Run the steps in the cell of the following table whose column header matches this
<code>OffscreenCanvas</code> object's <span data-x="offscreencanvas-context-mode">context
mode</span> and whose row header matches <var>contextId</var>:</p>
<table>
<thead>
<tr>
<td>
<th><span data-x="offscreencanvas-context-none">none</span>
<th><span data-x="offscreencanvas-context-2d">2d</span>
<th><span data-x="offscreencanvas-context-bitmaprenderer">bitmaprenderer</span>
<th><span data-x="offscreencanvas-context-webgl">webgl</span> or <span
data-x="offscreencanvas-context-webgl2">webgl2</span>
<th><span data-x="offscreencanvas-context-webgpu">webgpu</span>
<th><span data-x="offscreencanvas-context-detached">detached</span>
<tbody>
<tr>
<th>"<dfn><code data-x="offscreen-context-type-2d">2d</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of running the
<span>offscreen 2D context creation algorithm</span> given
<span>this</span> and <var>options</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="offscreencanvas-context-mode">context
mode</span> to <span data-x="offscreencanvas-context-2d">2d</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="offscreen-context-type-bitmaprenderer">bitmaprenderer</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of running the
<span><code>ImageBitmapRenderingContext</code> creation
algorithm</span> given <span>this</span> and <var>options</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="offscreencanvas-context-mode">context
mode</span> to <span
data-x="offscreencanvas-context-bitmaprenderer">bitmaprenderer</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="offscreen-context-type-webgl">webgl</code></dfn>" or "<dfn><code
data-x="offscreen-context-type-webgl2">webgl2</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of following the instructions given in the
WebGL specifications' <i>Context Creation</i> sections. <ref>WEBGL</ref></p></li>
<li><p>If <var>context</var> is null, then return null; otherwise set
<span>this</span>'s <span data-x="offscreencanvas-context-mode">context
mode</span> to <span data-x="offscreencanvas-context-webgl">webgl</span> or <span
data-x="offscreencanvas-context-webgl2">webgl2</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return null.
<td>
Return the same value as was returned the last time the method was invoked with this same
first argument.
<td>
Return null.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<tr>
<th>"<dfn><code data-x="offscreen-context-type-webgpu">webgpu</code></dfn>"
<td>
<ol>
<li><p>Let <var>context</var> be the result of following the instructions given in
<cite>WebGPU</cite>'s <a
href="https://gpuweb.github.io/gpuweb/#canvas-rendering">Canvas Rendering</a> section.
<ref>WEBGPU</ref></p></li>
<li><p>If <var>context</var> is null, then return null; otherwise set <span>this</span>'s
<span data-x="offscreencanvas-context-mode">context mode</span> to <span
data-x="offscreencanvas-context-webgpu">webgpu</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<td>
Return null.
<td>
Return null.
<td>
Return null.
<td>
Return the same value as was returned the last time the method was invoked with this same
first argument.
<td>
Throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
</table>
</li>
</ol>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>offscreenCanvas</var>.<span subdfn data-x="dom-OffscreenCanvas-width">width</span> [
= <var>value</var> ]</code></dt>
<dt><code data-x=""><var>offscreenCanvas</var>.<span subdfn data-x="dom-OffscreenCanvas-height">height</span> [
= <var>value</var> ]</code></dt>
<dd>
<p>These attributes return the dimensions of the <code>OffscreenCanvas</code> object's <span
data-x="offscreencanvas-bitmap">bitmap</span>.</p>
<p>They can be set, to replace the <span data-x="offscreencanvas-bitmap">bitmap</span> with a
new, <span>transparent black</span> bitmap of the specified dimensions (effectively resizing
it).</p>
</dd>
</dl>
<div w-nodev>
<p>If either the <dfn attribute for="OffscreenCanvas"><code
data-x="dom-OffscreenCanvas-width">width</code></dfn> or <dfn attribute
for="OffscreenCanvas"><code data-x="dom-OffscreenCanvas-height">height</code></dfn> attributes of
an <code>OffscreenCanvas</code> object are set (to a new value or to the same value as before) and
the <code>OffscreenCanvas</code> object's <span data-x="offscreencanvas-context-mode">context
mode</span> is <span data-x="offscreencanvas-context-2d">2d</span>, then <span>reset the rendering
context to its default state</span> and resize the <code>OffscreenCanvas</code> object's <span
data-x="offscreencanvas-bitmap">bitmap</span> to the new values of the <code
data-x="dom-OffscreenCanvas-width">width</code> and <code
data-x="dom-OffscreenCanvas-height">height</code> attributes.</p>
<p>The resizing behavior for "<code data-x="offscreen-context-type-webgl">webgl</code>" and "<code
data-x="offscreen-context-type-webgl2">webgl2</code>" contexts is defined in the WebGL
specifications. <ref>WEBGL</ref></p>
<p>The resizing behavior for "<code data-x="offscreen-context-type-webgpu">webgpu</code>" context
is defined in <cite>WebGPU</cite>. <ref>WEBGPU</ref></p>
</div>
<p class="note">If an <code>OffscreenCanvas</code> object whose dimensions were changed has
a <span data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>, then
the <span data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>'s
<span data-x="natural dimensions">natural size</span> will only be updated during the
<code>OffscreenCanvas</code>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>update the rendering</span> steps.</p>
<dl class="domintro">
<dt><code data-x=""><var>promise</var> = <var>offscreenCanvas</var>.<span subdfn data-x="dom-OffscreenCanvas-convertToBlob">convertToBlob</span>([<var>options</var>])</code></dt>
<dd>
<p>Returns a promise that will fulfill with a new <code>Blob</code> object representing a file
containing the image in the <code>OffscreenCanvas</code> object.</p>
<p>The argument, if provided, is a dictionary that controls the encoding options of the image
file to be created. The <code data-x="image-encode-options-type">type</code> field specifies the
file format and has a default value of "<code>image/png</code>"; that type is also used if the
requested type isn't supported. If the image format supports variable quality (such as
"<code>image/jpeg</code>"), then the <code data-x="image-encode-options-quality">quality</code>
field is a number in the range 0.0 to 1.0 inclusive indicating the desired quality level for the
resulting image.</p>
</dd>
<dt><code data-x=""><var>canvas</var>.<span subdfn data-x="dom-OffscreenCanvas-transferToImageBitmap">transferToImageBitmap</span>()</code></dt>
<dd>
<p>Returns a newly created <code>ImageBitmap</code> object with the image in the
<code>OffscreenCanvas</code> object. The image in the <code>OffscreenCanvas</code> object is
replaced with a new blank image.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="OffscreenCanvas"><code
data-x="dom-OffscreenCanvas-convertToBlob">convertToBlob(<var>options</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>If the value of <span>this</span>'s <span>[[Detached]]</span> internal slot is true, then
return <span>a promise rejected with</span> an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="offscreencanvas-context-mode">context mode</span> is
<span data-x="offscreencanvas-context-2d">2d</span> and the rendering context's <span>output
bitmap</span>'s <span data-x="concept-canvas-origin-clean">origin-clean</span> flag is set to
false, then return <span>a promise rejected with</span> a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p>
<li><p>If <span>this</span>'s <span data-x="offscreencanvas-bitmap">bitmap</span> has no pixels
(i.e., either its horizontal dimension or its vertical dimension is zero), then return <span>a
promise rejected with</span> an <span>"<code>IndexSizeError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>bitmap</var> be a copy of <span>this</span>'s <span
data-x="offscreencanvas-bitmap">bitmap</span>.</p></li>
<li><p>Let <var>result</var> be a new promise object.</p></li>
<li><p>Let <var>global</var> be <span>this</span>'s <span>relevant global object</span>.</p></li>
<li>
<p>Run these steps <span>in parallel</span>:</p>
<ol>
<li><p>Let <var>file</var> be <span data-x="a serialization of the bitmap as a file">a
serialization of <var>bitmap</var> as a file</span>, with <var>options</var>'s <dfn><code
data-x="image-encode-options-type">type</code></dfn> and <dfn><code
data-x="image-encode-options-quality">quality</code></dfn> if present.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>canvas blob serialization task source</span>
given <var>global</var> to run these steps:</p>
<ol>
<li><p>If <var>file</var> is null, then reject <var>result</var> with an
<span>"<code>EncodingError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Otherwise, resolve <var>result</var> with a new <code>Blob</code> object, created in
<var>global</var>'s <span data-x="concept-relevant-realm">relevant realm</span>, representing
<var>file</var>. <ref>FILEAPI</ref></p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p>The <dfn method for="OffscreenCanvas"><code
data-x="dom-OffscreenCanvas-transferToImageBitmap">transferToImageBitmap()</code></dfn> method,
when invoked, must run the following steps:</p>
<ol>
<li><p>If the value of this <code>OffscreenCanvas</code> object's <span>[[Detached]]</span>
internal slot is set to true, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If this <code>OffscreenCanvas</code> object's <span
data-x="offscreencanvas-context-mode">context mode</span> is set to <span
data-x="offscreencanvas-context-none">none</span>, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>image</var> be a newly created <code>ImageBitmap</code> object that references
the same underlying bitmap data as this <code>OffscreenCanvas</code> object's <span
data-x="offscreencanvas-bitmap">bitmap</span>.</p></li>
<li>
<p>Set this <code>OffscreenCanvas</code> object's <span
data-x="offscreencanvas-bitmap">bitmap</span> to reference a newly created bitmap of the same
dimensions and color space as the previous bitmap, and with its pixels initialized to
<span>transparent black</span>, or <span>opaque black</span> if the rendering context's <span
data-x="concept-canvas-alpha">alpha</span> is false.</p>
<p class="note">This means that if the rendering context of this <code>OffscreenCanvas</code> is
a <code>WebGLRenderingContext</code>, the value of <code
data-x="WebGLContextAttributes">preserveDrawingBuffer</code> will have no effect.
<ref>WEBGL</ref></p>
</li>
<li><p>Return <var>image</var>.</p></li>
</ol>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>OffscreenCanvas</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="OffscreenCanvas"><code data-x="handler-offscreencanvas-oncontextlost">oncontextlost</code></dfn> <td> <code data-x="event-contextlost">contextlost</code>
<tr><td><dfn attribute for="OffscreenCanvas"><code data-x="handler-offscreencanvas-oncontextrestored">oncontextrestored</code></dfn> <td> <code data-x="event-contextrestored">contextrestored</code>
</table>
<h6>The offscreen 2D rendering context</h6>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>OffscreenCanvasRenderingContext2D</dfn> {
readonly attribute <span>OffscreenCanvas</span> <span data-x="offscreencontext2d-canvas">canvas</span>;
};
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasSettings</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasState</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasTransform</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasCompositing</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasImageSmoothing</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasFillStrokeStyles</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasShadowStyles</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasFilters</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasRect</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasDrawPath</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasText</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasDrawImage</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasImageData</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasPathDrawingStyles</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasTextDrawingStyles</span>;
<span>OffscreenCanvasRenderingContext2D</span> includes <span>CanvasPath</span>;</code></pre>
<p>The <code>OffscreenCanvasRenderingContext2D</code> object is a rendering context for drawing to
the <span data-x="offscreencanvas-bitmap">bitmap</span> of an <code>OffscreenCanvas</code> object.
It is similar to the <code>CanvasRenderingContext2D</code> object, with the following
differences:</p>
<ul>
<li><p>there is no support for <span data-x="CanvasUserInterface">user interface</span>
features;</p></li>
<li><p>its <code data-x="offscreencontext2d-canvas">canvas</code> attribute refers to an
<code>OffscreenCanvas</code> object rather than a <code>canvas</code> element;</p></li>
</ul>
<p>An <code>OffscreenCanvasRenderingContext2D</code> object has an <dfn>associated
<code>OffscreenCanvas</code> object</dfn>, which is the <code>OffscreenCanvas</code> object
from which the <code>OffscreenCanvasRenderingContext2D</code> object was created.
<dl class="domintro">
<dt><code data-x=""><var>offscreenCanvas</var> = <var>offscreenCanvasRenderingContext2D</var>.<span subdfn data-x="offscreencontext2d-canvas">canvas</span></code></dt>
<dd><p>Returns the <span>associated <code>OffscreenCanvas</code> object</span>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn>offscreen 2D context creation algorithm</dfn>, which is passed a
<var>target</var> (an <code>OffscreenCanvas</code> object) and optionally some arguments,
consists of running the following steps:</p>
<ol>
<li><p>If the algorithm was passed some arguments, let <var>arg</var> be the first such
argument. Otherwise, let <var>arg</var> be undefined.</p></li>
<li><p>Let <var>settings</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>arg</var> to the dictionary type
<code>CanvasRenderingContext2DSettings</code>. (This can throw an exception.).</p></li>
<li><p>Let <var>context</var> be a new <code>OffscreenCanvasRenderingContext2D</code>
object.</p></li>
<li><p>Set <var>context</var>'s <span>associated <code>OffscreenCanvas</code> object</span> to
<var>target</var>.</p></li>
<li><p>Run the <span data-x="canvas-setting-init-bitmap">canvas settings output bitmap
initialization algorithm</span>, given <var>context</var> and <var>settings</var>.</li>
<li><p>Set <var>context</var>'s <span>output bitmap</span> to a newly created bitmap with the
dimensions specified by the <code data-x="dom-OffscreenCanvas-width">width</code> and <code
data-x="dom-OffscreenCanvas-height">height</code> attributes of <var>target</var>, and set
<var>target</var>'s bitmap to the same bitmap (so that they are shared).</p></li>
<li><p>If <var>context</var>'s <span data-x="concept-canvas-alpha">alpha</span> flag is set to
true, initialize all the pixels of <var>context</var>'s <span>output bitmap</span> to
<span>transparent black</span>. Otherwise, initialize the pixels to <span>opaque
black</span>.</p></li>
<li><p>Return <var>context</var>.</p></li>
</ol>
<p class="note">Implementations are encouraged to short-circuit the graphics update steps of
the <span>window event loop</span> for the purposes of updating the contents of a <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span> to the
display. This could mean, for example, that the bitmap contents are copied directly to a graphics
buffer that is mapped to the physical display location of the <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>. This or
similar short-circuiting approaches can significantly reduce display latency, especially in cases
where the <code>OffscreenCanvas</code> is updated from a
<span>worker event loop</span> and the <span>window event loop</span> of the <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span> is busy.
However, such shortcuts cannot have any script-observable side-effects. This means that the
committed bitmap still needs to be sent to the <span
data-x="offscreencanvas-placeholder">placeholder <code>canvas</code> element</span>, in case the
element is used as a <code>CanvasImageSource</code>, as an <code>ImageBitmapSource</code>, or in
case <code data-x="dom-canvas-toDataURL">toDataURL()</code> or <code
data-x="dom-canvas-toBlob">toBlob()</code> are called on it.</p>
<p>The <dfn attribute for="OffscreenCanvas"><code
data-x="offscreencontext2d-canvas">canvas</code></dfn> attribute, on getting, must return this
<code>OffscreenCanvasRenderingContext2D</code>'s <span>associated <code>OffscreenCanvas</code>
object</span>.
</div>
<div w-nodev>
<!--en-GB--><h5 id="colour-spaces-and-colour-correction">Color spaces and color space
conversion</h5>
<p>The <code>canvas</code> APIs provide mechanisms for specifying the color space of the canvas's
backing store. The default backing store color space for all canvas APIs is
<span>'srgb'</span>.</p>
<p><span data-x="Converting Colors">Color space conversion</span> must be applied to the canvas's
backing store when rendering the canvas to the output device. This color space conversion must be
identical to the color space conversion that would be applied to an <code>img</code> element with
a color profile that specifies the same <span data-x="concept-canvas-color-space">color
space</span> as the canvas's backing store.</p>
<p>When drawing content to a 2D context, all inputs must be <span data-x="Converting
Colors">converted</span> to the <span data-x="concept-canvas-color-space">context's color
space</span> before drawing. Interpolation of gradient color stops must be performed on color
values after conversion to the <span data-x="concept-canvas-color-space">context's color
space</span>. Alpha blending must be performed on values after conversion to the <span
data-x="concept-canvas-color-space">context's color space</span>.</p>
<p class="note">There do not exist any inputs to a 2D context for which the color space is
undefined. The color space for CSS colors is defined in <cite>CSS Color</cite>. The color space
for images that specify no color profile information is assumed to be <span>'srgb'</span>, as
specified in the <a href="https://drafts.csswg.org/css-color/#untagged">Color Spaces of Untagged
Colors</a> section of <cite>CSS Color</cite>. <ref>CSSCOLOR</ref></p>
</div>
<!--en-GB--><h5 id="serialising-bitmaps-to-a-file">Serializing bitmaps to a file</h5>
<div w-nodev>
<p>When a user agent is to create <!--en-GB--><dfn id="a-serialisation-of-the-bitmap-as-a-file">a
serialization of the bitmap as a file</dfn>, given a <var>type</var> and an optional
<var>quality</var>, it must create an image file in the format given by <var>type</var>. If an
error occurs during the creation of the image file (e.g. an internal encoder error), then the
result of the serialization is null. <ref>PNG</ref></p>
<p>The image file's pixel data must be the bitmap's pixel data scaled to one image pixel per
coordinate space unit, and if the file format used supports encoding resolution metadata, the
resolution must be given as 96dpi (one image pixel per <span data-x="'px'">CSS pixel</span>).</p>
<p>If <var>type</var> is supplied, then it must be interpreted as a <span data-x="MIME type">MIME
type</span> giving the format to use. If the type has any parameters, then it must be treated as
not supported.</p>
<p class="example">For example, the value "<code>image/png</code>" would mean to generate a PNG
image, the value "<code>image/jpeg</code>" would mean to generate a JPEG image, and the value
"<code>image/svg+xml</code>" would mean to generate an SVG image (which would require that the
user agent track how the bitmap was generated, an unlikely, though potentially awesome,
feature).</p>
<p>User agents must support PNG ("<code>image/png</code>"). User agents may support other types.
If the user agent does not support the requested type, then it must create the file using the PNG
format. <ref>PNG</ref></p>
<p>User agents must <span data-x="converted to ASCII lowercase">convert the provided type to ASCII
lowercase</span> before establishing if they support that type.</p>
<p>For image types that do not support an alpha component, the serialized image must be the bitmap
image composited onto an <span>opaque black</span> background using the <span
data-x="gcop-source-over">source-over</span> compositing operator.</p>
<p>For image types that support color profiles, the serialized image must include a color profile
indicating the color space of the underlying bitmap. For image types that do not support color
profiles, the serialized image must be <span data-x="Converting Colors">converted</span> to the
<span>'srgb'</span> color space using <span>'relative-colorimetric'</span> rendering intent.</p>
<p class="note">Thus, in the 2D context, calling the <code
data-x="dom-context-2d-drawImage">drawImage()</code> method to render the output of the <code
data-x="dom-canvas-toDataURL">toDataURL()</code> or <code
data-x="dom-canvas-toBlob">toBlob()</code> method to the canvas, given the appropriate dimensions,
has no visible effect beyond, at most, clipping colors of the canvas to a more narrow gamut.</p>
<p>For image types that support multiple bit depths, the serialized image must use the bit depth
that best preserves content of the underlying bitmap.</p>
<p class="example">For example, when serializing a 2D context that has
<span data-x="concept-canvas-color-type">color type</span> of
<span data-x="dom-CanvasColorType-float16">float16</span> to <var>type</var>
"<code>image/png</code>", the resulting image would have 16 bits per sample.
This serialization will still lose significant detail (all values less than 0.5/65535
would be clamped to 0, and all values greater than 1 would be clamped to 1).</p>
<p>If <var>type</var> is an image format that supports variable quality (such as
"<code>image/jpeg</code>"), <var>quality</var> is given, and <var>type</var> is not
"<code>image/png</code>", then, if <var>quality</var> <span data-x="js-Number">is a Number</span>
in the range 0.0 to 1.0 inclusive, the user agent must treat <var>quality</var> as the desired
quality level. Otherwise, the user agent must use its default quality value, as if the
<var>quality</var> argument had not been given.</p>
<p class="note">The use of type-testing here, instead of simply declaring <var>quality</var> as
a Web IDL <code data-x="">double</code>, is a historical artifact.</p>
<p class="note">Different implementations can have slightly different interpretations of
"quality". When the quality is not specified, an implementation-specific default is used that
represents a reasonable compromise between compression ratio, image quality, and encoding
time.</p>
</div>
<div w-nodev>
<h5>Security with <code>canvas</code> elements</h5>
<!-- NON-NORMATIVE SECTION -->
<p><strong>Information leakage</strong> can occur if scripts from one <span>origin</span> can
access information (e.g. read pixels) from images from another origin (one that isn't the <span
data-x="same origin">same</span>).</p>
<p>To mitigate this, bitmaps used with <code>canvas</code> elements, <code>OffscreenCanvas</code>
objects, and <code>ImageBitmap</code> objects are defined to have a flag indicating whether they
are <span data-x="concept-canvas-origin-clean">origin-clean</span>. All bitmaps start with their
<span data-x="concept-canvas-origin-clean">origin-clean</span> set to true. The flag is set to
false when cross-origin images are used.</p>
<p>The <code data-x="dom-canvas-toDataURL">toDataURL()</code>, <code
data-x="dom-canvas-toBlob">toBlob()</code>, and <code
data-x="dom-context-2d-getImageData">getImageData()</code> methods check the flag and will
throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> rather than leak
cross-origin data.</p>
<p>The value of the <span data-x="concept-canvas-origin-clean">origin-clean</span> flag is
propagated from a source's bitmap to a new <code>ImageBitmap</code> object by <code
data-x="dom-createImageBitmap">createImageBitmap()</code>. Conversely, a destination <code
>canvas</code> element's bitmap will have its <span
data-x="concept-canvas-origin-clean">origin-clean</span> flags set to false by <code
data-x="dom-context-2d-drawImage">drawImage</code> if the source image is an
<code>ImageBitmap</code> object whose bitmap has its <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag set to false.</p>
<p>The flag can be reset in certain situations; for example, when changing the value of the
<code data-x="attr-canvas-width">width</code> or the <code
data-x="attr-canvas-height">height</code> content attribute of the <code>canvas</code> element
to which a <code>CanvasRenderingContext2D</code> is bound, the bitmap is
cleared and its <span data-x="concept-canvas-origin-clean">origin-clean</span> flag is reset.</p>
<p>When using an <code>ImageBitmapRenderingContext</code>, the value of the <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag is propagated from
<code>ImageBitmap</code> objects when they are transferred to the <code>canvas</code>
via <span
data-x="dom-ImageBitmapRenderingContext-transferFromImageBitmap">transferFromImageBitmap()</span>.</p>
</div>
<h5>Premultiplied alpha and the 2D rendering context</h5>
<p><dfn data-x="concept-premultiplied-alpha">Premultiplied alpha</dfn> refers to one way of
representing transparency in an image, the other being non-premultiplied alpha.</p>
<p>Under non-premultiplied alpha, the red, green, and blue components of a pixel represent that
pixel's color, and its alpha component represents that pixel's opacity.</p>
<p>Under premultiplied alpha, however, the red, green, and blue components of a pixel represent
the amounts of color that the pixel adds to the image, and its alpha component represents the
amount that the pixel obscures whatever is behind it.</p>
<div class="example">
<p>For instance, assuming the color components range from 0 (off) to 255 (full intensity), these
example colors are represented in the following ways:</p>
<table>
<thead>
<tr>
<th>CSS color representation
<th>Premultiplied representation
<th>Non-premultiplied representation
<th>Description of color
<th>Image of color blended above other content
<tbody>
<tr>
<td>rgba(255, 127, 0, 1)
<td>255, 127, 0, 255
<td>255, 127, 0, 255
<td>Completely-opaque orange
<td><img src="images/premultiplied-example-1.png" width="96" height="96" alt="An opaque orange circle sits atop a background">
<tr>
<td>rgba(255, 255, 0, 0.5)
<td>127, 127, 0, 127
<td>255, 255, 0, 127
<td>Halfway-opaque yellow
<td><img src="images/premultiplied-example-2.png" width="96" height="96" alt="A yellow circle, halfway transparent, sits atop a background">
<tr>
<td>Unrepresentable
<td>255, 127, 0, 127
<td>Unrepresentable
<td>Additive halfway-opaque orange
<td><img src="images/premultiplied-example-3.png" width="96" height="96" alt="An orange circle somewhat brightens the background that it sits atop">
<tr>
<td>Unrepresentable
<td>255, 127, 0, 0
<td>Unrepresentable
<td>Additive fully-transparent orange
<td><img src="images/premultiplied-example-4.png" width="96" height="96" alt="An orange circle completely brightens the background that it sits atop">
<tr>
<td>rgba(255, 127, 0, 0)
<td>0, 0, 0, 0
<td>255, 127, 0, 0
<td>Fully-transparent ("invisible") orange
<td><img src="images/premultiplied-example-5.png" width="96" height="96" alt="An empty background with nothing atop it">
<tr>
<td>rgba(0, 127, 255, 0)
<td>0, 0, 0, 0
<td>255, 127, 0, 0
<td>Fully-transparent ("invisible") turquoise
<td><img src="images/premultiplied-example-5.png" width="96" height="96" alt="An empty background with nothing atop it">
</table>
</div>
<p><dfn data-x="convert-to-premultiplied">Converting a color value from a non-premultiplied
representation to a premultiplied one</dfn> involves multiplying the color's red, green, and
blue components by its alpha component (remapping the range of the alpha component such that
"fully transparent" is 0, and "fully opaque" is 1).</p>
<p><dfn data-x="convert-from-premultiplied">Converting a color value from a premultiplied
representation to a non-premultiplied one</dfn> involves the inverse: dividing the color's red,
green, and blue components by its alpha component.</p>
<p>As certain colors can only be represented under premultiplied alpha (for instance, additive
colors), and others can only be represented under non-premultiplied alpha (for instance,
"invisible" colors which hold certain red, green, and blue values even with no opacity); and
division and multiplication using finite precision entails a loss of accuracy, converting between
premultiplied and non-premultiplied alpha is a lossy operation on colors that are not fully
opaque.</p>
<p>A <code>CanvasRenderingContext2D</code>'s <span>output bitmap</span> and an
<code>OffscreenCanvasRenderingContext2D</code>'s <span>output bitmap</span> must use premultiplied
alpha to represent transparent colors.</p>
<p class="note">It is important for canvas bitmaps to represent colors using premultiplied alpha
because it affects the range of representable colors. While additive colors cannot currently be
drawn onto canvases directly because CSS colors are non-premultiplied and cannot represent them,
it is still possible to, for instance, draw additive colors onto a WebGL canvas and then draw that
WebGL canvas onto a 2D canvas via <code data-x="dom-context-2d-drawImage">drawImage()</code>.</p>
<h3 split-filename="custom-elements" id="custom-elements">Custom elements</h3>
<h4 id="custom-elements-intro">Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p><span data-x="custom element">Custom elements</span> provide a way for authors to build their
own fully-featured DOM elements. Although authors could always use non-standard elements in their
documents, with application-specific behavior added after the fact by scripting or similar, such
elements have historically been non-conforming and not very functional. By <span
data-x="element definition">defining</span> a custom element, authors can inform the parser how to
properly construct an element and how elements of that class should react to changes.</p>
<p>Custom elements are part of a larger effort to "rationalise the platform", by explaining
existing platform features (like the elements of HTML) in terms of lower-level author-exposed
extensibility points (like custom element definition). Although today there are many limitations
on the capabilities of custom elements—both functionally and semantically—that prevent them from
fully explaining the behaviors of HTML's existing elements, we hope to shrink this gap over
time.</p>
<h5 id="custom-elements-autonomous-example">Creating an autonomous custom element</h5>
<!-- NON-NORMATIVE SECTION -->
<p>For the purposes of illustrating how to create an <span>autonomous custom element</span>, let's
define a custom element that encapsulates rendering a small icon for a country flag. Our goal is
to be able to use it like so:</p>
<pre><code class="html"><flag-icon country="nl"></flag-icon></code></pre>
<p>To do this, we first declare a class for the custom element, extending
<code>HTMLElement</code>:</p>
<pre><code class="js">class FlagIcon extends HTMLElement {
constructor() {
super();
this._countryCode = null;
}
static observedAttributes = ["country"];
attributeChangedCallback(name, oldValue, newValue) {
// name will always be "country" due to observedAttributes
this._countryCode = newValue;
this._updateRendering();
}
connectedCallback() {
this._updateRendering();
}
get country() {
return this._countryCode;
}
set country(v) {
this.setAttribute("country", v);
}
_updateRendering() {
// Left as an exercise for the reader. But, you'll probably want to
// check this.ownerDocument.defaultView to see if we've been
// inserted into a document with a browsing context, and avoid
// doing any work if not.
}
}</code></pre>
<p>We then need to use this class to define the element:</p>
<pre><code class="js">customElements.define("flag-icon", FlagIcon);</code></pre>
<p>At this point, our above code will work! The parser, whenever it sees the <code
data-x="">flag-icon</code> tag, will construct a new instance of our <code
data-x="">FlagIcon</code> class, and tell our code about its new <code data-x="">country</code>
attribute, which we then use to set the element's internal state and update its rendering (when
appropriate).</p>
<p>You can also create <code data-x="">flag-icon</code> elements using the DOM API:</p>
<pre><code class="js">const flagIcon = document.createElement("flag-icon")
flagIcon.country = "jp"
document.body.appendChild(flagIcon)</code></pre>
<p>Finally, we can also use the <span>custom element constructor</span> itself. That is, the above
code is equivalent to:</p>
<pre><code class="js">const flagIcon = new FlagIcon()
flagIcon.country = "jp"
document.body.appendChild(flagIcon)</code></pre>
<h5 id="custom-elements-face-example">Creating a form-associated custom element</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Adding a static <code data-x="">formAssociated</code> property, with a true value, makes an
<span>autonomous custom element</span> a <span>form-associated custom element</span>. The
<code>ElementInternals</code> interface helps you to implement functions and properties common
to form control elements.</p>
<pre><code class="js">class MyCheckbox extends HTMLElement {
static formAssociated = true;
static observedAttributes = ['checked'];
constructor() {
super();
this._internals = this.attachInternals();
this.addEventListener('click', this._onClick.bind(this));
}
get form() { return this._internals.form; }
get name() { return this.getAttribute('name'); }
get type() { return this.localName; }
get checked() { return this.hasAttribute('checked'); }
set checked(flag) { this.toggleAttribute('checked', Boolean(flag)); }
attributeChangedCallback(name, oldValue, newValue) {
// name will always be "checked" due to observedAttributes
this._internals.setFormValue(this.checked ? 'on' : null);
}
_onClick(event) {
this.checked = !this.checked;
}
}
customElements.define('my-checkbox', MyCheckbox);</code></pre>
<p>You can use the custom element <code data-x="">my-checkbox</code> like a built-in
form-associated element. For example, putting it in <code>form</code> or <code>label</code>
associates the <code data-x="">my-checkbox</code> element with them, and submitting the
<code>form</code> will send data provided by <code data-x="">my-checkbox</code> implementation.
</p>
<pre><code class="html"><form action="..." method="...">
<label><my-checkbox name="agreed"></my-checkbox> I read the agreement.</label>
<input type="submit">
</form>
</code></pre>
<h5 id="custom-elements-accessibility-example">Creating a custom element with default accessible roles, states, and properties</h5>
<!-- NON-NORMATIVE SECTION -->
<p>By using the appropriate properties of <code>ElementInternals</code>, your custom element can
have default accessibility semantics. The following code expands our form-associated checkbox from
the previous section to properly set its default role and checkedness, as viewed by accessibility
technology:</p>
<pre><code class="js" data-x="">class MyCheckbox extends HTMLElement {
static formAssociated = true;
static observedAttributes = ['checked'];
constructor() {
super();
this._internals = this.attachInternals();
this.addEventListener('click', this._onClick.bind(this));
<mark> this._internals.role = 'checkbox';
this._internals.ariaChecked = 'false';</mark>
}
get form() { return this._internals.form; }
get name() { return this.getAttribute('name'); }
get type() { return this.localName; }
get checked() { return this.hasAttribute('checked'); }
set checked(flag) { this.toggleAttribute('checked', Boolean(flag)); }
attributeChangedCallback(name, oldValue, newValue) {
// name will always be "checked" due to observedAttributes
this._internals.setFormValue(this.checked ? 'on' : null);
<mark> this._internals.ariaChecked = this.checked;</mark>
}
_onClick(event) {
this.checked = !this.checked;
}
}
customElements.define('my-checkbox', MyCheckbox);</code></pre>
<p>Note that, like for built-in elements, these are only defaults, and can be overridden by the
page author using the <code data-x="attr-aria-role">role</code> and <code
data-x="attr-aria-*">aria-*</code> attributes:</p>
<pre class="bad"><code class="html" data-x=""><!-- This markup is non-conforming -->
<input type="checkbox" checked role="button" aria-checked="false"></code></pre>
<pre class="bad"><code class="html" data-x=""><!-- This markup is probably not what the custom element author intended -->
<my-checkbox role="button" checked aria-checked="false"></code></pre>
<p>Custom element authors are encouraged to state what aspects of their accessibility semantics
are strong native semantics, i.e., should not be overridden by users of the custom element. In our
example, the author of the <code data-x="">my-checkbox</code> element would state that its
<span>role</span> and <code data-x="attr-aria-checked">aria-checked</code> values are strong
native semantics, thus discouraging code such as the above.</p>
<h5 id="custom-elements-customized-builtin-example">Creating a customized built-in element</h5>
<!-- NON-NORMATIVE SECTION -->
<p><span data-x="customized built-in element">Customized built-in elements</span> are a distinct
kind of <span>custom element</span>, which are defined slightly differently and used very
differently compared to <span data-x="autonomous custom element">autonomous custom
elements</span>. They exist to allow reuse of behaviors from the existing elements of HTML, by
extending those elements with new custom functionality. This is important since many of the
existing behaviors of HTML elements can unfortunately not be duplicated by using purely <span
data-x="autonomous custom element">autonomous custom elements</span>. Instead, <span
data-x="customized built-in element">customized built-in elements</span> allow the installation of
custom construction behavior, lifecycle hooks, and prototype chain onto existing elements,
essentially "mixing in" these capabilities on top of the already-existing element.</p>
<p><span data-x="customized built-in element">Customized built-in elements</span> require a
distinct syntax from <span data-x="autonomous custom element">autonomous custom elements</span>
because user agents and other software key off an element's local name in order to identify the
element's semantics and behavior. That is, the concept of <span data-x="customized built-in
element">customized built-in elements</span> building on top of existing behavior depends
crucially on the extended elements retaining their original local name.</p>
<p>In this example, we'll be creating a <span>customized built-in element</span> named <code
data-x="">plastic-button</code>, which behaves like a normal button but gets fancy animation
effects added whenever you click on it. We start by defining a class, just like before, although
this time we extend <code>HTMLButtonElement</code> instead of <code>HTMLElement</code>:</p>
<pre><code class="js">class PlasticButton extends HTMLButtonElement {
constructor() {
super();
this.addEventListener("click", () => {
// Draw some fancy animation effects!
});
}
}</code></pre>
<p>When defining our custom element, we have to also specify the <code
data-x="dom-ElementDefinitionOptions-extends">extends</code> option:</p>
<pre><code class="js">customElements.define("plastic-button", PlasticButton, { extends: "button" });</code></pre>
<p>In general, the name of the element being extended cannot be determined simply by looking at
what element interface it extends, as many elements share the same interface (such as
<code>q</code> and <code>blockquote</code> both sharing <code>HTMLQuoteElement</code>).</p>
<p>To construct our <span>customized built-in element</span> from parsed HTML source text, we use
the <code data-x="attr-is">is</code> attribute on a <code>button</code> element:</p>
<pre><code class="html"><button is="plastic-button">Click Me!</button></code></pre>
<p>Trying to use a <span>customized built-in element</span> as an <span>autonomous custom
element</span> will <em>not</em> work; that is, <code data-x=""><plastic-button>Click
me?</plastic-button></code> will simply create an <code>HTMLElement</code> with no special
behavior.</p>
<p>If you need to create a customized built-in element programmatically, you can use the following
form of <code data-x="dom-Document-createElement">createElement()</code>:</p>
<pre><code class="js">const plasticButton = document.createElement("button", { is: "plastic-button" });
plasticButton.textContent = "Click me!";</code></pre>
<p>And as before, the constructor will also work:</p>
<pre><code class="js">const plasticButton2 = new PlasticButton();
console.log(plasticButton2.localName); // will output "button"
console.assert(plasticButton2 instanceof PlasticButton);
console.assert(plasticButton2 instanceof HTMLButtonElement);</code></pre>
<p>Note that when creating a customized built-in element programmatically, the <code
data-x="attr-is">is</code> attribute will not be present in the DOM, since it was not explicitly
set. However, <a href="#attr-is-during-serialization">it will be added to the output when
serializing</a>:</p>
<pre><code class="js">console.assert(!plasticButton.hasAttribute("is"));
console.log(plasticButton.outerHTML); // will output '<button is="plastic-button"></button>'</code></pre>
<p>Regardless of how it is created, all of the ways in which <code>button</code> is special
apply to such "plastic buttons" as well: their focus behavior, ability to participate in <span
data-x="concept-form-submit">form submission</span>, the <code
data-x="attr-fe-disabled">disabled</code> attribute, and so on.</p>
<p id="customized-built-in-element-restrictions"><span data-x="customized built-in
element">Customized built-in elements</span> are designed to allow extension of existing HTML
elements that have useful user-agent supplied behavior or APIs. As such, they can only extend
existing HTML elements defined in this specification, and cannot extend legacy elements such as
<code>bgsound</code>, <code>blink</code>, <code>isindex</code>, <code>keygen</code>,
<code>multicol</code>, <code>nextid</code>, or <code>spacer</code> that have been defined to use
<code>HTMLUnknownElement</code> as their <span>element interface</span>.</p>
<p>One reason for this requirement is future-compatibility: if a <span>customized built-in
element</span> was defined that extended a currently-unknown element, for example <code
data-x="">combobox</code>, this would prevent this specification from defining a <code
data-x="">combobox</code> element in the future, as consumers of the derived <span>customized
built-in element</span> would have come to depend on their base element having no interesting
user-agent-supplied behavior.</p>
<h5 id="custom-elements-autonomous-drawbacks">Drawbacks of autonomous custom elements</h5>
<!-- NON-NORMATIVE SECTION -->
<p>As specified below, and alluded to above, simply defining and using an element called
<code data-x="">taco-button</code> does not mean that such elements <span
data-x="represents">represent</span> buttons. That is, tools such as web browsers, search engines,
or accessibility technology will not automatically treat the resulting element as a button just
based on its defined name.</p>
<p>To convey the desired button semantics to a variety of users, while still using an
<span>autonomous custom element</span>, a number of techniques would need to be employed:</p>
<ul>
<li><p>The addition of the <code data-x="attr-tabindex">tabindex</code> attribute would make the
<code data-x="">taco-button</code> <span>focusable</span>. Note that if the
<code data-x="">taco-button</code> were to become logically disabled, the <code
data-x="attr-tabindex">tabindex</code> attribute would need to be removed.</p></li>
<li><p>The addition of an ARIA role and various ARIA states and properties helps convey semantics
to accessibility technology. For example, setting the <span>role</span> to "<code
data-x="attr-aria-role-button">button</code>" will convey the semantics that this is a button,
enabling users to successfully interact with the control using usual button-like interactions in
their accessibility technology. Setting the <code data-x="attr-aria-label">aria-label</code>
property is necessary to give the button an <span data-x="concept-accessible-name">accessible
name</span>, instead of having accessibility technology traverse its child text nodes and
announce them. And setting the <code data-x="attr-aria-disabled">aria-disabled</code> state to
"<code data-x="">true</code>" when the button is logically disabled conveys to accessibility
technology the button's disabled state.</p></li>
<li><p>The addition of event handlers to handle commonly-expected button behaviors helps convey
the semantics of the button to web browser users. In this case, the most relevant event handler
would be one that proxies appropriate <code data-x="event-keydown">keydown</code> events to
become <code data-x="event-click">click</code> events, so that you can activate the button both
with keyboard and by clicking.</li>
<li><p>In addition to any default visual styling provided for <code data-x="">taco-button</code>
elements, the visual styling will also need to be updated to reflect changes in logical state,
such as becoming disabled; that is, whatever style sheet has rules for <code
data-x="">taco-button</code> will also need to have rules for <code
data-x="">taco-button[disabled]</code>.</p></li>
</ul>
<p>With these points in mind, a full-featured <code data-x="">taco-button</code> that took on the
responsibility of conveying button semantics (including the ability to be disabled) might look
something like this:</p>
<pre id="custom-elements-autonomous-drawbacks-example"><code
class="js">class TacoButton extends HTMLElement {
static observedAttributes = ["disabled"];
constructor() {
super();
this._internals = this.attachInternals();
this._internals.role = "button";
this.addEventListener("keydown", e => {
if (e.code === "Enter" || e.code === "Space") {
this.dispatchEvent(new PointerEvent("click", {
bubbles: true,
cancelable: true
}));
}
});
this.addEventListener("click", e => {
if (this.disabled) {
e.preventDefault();
e.stopImmediatePropagation();
}
});
this._observer = new MutationObserver(() => {
this._internals.ariaLabel = this.textContent;
});
}
connectedCallback() {
this.setAttribute("tabindex", "0");
this._observer.observe(this, {
childList: true,
characterData: true,
subtree: true
});
}
disconnectedCallback() {
this._observer.disconnect();
}
get disabled() {
return this.hasAttribute("disabled");
}
set disabled(flag) {
this.toggleAttribute("disabled", Boolean(flag));
}
attributeChangedCallback(name, oldValue, newValue) {
// name will always be "disabled" due to observedAttributes
if (this.disabled) {
this.removeAttribute("tabindex");
this._internals.ariaDisabled = "true";
} else {
this.setAttribute("tabindex", "0");
this._internals.ariaDisabled = "false";
}
}
}</code></pre>
<p>Even with this rather-complicated element definition, the element is not a pleasure to use for
consumers: it will be continually "sprouting" <code data-x="attr-tabindex">tabindex</code>
attributes of its own volition, and its choice of <code data-x="">tabindex="0"</code> focusability
behavior may not match the <code>button</code> behavior on the current platform. This is because
as of now there is no way to specify default focus behavior for custom elements, forcing the use
of the <code data-x="attr-tabindex">tabindex</code> attribute to do so (even though it is usually
reserved for allowing the consumer to override default behavior).</p>
<p>In contrast, a simple <span>customized built-in element</span>, as shown in the previous
section, would automatically inherit the semantics and behavior of the <code>button</code>
element, with no need to implement these behaviors manually. In general, for any elements with
nontrivial behavior and semantics that build on top of existing elements of HTML, <span
data-x="customized built-in element">customized built-in elements</span> will be easier to
develop, maintain, and consume.</p>
<h5 id="custom-elements-upgrades-examples">Upgrading elements after their creation</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Because <span>element definition</span> can occur at any time, a non-custom element could be
<span data-x="create an element">created</span>, and then later become a <span>custom
element</span> after an appropriate <span data-x="custom element definition">definition</span> is
registered. We call this process "upgrading" the element, from a normal element into a custom
element.</p>
<p><span data-x="custom-element-upgrades">Upgrades</span> enable scenarios where it may be
preferable for <span data-x="custom element definition">custom element definitions</span> to be
registered after relevant elements have been initially created, such as by the parser. They allow
progressive enhancement of the content in the custom element. For example, in the following HTML
document the element definition for <code data-x="">img-viewer</code> is loaded
asynchronously:</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<title>Image viewer example</title>
<img-viewer filter="Kelvin">
<img src="images/tree.jpg" alt="A beautiful tree towering over an empty savannah">
</img-viewer>
<script src="js/elements/img-viewer.js" async></script></code></pre>
<p>The definition for the <code data-x="">img-viewer</code> element here is loaded using a
<code>script</code> element marked with the <code data-x="attr-script-async">async</code>
attribute, placed after the <code data-x=""><img-viewer></code> tag in the markup. While the
script is loading, the <code data-x="">img-viewer</code> element will be treated as an undefined
element, similar to a <code>span</code>. Once the script loads, it will define the <code
data-x="">img-viewer</code> element, and the existing <code data-x="">img-viewer</code> element on
the page will be upgraded, applying the custom element's definition (which presumably includes
applying an image filter identified by the string "Kelvin", enhancing the image's visual
appearance).</p>
<hr>
<p>Note that <span data-x="custom-element-upgrades">upgrades</span> only apply to elements in the
document tree. (Formally, elements that are <span>connected</span>.) An element that is not
inserted into a document will stay un-upgraded. An example illustrates this point:</p>
<pre><code class="html"><!DOCTYPE html>
<html lang="en">
<title>Upgrade edge-cases example</title>
<example-element></example-element>
<script>
"use strict";
const inDocument = document.querySelector("example-element");
const outOfDocument = document.createElement("example-element");
// Before the element definition, both are HTMLElement:
console.assert(inDocument instanceof HTMLElement);
console.assert(outOfDocument instanceof HTMLElement);
class ExampleElement extends HTMLElement {}
customElements.define("example-element", ExampleElement);
// After element definition, the in-document element was upgraded:
console.assert(inDocument instanceof ExampleElement);
console.assert(!(outOfDocument instanceof ExampleElement));
document.body.appendChild(outOfDocument);
// Now that we've moved the element into the document, it too was upgraded:
console.assert(outOfDocument instanceof ExampleElement);
</script></code></pre>
<h5>Exposing custom element states</h5>
<p>Built-in elements provided by user agents have certain states that can change over time
depending on user interaction and other factors, and are exposed to web authors through <span
data-x="pseudo-class">pseudo-classes</span>. For example, some form controls have the "invalid"
state, which is exposed through the <code data-x="selector-invalid">:invalid</code>
<span>pseudo-class</span>.</p>
<p>Like built-in elements, <span data-x="custom element">custom elements</span> can have various
states to be in too, and <span>custom element</span> authors want to expose these states in a
similar fashion as the built-in elements.</p>
<p>This is done via the <code data-x="selector-custom">:state()</code> pseudo-class. A custom
element author can use the <code data-x="dom-ElementInternals-states">states</code> property of
<code>ElementInternals</code> to add and remove such custom states, which are then exposed as
arguments to the <code data-x="selector-custom">:state()</code> pseudo-class.
<div class="example">
<p>The following shows how <code data-x="selector-custom">:state()</code> can be used to style a
custom checkbox element. Assume that <code data-x="">LabeledCheckbox</code> doesn't expose its
"checked" state via a content attribute.</p>
<pre><code class="html"><script>
class LabeledCheckbox extends HTMLElement {
constructor() {
super();
this._internals = this.attachInternals();
this.addEventListener('click', this._onClick.bind(this));
const shadowRoot = this.attachShadow({mode: 'closed'});
shadowRoot.innerHTML =
`<style>
:host::before {
content: '[ ]';
white-space: pre;
font-family: monospace;
}
:host(:state(checked))::before { content: '[x]' }
</style>
<slot>Label</slot>`;
}
get checked() { return this._internals.states.has('checked'); }
set checked(flag) {
if (flag)
this._internals.states.add('checked');
else
this._internals.states.delete('checked');
}
_onClick(event) {
this.checked = !this.checked;
}
}
customElements.define('labeled-checkbox', LabeledCheckbox);
</script>
<style>
labeled-checkbox { border: dashed red; }
labeled-checkbox:state(checked) { border: solid; }
</style>
<labeled-checkbox>You need to check this</labeled-checkbox></code></pre>
</div>
<div class="example">
<p>Custom pseudo-classes can even target shadow parts. An extension of the above example shows
this:</p>
<pre><code class="html"><script>
class QuestionBox extends HTMLElement {
constructor() {
super();
const shadowRoot = this.attachShadow({mode: 'closed'});
shadowRoot.innerHTML =
`<div><slot>Question</slot></div>
<labeled-checkbox part='checkbox'>Yes</labeled-checkbox>`;
}
}
customElements.define('question-box', QuestionBox);
</script>
<style>
question-box::part(checkbox) { color: red; }
question-box::part(checkbox):state(checked) { color: green; }
</style>
<question-box>Continue?</question-box></code></pre>
</div>
<h4 id="custom-element-conformance">Requirements for custom element constructors and
reactions</h4>
<p>When authoring <span data-x="custom element constructor">custom element constructors</span>,
authors are bound by the following conformance requirements:</p>
<ul>
<li><p>A parameter-less call to <code data-x="">super()</code> must be the first statement in the
constructor body, to establish the correct prototype chain and <b>this</b> value before any
further code is run.</p></li>
<li><p>A <code data-x="">return</code> statement must not appear anywhere inside the constructor
body, unless it is a simple early-return (<code data-x="">return</code> or <code data-x="">return
this</code>).</p></li>
<li><p>The constructor must not use the <code data-x="dom-document-write">document.write()</code>
or <code data-x="dom-document-open">document.open()</code> methods.</p></li>
<li><p>The element's attributes and children must not be inspected, as in the non-<span
data-x="custom-element-upgrades">upgrade</span> case none will be present, and relying on
upgrades makes the element less usable.</p></li>
<li><p>The element must not gain any attributes or children, as this violates the expectations of
consumers who use the <code data-x="dom-Document-createElement">createElement</code> or <code
data-x="dom-Document-createElementNS">createElementNS</code> methods.</p></li>
<li><p>In general, work should be deferred to <code data-x="">connectedCallback</code> as much as
possible—especially work involving fetching resources or rendering. However, note that <code
data-x="">connectedCallback</code> can be called more than once, so any initialization work that
is truly one-time will need a guard to prevent it from running twice.</p></li>
<li><p>In general, the constructor should be used to set up initial state and default values, and
to set up event listeners and possibly a <span>shadow root</span>.</p></li>
</ul>
<p>Several of these requirements are checked during <span data-x="create an element">element
creation</span>, either directly or indirectly, and failing to follow them will result in a custom
element that cannot be instantiated by the parser or DOM APIs. This is true even if the work is
done inside a constructor-initiated <span>microtask</span>, as a <span data-x="perform a microtask
checkpoint">microtask checkpoint</span> can occur immediately after construction.</p>
<p>When authoring <span data-x="concept-custom-element-reaction">custom element reactions</span>,
authors should avoid manipulating the node tree as this can lead to unexpected results.</p>
<div class="example">
<p>An element's <code data-x="">connectedCallback</code> can be queued before the element is
disconnected, but as the callback queue is still processed, it results in a <code
data-x="">connectedCallback</code> for an element that is no longer connected:</p>
<pre><code class="js">class CParent extends HTMLElement {
connectedCallback() {
this.firstChild.remove();
}
}
customElements.define("c-parent", CParent);
class CChild extends HTMLElement {
connectedCallback() {
console.log("CChild connectedCallback: isConnected =", this.isConnected);
}
}
customElements.define("c-child", CChild);
const parent = new CParent(),
child = new CChild();
parent.append(child);
document.body.append(parent);
// Logs:
// CChild connectedCallback: isConnected = false</code></pre>
</div>
<h5>Preserving custom element state when moved</h5>
<!-- NON-NORMATIVE SECTION -->
<p>When manipulating the DOM tree, an element can be <span
data-x="concept-node-move-ext">moved</span> in the tree while connected. This applies to custom
elements as well. By default, the "<code data-x="">disconnectedCallback</code>" and "<code
data-x="">connectedCallback</code>" would be called on the element, one after the other. This is
done to maintain compatibility with existing custom elements that predate the <code
data-x="dom-ParentNode-moveBefore">moveBefore()</code> method. This means that by default, custom
elements reset their state as if they were removed and re-inserted. In the example <a
href="#custom-elements-autonomous-drawbacks-example">above</a>, the impact would be that the
observer would be disconnected and re-connected, and the tab index would be reset.</p>
<p>To opt in to a state-preserving behavior while <span
data-x="concept-node-move-ext">moving</span>, the author can implement a "<code
data-x="">connectedMoveCallback</code>". The existence of this callback, even if empty, would
supercede the default behavior of calling "<code data-x="">disconnectedCallback</code>" and "<code
data-x="">connectedCallback</code>". "<code data-x="">connectedMoveCallback</code>" can also be an
appropriate place to execute logic that depends on the element's ancestors. For example:</p>
<pre><code class="js">class TacoButton extends HTMLElement {
static observedAttributes = ["disabled"];
constructor() {
super();
this._internals = this.attachInternals();
this._internals.role = "button";
this._observer = new MutationObserver(() => {
this._internals.ariaLabel = this.textContent;
});
}
_notifyMain() {
if (this.parentElement.tagName === "MAIN") {
// Execute logic that depends on ancestors.
}
}
connectedCallback() {
this.setAttribute("tabindex", "0");
this._observer.observe(this, {
childList: true,
characterData: true,
subtree: true
});
this._notifyMain();
}
disconnectedCallback() {
this._observer.disconnect();
}
// Implementing this function would avoid resetting the tab index or re-registering the
// mutation observer when this element is moved inside the DOM without being disconnected.
connectedMoveCallback() {
// The parent can change during a state-preserving move.
this._notifyMain();
}
}</code></pre>
<h4 id="custom-elements-core-concepts">Core concepts</h4>
<p>A <dfn export>custom element</dfn> is an element that is <span
data-x="concept-element-custom">custom</span>. Informally, this means that its constructor and
prototype are defined by the author, instead of by the user agent. This author-supplied
constructor function is called the <dfn export>custom element constructor</dfn>.</p>
<p>Two distinct types of <span data-x="custom element">custom elements</span> can be defined:</p>
<ol>
<li><p>An <dfn export>autonomous custom element</dfn>, which is defined with no <code
data-x="dom-ElementDefinitionOptions-extends">extends</code> option. These types of custom
elements have a local name equal to their <span
data-x="concept-custom-element-definition-name">defined name</span>.</p></li>
<li><p>A <dfn export>customized built-in element</dfn>, which is defined with an <code
data-x="dom-ElementDefinitionOptions-extends">extends</code> option. These types of custom
elements have a local name equal to the value passed in their <code
data-x="dom-ElementDefinitionOptions-extends">extends</code> option, and their <span
data-x="concept-custom-element-definition-name">defined name</span> is used as the value of the
<dfn element-attr for="html-global"><code data-x="attr-is">is</code></dfn> attribute, which
therefore must be a <span>valid custom element name</span>.</p></li>
</ol>
<p>After a <span>custom element</span> is <span data-x="create an element">created</span>,
changing the value of the <code data-x="attr-is">is</code> attribute does not
change the element's behavior<span w-nodev>, as it is saved on the element as its <span
data-x="concept-element-is-value"><code data-x="">is</code> value</span></span>.</p>
<p><span data-x="autonomous custom element">Autonomous custom elements</span> have the following
element definition:</p>
<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Phrasing content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dd>For <span data-x="form-associated custom element">form-associated custom elements</span>: <span data-x="category-listed">Listed</span>, <span data-x="category-label">labelable</span>, <span data-x="category-submit">submittable</span>, and <span data-x="category-reset">resettable</span> <span>form-associated element</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>phrasing content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Transparent</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span>, except the <code data-x="attr-is">is</code> attribute<!-- no-annotate --></dd>
<dd><code data-x="attr-fae-form">form</code>, for <span data-x="form-associated custom element">form-associated custom elements</span></dd>
<dd><code data-x="attr-fe-disabled">disabled</code>, for <span data-x="form-associated custom element">form-associated custom elements</span></dd>
<dd><code data-x="attr-face-readonly">readonly</code>, for <span data-x="form-associated custom element">form-associated custom elements</span></dd>
<dd><code data-x="attr-fe-name">name</code>, for <span data-x="form-associated custom element">form-associated custom elements</span></dd>
<dd>Any other attribute that has no namespace (see prose).</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd>For <span data-x="form-associated custom element">form-associated custom elements</span>: <a
href="https://w3c.github.io/html-aria/#el-form-associated-custom-element">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-form-associated-custom-element">for implementers</a>.</dd>
<dd>Otherwise: <a
href="https://w3c.github.io/html-aria/#el-autonomous-custom-element">for authors</a>; <a
href="https://w3c.github.io/html-aam/#el-autonomous-custom-element">for implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Supplied by the element's author (inherits from <code>HTMLElement</code>)</dd>
</dl>
<p>An <span>autonomous custom element</span> does not have any special meaning: it
<span>represents</span> its children. A <span>customized built-in element</span> inherits the
semantics of the element that it extends.</p>
<p>Any namespace-less attribute that is relevant to the element's functioning, as determined by
the element's author, may be specified on an <span>autonomous custom element</span>, so long as
the attribute name is <span>XML-compatible</span> and contains no <span data-x="ASCII upper
alpha">ASCII upper alphas</span>. The exception is the <code data-x="attr-is">is</code> attribute,
which must not be specified on an <span>autonomous custom element</span> (and which will have no
effect if it is).</p>
<p><span data-x="customized built-in element">Customized built-in elements</span> follow the
normal requirements for attributes, based on the elements they extend. To add custom
attribute-based behavior, use <code data-x="attr-data-*">data-*</code> attributes.</p>
<hr>
<p>An <span>autonomous custom element</span> is called a <dfn export>form-associated custom
element</dfn> if the element is associated with a <span>custom element definition</span> whose
<span data-x="concept-custom-element-definition-form-associated">form-associated</span> field is
set to true.</p>
<p>The <code data-x="attr-fe-name">name</code> attribute represents the <span>form-associated
custom element</span>'s name. The <code data-x="attr-fe-disabled">disabled</code> attribute is
used to make the <span>form-associated custom element</span> non-interactive and to prevent its
<span data-x="face-submission-value">submission value</span> from being submitted. The <code
data-x="attr-fae-form">form</code> attribute is used to explicitly associate the
<span>form-associated custom element</span> with its <span>form owner</span>.</p>
<p>The <dfn element-attr for="form-associated custom elements"
data-x="attr-face-readonly"><code>readonly</code></dfn> attribute of <span data-x="form-associated
custom element">form-associated custom elements</span> specifies that the element is <span>barred
from constraint validation</span>. User agents don't provide any other behavior for the attribute,
but custom element authors should, where possible, use its presence to make their control
non-editable in some appropriate fashion, similar to the behavior for the <span
data-x="attr-input-readonly">readonly</span> attribute on built-in form controls.</p>
<p><strong>Constraint validation</strong>: If the <code
data-x="attr-face-readonly">readonly</code> attribute is specified on a <span>form-associated
custom element</span>, the element is <span>barred from constraint validation</span>.</p>
<p>The <span data-x="concept-form-reset-control">reset algorithm</span> for <span
data-x="form-associated custom element">form-associated custom elements</span> is to <span>enqueue
a custom element callback reaction</span> with the element, callback name "<code
data-x="">formResetCallback</code>", and « ».</p>
<hr>
<p>A <dfn export>valid custom element name</dfn> is a sequence of characters <var>name</var> that
meets all of the following requirements:</p>
<ul>
<li>
<p><var>name</var> must match the <code
data-x="prod-PotentialCustomElementName">PotentialCustomElementName</code> production:</p>
<dl>
<dt><code data-x=""><dfn
data-x="prod-PotentialCustomElementName">PotentialCustomElementName</dfn> ::=</code></dt>
<dd><code data-x="">[a-z] (<span data-x="prod-PCENChar">PCENChar</span>)* '-'
(<span data-x="prod-PCENChar">PCENChar</span>)*</code></dd>
<dt><code data-x=""><dfn data-x="prod-PCENChar">PCENChar</dfn> ::=</code></dt>
<dd><code data-x="">"-" | "." | [0-9] | "_" | [a-z] | #xB7 | [#xC0-#xD6] | [#xD8-#xF6] |
[#xF8-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x203F-#x2040] | [#x2070-#x218F] |
[#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] |
[#x10000-#xEFFFF]</code></dd>
</dl>
<p>This uses the <a href="https://www.w3.org/TR/xml/#sec-notation">EBNF notation</a> from the
<cite>XML</cite> specification. <ref>XML</ref></p>
</li>
<li>
<p><var>name</var> must not be any of the following:</p>
<ul class="brief">
<li><code data-x="">annotation-xml</code></li>
<li><code data-x="">color-profile</code></li>
<li><code data-x="">font-face</code></li>
<li><code data-x="">font-face-src</code></li>
<li><code data-x="">font-face-uri</code></li>
<li><code data-x="">font-face-format</code></li>
<li><code data-x="">font-face-name</code></li>
<li><code data-x="">missing-glyph</code></li>
</ul>
<p class="note">The list of names above is the summary of all hyphen-containing element names
from the <span data-x="other applicable specifications">applicable specifications</span>, namely
<cite>SVG 2</cite> and <cite>MathML</cite>. <ref>SVG</ref> <ref>MATHML</ref></p>
</li>
</ul>
<div class="note">
<p>These requirements ensure a number of goals for <span data-x="valid custom element name">valid
custom element names</span>:</p>
<ul>
<li><p>They start with an <span>ASCII lower alpha</span>, ensuring that the HTML parser will
treat them as tags instead of as text.</li>
<li><p>They do not contain any <span data-x="ASCII upper alpha">ASCII upper alphas</span>,
ensuring that the user agent can always treat HTML elements ASCII-case-insensitively.</p></li>
<li><p>They contain a hyphen, used for namespacing and to ensure forward compatibility (since no
elements will be added to HTML, SVG, or MathML with hyphen-containing local names in the
future).</p></li>
<li><p>They can always be created with <code
data-x="dom-Document-createElement">createElement()</code> and <code
data-x="dom-Document-createElementNS">createElementNS()</code>, which have restrictions that go
beyond the parser's.</p></li>
</ul>
<p>Apart from these restrictions, a large variety of names is allowed, to give maximum
flexibility for use cases like <code data-x=""><math-α></code> or <code
data-x=""><emotion-😍></code>.</p>
</div>
<div w-nodev>
<p>A <dfn>custom element definition</dfn> describes a <span>custom element</span> and consists
of:</p>
<dl>
<dt>A <dfn data-x="concept-custom-element-definition-name" export
for="custom element definition">name</dfn></dt>
<dd>A <span>valid custom element name</span></dd>
<dt>A <dfn data-x="concept-custom-element-definition-local-name" export
for="custom element definition">local name</dfn></dt>
<dd>A local name</dd>
<dt>A <dfn data-x="concept-custom-element-definition-constructor" export
for="custom element definition">constructor</dfn></dt>
<dd>A Web IDL <code>CustomElementConstructor</code> callback function type value wrapping
the <span>custom element constructor</span></dd>
<dt>A list of <dfn data-x="concept-custom-element-definition-observed-attributes">observed
attributes</dfn></dt>
<dd>A <code data-x="">sequence<DOMString></code></dd>
<dt>A collection of <dfn
data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</dfn></dt>
<dd>A map, whose keys are the strings "<code data-x="">connectedCallback</code>", "<code
data-x="">disconnectedCallback</code>", "<code data-x="">adoptedCallback</code>", "<code
data-x="">connectedMoveCallback</code>", "<code data-x="">attributeChangedCallback</code>",
"<code data-x="">formAssociatedCallback</code>", "<code data-x="">formDisabledCallback</code>",
"<code data-x="">formResetCallback</code>", and "<code
data-x="">formStateRestoreCallback</code>". The corresponding values are either a Web IDL <code
data-x="idl-Function">Function</code> callback function type value, or null. By default the value
of each entry is null.</dd>
<dt>A <dfn data-x="concept-custom-element-definition-construction-stack">construction
stack</dfn></dt>
<dd>A list, initially empty, that is manipulated by the <span
data-x="concept-upgrade-an-element">upgrade an element</span> algorithm and the <a
href="#html-element-constructors">HTML element constructors</a>. Each entry in the list will be
either an element or an <dfn data-x="concept-already-constructed-marker"><i>already
constructed</i> marker</dfn>.</dd>
<dt>A <dfn data-x="concept-custom-element-definition-form-associated">form-associated</dfn>
boolean</dt>
<dd>If this is true, user agent treats elements associated to this
<span>custom element definition</span> as <span data-x="form-associated custom
element">form-associated custom elements</span>.</dd>
<dt>A <dfn data-x="concept-custom-element-definition-disable-internals">disable
internals</dfn> boolean</dt>
<dd>Controls <code data-x="dom-attachInternals">attachInternals()</code>.
<dt>A <dfn data-x="concept-custom-element-definition-disable-shadow" export
for="custom element definition">disable shadow</dfn> boolean</dt>
<dd>Controls <code data-x="dom-Element-attachShadow">attachShadow()</code>.
</dl>
<p>To <dfn export>look up a custom element definition</dfn>, given a <var>document</var>,
<var>namespace</var>, <var>localName</var>, and <var>is</var>, perform the following steps. They
will return either a <span>custom element definition</span> or null:</p>
<ol>
<li><p>If <var>namespace</var> is not the <span>HTML namespace</span>, then return null.</p></li>
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> is
null, then return null.</p></li>
<li><p>Let <var>registry</var> be <var>document</var>'s <span>relevant global object</span>'s
<span data-x="global-custom-element-registry">custom element registry</span>.</p></li>
<li><p>If <var>registry</var>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-name">name</span> and <span
data-x="concept-custom-element-definition-local-name">local name</span> both equal to
<var>localName</var>, then return that item.</p></li>
<li><p>If <var>registry</var>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-name">name</span> equal to <var>is</var> and <span
data-x="concept-custom-element-definition-local-name">local name</span> equal to
<var>localName</var>, then return that item.</p></li>
<li><p>Return null.</p></li>
</ol>
</div>
<h4 id="custom-elements-api">The <code>CustomElementRegistry</code> interface</h4>
<p w-nodev>Each <code>Window</code> object has an associated <dfn
data-x="global-custom-element-registry">custom element registry</dfn> (a
<code>CustomElementRegistry</code> object). It is set to a new
<code>CustomElementRegistry</code> object when the <code>Window</code> object is created.</p>
<p class="note">Custom element registries are associated with <code>Window</code> objects, instead
of <code>Document</code> objects, since each <span>custom element constructor</span> inherits from
the <code>HTMLElement</code> interface, and there is exactly one <code>HTMLElement</code>
interface per <code>Window</code> object.</p>
<div w-nodev>
<p>The <dfn attribute for="Window"><code
data-x="dom-window-customElements">customElements</code></dfn> attribute of the
<code>Window</code> interface must return the <code>CustomElementRegistry</code> object for that
<code>Window</code> object.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>CustomElementRegistry</dfn> {
[<span>CEReactions</span>] undefined <span data-x="dom-CustomElementRegistry-define">define</span>(DOMString name, <span>CustomElementConstructor</span> constructor, optional <span>ElementDefinitionOptions</span> options = {});
(<span>CustomElementConstructor</span> or undefined) <span data-x="dom-CustomElementRegistry-get">get</span>(DOMString name);
DOMString? <span data-x="dom-CustomElementRegistry-getName">getName</span>(CustomElementConstructor constructor);
<span data-x="idl-Promise">Promise</span><<span>CustomElementConstructor</span>> <span data-x="dom-CustomElementRegistry-whenDefined">whenDefined</span>(DOMString name);
[<span>CEReactions</span>] undefined <span data-x="dom-CustomElementRegistry-upgrade">upgrade</span>(<span>Node</span> root);
};
callback <dfn callback>CustomElementConstructor</dfn> = <span>HTMLElement</span> ();
dictionary <dfn dictionary>ElementDefinitionOptions</dfn> {
DOMString <dfn dict-member for="ElementDefinitionOptions" data-x="dom-ElementDefinitionOptions-extends">extends</dfn>;
};</code></pre>
<p>Every <code>CustomElementRegistry</code> has a <dfn>custom element definition set</dfn>, a
<span>set</span> of <span data-x="custom element definition">custom element definitions</span>,
initially « ». Lookup of items in this <span>set</span> uses their <span
data-x="concept-custom-element-definition-name">name</span>, <span
data-x="concept-custom-element-definition-local-name">local name</span>, or <span
data-x="concept-custom-element-definition-constructor">constructor</span>.</p>
<p>Every <code>CustomElementRegistry</code> also has an <dfn>element definition is running</dfn>
boolean which is used to prevent reentrant invocations of <span>element definition</span>. It is
initially false.</p>
<p>Every <code>CustomElementRegistry</code> also has a <dfn>when-defined promise map</dfn>, a
<span data-x="ordered map">map</span> of <span data-x="valid custom element name">valid custom
element names</span> to promises. It is used to implement the <code
data-x="dom-CustomElementRegistry-whenDefined">whenDefined()</code> method.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span subdfn data-x="dom-CustomElementRegistry-define">define</span>(<var>name</var>,
<var>constructor</var>)</code></dt>
<dd>Defines a new <span>custom element</span>, mapping the given name to the given constructor
as an <span>autonomous custom element</span>.</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span data-x="dom-CustomElementRegistry-define">define</span>(<var>name</var>, <var>constructor</var>,
{ extends: <var>baseLocalName</var> })</code></dt>
<dd>Defines a new <span>custom element</span>, mapping the given name to the given constructor as
a <span>customized built-in element</span> for the <span>element type</span> identified by the
supplied <var>baseLocalName</var>. A <span>"<code>NotSupportedError</code>"</span>
<code>DOMException</code> will be thrown upon trying to extend a <span>custom element</span> or
an unknown element.</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span subdfn data-x="dom-CustomElementRegistry-get">get</span>(<var>name</var>)</code></dt>
<dd>Retrieves the <span>custom element constructor</span> defined for the given <span data-x="concept-custom-element-definition-name">name</span>. Returns undefined if there is no
<span>custom element definition</span> with the given <span data-x="concept-custom-element-definition-name">name</span>.</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span subdfn data-x="dom-CustomElementRegistry-getName">getName</span>(<var>constructor</var>)</code></dt>
<dd>Retrieves the given name for a <span>custom element</span> defined for the given <span data-x="concept-custom-element-definition-constructor">constructor</span>. Returns null if there is no
<span>custom element definition</span> with the given <span data-x="concept-custom-element-definition-constructor">constructor</span>.</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span subdfn data-x="dom-CustomElementRegistry-whenDefined">whenDefined</span>(<var>name</var>)</code></dt>
<dd>Returns a promise that will be fulfilled with the <span>custom element</span>'s constructor
when a <span>custom element</span> becomes defined with the given name. (If such a <span>custom
element</span> is already defined, the returned promise will be immediately fulfilled.) Returns a
promise rejected with a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if not
given a <span>valid custom element name</span>.</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-customElements">customElements</span>.<span subdfn data-x="dom-CustomElementRegistry-upgrade">upgrade</span>(<var>root</var>)</code></dt>
<dd><span data-x="concept-try-upgrade">Tries to upgrade</span> all <span>shadow-including
inclusive descendant</span> elements of <var>root</var>, even if they are not
<span>connected</span>.</dd>
</dl>
<p><dfn>Element definition</dfn> is a process of adding a <span>custom element definition</span>
to the <code>CustomElementRegistry</code>. This is accomplished by the <code
data-x="dom-CustomElementRegistry-define">define()</code> method. <span w-nodev>The <dfn method
for="CustomElementRegistry"><code
data-x="dom-CustomElementRegistry-define">define(<var>name</var>, <var>constructor</var>,
<var>options</var>)</code></dfn> method steps are:</span></p>
<div w-nodev>
<ol>
<li><p>If <span>IsConstructor</span>(<var>constructor</var>) is false, then throw a
<code>TypeError</code>.</p></li>
<li><p>If <var>name</var> is not a <span>valid custom element name</span>, then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-name">name</span> <var>name</var>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-constructor">constructor</span> <var>constructor</var>,
then throw a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>localName</var> be <var>name</var>.</p></li>
<li><p>Let <var>extends</var> be <var>options</var>["<code
data-x="dom-ElementDefinitionOptions-extends">extends</code>"] if it <span data-x="map
exists">exists</span>; otherwise null.</p></li>
<li>
<p>If <var>extends</var> is not null:</p>
<ol>
<li><p>If <var>extends</var> is a <span>valid custom element name</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the <span>element interface</span> for <var>extends</var> and the <span>HTML
namespace</span> is <code>HTMLUnknownElement</code> (e.g., if <var>extends</var> does not
indicate an element definition in this specification), then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <var>localName</var> to <var>extends</var>.</p></li>
</ol>
</li>
<li><p>If <span>this</span>'s <span>element definition is running</span> is true, then throw
a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <span>this</span>'s <span>element definition is running</span> to true.</p></li>
<li><p>Let <var>formAssociated</var> be false.</p></li>
<li><p>Let <var>disableInternals</var> be false.
<li><p>Let <var>disableShadow</var> be false.
<li><p>Let <var>observedAttributes</var> be an empty <code
data-x="">sequence<DOMString></code>.</p></li>
<li>
<p>Run the following steps while catching any exceptions:</p>
<ol>
<li><p>Let <var>prototype</var> be ? <span data-x="js-Get">Get</span>(<var>constructor</var>,
"prototype").</p></li>
<li><p>If <var>prototype</var> <span data-x="js-Object">is not an Object</span>, then throw a
<code>TypeError</code> exception.</p></li>
<li><p>Let <var>lifecycleCallbacks</var> be the <span>ordered map</span> «[ "<code
data-x="">connectedCallback</code>" → null, "<code data-x="">disconnectedCallback</code>" →
null, "<code data-x="">adoptedCallback</code>" → null, "<code
data-x="">connectedMoveCallback</code>" → null, "<code
data-x="">attributeChangedCallback</code>" → null ]».</p>
<li>
<p>For each <var>callbackName</var> of <span data-x="map get the keys">the keys</span> of
<var>lifecycleCallbacks</var>:</p>
<ol>
<li><p>Let <var>callbackValue</var> be ? <span data-x="js-Get">Get</span>(<var>prototype</var>,
<var>callbackName</var>).</p>
<li><p>If <var>callbackValue</var> is not undefined, then <span data-x="map set">set</span>
<var>lifecycleCallbacks</var>[<var>callbackName</var>] to the result of <span
data-x="concept-idl-convert">converting</span> <var>callbackValue</var> to the Web IDL <code
data-x="idl-Function">Function</code> callback type.</p></li>
</ol>
</li>
<li>
<p>If <var>lifecycleCallbacks</var>["<code data-x="">attributeChangedCallback</code>"] is not
null:</p>
<ol>
<li><p>Let <var>observedAttributesIterable</var> be ? <span
data-x="js-Get">Get</span>(<var>constructor</var>, "observedAttributes").</p></li>
<li><p>If <var>observedAttributesIterable</var> is not undefined, then set
<var>observedAttributes</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>observedAttributesIterable</var> to a
<code data-x="">sequence<DOMString></code>. Rethrow any exceptions from the
conversion.</p></li>
</ol>
<li><p>Let <var>disabledFeatures</var> be an empty <code
data-x="">sequence<DOMString></code>.</p></li>
<li><p>Let <var>disabledFeaturesIterable</var> be ? <span
data-x="js-Get">Get</span>(<var>constructor</var>, "disabledFeatures").</p></li>
<li><p>If <var>disabledFeaturesIterable</var> is not undefined, then set
<var>disabledFeatures</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>disabledFeaturesIterable</var> to a <code
data-x="">sequence<DOMString></code>. Rethrow any exceptions from the conversion.</p></li>
<li><p>If <var>disabledFeatures</var> <span data-x="list contains">contains</span> "<code
data-x="">internals</code>", then set <var>disableInternals</var> to true.</p></li>
<li><p>If <var>disabledFeatures</var> <span data-x="list contains">contains</span> "<code
data-x="">shadow</code>", then set <var>disableShadow</var> to true.</p></li>
<li><p>Let <var>formAssociatedValue</var> be ? <span data-x="js-Get">Get</span>(
<var>constructor</var>, "formAssociated").</p></li>
<li><p>Set <var>formAssociated</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>formAssociatedValue</var> to a <code
data-x="">boolean</code>.</p></li>
<li>
<p>If <var>formAssociated</var> is true, then for each <var>callbackName</var> of « "<code
data-x="">formAssociatedCallback</code>", "<code data-x="">formResetCallback</code>", "<code
data-x="">formDisabledCallback</code>", "<code data-x="">formStateRestoreCallback</code>"
»:</p>
<ol>
<li><p>Let <var>callbackValue</var> be ? <span data-x="js-Get">Get</span>(<var>prototype</var>,
<var>callbackName</var>).</p></li>
<li><p>If <var>callbackValue</var> is not undefined, then <span data-x="map set">set</span>
<var>lifecycleCallbacks</var>[<var>callbackName</var>] to the result of <span
data-x="concept-idl-convert">converting</span> <var>callbackValue</var> to the Web IDL <code
data-x="idl-Function">Function</code> callback type.</p></li>
</ol>
</li>
</ol>
<p>Then, regardless of whether the above steps threw an exception or not: set
<span>this</span>'s <span>element definition is running</span> to false.</p>
<p>Finally, if the steps threw an exception, rethrow that exception.</p>
</li>
<li><p>Let <var>definition</var> be a new <span>custom element definition</span> with <span
data-x="concept-custom-element-definition-name">name</span> <var>name</var>, <span
data-x="concept-custom-element-definition-local-name">local name</span> <var>localName</var>,
<span data-x="concept-custom-element-definition-constructor">constructor</span>
<var>constructor</var>, <span
data-x="concept-custom-element-definition-observed-attributes">observed attributes</span>
<var>observedAttributes</var>, <span
data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span>
<var>lifecycleCallbacks</var>,
<span data-x="concept-custom-element-definition-form-associated">form-associated</span>
<var>formAssociated</var>, <span
data-x="concept-custom-element-definition-disable-internals">disable internals</span>
<var>disableInternals</var>, and <span
data-x="concept-custom-element-definition-disable-shadow">disable shadow</span>
<var>disableShadow</var>.</p></li>
<li><p><span data-x="set append">Append</span> <var>definition</var> to <span>this</span>'s
<span>custom element definition set</span>.</p></li>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>upgradeCandidates</var> be all elements that are <span data-x="shadow-including
descendant">shadow-including descendants</span> of <var>document</var>, whose namespace
is the <span>HTML namespace</span> and whose local name is <var>localName</var>, in
<span>shadow-including tree order</span>. Additionally, if <var>extends</var> is non-null, only
include elements whose <span data-x="concept-element-is-value"><code data-x="">is</code>
value</span> is equal to <var>name</var>.</p></li>
<li><p>For each element <var>element</var> of <var>upgradeCandidates</var>, <span>enqueue a
custom element upgrade reaction</span> given <var>element</var> and
<var>definition</var>.</p></li>
<!-- It is equivalent to just try to upgrade all elements in the document, and let "try to
upgrade" bail out, but this seems a bit more explicit. -->
<li>
<p>If <span>this</span>'s <span>when-defined promise map</span>[<var>name</var>] <span data-x="map
exists">exists</span>:</p>
<ol>
<li><p>Resolve <span>this</span>'s <span>when-defined promise map</span>[<var>name</var>] with
<var>constructor</var>.</p></li>
<li><p><span data-x="map remove">Remove</span> <span>this</span>'s <span>when-defined promise
map</span>[<var>name</var>].</p></li>
</ol>
</li>
</ol>
<p>The <dfn method for="CustomElementRegistry"><code
data-x="dom-CustomElementRegistry-get">get(<var>name</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-name">name</span> <var>name</var>, then return that
item's <span data-x="concept-custom-element-definition-constructor">constructor</span>.</p></li>
<li><p>Return undefined.</p></li>
</ol>
<p>The <dfn method for="CustomElementRegistry"><code
data-x="dom-CustomElementRegistry-getName">getName(<var>constructor</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-constructor">constructor</span>
<var>constructor</var>, then return that item's <span
data-x="concept-custom-element-definition-name">name</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <dfn method for="CustomElementRegistry"><code
data-x="dom-CustomElementRegistry-whenDefined">whenDefined(<var>name</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>If <var>name</var> is not a <span>valid custom element name</span>, then return <span>a
promise rejected with</span> a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>custom element definition set</span> <span data-x="list
contains">contains</span> an item with <span
data-x="concept-custom-element-definition-name">name</span> <var>name</var>, then return <span>a
promise resolved with</span> that item's <span
data-x="concept-custom-element-definition-constructor">constructor</span>.</p></li>
<li><p>If <span>this</span>'s <span>when-defined promise map</span>[<var>name</var>] does not
<span data-x="map exists">exist</span>, then <span data-x="map set">set</span>
<span>this</span>'s <span>when-defined promise map</span>[<var>name</var>] to a new
promise.</p></li>
<li><p>Return <span>this</span>'s <span>when-defined promise
map</span>[<var>name</var>].</p></li>
</ol>
</div>
<div class="example">
<p>The <code data-x="dom-CustomElementRegistry-whenDefined">whenDefined()</code> method can be
used to avoid performing an action until all appropriate <span data-x="custom element">custom
elements</span> are <span data-x="concept-element-defined">defined</span>. In this example, we
combine it with the <code data-x="selector-defined">:defined</code> pseudo-class to hide a
dynamically-loaded article's contents until we're sure that all of the <span data-x="autonomous
custom element">autonomous custom elements</span> it uses are defined.</p>
<pre><code class="js">articleContainer.hidden = true;
fetch(articleURL)
.then(response => response.text())
.then(text => {
articleContainer.innerHTML = text;
return Promise.all(
[...articleContainer.querySelectorAll(":not(:defined)")]
.map(el => customElements.whenDefined(el.localName))
);
})
.then(() => {
articleContainer.hidden = false;
});</code></pre>
</div>
<div w-nodev>
<p>When invoked, the <dfn method for="CustomElementRegistry"><code
data-x="dom-CustomElementRegistry-upgrade">upgrade(<var>root</var>)</code></dfn> method must run
these steps:</p>
<ol>
<li><p>Let <var>candidates</var> be a <span>list</span> of all of <var>root</var>'s
<span>shadow-including inclusive descendant</span> elements, in <span>shadow-including tree
order</span>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>candidate</var> of <var>candidates</var>,
<span data-x="concept-try-upgrade">try to upgrade</span> <var>candidate</var>.</p></li>
</ol>
</div>
<div class="example">
<p>The <code data-x="dom-CustomElementRegistry-upgrade">upgrade()</code> method allows upgrading
of elements at will. Normally elements are automatically upgraded when they become
<span>connected</span>, but this method can be used if you need to upgrade before you're ready to
connect the element.</p>
<pre><code class="js">const el = document.createElement("spider-man");
class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);
console.assert(!(el instanceof SpiderMan)); // not yet upgraded
customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // upgraded!</code></pre>
</div>
<div w-nodev>
<h4><dfn data-x="custom-element-upgrades">Upgrades</dfn></h4>
<p>To <dfn data-x="concept-upgrade-an-element" export>upgrade an element</dfn>, given as input a
<span>custom element definition</span> <var>definition</var> and an element <var>element</var>,
run the following steps:</p>
<ol>
<li id="concept-upgrade-an-element-early-exit">
<p>If <var>element</var>'s <span>custom element state</span> is not "<code
data-x="">undefined</code>" or "<code data-x="">uncustomized</code>", then return.</p>
<div class="example">
<p>One scenario where this can occur due to reentrant invocation of this algorithm, as in the
following example:</p>
<pre><code class="html"><!DOCTYPE html>
<x-foo id="a"></x-foo>
<x-foo id="b"></x-foo>
<script>
// Defining enqueues upgrade reactions for both "a" and "b"
customElements.define("x-foo", class extends HTMLElement {
constructor() {
super();
const b = document.querySelector("#b");
b.remove();
// While this constructor is running for "a", "b" is still
// undefined, and so inserting it into the document will enqueue a
// second upgrade reaction for "b" in addition to the one enqueued
// by defining x-foo.
document.body.appendChild(b);
}
})
</script></code></pre>
<p>This step will thus bail out the algorithm early when <span
data-x="concept-upgrade-an-element">upgrade an element</span> is invoked
with "<code data-x="">b</code>" a second time.</p>
</div>
</li>
<li><p>Set <var>element</var>'s <span data-x="concept-element-custom-element-definition">custom
element definition</span> to <var>definition</var>.</p></li>
<li>
<p>Set <var>element</var>'s <span>custom element state</span> to "<code
data-x="">failed</code>".</p>
<p class="note">It will be set to "<code data-x="">custom</code>" <a
href="#concept-upgrade-an-element-set-state-to-custom">after the upgrade succeeds</a>. For now,
we set it to "<code data-x="">failed</code>" so that any reentrant invocations will hit <a
href="#concept-upgrade-an-element-early-exit">the above early-exit step</a>.</p>
</li>
<li><p>For each <var>attribute</var> in <var>element</var>'s <span>attribute list</span>, in
order, <span>enqueue a custom element callback reaction</span> with <var>element</var>, callback
name "<code data-x="">attributeChangedCallback</code>", and « <var>attribute</var>'s local name,
null, <var>attribute</var>'s value, <var>attribute</var>'s namespace ».</p></li>
<li><p>If <var>element</var> is <span>connected</span>, then <span>enqueue a custom element
callback reaction</span> with <var>element</var>, callback name "<code
data-x="">connectedCallback</code>", and « ».</p></li>
<li><p>Add <var>element</var> to the end of <var>definition</var>'s <span
data-x="concept-custom-element-definition-construction-stack">construction stack</span>.</p></li>
<li><p>Let <var>C</var> be <var>definition</var>'s <span
data-x="concept-custom-element-definition-constructor">constructor</span>.</p></li>
<li>
<p>Run the following substeps while catching any exceptions:</p>
<ol>
<li>
<p>If <var>definition</var>'s <span
data-x="concept-custom-element-definition-disable-shadow">disable shadow</span> is true and
<var>element</var>'s <span data-x="concept-element-shadow-root">shadow root</span> is
non-null, then throw a <span>"<code>NotSupportedError</code>"</span>
<code>DOMException</code>.</p>
<p class="note">This is needed as <code
data-x="dom-Element-attachShadow">attachShadow()</code> does not use <span>look up a custom
element definition</span> while <code data-x="dom-attachInternals">attachInternals()</code>
does.</p>
</li>
<li><p>Set <var>element</var>'s <span>custom element state</span> to "<code
data-x="">precustomized</code>".</p></li>
<li>
<p>Let <var>constructResult</var> be the result of <span
data-x="es-constructing-callback-functions">constructing</span> <var>C</var>, with no
arguments.</p>
<p class="note">If <var>C</var> <a href="#custom-element-conformance">non-conformantly</a>
uses an API decorated with the <code data-x="CEReactions">[CEReactions]</code> extended
attribute, then the reactions enqueued at the beginning of this algorithm will execute during
this step, before <var>C</var> finishes and control returns to this algorithm. Otherwise, they
will execute after <var>C</var> and the rest of the upgrade process finishes.</p>
</li>
<li>
<p>If <span>SameValue</span>(<var>constructResult</var>, <var>element</var>) is false, then
throw a <code>TypeError</code>.</p>
<p class="note">This can occur if <var>C</var> constructs another instance of the same custom
element before calling <code data-x="">super()</code>, or if <var>C</var> uses JavaScript's
<code data-x="">return</code>-override feature to return an arbitrary <code>HTMLElement</code>
object from the constructor.</p>
</li>
</ol>
<p>Then, perform the following substep, regardless of whether the above steps threw an exception
or not:</p>
<ol>
<li>
<p>Remove the last entry from the end of <var>definition</var>'s <span
data-x="concept-custom-element-definition-construction-stack">construction stack</span>.</p>
<div class="note">
<p>Assuming <var>C</var> calls <code data-x="">super()</code> (as it will if it is <a
href="#custom-element-conformance">conformant</a>), and that the call succeeds, this will be
the <span data-x="concept-already-constructed-marker"><i>already
constructed</i> marker</span> that replaced the <var>element</var> we pushed at the beginning
of this algorithm. (The <a href="#html-element-constructors">HTML element constructor</a>
carries out this replacement.)</p>
<p>If <var>C</var> does not call <code data-x="">super()</code> (i.e. it is not <a
href="#custom-element-conformance">conformant</a>), or if any step in the <a
href="#html-element-constructors">HTML element constructor</a> throws, then this entry will
still be <var>element</var>.</p>
</div>
</li>
</ol>
<p>Finally, if the above steps threw an exception, then:</p>
<ol>
<li><p>Set <var>element</var>'s <span data-x="concept-element-custom-element-definition">custom
element definition</span> to null.</p></li>
<li><p>Empty <var>element</var>'s <span>custom element reaction queue</span>.</p>
<li><p>Rethrow the exception (thus terminating this algorithm).</p></li>
</ol>
<p class="note">If the above steps threw an exception, then <var>element</var>'s <span>custom
element state</span> will remain "<code data-x="">failed</code>" or "<code
data-x="">precustomized</code>".</p>
</li>
<li>
<p>If <var>element</var> is a <span>form-associated custom element</span>, then:</p>
<ol>
<li><p><span>Reset the form owner</span> of <var>element</var>. If <var>element</var> is
associated with a <code>form</code> element, then
<span>enqueue a custom element callback reaction</span> with <var>element</var>, callback
name "<code data-x="">formAssociatedCallback</code>", and « the associated <code>form</code>
».</p></li>
<li><p>If <var>element</var> is <span data-x="concept-fe-disabled">disabled</span>, then
<span>enqueue a custom element callback reaction</span> with <var>element</var>, callback name
"<code data-x="">formDisabledCallback</code>" and « true ».</p></li>
</ol>
</li>
<li id="concept-upgrade-an-element-set-state-to-custom"><p>Set <var>element</var>'s <span>custom
element state</span> to "<code data-x="">custom</code>".</p></li>
</ol>
<p>To <dfn data-x="concept-try-upgrade" export>try to upgrade an element</dfn>, given as input an
element <var>element</var>, run the following steps:</p>
<ol>
<li><p>Let <var>definition</var> be the result of <span data-x="look up a custom element
definition">looking up a custom element definition</span> given <var>element</var>'s <span>node
document</span>, <var>element</var>'s namespace, <var>element</var>'s local name, and
<var>element</var>'s <span data-x="concept-element-is-value"><code data-x="">is</code>
value</span>.</p></li>
<li><p>If <var>definition</var> is not null, then <span>enqueue a custom element upgrade
reaction</span> given <var>element</var> and <var>definition</var>.</p></li>
</ol>
</div>
<h4 id="custom-element-reactions">Custom element reactions</h4>
<p>A <span>custom element</span> possesses the ability to respond to certain occurrences by
running author code:</p>
<ul>
<li><p>When <span data-x="custom-element-upgrades">upgraded</span>, its <span data-x="custom
element constructor">constructor</span> is run, with no arguments.</p></li>
<li><p>When it <span>becomes connected</span>, its <code data-x="">connectedCallback</code> is
called, with no arguments.</p></li>
<li><p>When it <span>becomes disconnected</span>, its <code data-x="">disconnectedCallback</code>
is called, with no arguments.</p></li>
<li><p>When it is <span data-x="concept-node-move-ext">moved</span>, its <code
data-x="">connectedMoveCallback</code> is called, with no arguments.</p></li>
<li><p>When it is <span data-x="concept-node-adopt">adopted</span> into a new document, its <code
data-x="">adoptedCallback</code> is called, given the old document and new document as
arguments.</p></li>
<li><p>When any of its attributes are <span
data-x="concept-element-attributes-change">changed</span>, <span
data-x="concept-element-attributes-append">appended</span>, <span
data-x="concept-element-attributes-remove">removed</span>, or <span
data-x="concept-element-attributes-replace">replaced</span>, its <code
data-x="">attributeChangedCallback</code> is called, given the attribute's local name, old value,
new value, and namespace as arguments. (An attribute's old or new value is considered to be null
when the attribute is added or removed, respectively.)</p></li>
<li><p>When the user agent <span data-x="reset the form owner">resets the form owner</span> of a
<span>form-associated custom element</span> and doing so changes the form owner, its <code
data-x="">formAssociatedCallback</code> is called, given the new form owner (or null if no owner)
as an argument.</p></li>
<li><p>When the form owner of a <span>form-associated custom element</span> is <span
data-x="concept-form-reset">reset</span>, its <code data-x="">formResetCallback</code> is
called.</p></li>
<li><p>When the <span data-x="concept-fe-disabled">disabled</span> state of a
<span>form-associated custom element</span> is changed, its <code
data-x="">formDisabledCallback</code> is called, given the new state as an
argument.</p></li>
<li><p>When user agent updates a <span>form-associated custom element</span>'s value on behalf of
a user or <span data-x="restore persisted state">as part of navigation</span>, its <code
data-x="">formStateRestoreCallback</code> is called, given the new state and a string indicating
a reason, "<code data-x="">autocomplete</code>" or "<code data-x="">restore</code>", as
arguments.</p></li>
</ul>
<p>We call these reactions collectively <dfn data-x="concept-custom-element-reaction">custom
element reactions</dfn>.</p>
<p>The way in which <span data-x="concept-custom-element-reaction">custom element reactions</span>
are invoked is done with special care, to avoid running author code during the middle of delicate
operations. Effectively, they are delayed until "just before returning to user script". This means
that for most purposes they appear to execute synchronously, but in the case of complicated
composite operations (like <span data-x="concept-node-clone">cloning</span>, or <span
data-x="concept-range">range</span> manipulation), they will instead be delayed until after all
the relevant user agent processing steps have completed, and then run together as a batch.</p>
<p><span w-nodev>Additionally, the precise ordering of these reactions is managed via a
somewhat-complicated stack-of-queues system, described below. The intention behind this system is
to guarantee</span><span w-dev>It is guaranteed</span> that <span
data-x="concept-custom-element-reaction">custom element reactions</span> always are invoked in the
same order as their triggering actions, at least within the local context of a single <span>custom
element</span>. (Because <span data-x="concept-custom-element-reaction">custom element
reaction</span> code can perform its own mutations, it is not possible to give a global ordering
guarantee across multiple elements.)</p>
<div w-nodev>
<hr>
<p>Each <span>similar-origin window agent</span> has a <dfn>custom element reactions stack</dfn>,
which is initially empty. A <span>similar-origin window agent</span>'s <dfn>current element
queue</dfn> is the <span>element queue</span> at the top of its <span>custom element reactions
stack</span>. Each item in the stack is an <dfn>element queue</dfn>, which is initially empty as
well. Each item in an <span>element queue</span> is an element. (The elements are not necessarily
<span data-x="concept-element-custom">custom</span> yet, since this queue is used for <span
data-x="custom-element-upgrades">upgrades</span> as well.)</p>
<p>Each <span>custom element reactions stack</span> has an associated <dfn>backup element
queue</dfn>, which is an initially-empty <span>element queue</span>. Elements are pushed onto the
<span>backup element queue</span> during operations that affect the DOM without going through an
API decorated with <code data-x="CEReactions">[CEReactions]</code>, or through the parser's
<span>create an element for the token</span> algorithm. An example of this is a user-initiated
editing operation which modifies the descendants or attributes of an <span>editable</span>
element. To prevent reentrancy when processing the <span>backup element queue</span>, each
<span>custom element reactions stack</span> also has a <dfn>processing the backup element
queue</dfn> flag, initially unset.</p>
<p>All elements have an associated <dfn>custom element reaction queue</dfn>, initially empty. Each
item in the <span>custom element reaction queue</span> is of one of two types:</p>
<ul>
<li><p>An <dfn>upgrade reaction</dfn>, which will <span
data-x="custom-element-upgrades">upgrade</span> the custom element and contains a <span>custom
element definition</span>; or</p></li>
<li><p>A <dfn>callback reaction</dfn>, which will call a lifecycle callback, and contains a
callback function as well as a list of arguments.</p></li>
</ul>
<p>This is all summarized in the following schematic diagram:</p>
<p><img src="/images/custom-element-reactions.svg" style="width: 80%; max-width: 580px;" alt="A custom element reactions stack consists of a stack of element queues. Zooming in on a particular queue, we see that it contains a number of elements (in our example, <x-a>, then <x-b>, then <x-c>). Any particular element in the queue then has a custom element reaction queue. Zooming in on the custom element reaction queue, we see that it contains a variety of queued-up reactions (in our example, upgrade, then attribute changed, then another attribute changed, then connected)." class="darkmode-aware"></p>
<p>To <dfn>enqueue an element on the appropriate element queue</dfn>, given an element
<var>element</var>, run the following steps:</p>
<ol>
<li><p>Let <var>reactionsStack</var> be <var>element</var>'s <span>relevant agent</span>'s
<span>custom element reactions stack</span>.</p></li>
<li>
<p>If <var>reactionsStack</var> is empty, then:</p>
<ol>
<li><p>Add <var>element</var> to <var>reactionsStack</var>'s <span>backup element
queue</span>.</p></li>
<li><p>If <var>reactionsStack</var>'s <span>processing the backup element queue</span> flag is
set, then return.</p></li>
<li><p>Set <var>reactionsStack</var>'s <span>processing the backup element queue</span>
flag.</p></li>
<li>
<p><span>Queue a microtask</span> to perform the following steps:</p>
<ol>
<li><p><span>Invoke custom element reactions</span> in <var>reactionsStack</var>'s
<span>backup element queue</span>.</p></li>
<li><p>Unset <var>reactionsStack</var>'s <span>processing the backup element queue</span>
flag.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Otherwise, add <var>element</var> to <var>element</var>'s <span>relevant agent</span>'s
<span>current element queue</span>.</p></li>
</ol>
<p>To <dfn export>enqueue a custom element callback reaction</dfn>, given a <span>custom
element</span> <var>element</var>, a callback name <var>callbackName</var>, and a list of
arguments <var>args</var>, run the following steps:</p>
<ol>
<li><p>Let <var>definition</var> be <var>element</var>'s <span
data-x="concept-element-custom-element-definition">custom element definition</span>.</p>
<li><p>Let <var>callback</var> be the value of the entry in <var>definition</var>'s <span
data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span> with
key <var>callbackName</var>.</p></li>
<li>
<p>If <var>callbackName</var> is "<code data-x="">connectedMoveCallback</code>" and
<var>callback</var> is null:
<ol>
<li><p>Let <var>disconnectedCallback</var> be the value of the entry in <var>definition</var>'s
<span data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span>
with key "<code data-x="">disconnectedCallback</code>".</p></li>
<li><p>Let <var>connectedCallback</var> be the value of the entry in <var>definition</var>'s
<span data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span>
with key "<code data-x="">connectedCallback</code>".</p></li>
<li><p>If <var>connectedCallback</var> and <var>disconnectedCallback</var> are null, then
return.</p></li>
<li>
<p>Set <var>callback</var> to the following steps:</p>
<ol>
<li><p>If <var>disconnectedCallback</var> is not null, then call
<var>disconnectedCallback</var> with no arguments.</p></li>
<li><p>If <var>connectedCallback</var> is not null, then call <var>connectedCallback</var>
with no arguments.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If <var>callback</var> is null, then return.</p></li>
<li>
<p>If <var>callbackName</var> is "<code data-x="">attributeChangedCallback</code>":</p>
<ol>
<li><p>Let <var>attributeName</var> be the first element of <var>args</var>.</p></li>
<li><p>If <var>definition</var>'s <span
data-x="concept-custom-element-definition-observed-attributes">observed attributes</span> does
not contain <var>attributeName</var>, then return.</p></li>
</ol>
</li>
<li><p>Add a new <span>callback reaction</span> to <var>element</var>'s <span>custom element
reaction queue</span>, with callback function <var>callback</var> and arguments
<var>args</var>.</p></li>
<li><p><span>Enqueue an element on the appropriate element queue</span> given
<var>element</var>.</p></li>
</ol>
<p>To <dfn export>enqueue a custom element upgrade reaction</dfn>, given an element
<var>element</var> and <span>custom element definition</span> <var>definition</var>, run the
following steps:</p>
<ol>
<li><p>Add a new <span>upgrade reaction</span> to <var>element</var>'s <span>custom element
reaction queue</span>, with <span>custom element definition</span>
<var>definition</var>.</p></li>
<li><p><span>Enqueue an element on the appropriate element queue</span> given
<var>element</var>.</p></li>
</ol>
<p>To <dfn>invoke custom element reactions</dfn> in an <span>element queue</span>
<var>queue</var>, run the following steps:</p>
<ol>
<li>
<p>While <var>queue</var> is not <span data-x="list is empty">empty</span>:</p>
<ol>
<li><p>Let <var>element</var> be the result of <span data-x="dequeue">dequeuing</span>
from <var>queue</var>.</p></li>
<li><p>Let <var>reactions</var> be <var>element</var>'s <span>custom element reaction
queue</span>.</p></li>
<li>
<p>Repeat until <var>reactions</var> is empty:</p>
<ol>
<li>
<p>Remove the first element of <var>reactions</var>, and let <var>reaction</var> be that
element. Switch on <var>reaction</var>'s type:</p>
<dl class="switch">
<dt><span>upgrade reaction</span></dt>
<dd>
<p><span data-x="concept-upgrade-an-element">Upgrade</span> <var>element</var> using
<var>reaction</var>'s <span>custom element definition</span>.</p>
<p>If this throws an exception, catch it, and <span data-x="report an
exception">report</span> it for <var>reaction</var>'s <span>custom element
definition</span>'s <span
data-x="concept-custom-element-definition-constructor">constructor</span>'s corresponding
JavaScript object's <span>associated realm</span>'s <span
data-x="concept-realm-global">global object</span>.</p>
</dd>
<dt><span>callback reaction</span></dt>
<dd>
<p><span data-x="es-invoking-callback-functions">Invoke</span> <var>reaction</var>'s
callback function with <var>reaction</var>'s arguments and "<code
data-x="">report</code>", and <i data-x="dfn-callback-this-value">callback this value</i>
set to <var>element</var>.</p>
</dd>
</dl>
</li>
</ol>
</li>
</ol>
</li>
</ol>
<hr>
<p>To ensure <span data-x="concept-custom-element-reaction">custom element reactions</span> are
triggered appropriately, we introduce the <dfn extended-attribute data-lt="CEReactions"
data-x="CEReactions"><code>[CEReactions]</code></dfn> IDL <span>extended attribute</span>. It
indicates that the relevant algorithm is to be supplemented with additional steps in order to
appropriately track and invoke <span data-x="concept-custom-element-reaction">custom element
reactions</span>.</p>
<p>The <code data-x="CEReactions">[CEReactions]</code> extended attribute must take no
arguments, and must not appear on anything other than an operation, attribute, setter, or deleter.
Additionally, it must not appear on readonly attributes.</p>
<p>Operations, attributes, setters, or deleters annotated with the <code
data-x="CEReactions">[CEReactions]</code> extended attribute must run the following steps in place
of the ones specified in their description:</p>
<ol>
<li><p><span data-x="stack push">Push</span> a new <span>element queue</span> onto this object's
<span>relevant agent</span>'s <span>custom element reactions stack</span>.</p></li>
<li><p>Run the originally-specified steps for this construct, catching any exceptions. If the
steps return a value, let <var>value</var> be the returned value. If they throw an exception, let
<var>exception</var> be the thrown exception.</p></li>
<li><p>Let <var>queue</var> be the result of <span data-x="stack pop">popping</span> from this
object's <span>relevant agent</span>'s <span>custom element reactions stack</span>.</p></li>
<li><p><span>Invoke custom element reactions</span> in <var>queue</var>.</p></li>
<li><p>If an exception <var>exception</var> was thrown by the original steps, rethrow
<var>exception</var>.</p></li>
<li><p>If a value <var>value</var> was returned from the original steps, return
<var>value</var>.</p></li>
</ol>
<div class="note">
<p>The intent behind this extended attribute is somewhat subtle. One way of accomplishing its
goals would be to say that every operation, attribute, setter, and deleter on the platform
<!--non-normative-->must have these steps inserted, and to allow implementers to optimize away
unnecessary cases (where no DOM mutation is possible that could cause <span
data-x="concept-custom-element-reaction">custom element reactions</span> to occur).</p>
<p>However, in practice this imprecision could lead to non-interoperable implementations of <span
data-x="concept-custom-element-reaction">custom element reactions</span>, as some implementations
might forget to invoke these steps in some cases. Instead, we settled on the approach of
explicitly annotating all relevant IDL constructs, as a way of ensuring interoperable behavior
and helping implementations easily pinpoint all cases where these steps are necessary.</p>
</div>
<p>Any nonstandard APIs introduced by the user agent that could modify the DOM in such a way as to
cause <span data-x="enqueue a custom element callback reaction">enqueuing a custom element
callback reaction</span> or <span data-x="enqueue a custom element upgrade reaction">enqueuing a
custom element upgrade reaction</span>, for example by modifying any attributes or child elements,
must also be decorated with the <code data-x="CEReactions">[CEReactions]</code> attribute.</p>
<div class="note">
<p>As of the time of this writing, the following nonstandard or not-yet-standardized APIs are
known to fall into this category:</p>
<ul>
<li><p><code>HTMLInputElement</code>'s <code data-x="">webkitdirectory</code> and <code
data-x="">incremental</code> IDL attributes</p></li>
<li><p><code>HTMLLinkElement</code>'s <code data-x="">scope</code> IDL attribute</p></li>
</ul>
</div>
</div>
<h4>Element internals</h4>
<p>Certain capabilities are meant to be available to a custom element author, but not to a custom
element consumer. These are provided by the <code
data-x="dom-attachInternals">element.attachInternals()</code> method, which returns an instance of
<code>ElementInternals</code>. The properties and methods of <code>ElementInternals</code> allow
control over internal features which the user agent provides to all elements.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-attachInternals">attachInternals()</span></code></dt>
<dd><p>Returns an <code>ElementInternals</code> object targeting the <span>custom element</span>
<var>element</var>. Throws an exception if <var>element</var> is not a <span>custom
element</span>, if the "<code data-x="">internals</code>" feature was disabled as part of the
element definition, or if it is called twice on the same element.</p></dd>
</dl>
<div w-nodev>
<p>Each <code>HTMLElement</code> has an <dfn>attached internals</dfn> (null or an
<code>ElementInternals</code> object), initially null.</p>
<p>The <dfn method for="HTMLElement"><code
data-x="dom-attachInternals">attachInternals()</code></dfn> method steps are:</p>
<ol>
<!-- We could lift this restriction in the future. -->
<li><p>If <span>this</span>'s <span data-x="concept-element-is-value"><code data-x="">is</code>
value</span> is not null, then throw a <span>"<code>NotSupportedError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>definition</var> be the result of <span data-x="look up a custom element
definition">looking up a custom element definition</span> given <span>this</span>'s <span>node
document</span>, its namespace, its local name, and null as the <span
data-x="concept-element-is-value"><code data-x="">is</code> value</span>.</p></li>
<li><p>If <var>definition</var> is null, then throw an
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>definition</var>'s <span
data-x="concept-custom-element-definition-disable-internals">disable internals</span> is true,
then throw a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>attached internals</span> is non-null, then throw an
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>custom element state</span> is not "<code
data-x="">precustomized</code>" or "<code data-x="">custom</code>", then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <span>this</span>'s <span>attached internals</span> to a new
<code>ElementInternals</code> instance whose <span data-x="internals-target">target
element</span> is <span>this</span>.</p></li>
<li><p>Return <span>this</span>'s <span>attached internals</span>.</p></li>
</ol>
<h5>The <code>ElementInternals</code> interface</h5>
<p>The IDL for the <code>ElementInternals</code> interface is as follows, with the various operations and attributes
defined in the following sections:</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>ElementInternals</dfn> {
// <a href="#shadow-root-access">Shadow root access</a>
readonly attribute <code>ShadowRoot</code>? <span data-x="dom-ElementInternals-shadowRoot">shadowRoot</span>;
// <a href="#form-associated-custom-elements">Form-associated custom elements</a>
undefined <span data-x="dom-ElementInternals-setFormValue">setFormValue</span>((<span>File</span> or <span data-x="idl-USVString">USVString</span> or <span>FormData</span>)? value,
optional (<span>File</span> or <span data-x="idl-USVString">USVString</span> or <span>FormData</span>)? state);
readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-ElementInternals-form">form</span>;
undefined <span data-x="dom-ElementInternals-setValidity">setValidity</span>(optional <span>ValidityStateFlags</span> flags = {},
optional DOMString message,
optional <span>HTMLElement</span> anchor);
readonly attribute boolean <span data-x="dom-ElementInternals-willValidate">willValidate</span>;
readonly attribute <span>ValidityState</span> <span data-x="dom-ElementInternals-validity">validity</span>;
readonly attribute DOMString <span data-x="dom-ElementInternals-validationMessage">validationMessage</span>;
boolean <span data-x="dom-ElementInternals-checkValidity">checkValidity</span>();
boolean <span data-x="dom-ElementInternals-reportValidity">reportValidity</span>();
readonly attribute <span>NodeList</span> <span data-x="dom-ElementInternals-labels">labels</span>;
// <a href="#custom-state-pseudo-class">Custom state pseudo-class</a>
[SameObject] readonly attribute <span>CustomStateSet</span> <span data-x="dom-ElementInternals-states">states</span>;
};
// <a href="#accessibility-semantics">Accessibility semantics</a>
<span>ElementInternals</span> includes <span>ARIAMixin</span>;
dictionary <dfn dictionary>ValidityStateFlags</dfn> {
boolean valueMissing = false;
boolean typeMismatch = false;
boolean patternMismatch = false;
boolean tooLong = false;
boolean tooShort = false;
boolean rangeUnderflow = false;
boolean rangeOverflow = false;
boolean stepMismatch = false;
boolean badInput = false;
boolean customError = false;
};</code></pre>
<p>Each <code>ElementInternals</code> has a <dfn data-x="internals-target">target element</dfn>,
which is a <span>custom element</span>.</p>
</div>
<h5>Shadow root access</h5>
<dl class="domintro">
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-shadowRoot">shadowRoot</span></code></dt>
<dd><p>Returns the <code>ShadowRoot</code> for <var>internals</var>'s <span
data-x="internals-target">target element</span>, if the <span data-x="internals-target">target
element</span> is a <span>shadow host</span>, or null otherwise.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-shadowRoot">shadowRoot</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>target</var> be <span>this</span>'s <span data-x="internals-target">target
element</span>.</p></li>
<li><p>If <var>target</var> is not a <span>shadow host</span>, then return null.</p></li>
<li><p>Let <var>shadow</var> be <var>target</var>'s <span
data-x="concept-element-shadow-root">shadow root</span>.</p></li>
<li><p>If <var>shadow</var>'s <span>available to element internals</span> is false, then return
null.</p></li>
<li><p>Return <var>shadow</var>.</p></li>
</ol>
</div>
<h5>Form-associated custom elements</h5>
<dl class="domintro">
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-setFormValue">setFormValue</span>(<var>value</var>)</code></dt>
<dd>
<p>Sets both the <span data-x="face-state">state</span> and <span
data-x="face-submission-value">submission value</span> of <var>internals</var>'s <span
data-x="internals-target">target element</span> to <var>value</var>.</p>
<p>If <var>value</var> is null, the element won't participate in form submission.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-setFormValue">setFormValue</span>(<var>value</var>,
<var>state</var>)</code></dt>
<dd>
<p>Sets the <span data-x="face-submission-value">submission value</span> of
<var>internals</var>'s <span data-x="internals-target">target element</span> to
<var>value</var>, and its <span data-x="face-state">state</span> to <var>state</var>.</p>
<p>If <var>value</var> is null, the element won't participate in form submission.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-form">form</span></code></dt>
<dd><p>Returns the <span>form owner</span> of <var>internals</var>'s <span
data-x="internals-target">target element</span>.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-setValidity">setValidity</span>(<var>flags</var>,
<var>message</var> [, <var>anchor</var> ])</code></dt>
<dd><p>Marks <var>internals</var>'s <span data-x="internals-target">target element</span> as
suffering from the constraints indicated by the <var>flags</var> argument, and sets the element's
validation message to <var>message</var>. If <var>anchor</var> is specified, the user agent might
use it to indicate problems with the constraints of <var>internals</var>'s <span
data-x="internals-target">target element</span> when the <span>form owner</span> is validated
interactively or <code data-x="dom-ElementInternals-reportValidity">reportValidity()</code> is
called.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-setValidity">setValidity</span>({})</code></dt>
<dd><p>Marks <var>internals</var>'s <span data-x="internals-target">target element</span> as
<span data-x="concept-fv-valid">satisfying its constraints</span>.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-willValidate">willValidate</span></code></dt>
<dd><p>Returns true if <var>internals</var>'s <span data-x="internals-target">target
element</span> will be validated when the form is submitted; false otherwise.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-validity">validity</span></code></dt>
<dd><p>Returns the <code>ValidityState</code> object for <var>internals</var>'s <span
data-x="internals-target">target element</span>.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-validationMessage">validationMessage</span></code></dt>
<dd><p>Returns the error message that would be shown to the user if <var>internals</var>'s <span
data-x="internals-target">target element</span> was to be checked for validity.</p></dd>
<dt><code data-x=""><var>valid</var> = <var>internals</var>.<span data-x="dom-ElementInternals-checkValidity">checkValidity()</span></code></dt>
<dd><p>Returns true if <var>internals</var>'s <span data-x="internals-target">target
element</span> has no validity problems; false otherwise. Fires an <code
data-x="event-invalid">invalid</code> event at the element in the latter case.</p></dd>
<dt><code data-x=""><var>valid</var> = <var>internals</var>.<span data-x="dom-ElementInternals-reportValidity">reportValidity()</span></code></dt>
<dd><p>Returns true if <var>internals</var>'s <span data-x="internals-target">target
element</span> has no validity problems; otherwise, returns false, fires an <code
data-x="event-invalid">invalid</code> event at the element, and (if the event isn't canceled)
reports the problem to the user.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-labels">labels</span></code></dt>
<dd><p>Returns a <code>NodeList</code> of all the <code>label</code> elements that
<var>internals</var>'s <span data-x="internals-target">target element</span> is associated
with.</p></dd>
</dl>
<p>Each <span>form-associated custom element</span> has <dfn
data-x="face-submission-value">submission value</dfn>. It is used to provide one or more
<span data-x="form entry">entries</span> on form submission.
The initial value of <span data-x="face-submission-value">submission value</span> is null, and
<span data-x="face-submission-value">submission value</span> can be null, a string, a
<code>File</code>, or a <span>list</span> of <span data-x="form entry">entries</span>.</p>
<p>Each <span>form-associated custom element</span> has <dfn data-x="face-state">state</dfn>.
It is information with which the user agent can restore a user's input for the element.
The initial value of <span data-x="face-state">state</span> is null, and <span
data-x="face-state">state</span> can be null, a string, a <code>File</code>, or a
<span>list</span> of <span data-x="form entry">entries</span>.</p>
<p>The <code data-x="dom-ElementInternals-setFormValue">setFormValue()</code> method is used by
the custom element author to set the element's <span data-x="face-submission-value">submission
value</span> and <span data-x="face-state">state</span>, thus communicating these to the user
agent.</p>
<p>When the user agent believes it is a good idea to restore a <span>form-associated custom
element</span>'s <span data-x="face-state">state</span>, for example <span data-x="restore
persisted state">after navigation</span> or restarting the user agent, they may <span>enqueue a
custom element callback reaction</span> with that element, callback name "<code
data-x="">formStateRestoreCallback</code>", and « the state to be restored, "<code
data-x="">restore</code>" ».</p>
<p>If the user agent has a form-filling assist feature, then when the feature is invoked, it may
<span>enqueue a custom element callback reaction</span> with a <span>form-associated custom
element</span>, callback name "<code data-x="">formStateRestoreCallback</code>", and « the state
value determined by history of state value and some heuristics, "<code
data-x="">autocomplete</code>" ».</p>
<p>In general, the <span data-x="face-state">state</span> is information specified by a user, and
the <span data-x="face-submission-value">submission value</span> is a value after canonicalization
or sanitization, suitable for submission to the server. The following examples makes this
concrete:</p>
<p class="example">Suppose that we have a <span>form-associated custom element</span> which asks a
user to specify a date. The user specifies <kbd>"3/15/2019"</kbd>, but the control wishes to
submit <code data-x="">"2019-03-15"</code> to the server. <kbd>"3/15/2019"</kbd> would be a <span
data-x="face-state">state</span> of the element, and <code data-x="">"2019-03-15"</code> would be
a <span data-x="face-submission-value">submission value</span>.</p>
<p class="example">Suppose you develop a custom element emulating a the behavior of the existing
<span data-x="attr-input-type-checkbox">checkbox</span> <code>input</code> type. Its <span
data-x="face-submission-value">submission value</span> would be the value of its <code
data-x="">value</code> content attribute, or the string <code data-x="">"on"</code>. Its <span
data-x="face-state">state</span> would be one of <code data-x="">"checked"</code>, <code
data-x="">"unchecked"</code>, <code data-x="">"checked/indeterminate"</code>, or <code
data-x="">"unchecked/indeterminate"</code>.</p>
<div w-nodev>
<p>The <dfn method for="ElementInternals"><code
data-x="dom-ElementInternals-setFormValue">setFormValue(<var>value</var>,
<var>state</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>element</var> be <span>this</span>'s <span data-x="internals-target">target
element</span>.</p></li>
<li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Set <span data-x="internals-target">target element</span>'s <span
data-x="face-submission-value">submission value</span> to <var>value</var> if <var>value</var> is
not a <code>FormData</code> object, or to a <span data-x="list clone">clone</span> of
<var>value</var>'s <span data-x="FormData entry list">entry list</span> otherwise.</p></li>
<li><p>If the <var>state</var> argument of the function is omitted, set <var>element</var>'s
<span data-x="face-state">state</span> to its <span data-x="face-submission-value">submission
value</span>.
<li><p>Otherwise, if <var>state</var> is a <code>FormData</code> object, set <var>element</var>'s
<span data-x="face-state">state</span> to a <span data-x="list clone">clone</span> of
<var>state</var>'s <span data-x="FormData entry list">entry list</span>.</p></li>
<li><p>Otherwise, set <var>element</var>'s <span data-x="face-state">state</span> to
<var>state</var>.</p></li>
</ol>
<hr>
<p>Each <span>form-associated custom element</span> has validity flags named
<code data-x="">valueMissing</code>, <code data-x="">typeMismatch</code>,
<code data-x="">patternMismatch</code>, <code data-x="">tooLong</code>,
<code data-x="">tooShort</code>, <code data-x="">rangeUnderflow</code>,
<code data-x="">rangeOverflow</code>, <code data-x="">stepMismatch</code>, and
<code data-x="">customError</code>. They are false initially.</p>
<p>Each <span>form-associated custom element</span> has a
<dfn data-x="face-validation-message">validation message</dfn> string. It is the empty string
initially.</p>
<p>Each <span>form-associated custom element</span> has a
<dfn data-x="face-validation-anchor">validation anchor</dfn> element. It is null initially.</p>
<p>The <dfn method for="ElementInternals"><code
data-x="dom-ElementInternals-setValidity">setValidity(<var>flags</var>, <var>message</var>,
<var>anchor</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>element</var> be <span>this</span>'s <span data-x="internals-target">target
element</span>.</p></li>
<li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>flags</var> contains one or more true values and <var>message</var> is not given
or is the empty string, then throw a <code>TypeError</code>.</p></li>
<li><p>For each entry <var>flag</var> → <var>value</var> of <var>flags</var>, set
<var>element</var>'s validity flag with the name <var>flag</var> to <var>value</var>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="face-validation-message">validation message</span>
to the empty string if <var>message</var> is not given or all of <var>element</var>'s validity
flags are false, or to <var>message</var> otherwise.</p></li>
<li><p>If <var>element</var>'s <code data-x="">customError</code> validity flag is true, then set
<var>element</var>'s <span>custom validity error message</span> to <var>element</var>'s
<span data-x="face-validation-message">validation message</span>. Otherwise, set
<var>element</var>'s <span>custom validity error message</span> to the empty string.</p></li>
<li><p>Set <var>element</var>'s <span data-x="face-validation-anchor">validation anchor</span> to
null if <var>anchor</var> is not given. Otherwise, if <var>anchor</var> is not a
<span>shadow-including descendant</span> of <var>element</var>, then throw a
<span>"<code>NotFoundError</code>"</span> <code>DOMException</code>. Otherwise, set
<var>element</var>'s <span data-x="face-validation-anchor">validation anchor</span> to
<var>anchor</var>.</p></li>
</ol>
<p>The <dfn attribute for="ElementInternals"><code
data-x="dom-ElementInternals-validationMessage">validationMessage</code></dfn> getter steps
are:</p>
<ol>
<li><p>Let <var>element</var> be <span>this</span>'s <span data-x="internals-target">target
element</span>.</p></li>
<li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return <var>element</var>'s <span data-x="face-validation-message">validation
message</span>.</p></li>
</ol>
<p>The <dfn data-x="face-entry-construction">entry construction algorithm</dfn> for a
<span>form-associated custom element</span>, given an element <var>element</var> and an
<span>entry list</span> <var>entry list</var>, consists of the following steps:</p>
<ol>
<li>
<p>If <var>element</var>'s <span data-x="face-submission-value">submission value</span> is a
<span>list</span> of <span data-x="form entry">entries</span>, then <span data-x="list
append">append</span> each item of <var>element</var>'s <span
data-x="face-submission-value">submission value</span> to <var>entry list</var>, and return.</p>
<p class="note">In this case, user agent does not refer to the
<code data-x="attr-fe-name">name</code> content attribute value. An implementation of
<span>form-associated custom element</span> is responsible to decide names of
<span data-x="form entry">entries</span>. They can be the
<code data-x="attr-fe-name">name</code> content attribute value, they can be strings based on
the <code data-x="attr-fe-name">name</code> content attribute value, or they can be unrelated
to the <code data-x="attr-fe-name">name</code> content attribute.</p>
</li>
<li><p>If the element does not have a <code data-x="attr-fe-name">name</code> attribute
specified, or its <code data-x="attr-fe-name">name</code> attribute's value is the empty string,
then return.</p></li>
<li><p>If the element's <span data-x="face-submission-value">submission value</span> is not
null, <span>create an entry</span> with the <code data-x="attr-fe-name">name</code> attribute
value and the <span data-x="face-submission-value">submission value</span>, and <span
data-x="list append">append</span> it to <var>entry list</var>.</p></li>
</ol>
</div>
<h5>Accessibility semantics</h5>
<dl class="domintro">
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ARIAMixin-role">role</span> [ = <var>value</var> ]</code></dt>
<dd><p>Sets or retrieves the default ARIA role for <var>internals</var>'s <span
data-x="internals-target">target element</span>, which will be used unless the page author
overrides it using the <code data-x="attr-aria-role">role</code> attribute.</p></dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ARIAMixin-aria*">aria*</span> [ = <var>value</var> ]</code></dt>
<dd><p>Sets or retrieves various default ARIA states or property values for
<var>internals</var>'s <span data-x="internals-target">target element</span>, which will be used
unless the page author overrides them using the <code data-x="attr-aria-*">aria-*</code>
attributes.</p></dd>
</dl>
<p w-dev>By using the <code data-x="">role</code> and <code data-x="">aria*</code> properties of
<code>ElementInternals</code>, custom element authors can set default accessibile roles, states,
and property values for their custom element, similar to how native elements behave. See <a
href="#custom-elements-accessibility-example">the example above</a> for more details.</p>
<div w-nodev>
<p>Each <span>custom element</span> has an <dfn>internal content attribute map</dfn>, which is a
<span data-x="ordered map">map</span>, initially empty. See the <a href="#wai-aria">Requirements
related to ARIA and to platform accessibility APIs</a> section for information on how this impacts
platform accessibility APIs.</p>
</div>
<h5>Custom state pseudo-class</h5>
<dl class="domintro">
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.add(<var>value</var>)</code></dt>
<dd>
<p>Adds the string <var>value</var> to the element's <span>states set</span> to be exposed as a
pseudo-class.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.has(<var>value</var>)</code></dt>
<dd>
<p>Returns true if <var>value</var> is in the element's <span>states set</span>, otherwise
false.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.delete(<var>value</var>)</code></dt>
<dd>
<p>If the element's <span>states set</span> has <var>value</var>, then it will be removed and
true will be returned. Otherwise, false will be returned.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.clear()</code></dt>
<dd>
<p>Removes all values from the element's <span>states set</span>.</p>
</dd>
<dt><code data-x="">for (const <var>stateName</var> of <var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>)</code></dt>
<dt><code data-x="">for (const <var>stateName</var> of <var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.entries())</code></dt>
<dt><code data-x="">for (const <var>stateName</var> of <var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.keys())</code></dt>
<dt><code data-x="">for (const <var>stateName</var> of <var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.values())</code></dt>
<dd>
<p>Iterates over all values in the element's <span>states set</span>.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.forEach(<var>callback</var>)</code></dt>
<dd>
<p>Iterates over all values in the element's <span>states set</span> by calling
<var>callback</var> once for each value.</p>
</dd>
<dt><code data-x=""><var>internals</var>.<span data-x="dom-ElementInternals-states">states</span>.size</code></dt>
<dd>
<p>Returns the number of values in the element's <span>states set</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <span>custom element</span> has a <dfn>states set</dfn>, which is a
<code>CustomStateSet</code>, initially empty.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>CustomStateSet</dfn> {
setlike<DOMString>;
};</code></pre>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-ElementInternals-states">states</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="internals-target">target element</span>'s <span>states
set</span>.</p>
</div>
<div class="example">
<p>The <span>states set</span> can expose boolean states represented by existence/non-existence
of string values. If an author wants to expose a state which can have three values, it can be
converted to three exclusive boolean states. For example, a state called <code
data-x="">readyState</code> with <code data-x="">"loading"</code>, <code
data-x="">"interactive"</code>, and <code data-x="">"complete"</code> values can be mapped to
three exclusive boolean states, <code data-x="">"loading"</code>, <code
data-x="">"interactive"</code>, and <code data-x="">"complete"</code>:</p>
<pre><code class="js">// Change the readyState from anything to "complete".
this._readyState = "complete";
this._internals.states.delete("loading");
this._internals.states.delete("interactive");
this._internals.states.add("complete");</code></pre>
</div>
<h3 split-filename="semantics-other" id="common-idioms">Common idioms without dedicated elements</h3>
<h4 id="rel-up">Breadcrumb navigation</h4>
<p>This specification does not provide a machine-readable way of describing breadcrumb navigation
menus. Authors are encouraged to just use a series of links in a paragraph. The <code>nav</code>
element can be used to mark the section containing these paragraphs as being navigation
blocks.</p>
<!-- If there was implementation interest, we could go back to rel="up", rel="up up", rel="up up
top" to programmatically indicate the actual breadcrumb structure. However, UAs and ATs don't seem
interested in exposing this in a useful way to users. So... -->
<div class="example">
<p>In the following example, the current page can be reached via two paths.</p>
<pre><code class="html"><nav>
<p>
<a href="/">Main</a> ▸
<a href="/products/">Products</a> ▸
<a href="/products/dishwashers/">Dishwashers</a> ▸
<a>Second hand</a>
</p>
<p>
<a href="/">Main</a> ▸
<a href="/second-hand/">Second hand</a> ▸
<a>Dishwashers</a>
</p>
</nav></code></pre>
</div>
<h4>Tag clouds</h4>
<p id="tag-cloud">This specification does not define any markup specifically for marking up lists
of keywords that apply to a group of pages (also known as <i>tag clouds</i>). In general, authors
are encouraged to either mark up such lists using <code>ul</code> elements with explicit inline
counts that are then hidden and turned into a presentational effect using a style sheet, or to use
SVG.</p>
<div class="example">
<p>Here, three tags are included in a short tag cloud:</p>
<pre><code class="html"><style>
.tag-cloud > li > span { display: none; }
.tag-cloud > li { display: inline; }
.tag-cloud-1 { font-size: 0.7em; }
.tag-cloud-2 { font-size: 0.9em; }
.tag-cloud-3 { font-size: 1.1em; }
.tag-cloud-4 { font-size: 1.3em; }
.tag-cloud-5 { font-size: 1.5em; }
@media speech {
.tag-cloud > li > span { display:inline }
}
</style>
...
<ul class="tag-cloud">
<li class="tag-cloud-4"><a title="28 instances" href="/t/apple">apple</a> <span>(popular)</span>
<li class="tag-cloud-2"><a title="6 instances" href="/t/kiwi">kiwi</a> <span>(rare)</span>
<li class="tag-cloud-5"><a title="41 instances" href="/t/pear">pear</a> <span>(very popular)</span>
</ul></code></pre>
<p>The actual frequency of each tag is given using the <code data-x="attr-title">title</code>
attribute. A CSS style sheet is provided to convert the markup into a cloud of differently-sized
words, but for user agents that do not support CSS or are not visual, the markup contains
annotations like "(popular)" or "(rare)" to categorize the various tags by frequency, thus
enabling all users to benefit from the information.</p>
<p>The <code>ul</code> element is used (rather than <code>ol</code>) because the order is not
particularly important: while the list is in fact ordered alphabetically, it would convey the
same information if ordered by, say, the length of the tag.</p>
<p>The <code data-x="rel-tag">tag</code> <code data-x="attr-hyperlink-rel">rel</code>-keyword is
<em>not</em> used on these <code>a</code> elements because they do not represent tags that apply
to the page itself; they are just part of an index listing the tags themselves.</p>
</div>
<h4>Conversations</h4>
<!-- https://lists.w3.org/Archives/Public/public-whatwg-archive/2009Sep/0043.html -->
<p>This specification does not define a specific element for marking up conversations, meeting
minutes, chat transcripts, dialogues in screenplays, instant message logs, and other situations
where different players take turns in discourse.</p>
<p>Instead, authors are encouraged to mark up conversations using <code>p</code> elements and
punctuation. Authors who need to mark the speaker for styling purposes are encouraged to use
<code>span</code> or <code>b</code>. Paragraphs with their text wrapped in the <code>i</code>
element can be used for marking up stage directions.</p>
<div class="example">
<p>This example demonstrates this using an extract from Abbot and Costello's famous sketch,
<cite>Who's on first</cite>:</p>
<pre><code class="html"><p> Costello: Look, you gotta first baseman?
<p> Abbott: Certainly.
<p> Costello: Who's playing first?
<p> Abbott: That's right.
<p> Costello becomes exasperated.
<p> Costello: When you pay off the first baseman every month, who gets the money?
<p> Abbott: Every dollar of it.</code></pre>
</div>
<div class="example">
<p>The following extract shows how an IM conversation log could be marked up, using the
<code>data</code> element to provide Unix timestamps for each line. Note that the timestamps are
provided in a format that the <code>time</code> element does not support, so the
<code>data</code> element is used instead (namely, Unix <code data-x="">time_t</code> timestamps).
Had the author wished to mark up the data using one of the date and time formats supported by the
<code>time</code> element, that element could have been used instead of <code>data</code>. This
could be advantageous as it would allow data analysis tools to detect the timestamps
unambiguously, without coordination with the page author.</p>
<pre><code class="html"><p> <data value="1319898155">14:22</data> <b>egof</b> I'm not that nerdy, I've only seen 30% of the star trek episodes
<p> <data value="1319898192">14:23</data> <b>kaj</b> if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy
<p> <data value="1319898200">14:23</data> <b>egof</b> it's unarguably
<p> <data value="1319898228">14:23</data> <i>* kaj blinks</i>
<p> <data value="1319898260">14:24</data> <b>kaj</b> you are not helping your case</code></pre>
<!-- with thanks to http://bash.org/?854262 -->
</div>
<div class="example">
<p>HTML does not have a good way to mark up graphs, so descriptions of interactive conversations
from games are more difficult to mark up. This example shows one possible convention using
<code>dl</code> elements to list the possible responses at each point in the conversation.
Another option to consider is describing the conversation in the form of a DOT file, and
outputting the result as an SVG image to place in the document. <ref>DOT</ref></p>
<pre><code class="html"><p> Next, you meet a fisher. You can say one of several greetings:
<dl>
<dt> "Hello there!"
<dd>
<p> She responds with "Hello, how may I help you?"; you can respond with:
<dl>
<dt> "I would like to buy a fish."
<dd> <p> She sells you a fish and the conversation finishes.
<dt> "Can I borrow your boat?"
<dd>
<p> She is surprised and asks "What are you offering in return?".
<dl>
<dt> "Five gold." (if you have enough)
<dt> "Ten gold." (if you have enough)
<dt> "Fifteen gold." (if you have enough)
<dd> <p> She lends you her boat. The conversation ends.
<dt> "A fish." (if you have one)
<dt> "A newspaper." (if you have one)
<dt> "A pebble." (if you have one)
<dd> <p> "No thanks", she replies. Your conversation options
at this point are the same as they were after asking to borrow
her boat, minus any options you've suggested before.
</dl>
</dd>
</dl>
</dd>
<dt> "Vote for me in the next election!"
<dd> <p> She turns away. The conversation finishes.
<dt> "Madam, are you aware that your fish are running away?"
<dd>
<p> She looks at you skeptically and says "Fish cannot run, miss".
<dl>
<dt> "You got me!"
<dd> <p> The fisher sighs and the conversation ends.
<dt> "Only kidding."
<dd> <p> "Good one!" she retorts. Your conversation options at this
point are the same as those following "Hello there!" above.
<dt> "Oh, then what are they doing?"
<dd> <p> She looks at her fish, giving you an opportunity to steal
her boat, which you do. The conversation ends.
</dl>
</dd>
</dl></code></pre>
</div>
<div class="example">
<p>In some games, conversations are simpler: each character merely has a fixed set of lines that
they say. In this example, a game FAQ/walkthrough lists some of the known possible responses for
each character:</p>
<pre><code class="html"><section>
<h1>Dialogue</h1>
<p><small>Some characters repeat their lines in order each time you interact
with them, others randomly pick from amongst their lines. Those who respond in
order have numbered entries in the lists below.</small>
<h2>The Shopkeeper</h2>
<ul>
<li>How may I help you?
<li>Fresh apples!
<li>A loaf of bread for madam?
</ul>
<h2>The pilot</h2>
<p>Before the accident:
<ul>
<li>I'm about to fly out, sorry!
<li>Sorry, I'm just waiting for flight clearance and then I'll be off!
</ul>
<p>After the accident:
<ol>
<li>I'm about to fly out, sorry!
<li>Ok, I'm not leaving right now, my plane is being cleaned.
<li>Ok, it's not being cleaned, it needs a minor repair first.
<li>Ok, ok, stop bothering me! Truth is, I had a crash.
</ol>
<h2>Clan Leader</h2>
<p>During the first clan meeting:
<ul>
<li>Hey, have you seen my daughter? I bet she's up to something nefarious again...
<li>Nice weather we're having today, eh?
<li>The name is Bailey, Jeff Bailey. How can I help you today?
<li>A glass of water? Fresh from the well!
</ul>
<p>After the earthquake:
<ol>
<li>Everyone is safe in the shelter, we just have to put out the fire!
<li>I'll go and tell the fire brigade, you keep hosing it down!
</ol>
</section></code></pre>
</div>
<h4 id="footnotes">Footnotes</h4>
<p>HTML does not have a dedicated mechanism for marking up footnotes. Here are the suggested
alternatives.</p>
<hr>
<p>For short inline annotations, the <code data-x="attr-title">title</code> attribute could <!--
SHOULD, modulo title-warning --> be used.</p>
<div class="example">
<p>In this example, two parts of a dialogue are annotated with footnote-like content using the
<code data-x="attr-title">title</code> attribute.</p>
<pre><code class="html"><p> <b>Customer</b>: Hello! I wish to register a complaint. Hello. Miss?
<p> <b>Shopkeeper</b>: <strong><span title="Colloquial pronunciation of 'What do you'"</strong>
>Watcha</span> mean, miss?
<p> <b>Customer</b>: Uh, I'm sorry, I have a cold. I wish to make a complaint.
<p> <b>Shopkeeper</b>: Sorry, <span <strong>title="This is, of course, a lie."</strong>>we're
closing for lunch</span>.</code></pre>
</div>
<!-- search for title-warning if modifying this paragraph -->
<p class="note">Unfortunately, relying on the <code data-x="attr-title">title</code> attribute is
currently discouraged as many user agents do not expose the attribute in an accessible manner as
required by this specification (e.g. requiring a pointing device such as a mouse to cause a
tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone with a
modern phone or tablet).</p>
<p class="note">If the <code data-x="attr-title">title</code> attribute is used, CSS can be used to
draw the reader's attention to the elements with the attribute.</p>
<div class="example">
<p>For example, the following CSS places a dashed line below elements that have a <code
data-x="attr-title">title</code> attribute.</p>
<pre><code class="css">[title] { border-bottom: thin dashed; }</code></pre>
</div>
<hr>
<p>For longer annotations, the <code>a</code> element should be used, pointing to an element later
in the document. The convention is that the contents of the link be a number in square
brackets.</p>
<div class="example">
<p>In this example, a footnote in the dialogue links to a paragraph below the dialogue. The
paragraph then reciprocally links back to the dialogue, allowing the user to return to the
location of the footnote.</p>
<pre><code class="html"><p> Announcer: Number 16: The <i>hand</i>.
<p> Interviewer: Good evening. I have with me in the studio tonight
Mr Norman St John Polevaulter, who for the past few years has been
contradicting people. Mr Polevaulter, why <em>do</em> you
contradict people?
<p> Norman: I don't. <sup><a href="#fn1" id="r1">[1]</a></sup>
<p> Interviewer: You told me you did!
<em>...</em>
<section>
<p id="fn1"><a href="#r1">[1]</a> This is, naturally, a lie,
but paradoxically if it were true he could not say so without
contradicting the interviewer and thus making it false.</p>
</section></code></pre>
</div>
<hr>
<p>For side notes, longer annotations that apply to entire sections of the text rather than just
specific words or sentences, the <code>aside</code> element should be used.</p>
<div class="example">
<p>In this example, a sidebar is given after a dialogue, giving it some context.</p>
<pre><code class="html"><p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched.
<p> <span class="speaker">Shopkeeper</span>: I'm sorry?
<p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched.
<p> <span class="speaker">Shopkeeper</span>: No no no, this's'a tobacconist's.
<aside>
<p>In 1970, the British Empire lay in ruins, and foreign
nationalists frequented the streets — many of them Hungarians
(not the streets — the foreign nationals). Sadly, Alexander
Yalt has been publishing incompetently-written phrase books.
</aside></code></pre>
</div>
<hr>
<p>For figures or tables, footnotes can be included in the relevant <code>figcaption</code> or
<code>caption</code> element, or in surrounding prose.</p>
<div class="example">
<p>In this example, a <!-- round --> table has cells with footnotes that are given in prose. A
<code>figure</code> element is used to give a single legend to the combination of the table and
its footnotes.</p>
<pre><code class="html"><figure>
<figcaption>Table 1. Alternative activities for knights.</figcaption>
<table>
<tr>
<th> Activity
<th> Location
<th> Cost
<tr>
<td> Dance
<td> Wherever possible
<td> £0<sup><a href="#fn1">1</a></sup>
<tr>
<td> Routines, chorus scenes<sup><a href="#fn2">2</a></sup>
<td> Undisclosed
<td> Undisclosed
<tr>
<td> Dining<sup><a href="#fn3">3</a></sup>
<td> Camelot
<td> Cost of ham, jam, and spam<sup><a href="#fn4">4</a></sup>
</table>
<p id="fn1">1. Assumed.</p>
<p id="fn2">2. Footwork impeccable.</p>
<p id="fn3">3. Quality described as "well".</p>
<p id="fn4">4. A lot.</p>
</figure></code></pre>
</div>
<h3>Disabled elements</h3>
<p>An element is said to be <dfn data-x="concept-element-disabled">actually disabled</dfn> if it
is one of the following:</p>
<ul>
<li>a <code>button</code> element that is <span data-x="concept-fe-disabled">disabled</span></li>
<li>an <code>input</code> element that is <span data-x="concept-fe-disabled">disabled</span></li>
<li>a <code>select</code> element that is <span data-x="concept-fe-disabled">disabled</span></li>
<li>a <code>textarea</code> element that is <span data-x="concept-fe-disabled">disabled</span></li>
<li>an <code>optgroup</code> element that has a <code data-x="attr-optgroup-disabled">disabled</code> attribute</li>
<li>an <code>option</code> element that is <span data-x="concept-option-disabled">disabled</span></li>
<li>a <code>fieldset</code> element that is a <span data-x="concept-fieldset-disabled">disabled fieldset</span></li>
<li>a <span>form-associated custom element</span> that is
<span data-x="concept-fe-disabled">disabled</span></li>
</ul>
<p class="note">This definition is used to determine what elements are <span>focusable</span> and
which elements match the <code data-x="selector-enabled">:enabled</code> and
<code data-x="selector-disabled">:disabled</code> <span data-x="pseudo-class">pseudo
classes</span>.</p>
<div w-nodev>
<h3 id="selectors">Matching HTML elements using selectors and CSS</h3>
<h4>Case-sensitivity of the CSS <span>'attr()'</span> function</h4>
<p><cite>CSS Values and Units</cite> leaves the case-sensitivity of attribute names for the
purpose of the <span>'attr()'</span> function to be defined by the host language.
<ref>CSSVALUES</ref></p>
<p>When comparing the attribute name part of a CSS <span>'attr()'</span> function to the names of
namespace-less attributes on <span>HTML elements</span> in <span>HTML documents</span>, the name
part of the CSS <span>'attr()'</span> function must first be <span>converted to ASCII
lowercase</span>. The same function when compared to other attributes must be compared according
to its original case. In both cases, to match the values must be <span>identical to</span> each
other (and therefore the comparison is case sensitive).</p>
<p class="note">This is the same as comparing the name part of a CSS <span>attribute
selector</span>, specified in the next section.</p>
<h4>Case-sensitivity of selectors</h4>
<p><cite>Selectors</cite> leaves the case-sensitivity of element names, attribute names, and
attribute values to be defined by the host language. <ref>SELECTORS</ref></p>
<p>When comparing a CSS element <span>type selector</span> to the names of <span>HTML
elements</span> in <span>HTML documents</span>, the CSS element <span>type selector</span> must
first be <span>converted to ASCII lowercase</span>. The same selector when compared to other
elements must be compared according to its original case. In both cases, to match the values must
be <span>identical to</span> each other (and therefore the comparison is case sensitive).</p>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2623 -->
<p>When comparing the name part of a CSS <span>attribute selector</span> to the names of
attributes on <span>HTML elements</span> in <span>HTML documents</span>, the name
part of the CSS <span>attribute selector</span> must first be <span>converted to ASCII
lowercase</span>. The same selector when compared to other attributes must be compared according
to its original case. In both cases, the comparison is case-sensitive.</p>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2624 -->
<p><span data-x="attribute selector">Attribute selectors</span> on an <span
data-x="HTML elements">HTML element</span> in an <span data-x="HTML documents">HTML
document</span> must treat the <em>values</em> of attributes with the following names as
<span>ASCII case-insensitive</span>:</p>
<!-- based on Mozilla's list, which was itself based on HTML4 -->
<!-- WebKit's was identical at the time of writing except as noted below -->
<ul class="brief">
<li><code data-x="">accept</code>
<li><code data-x="">accept-charset</code>
<li><code data-x="">align</code>
<li><code data-x="">alink</code>
<li><code data-x="">axis</code>
<li><code data-x="">bgcolor</code>
<li><code data-x="">charset</code>
<li><code data-x="">checked</code>
<li><code data-x="">clear</code>
<li><code data-x="">codetype</code>
<li><code data-x="">color</code>
<li><code data-x="">compact</code>
<li><code data-x="">declare</code>
<li><code data-x="">defer</code>
<li><code data-x="">dir</code>
<li><code data-x="">direction</code> <!-- not in WebKit -->
<li><code data-x="">disabled</code>
<li><code data-x="">enctype</code>
<li><code data-x="">face</code>
<li><code data-x="">frame</code>
<li><code data-x="">hreflang</code>
<li><code data-x="">http-equiv</code>
<li><code data-x="">lang</code>
<li><code data-x="">language</code>
<li><code data-x="">link</code>
<li><code data-x="">media</code>
<li><code data-x="">method</code>
<li><code data-x="">multiple</code>
<li><code data-x="">nohref</code>
<li><code data-x="">noresize</code>
<li><code data-x="">noshade</code>
<li><code data-x="">nowrap</code>
<li><code data-x="">readonly</code>
<li><code data-x="">rel</code>
<li><code data-x="">rev</code>
<li><code data-x="">rules</code>
<li><code data-x="">scope</code>
<li><code data-x="">scrolling</code>
<li><code data-x="">selected</code>
<li><code data-x="">shape</code>
<li><code data-x="">target</code>
<li><code data-x="">text</code>
<li><code data-x="">type</code>
<li><code data-x="">valign</code>
<li><code data-x="">valuetype</code>
<li><code data-x="">vlink</code>
</ul>
<div class="example">
<p>For example, the selector <code data-x="">[bgcolor="#ffffff"]</code> will match any HTML
element with a <code data-x="">bgcolor</code> attribute with values including <code
data-x="">#ffffff</code>, <code data-x="">#FFFFFF</code> and <code data-x="">#fffFFF</code>. This
happens even if <code data-x="">bgcolor</code> has no effect for a given element (e.g.,
<code>div</code>).</p>
<p>The selector <code data-x="">[type=a <!--grammar-check-override-->s]</code> will match any
HTML element with a <code data-x="">type</code> attribute whose value is <code
data-x="">a</code>, but not whose value is <code data-x="">A</code>, due to the <code
data-x="">s</code> flag.</p>
</div>
<p>All other attribute values and everything else must be treated as entirely <span>identical
to</span> each other for the purposes of selector matching. This includes:</p>
<ul>
<li><p><span data-x="concept-id">IDs</span> and <span data-x="concept-class">classes</span>
in <span>no-quirks mode</span> and <span>limited-quirks mode</span></p></li>
<li><p>the names of elements not in the <span>HTML namespace</span></p></li>
<li><p>the names of <span>HTML elements</span> in <span>XML documents</span></p></li>
<li><p>the names of attributes of elements not in the <span>HTML namespace</span></p></li>
<li><p>the names of attributes of <span>HTML elements</span> in <span>XML documents</span></p></li>
<li><p>the names of attributes that themselves have namespaces</p></li>
</ul>
<p class="note"><cite>Selectors</cite> defines that ID and class selectors (such as <code
data-x="">#foo</code> and <code data-x="">.bar</code>), when matched against elements in documents
that are in <span>quirks mode</span>, will be matched in an <span>ASCII case-insensitive</span>
manner. However, this does not apply for attribute selectors with "<code data-x="">id</code>" or
"<code data-x="">class</code>" as the name part. The selector <code
data-x="">[class="foobar"]</code> will treat its value as case-sensitive even in
<span>quirks mode</span>.</p>
<h4>Pseudo-classes</h4>
<p>There are a number of dynamic selectors that can be used with HTML. This section defines when
these selectors match HTML elements. <ref>SELECTORS</ref> <ref>CSSUI</ref></p>
<dl>
<dt><dfn selector noexport><code data-x="selector-defined">:defined</code></dfn></dt>
<!-- noexport is used explicitly here and for other psuedo-classes below as the script
scraping HTML for references (Shepherd) automatically exports terms that look like
pseudo-classes. -->
<dd>
<p>The <code data-x="selector-defined">:defined</code> <span>pseudo-class</span> must match
any element that is <span data-x="concept-element-defined">defined</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-link">:link</code></dfn></dt>
<dt><dfn selector noexport><code data-x="selector-visited">:visited</code></dfn></dt>
<dd>
<p>All <code>a</code> elements that have an <code data-x="attr-hyperlink-href">href</code>
attribute, and all <code>area</code> elements that have an <code
data-x="attr-hyperlink-href">href</code> attribute, must match one of <code
data-x="selector-link">:link</code> and <code data-x="selector-visited">:visited</code>.</p>
<p>Other specifications might apply more specific rules regarding how these elements are to
match these <span data-x="pseudo-class">pseudo-classes</span>, to mitigate some privacy concerns
that apply with straightforward implementations of this requirement.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-active">:active</code></dfn></dt>
<dd>
<p>The <code data-x="selector-active">:active</code> <span>pseudo-class</span> is defined to
match an element <q cite="https://drafts.csswg.org/selectors/#the-active-pseudo">while an
element is <dfn><i data-x="concept-selector-active">being activated</i></dfn> by the
user</q>.</p>
<p>To determine whether a particular element is <i data-x="concept-selector-active">being
activated</i> for the purposes of defining the <code data-x="selector-active">:active</code>
<span>pseudo-class</span> only, an HTML user agent must use the first relevant entry in the
following list.</p>
<dl>
<dt>If the element is a <code>button</code> element</dt>
<dt>If the element is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-submit">Submit Button</span>, <span
data-x="attr-input-type-image">Image Button</span>, <span data-x="attr-input-type-reset">Reset
Button</span>, or <span data-x="attr-input-type-button">Button</span> state</dt>
<dt>If the element is an <code>a</code> element that has an <code
data-x="attr-hyperlink-href">href</code> attribute</dt>
<dt>If the element is an <code>area</code> element that has an <code
data-x="attr-hyperlink-href">href</code> attribute</dt>
<dt>If the element is <span>focusable</span></dt>
<dd>
<p>The element is <i data-x="concept-selector-active">being activated</i> if it is <span>in a
formal activation state</span>.</p>
<p class="example">For example, if the user is using a keyboard to push a <code>button</code>
element by pressing the space bar, the element would match this <span>pseudo-class</span> in
between the time that the element received the <code data-x="event-keydown">keydown</code>
event and the time the element received the <code data-x="event-keyup">keyup</code> event.</p>
</dd>
<dt>If the element is <span>being actively pointed at</span></dt>
<dd><p>The element is <i data-x="concept-selector-active">being activated</i>.</p></dd>
</dl>
<p>An element is said to be <dfn>in a formal activation state</dfn> between the time the user
begins to indicate an intent to trigger the element's <span>activation behavior</span> and
either the time the user stops indicating an intent to trigger the element's <span>activation
behavior</span>, or the time the element's <span>activation behavior</span> has finished
running, which ever comes first.</p>
<p>An element is said to be <dfn>being actively pointed at</dfn> while the user indicates the
element using a pointing device while that pointing device is in the "down" state (e.g. for a
mouse, between the time the mouse button is pressed and the time it is depressed; for a finger
in a multitouch environment, while the finger is touching the display surface).</p>
<p class="note">Per the definition in <cite>Selectors</cite>, <code
data-x="selector-active">:active</code> also matches <span>flat tree</span> ancestors of
elements that are <i data-x="concept-selector-active">being activated</i>.
<ref>SELECTORS</ref></p>
<p>Additionally, any element that is the <span>labeled control</span> of a <code>label</code>
element that is currently matching <code data-x="selector-active">:active</code>, also matches
<code data-x="selector-active">:active</code>. (But, it does not count as being <i
data-x="concept-selector-active">being activated</i>.)</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-hover">:hover</code></dfn></dt>
<dd>
<p>The <code data-x="selector-hover">:hover</code> <span>pseudo-class</span> is defined to
match an element <q cite="https://drafts.csswg.org/selectors/#the-hover-pseudo">while the user
<dfn><i data-x="concept-selector-hover">designates</i></dfn> an element with a pointing
device</q>. For the purposes of defining the <code data-x="selector-hover">:hover</code>
<span>pseudo-class</span> only, an HTML user agent must consider an element as being one that
the user <i data-x="concept-selector-hover">designates</i> if it is an element that the user
indicates using a pointing device.</p>
<p class="note">Per the definition in <cite>Selectors</cite>, <code
data-x="selector-hover">:hover</code> also matches <span>flat tree</span> ancestors of elements
that are <i data-x="concept-selector-hover">designated</i>. <ref>SELECTORS</ref></p>
<p>Additionally, any element that is the <span>labeled control</span> of a <code>label</code>
element that is currently matching <code data-x="selector-hover">:hover</code>, also matches
<code data-x="selector-hover">:hover</code>. (But, it does not count as being <i
data-x="concept-selector-hover">designated</i>.)</p>
<!--
Demos:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1315
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1316
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1317
-->
<div class="example">
<p>Consider in particular a fragment such as:</p>
<pre><code class="html"><p> <label for=c> <input id=a> </label> <span id=b> <input id=c> </span> </p></code></pre>
<p>If the user designates the element with ID "<code data-x="">a</code>" with their pointing
device, then the <code>p</code> element (and all its ancestors not shown in the snippet
above), the <code>label</code> element, the element with ID "<code data-x="">a</code>", and
the element with ID "<code data-x="">c</code>" will match the <code
data-x="selector-hover">:hover</code> <span>pseudo-class</span>. The element with ID "<code
data-x="">a</code>" matches it by being <i data-x="concept-selector-hover">designated</i>; the
<code>label</code> and <code>p</code> elements match it because of the condition in
<cite>Selectors</cite> about flat tree ancestors; and the element with ID "<code
data-x="">c</code>" matches it through the additional condition above on <span data-x="labeled
control">labeled controls</span> (i.e., its <code>label</code> element matches <code
data-x="selector-hover">:hover</code>). However, the element with ID "<code
data-x="">b</code>" does <em>not</em> match <code data-x="selector-hover">:hover</code>: its
flat tree descendant is not designated, even though that flat tree descendant matches <code
data-x="selector-hover">:hover</code>.</p>
</div>
</dd>
<dt><dfn selector noexport><code data-x="selector-focus">:focus</code></dfn></dt>
<dd>
<p>For the purposes of the CSS <code data-x="selector-focus">:focus</code>
<span>pseudo-class</span>, an <dfn>element has the focus</dfn> when:</p>
<ul>
<li><p>it is not itself a <span>navigable container</span>; and</p></li>
<li>
<p>any of the following are true:</p>
<ul>
<li><p>it is one of the elements listed in the <span data-x="current focus chain of a
top-level traversable">current focus chain of the top-level traversable</span>; or</p></li>
<li><p>its <span data-x="concept-element-shadow-root">shadow root</span>
<var>shadowRoot</var> is not null and <var>shadowRoot</var> is the <span>root</span> of at
least one element that <span data-x="element has the focus">has the focus</span>.</p></li>
</ul>
</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-target">:target</code></dfn></dt>
<dd>
<p>For the purposes of the CSS <code data-x="selector-target">:target</code>
<span>pseudo-class</span>, the <code>Document</code>'s <i>target elements</i> are a list
containing the <code>Document</code>'s <span>target element</span>, if it is not null, or
containing no elements, if it is. <ref>SELECTORS</ref></p>
</dd>
<dt><dfn selector noexport><code data-x="selector-popover-open">:popover-open</code></dfn></dt>
<dd>
<p>The <code data-x="selector-popover-open">:popover-open</code> <span>pseudo-class</span> is
defined to match any <span data-x="html elements">HTML element</span> whose <code
data-x="attr-popover">popover</code> attribute is not in the <span
data-x="attr-popover-none-state">no popover state</span> and whose <span>popover visibility
state</span> is <span data-x="popover-showing-state">showing</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-enabled">:enabled</code></dfn></dt>
<dd>
<p>The <code data-x="selector-enabled">:enabled</code> <span>pseudo-class</span> must match any
<code>button</code>, <code>input</code>, <code>select</code>, <code>textarea</code>,
<code>optgroup</code>, <code>option</code>, <code>fieldset</code> element, or
<span>form-associated custom element</span> that is not <span
data-x="concept-element-disabled">actually disabled</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-disabled">:disabled</code></dfn></dt>
<dd>
<p>The <code data-x="selector-disabled">:disabled</code> <span>pseudo-class</span> must match
any element that is <span data-x="concept-element-disabled">actually disabled</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-checked">:checked</code></dfn></dt>
<dd>
<p>The <code data-x="selector-checked">:checked</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> state is true</li>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state and whose <span
data-x="concept-fe-checked">checkedness</span> state is true</li>
<li><code>option</code> elements whose <span
data-x="concept-option-selectedness">selectedness</span> is true</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-indeterminate">:indeterminate</code></dfn></dt>
<dd>
<p>The <code data-x="selector-indeterminate">:indeterminate</code> <span>pseudo-class</span>
must match any element falling into one of the following categories:</p>
<ul>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state and whose <code
data-x="dom-input-indeterminate">indeterminate</code> IDL attribute is set to true</li>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state and whose <span>radio button
group</span> contains no <code>input</code> elements whose <span
data-x="concept-fe-checked">checkedness</span> state is true.</li>
<li><code>progress</code> elements with no <code data-x="attr-progress-value">value</code>
content attribute</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-default">:default</code></dfn></dt>
<dd>
<p>The <code data-x="selector-default">:default</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li><span data-x="concept-submit-button">Submit buttons</span> that are <span data-x="default
button">default buttons</span> of their <span>form owner</span>.</li>
<li><code>input</code> elements to which the <code data-x="attr-input-checked">checked</code>
attribute applies and that have a <code data-x="attr-input-checked">checked</code>
attribute</li>
<li><code>option</code> elements that have a <code data-x="attr-option-selected">selected</code>
attribute</li>
</ul>
</dd>
<dt><dfn selector noexport><code
data-x="selector-placeholder-shown">:placeholder-shown</code></dfn></dt>
<dd>
<p>The <code data-x="selector-placeholder-shown">:placeholder-shown</code>
<span>pseudo-class</span> must match any element falling into one of the following
categories:</p>
<ul>
<li><code>input</code> elements that have a <code
data-x="attr-input-placeholder">placeholder</code> attribute whose value is currently being
presented to the user</li>
<li><code>textarea</code> elements that have a <code
data-x="attr-textarea-placeholder">placeholder</code> attribute whose value is currently being
presented to the user</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-valid">:valid</code></dfn></dt>
<dd>
<p>The <code data-x="selector-valid">:valid</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li>elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span> and that <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
<li><code>form</code> elements that are not the <span>form owner</span> of any elements that
themselves are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
<li><code>fieldset</code> elements that have no descendant elements that themselves are <span
data-x="candidate for constraint validation">candidates for constraint validation</span> but do
not <span data-x="concept-fv-valid">satisfy their constraints</span></li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-invalid">:invalid</code></dfn></dt>
<dd>
<p>The <code data-x="selector-invalid">:invalid</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li>elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span> but that do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
<li><code>form</code> elements that are the <span>form owner</span> of one or more elements
that themselves are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
<li><code>fieldset</code> elements that have of one or more descendant elements that themselves
are <span data-x="candidate for constraint validation">candidates for constraint
validation</span> but do not <span data-x="concept-fv-valid">satisfy their
constraints</span></li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-user-valid">:user-valid</code></dfn></dt>
<dd>
<p>The <code data-x="selector-user-valid">:user-valid</code> <span>pseudo-class</span> must
match <code>input</code>, <code>textarea</code>, and <code>select</code> elements whose
<span>user validity</span> is true, are
<span data-x="candidate for constraint validation">candidates for constraint validation</span>,
and that <span data-x="concept-fv-valid">satisfy their constraints</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-user-invalid">:user-invalid</code></dfn></dt>
<dd>
<p>The <code data-x="selector-user-invalid">:user-invalid</code> <span>pseudo-class</span> must
match <code>input</code>, <code>textarea</code>, and <code>select</code> elements whose
<span>user validity</span> is true, are
<span data-x="candidate for constraint validation">candidates for constraint validation</span>
but do not <span data-x="concept-fv-valid">satisfy their constraints</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-in-range">:in-range</code></dfn></dt>
<dd>
<p>The <code data-x="selector-in-range">:in-range</code> <span>pseudo-class</span> must match
all elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span>, <span>have range limitations</span>, and that are neither
<span>suffering from an underflow</span> nor <span>suffering from an overflow</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-out-of-range">:out-of-range</code></dfn></dt>
<dd>
<p>The <code data-x="selector-out-of-range">:out-of-range</code> <span>pseudo-class</span> must
match all elements that are <span data-x="candidate for constraint validation">candidates for
constraint validation</span>, <span>have range limitations</span>, and that are either
<span>suffering from an underflow</span> or <span>suffering from an overflow</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-required">:required</code></dfn></dt>
<dd>
<p>The <code data-x="selector-required">:required</code> <span>pseudo-class</span> must match
any element falling into one of the following categories:</p>
<ul>
<li><code>input</code> elements that are <i data-x="concept-input-required">required</i></li>
<li><code>select</code> elements that have a <code data-x="attr-select-required">required</code>
attribute</li>
<li><code>textarea</code> elements that have a <code
data-x="attr-textarea-required">required</code> attribute</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-optional">:optional</code></dfn></dt>
<dd>
<p>The <code data-x="selector-optional">:optional</code> <span>pseudo-class</span> must match
any element falling into one of the following categories:</p>
<ul>
<li><code>input</code> elements to which the <code data-x="attr-input-required">required</code>
attribute applies that are not <i data-x="concept-input-required">required</i></li>
<li><code>select</code> elements that do not have a <code
data-x="attr-select-required">required</code> attribute</li>
<li><code>textarea</code> elements that do not have a <code
data-x="attr-textarea-required">required</code> attribute</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-autofill">:autofill</code></dfn></dt>
<dt><dfn selector noexport><code
data-x="selector-webkit-autofill">:-webkit-autofill</code></dfn></dt>
<dd>
<p>The <code data-x="selector-autofill">:autofill</code> and <code
data-x="selector-webkit-autofill">:-webkit-autofill</code> <span
data-x="pseudo-class">pseudo-classes</span> must match <code>input</code> elements which have
been autofilled by user agent. These pseudo-classes must stop matching if the user edits the
autofilled field.</p>
<p class="note">One way such autofilling might happen is via the <code
data-x="attr-fe-autocomplete">autocomplete</code> attribute, but user agents could autofill even
without that attribute being involved.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-read-only">:read-only</code></dfn></dt>
<dt><dfn selector noexport><code data-x="selector-read-write">:read-write</code></dfn></dt>
<dd>
<p>The <code data-x="selector-read-write">:read-write</code> <span>pseudo-class</span> must
match any element falling into one of the following categories, which for the purposes of
Selectors are thus considered <i>user-alterable</i>: <ref>SELECTORS</ref></p>
<ul>
<li><code>input</code> elements to which the <code data-x="attr-input-readonly">readonly</code>
attribute applies, and that are <i data-x="concept-fe-mutable">mutable</i> (i.e. that do not
have the <code data-x="attr-input-readonly">readonly</code> attribute specified and that are not
<span data-x="concept-fe-disabled">disabled</span>)</li>
<li><code>textarea</code> elements that do not have a <code
data-x="attr-textarea-readonly">readonly</code> attribute, and that are not <span
data-x="concept-fe-disabled">disabled</span></li>
<li>elements that are <span data-x="editing host">editing hosts</span> or <span>editable</span>
and are neither <code>input</code> elements nor <code>textarea</code> elements</li>
</ul>
<p>The <code data-x="selector-read-only">:read-only</code> <span>pseudo-class</span> must match
all other <span>HTML elements</span>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-modal">:modal</code></dfn></dt>
<dd>
<p>The <code data-x="selector-modal">:modal</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li><code>dialog</code> elements whose <span>is modal</span> is true</li>
<li>elements whose <span>fullscreen flag</span> is true</li>
</ul>
</dd>
<dt><dfn selector noexport><code data-x="selector-ltr">:dir(ltr)</code></dfn></dt>
<dd>
<p>The <code data-x="selector-ltr">:dir(ltr)</code> <span>pseudo-class</span> must match all
elements whose <span data-x="the directionality">directionality</span> is '<span
data-x="concept-ltr">ltr</span>'.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-rtl">:dir(rtl)</code></dfn></dt>
<dd>
<p>The <code data-x="selector-rtl">:dir(rtl)</code> <span>pseudo-class</span> must match all
elements whose <span data-x="the directionality">directionality</span> is '<span
data-x="concept-rtl">rtl</span>'.</p>
</dd>
<dt><dfn selector noexport data-x="selector-custom">Custom state pseudo-class</dfn></dt>
<dd>
<p>The <code data-x="selector-custom">:state(<var>identifier</var>)</code> pseudo-class must
match all <span>custom element</span>s whose <span>states set</span>'s <span>set entries</span>
contains <var>identifier</var>.</p>
</dd>
<dt><dfn selector noexport><code data-x="selector-playing">:playing</code></dfn></dt>
<dd>
<p>The <code data-x="selector-playing">:playing</code> <span>pseudo-class</span> must match all
<span data-x="media element">media elements</span> whose <code
data-x="dom-media-paused">paused</code> attribute is false.</p>
<!-- This should really use a non-public API. -->
</dd>
<dt><dfn selector noexport><code data-x="selector-paused">:paused</code></dfn></dt>
<dd>
<p>The <code data-x="selector-paused">:paused</code> <span>pseudo-class</span> must match all
<span data-x="media element">media elements</span> whose <code
data-x="dom-media-paused">paused</code> attribute is true.</p>
<!-- This should really use a non-public API. -->
</dd>
<dt><dfn selector noexport><code data-x="selector-seeking">:seeking</code></dfn></dt>
<dd>
<p>The <code data-x="selector-seeking">:seeking</code> <span>pseudo-class</span> must match all
<span data-x="media element">media elements</span> whose <code
data-x="dom-media-seeking">seeking</code> attribute is true.</p>
<!-- This should really use a non-public API. -->
</dd>
<dt><dfn selector noexport><code data-x="selector-buffering">:buffering</code></dfn></dt>
<dd>
<p>The <code data-x="selector-buffering">:buffering</code> <span>pseudo-class</span> must match
all <span data-x="media element">media elements</span> whose <code
data-x="dom-media-paused">paused</code> attribute is false, <code
data-x="dom-media-networkState">networkState</code> attribute is <code
data-x="dom-media-NETWORK_LOADING">NETWORK_LOADING</code>, and ready state is <code
data-x="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</code> or less.</p>
<!-- This should really use a non-public API. -->
</dd>
<dt><dfn selector noexport><code data-x="selector-stalled">:stalled</code></dfn></dt>
<dd><p>The <code data-x="selector-stalled">:stalled</code> <span>pseudo-class</span> must match
all <span data-x="media element">media elements</span> that match the <code
data-x="selector-buffering">:buffering</code> <span>pseudo-class</span> and whose <span>is
currently stalled</span> is true.</p></dd>
<dt><dfn selector noexport><code data-x="selector-muted">:muted</code></dfn></dt>
<dd><p>The <code data-x="selector-muted">:muted</code> <span>pseudo-class</span> must match all
<span data-x="media element">media elements</span> that are <span
data-x="concept-media-muted">muted</span>.</p></dd>
<dt><dfn selector noexport><code data-x="selector-volume-locked">:volume-locked</code></dfn></dt>
<dd><p>The <code data-x="selector-volume-locked">:volume-locked</code> <span>pseudo-class</span>
must match all <span data-x="media element">media elements</span> when the user agent's
<span>volume locked</span> is true.</p></dd>
<dt><dfn selector><code data-x="selector-open">:open</code></dfn></dt>
<dd>
<p>The <code data-x="selector-open">:open</code> <span>pseudo-class</span> must match any
element falling into one of the following categories:</p>
<ul>
<li><p><code>details</code> elements that have an <code data-x="attr-details-open">open</code>
attribute</p></li>
<li><p><code>dialog</code> elements that have an <code data-x="attr-dialog-open">open</code>
attribute</p></li>
<li><p><code>select</code> elements that are a <span>drop-down box</span> and whose drop-down
boxes are open</p></li>
<li><p><code>input</code> elements that <span data-x="input-support-picker">support a
picker</span> and whose pickers are open</p></li>
</ul>
</dd>
</dl>
<p class="note">This specification does not define when an element matches the <code undefined
data-x="selector-lang()">:lang()</code> dynamic <span>pseudo-class</span>, as it is defined in
sufficient detail in a language-agnostic fashion in <cite>Selectors</cite>.
<ref>SELECTORS</ref></p>
</div>
<h2 split-filename="microdata" id="microdata"><dfn>Microdata</dfn></h2>
<!-- USE CASES
Getting data out of poorly written web pages
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019595.html
Allowing authors to keep track of where content originates
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019620.html
Helping people searching for content filtered by license
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019668.html
Allowing authors to annotate their documents to explain things for readers
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019672.html
Annotating structured data that HTML has no semantics for
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019681.html
Exposing known data types in a reusable way
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019833.html
Providing enhanced search results
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019834.html
Dragging or copying data between sites
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019835.html
Writing authoring tools and validators for custom microdata vocabularies
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019839.html
Removing the need for separate feeds
https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2009-May/019884.html
Use cases for which I haven't been able to find solutions
http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019886.html
-->
<!-- v2
* <itemref itemprop="foo" src="url#id"> to import the item with id="id" from url into the current
microdata block as the value of property foo?
* splitting the 'content' part of a property into multiple sub-bits, as in:
<span itemprop="tel" item-content-in-bits>
Telephone:
<span content-bit>+44</span> (0) <span content-bit>1223 123 123</span>
</span>
maybe vocabs that need this can use a sub vocabulary specifically for this:
<span itemprop="tel" itemscope itemtype="https://bits.example/">
Telephone:
<span itemprop=bit>+44</span> (0) <span itemprop=bit>1223 123 123</span>
</span>
-->
<h3>Introduction</h3>
<h4>Overview</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to
allow generic scripts to provide services that are customized to the page, or to enable content
from a variety of cooperating authors to be processed by a single script in a consistent
manner.</p>
<p>For this purpose, authors can use the microdata features described in this section. Microdata
allows nested groups of name-value pairs to be added to documents, in parallel with the existing
content.</p>
<h4>The basic syntax</h4>
<!-- NON-NORMATIVE SECTION -->
<p>At a high level, microdata consists of a group of name-value pairs. The groups are called <span
data-x="concept-item">items</span>, and each name-value pair is a property. Items and properties
are represented by regular elements.</p>
<p>To create an item, the <code data-x="attr-itemscope">itemscope</code> attribute is used.</p>
<p>To add a property to an item, the <code data-x="attr-itemprop">itemprop</code> attribute is used
on one of the <span data-x="concept-item">item's</span> descendants.</p>
<div class="example">
<p>Here there are two items, each of which has the property "name":</p>
<pre><code class="html"><div itemscope>
<p>My name is <span itemprop="name">Elizabeth</span>.</p>
</div>
<div itemscope>
<p>My name is <span itemprop="name">Daniel</span>.</p>
</div></code></pre>
</div>
<p>Markup without the microdata-related attributes does not have any effect on the microdata
model.</p>
<div class="example">
<p>These two examples are exactly equivalent, at a microdata level, as the previous two examples
respectively:</p>
<pre><code class="html"><div itemscope>
<p>My <em>name</em> is <span itemprop="name">E<strong>liz</strong>abeth</span>.</p>
</div>
<section>
<div itemscope>
<aside>
<p>My name is <span itemprop="name"><a href="/?user=daniel">Daniel</a></span>.</p>
</aside>
</div>
</section></code></pre>
</div>
<p>Properties generally have values that are strings.</p>
<div class="example">
<p>Here the item has three properties:</p>
<pre><code class="html"><div itemscope>
<p>My name is <span itemprop="name">Neil</span>.</p>
<p>My band is called <span itemprop="band">Four Parts Water</span>.</p>
<p>I am <span itemprop="nationality">British</span>.</p>
</div></code></pre>
</div>
<p>When a string value is a <span>URL</span>, it is expressed using the <code>a</code> element and
its <code data-x="attr-hyperlink-href">href</code> attribute, the <code>img</code> element and its
<code data-x="attr-img-src">src</code> attribute, or other elements that link to or embed external
resources.</p>
<div class="example">
<p>In this example, the item has one property, "image", whose value is a URL:</p>
<pre><code class="html"><div itemscope>
<img itemprop="image" src="google-logo.png" alt="Google">
</div></code></pre>
</div>
<p>When a string value is in some machine-readable format unsuitable for human consumption, it is
expressed using the <code data-x="attr-data-value">value</code> attribute of the <code>data</code>
element, with the human-readable version given in the element's contents.</p>
<div class="example">
<p>Here, there is an item with a property whose value is a product ID. The ID is not
human-friendly, so the product's name is used the human-visible text instead of the ID.</p>
<pre><code class="html"><h1 itemscope>
<data itemprop="product-id" value="9678AOU879">The Instigator 2000</data>
</h1></code></pre>
</div>
<p>For numeric data, the <code>meter</code> element and its <code
data-x="attr-meter-value">value</code> attribute can be used instead.</p>
<div class="example">
<p>Here a rating is given using a <code>meter</code> element.</p>
<pre><code class="html"><div itemscope itemtype="http://schema.org/Product">
<span itemprop="name">Panasonic White 60L Refrigerator</span>
<img src="panasonic-fridge-60l-white.jpg" alt="">
<div itemprop="aggregateRating"
itemscope itemtype="http://schema.org/AggregateRating">
<meter itemprop="ratingValue" min=0 value=3.5 max=5>Rated 3.5/5</meter>
(based on <span itemprop="reviewCount">11</span> customer reviews)
</div>
</div></code></pre>
</div>
<p>Similarly, for date- and time-related data, the <code>time</code> element and its <code
data-x="attr-time-datetime">datetime</code> attribute can be used instead.</p>
<div class="example">
<p>In this example, the item has one property, "birthday", whose value is a date:</p>
<pre><code class="html"><div itemscope>
I was born on <time itemprop="birthday" datetime="2009-05-10">May 10th 2009</time>.
</div></code></pre>
</div>
<p>Properties can also themselves be groups of name-value pairs, by putting the <code
data-x="attr-itemscope">itemscope</code> attribute on the element that declares the property.</p>
<p>Items that are not part of others are called <span>top-level microdata items</span>.</p>
<div class="example">
<p>In this example, the outer item represents a person, and the inner one represents a band:</p>
<pre><code class="html"><div itemscope>
<p>Name: <span itemprop="name">Amanda</span></p>
<p>Band: <span itemprop="band" itemscope> <span itemprop="name">Jazz Band</span> (<span itemprop="size">12</span> players)</span></p>
</div></code></pre>
<p>The outer item here has two properties, "name" and "band". The "name" is "Amanda", and the
"band" is an item in its own right, with two properties, "name" and "size". The "name" of the
band is "Jazz Band", and the "size" is "12".</p>
<p>The outer item in this example is a top-level microdata item.</p>
</div>
<p>Properties that are not descendants of the element with the <code
data-x="attr-itemscope">itemscope</code> attribute can be associated with the <span
data-x="concept-item">item</span> using the <code data-x="attr-itemref">itemref</code> attribute.
This attribute takes a list of IDs of elements to crawl in addition to crawling the children of
the element with the <code data-x="attr-itemscope">itemscope</code> attribute.</p>
<div class="example">
<p>This example is the same as the previous one, but all the properties are separated from their
<span data-x="concept-item">items</span>:</p>
<pre><code class="html"><div itemscope id="amanda" itemref="a b"></div>
<p id="a">Name: <span itemprop="name">Amanda</span></p>
<div id="b" itemprop="band" itemscope itemref="c"></div>
<div id="c">
<p>Band: <span itemprop="name">Jazz Band</span></p>
<p>Size: <span itemprop="size">12</span> players</p>
</div></code></pre>
<p>This gives the same result as the previous example. The first item has two properties, "name",
set to "Amanda", and "band", set to another item. That second item has two further properties,
"name", set to "Jazz Band", and "size", set to "12".</p>
</div>
<p>An <span data-x="concept-item">item</span> can have multiple properties with the same name and
different values.</p>
<div class="example">
<p>This example describes an ice cream, with two flavors:</p>
<pre><code class="html"><div itemscope>
<p>Flavors in my favorite ice cream:</p>
<ul>
<li itemprop="flavor">Lemon sorbet</li>
<li itemprop="flavor">Apricot sorbet</li>
</ul>
</div></code></pre>
<p>This thus results in an item with two properties, both "flavor", having the values "Lemon
sorbet" and "Apricot sorbet".</p>
</div>
<p>An element introducing a property can also introduce multiple properties at once, to avoid
duplication when some of the properties have the same value.</p>
<div class="example">
<p>Here we see an item with two properties, "favorite-color" and "favorite-fruit", both set to
the value "orange":</p>
<pre><code class="html"><div itemscope>
<span itemprop="favorite-color favorite-fruit">orange</span>
</div></code></pre>
</div>
<p>It's important to note that there is no relationship between the microdata and the content of
the document where the microdata is marked up.</p>
<div class="example">
<p>There is no semantic difference, for instance, between the following two examples:</p>
<pre><code class="html"><figure>
<img src="castle.jpeg">
<figcaption><span itemscope><span itemprop="name">The Castle</span></span> (1986)</figcaption>
</figure></code></pre>
<pre><code class="html"><span itemscope><meta itemprop="name" content="The Castle"></span>
<figure>
<img src="castle.jpeg">
<figcaption>The Castle (1986)</figcaption>
</figure></code></pre>
<p>Both have a figure with a caption, and both, completely unrelated to the figure, have an item
with a name-value pair with the name "name" and the value "The Castle". The only difference is
that if the user drags the caption out of the document, in the former case, the item will be
included in the drag-and-drop data. In neither case is the image in any way associated with the
item.</p>
</div>
<h4>Typed items</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The examples in the previous section show how information could be marked up on a page that
doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in
contexts where other authors and readers are able to cooperate to make new uses of the markup.</p>
<p>For this purpose, it is necessary to give each <span data-x="concept-item">item</span> a type,
such as "https://example.com/person", or "https://example.org/cat", or
"https://band.example.net/". Types are identified as <span data-x="URL">URLs</span>.</p>
<p>The type for an <span data-x="concept-item">item</span> is given as the value of an <code
data-x="attr-itemtype">itemtype</code> attribute on the same element as the <code
data-x="attr-itemscope">itemscope</code> attribute.</p>
<div class="example">
<p>Here, the item's type is "https://example.org/animals#cat":</p>
<pre><code class="html"><section itemscope itemtype="https://example.org/animals#cat">
<h1 itemprop="name">Hedral</h1>
<p itemprop="desc">Hedral is a male american domestic
shorthair, with a fluffy black fur with white paws and belly.</p>
<img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section></code></pre>
<p>In this example the "https://example.org/animals#cat" item has three properties, a "name"
("Hedral"), a "desc" ("Hedral is..."), and an "img" ("hedral.jpeg").</p>
</div>
<p>The type gives the context for the properties, thus selecting a vocabulary: a property named
"class" given for an item with the type "https://census.example/person" might refer to the economic
class of an individual, while a property named "class" given for an item with the type
"https://example.com/school/teacher" might refer to the classroom a teacher has been assigned.
Several types can share a vocabulary. For example, the types "<code
data-x="">https://example.org/people/teacher</code>" and "<code
data-x="">https://example.org/people/engineer</code>" could be defined to use the same vocabulary
(though maybe some properties would not be especially useful in both cases, e.g. maybe the "<code
data-x="">https://example.org/people/engineer</code>" type might not typically be used with the
"<code data-x="">classroom</code>" property). Multiple types defined to use the same vocabulary can
be given for a single item by listing the URLs as a space-separated list in the attribute' value.
An item cannot be given two types if they do not use the same vocabulary, however.</p>
<h4>Global identifiers for items</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Sometimes, an <span data-x="concept-item">item</span> gives information about a topic that has a
global identifier. For example, books can be identified by their ISBN number.</p>
<p>Vocabularies (as identified by the <code data-x="attr-itemtype">itemtype</code> attribute) can
be designed such that <span data-x="concept-item">items</span> get associated with their global
identifier in an unambiguous way by expressing the global identifiers as <span
data-x="URL">URLs</span> given in an <code data-x="attr-itemid">itemid</code> attribute.</p>
<p>The exact meaning of the <span data-x="URL">URLs</span> given in <code
data-x="attr-itemid">itemid</code> attributes depends on the vocabulary used.</p>
<div class="example">
<p>Here, an item is talking about a particular book:</p>
<pre><code class="html"><dl itemscope
itemtype="https://vocab.example.net/book"
<strong>itemid="urn:isbn:0-330-34032-8"</strong>>
<dt>Title
<dd itemprop="title">The Reality Dysfunction
<dt>Author
<dd itemprop="author">Peter F. Hamilton
<dt>Publication date
<dd><time itemprop="pubdate" datetime="1996-01-26">26 January 1996</time>
</dl></code></pre>
<p>The "<code data-x="">https://vocab.example.net/book</code>" vocabulary in this example would
define that the <code data-x="attr-itemid">itemid</code> attribute takes a <code data-x="urn
protocol">urn:</code> <span>URL</span> pointing to the ISBN of the book.</p>
</div>
<!-- (commented out since itemtype="" defines the meaning of the
identifier for now)
<p>Although it is common practice, authors are encouraged not to use the same URL to identify
multiple topics; in particular, an HTTP URL usually identifies a specific resource (such as an
image or document), and authors are encouraged to not use them to identify people, non-Web
resources like companies, movies, and products, or other abstract concepts. Using an HTTP URL as a
global identifier for something other than the resource actually designated by the URL leads to a
situation where it is ambiguous whether the identifier, and thus the set of properties specified
in the microdata, references the page or something else.</p>
-->
<h4>Selecting names when defining vocabularies</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Using microdata means using a vocabulary. For some purposes, an ad-hoc vocabulary is adequate.
For others, a vocabulary will need to be designed. Where possible, authors are encouraged to
re-use existing vocabularies, as this makes content re-use easier.</p>
<p>When designing new vocabularies, identifiers can be created either using <span
data-x="URL">URLs</span>, or, for properties, as plain words (with no dots or colons). For URLs,
conflicts with other vocabularies can be avoided by only using identifiers that correspond to
pages that the author has control over.</p>
<div class="example">
<p>For instance, if Jon and Adam both write content at <code
data-x="">example.com</code>, at <code
data-x="">https://example.com/~jon/...</code> and <code
data-x="">https://example.com/~adam/...</code> respectively, then
they could select identifiers of the form
"https://example.com/~jon/name" and "https://example.com/~adam/name"
respectively.</p>
</div>
<p>Properties whose names are just plain words can only be used within the context of the types
for which they are intended; properties named using URLs can be reused in items of any type. If an
item has no type, and is not part of another item, then if its properties have names that are just
plain words, they are not intended to be globally unique, and are instead only intended for
limited use. Generally speaking, authors are encouraged to use either properties with globally
unique names (URLs) or ensure that their items are typed.</p>
<div class="example">
<p>Here, an item is an "https://example.org/animals#cat", and most of the properties have names
that are words defined in the context of that type. There are also a few additional properties
whose names come from other vocabularies.</p>
<pre><code class="html"><section itemscope itemtype="https://example.org/animals#cat">
<h1 itemprop="name https://example.com/fn">Hedral</h1>
<p itemprop="desc">Hedral is a male American domestic
shorthair, with a fluffy <span
itemprop="https://example.com/color">black</span> fur with <span
itemprop="https://example.com/color">white</span> paws and belly.</p>
<img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section></code></pre>
<p>This example has one item with the type "https://example.org/animals#cat" and the following
properties:</p>
<table>
<thead>
<tr>
<td>Property
<td>Value
<tbody>
<tr>
<td>name
<td>Hedral
<tr>
<td>https://example.com/fn
<td>Hedral
<tr>
<td>desc
<td>Hedral is a male American domestic shorthair, with a fluffy black fur with white paws and belly.
<tr>
<td>https://example.com/color
<td>black
<tr>
<td>https://example.com/color
<td>white
<tr>
<td>img
<td>.../hedral.jpeg
</table>
</div>
<h3>Encoding microdata</h3>
<h4>The microdata model</h4>
<p>The microdata model consists of groups of name-value pairs known as <span
data-x="concept-item">items</span>.</p>
<p>Each group is known as an <span data-x="concept-item">item</span>. Each <span
data-x="concept-item">item</span> can have <span>item types</span>, a <span>global
identifier</span> (if the vocabulary specified by the <span>item types</span> <span>support global
identifiers for items</span>), and a list of name-value pairs. Each name in the name-value pair is
known as a <span data-x="the properties of an item">property</span>, and each <span data-x="the
properties of an item">property</span> has one or more <span
data-x="concept-property-value">values</span>. Each <span
data-x="concept-property-value">value</span> is either a string or itself a group of name-value
pairs (an <span data-x="concept-item">item</span>). The names are unordered relative to each other,
but if a particular name has multiple values, they do have a relative order.</p>
<h4>Items</h4>
<p>Every <span data-x="HTML elements">HTML element</span> may have an <dfn element-attr
for="html-global"><code data-x="attr-itemscope">itemscope</code></dfn> attribute specified. The
<code data-x="attr-itemscope">itemscope</code> attribute is a <span>boolean attribute</span>.</p>
<p>An element with the <code data-x="attr-itemscope">itemscope</code> attribute specified creates a
new <dfn data-x="concept-item">item</dfn>, a group of name-value pairs.</p>
<hr>
<p>Elements with an <code data-x="attr-itemscope">itemscope</code> attribute may have an <dfn
element-attr for="html-global"><code data-x="attr-itemtype">itemtype</code></dfn> attribute
specified, to give the <span>item types</span> of the <span data-x="concept-item">item</span>.</p>
<p>The <code data-x="attr-itemtype">itemtype</code> attribute, if specified, must have a value that
is an <span>unordered set of unique space-separated tokens</span>, none of which are
<span>identical to</span> another token and each of which is a <span>valid URL string</span> that
is an <span>absolute URL</span>, and all of which are defined to use the same vocabulary. The
attribute's value must have at least one token.</p>
<p>The <dfn>item types</dfn> of an <span data-x="concept-item">item</span> are the tokens obtained
by <span data-x="split a string on ASCII whitespace">splitting the element's <code
data-x="attr-itemtype">itemtype</code> attribute's value on ASCII whitespace</span>. If the <code
data-x="attr-itemtype">itemtype</code> attribute is missing or parsing it in this way finds no
tokens, the <span data-x="concept-item">item</span> is said to have no <span>item types</span>.</p>
<p>The <span>item types</span> must all be types defined in <span data-x="other applicable
specifications">applicable specifications</span> and must all be defined to use the same
vocabulary.</p>
<div w-nodev>
<p>Except if otherwise specified by that specification, the <span data-x="URL">URLs</span> given
as the <span>item types</span> should not be automatically dereferenced.</p>
<p class="note">A specification could define that its <span data-x="item types">item type</span>
can be dereferenced to provide the user with help information, for example. In fact, vocabulary
authors are encouraged to provide useful information at the given <span>URL</span>.</p>
<p><span>Item types</span> are opaque identifiers, and user agents must not dereference unknown
<span>item types</span>, or otherwise deconstruct them, in order to determine how to process
<span data-x="concept-item">items</span> that use them.</p>
</div>
<p>The <code data-x="attr-itemtype">itemtype</code> attribute must not be specified on elements
that do not have an <code data-x="attr-itemscope">itemscope</code> attribute specified.</p>
<hr>
<p>An <span data-x="concept-item">item</span> is said to be a <dfn>typed item</dfn> when either it
has an <span data-x="item types">item type</span>, or it is the <span
data-x="concept-property-value">value</span> of a <span data-x="the properties of an
item">property</span> of a <span>typed item</span>. The <dfn>relevant types</dfn> for a
<span>typed item</span> is the <span data-x="concept-item">item</span>'s <span>item types</span>,
if it has any, or else is the <span>relevant types</span> of the <span
data-x="concept-item">item</span> for which it is a <span data-x="the properties of an
item">property</span>'s <span data-x="concept-property-value">value</span>.</p>
<hr>
<p>Elements with an <code data-x="attr-itemscope">itemscope</code> attribute and an <code
data-x="attr-itemtype">itemtype</code> attribute that references a vocabulary that is defined to
<dfn>support global identifiers for items</dfn> may also have an <dfn element-attr
for="html-global"><code data-x="attr-itemid">itemid</code></dfn> attribute specified, to give a
global identifier for the <span data-x="concept-item">item</span>, so that it can be related to
other <span data-x="concept-item">items</span> on pages elsewhere on the web.</p>
<p>The <code data-x="attr-itemid">itemid</code> attribute, if specified, must have a value that is
a <span>valid URL potentially surrounded by spaces</span>.</p>
<p>The <dfn>global identifier</dfn> of an <span data-x="concept-item">item</span> is the value of
its element's <code data-x="attr-itemid">itemid</code> attribute, if it has one, <span
data-x="encoding-parsing a URL">parsed</span> relative to the <span>node document</span> of the
element on which the attribute is specified. If the <code data-x="attr-itemid">itemid</code>
attribute is missing or if parsing it returns failure, it is said to have no <span>global
identifier</span>.</p>
<p>The <code data-x="attr-itemid">itemid</code> attribute must not be specified on elements that do
not have both an <code data-x="attr-itemscope">itemscope</code> attribute and an <code
data-x="attr-itemtype">itemtype</code> attribute specified, and must not be specified on elements
with an <code data-x="attr-itemscope">itemscope</code> attribute whose <code
data-x="attr-itemtype">itemtype</code> attribute specifies a vocabulary that does not <span>support
global identifiers for items</span>, as defined by that vocabulary's specification.</p>
<p>The exact meaning of a <span>global identifier</span> is determined by the vocabulary's
specification. It is up to such specifications to define whether multiple items with the same
global identifier (whether on the same page or on different pages) are allowed to exist, and what
the processing rules for that vocabulary are with respect to handling the case of multiple items
with the same ID.</p>
<hr>
<p>Elements with an <code data-x="attr-itemscope">itemscope</code> attribute may have an <dfn
element-attr for="html-global"><code data-x="attr-itemref">itemref</code></dfn> attribute
specified, to give a list of additional elements to crawl to find the name-value pairs of the
<span data-x="concept-item">item</span>.</p>
<p>The <code data-x="attr-itemref">itemref</code> attribute, if specified, must have a value that
is an <span>unordered set of unique space-separated tokens</span> none of which are
<span>identical to</span> another token and consisting of <span data-x="concept-ID">IDs</span> of
elements in the same <span>tree</span>.</p>
<p>The <code data-x="attr-itemref">itemref</code> attribute must not be specified on elements that
do not have an <code data-x="attr-itemscope">itemscope</code> attribute specified.</p>
<p class="note">The <code data-x="attr-itemref">itemref</code> attribute is not part of the
microdata data model. It is merely a syntactic construct to aid authors in adding annotations to
pages where the data to be annotated does not follow a convenient tree structure. For example, it
allows authors to mark up data in a table so that each column defines a separate <span
data-x="concept-item">item</span>, while keeping the properties in the cells.</p>
<div class="example">
<p>This example shows a simple vocabulary used to describe the products of a model railway
manufacturer. The vocabulary has just five property names:</p>
<dl>
<dt>product-code</dt>
<dd>An integer that names the product in the manufacturer's catalog.</dd>
<dt>name</dt>
<dd>A brief description of the product.</dd>
<dt>scale</dt>
<dd>One of "HO", "1", or "Z" (potentially with leading or trailing
whitespace), indicating the scale of the product.</dd>
<dt>digital</dt>
<dd>If present, one of "Digital", "Delta", or "Systems"
(potentially with leading or trailing whitespace) indicating that
the product has a digital decoder of the given type.</dd>
<dt>track-type</dt>
<dd>For track-specific products, one of "K", "M", "C" (potentially
with leading or trailing whitespace) indicating the type of track
for which the product is intended.</dd>
</dl>
<p>This vocabulary has four defined <span>item types</span>:</p>
<dl>
<dt>https://md.example.com/loco</dt>
<dd>Rolling stock with an engine</dd>
<dt>https://md.example.com/passengers</dt>
<dd>Passenger rolling stock</dd>
<dt>https://md.example.com/track</dt>
<dd>Track pieces</dd>
<dt>https://md.example.com/lighting</dt>
<dd>Equipment with lighting</dd>
</dl>
<p>Each <span data-x="concept-item">item</span> that uses this vocabulary can be given one or more
of these types, depending on what the product is.</p>
<p>Thus, a locomotive might be marked up as:</p>
<pre><code class="html"><dl itemscope itemtype="https://md.example.com/loco
https://md.example.com/lighting">
<dt>Name:
<dd itemprop="name">Tank Locomotive (DB 80)
<dt>Product code:
<dd itemprop="product-code">33041
<dt>Scale:
<dd itemprop="scale">HO
<dt>Digital:
<dd itemprop="digital">Delta
</dl></code></pre>
<p>A turnout lantern retrofit kit might be marked up as:</p>
<pre><code class="html"><dl itemscope itemtype="https://md.example.com/track
https://md.example.com/lighting">
<dt>Name:
<dd itemprop="name">Turnout Lantern Kit
<dt>Product code:
<dd itemprop="product-code">74470
<dt>Purpose:
<dd>For retrofitting 2 <span itemprop="track-type">C</span> Track
turnouts. <meta itemprop="scale" content="HO">
</dl></code></pre>
<p>A passenger car with no lighting might be marked up as:</p>
<pre><code class="html"><dl itemscope itemtype="https://md.example.com/passengers">
<dt>Name:
<dd itemprop="name">Express Train Passenger Car (DB Am 203)
<dt>Product code:
<dd itemprop="product-code">8710
<dt>Scale:
<dd itemprop="scale">Z
</dl></code></pre>
<p>Great care is necessary when creating new vocabularies. Often, a hierarchical approach to
types can be taken that results in a vocabulary where each item only ever has a single type,
which is generally much simpler to manage.</p>
</div>
<h4>Names: the <dfn element-attr for="html-global"><code
data-x="attr-itemprop">itemprop</code></dfn> attribute</h4>
<p>Every <span data-x="HTML elements">HTML element</span> may have an <code
data-x="attr-itemprop">itemprop</code> attribute specified, if doing so <span data-x="the properties
of an item">adds one or more properties</span> to one or more <span
data-x="concept-item">items</span> (as defined below).</p>
<p>The <code data-x="attr-itemprop">itemprop</code> attribute, if specified, must have a value
that is an <span>unordered set of unique space-separated tokens</span> none of which are
<span>identical to</span> another token, representing the names of the name-value pairs that it
adds. The attribute's value must have at least one token.</p>
<p>Each token must be either:</p>
<ul>
<li>If the item is a <span>typed item</span>: a <dfn>defined property name</dfn> allowed in this
situation according to the specification that defines the <span>relevant types</span> for the
item, or</li>
<li>A <span>valid URL string</span> that is an <span>absolute URL</span> defined as an item
property name allowed in this situation by a vocabulary specification, or</li>
<li>A <span>valid URL string</span> that is an <span>absolute URL</span>, used as a proprietary
item property name (i.e. one used by the author for private purposes, not defined in a public
specification), or</li>
<li>If the item is not a <span>typed item</span>: a string that contains no U+002E FULL STOP
characters (.) and no U+003A COLON characters (:), used as a proprietary item property name (i.e.
one used by the author for private purposes, not defined in a public specification).</li>
</ul>
<p>Specifications that introduce <span data-x="defined property name">defined property names</span>
must ensure all such property names contain no U+002E FULL STOP characters (.), no U+003A COLON
characters (:), and no <span>ASCII whitespace</span>.</p>
<p class="note">The rules above disallow U+003A COLON characters (:) in non-URL values because
otherwise they could not be distinguished from URLs. Values with U+002E FULL STOP characters (.)
are reserved for future extensions. <span>ASCII whitespace</span> are disallowed because otherwise
the values would be parsed as multiple tokens.</p>
<p>When an element with an <code data-x="attr-itemprop">itemprop</code> attribute <span data-x="the
properties of an item">adds a property</span> to multiple <span data-x="concept-item">items</span>,
the requirement above regarding the tokens applies for each <span data-x="concept-item">item</span>
individually.</p>
<!--
e.g.:
<div itemscope itemtype="https://example.com/a"> <ref refid="x"> </div>
<div itemscope itemtype="https://example.com/b"> <ref refid="x"> </div>
<meta id="x" itemprop="z" content="">
"z" had better be valid for both https://example.com/a and https://example.com/b
-->
<p>The <dfn>property names</dfn> of an element are the tokens that the element's <code
data-x="attr-itemprop">itemprop</code> attribute is found to contain when its value is <span
data-x="split a string on ASCII whitespace">split on ASCII whitespace</span>, with the order
preserved but with duplicates removed (leaving only the first occurrence of each name).</p>
<p>Within an <span data-x="concept-item">item</span>, the properties are unordered with respect to
each other, except for properties with the same name, which are ordered in the order they are
given by the algorithm that defines <span>the properties of an item</span>.</p>
<div class="example">
<p>In the following example, the "a" property has the values "1" and "2", <em>in that order</em>,
but whether the "a" property comes before the "b" property or not is not important:</p>
<pre><code class="html"><div itemscope>
<p itemprop="a">1</p>
<p itemprop="a">2</p>
<p itemprop="b">test</p>
</div></code></pre>
<p>Thus, the following is equivalent:</p>
<pre><code class="html"><div itemscope>
<p itemprop="b">test</p>
<p itemprop="a">1</p>
<p itemprop="a">2</p>
</div></code></pre>
<p>As is the following:</p>
<pre><code class="html"><div itemscope>
<p itemprop="a">1</p>
<p itemprop="b">test</p>
<p itemprop="a">2</p>
</div></code></pre>
<p>And the following:</p>
<pre><code class="html"><div id="x">
<p itemprop="a">1</p>
</div>
<div itemscope itemref="x">
<p itemprop="b">test</p>
<p itemprop="a">2</p>
</div></code></pre>
</div>
<h4>Values</h4>
<p>The <dfn data-x="concept-property-value">property value</dfn> of a name-value pair added by an
element with an <code data-x="attr-itemprop">itemprop</code> attribute is as given for the first
matching case in the following list:</p>
<dl class="switch">
<dt>If the element also has an <code data-x="attr-itemscope">itemscope</code> attribute</dt>
<dd>
<p>The value is the <span data-x="concept-item">item</span> created by the element.</p>
</dd>
<dt>If the element is a <code>meta</code> element</dt>
<dd>
<p>The value is the value of the element's <code data-x="attr-meta-content">content</code>
attribute, if any, or the empty string if there is no such attribute.</p>
</dd>
<dt>If the element is an <code>audio</code>, <code>embed</code>, <code>iframe</code>,
<code>img</code>, <code>source</code>, <code>track</code>, or <code>video</code> element</dt>
<dd>
<p>The value is the result of <span>encoding-parsing-and-serializing a URL</span> given the
element's <code data-x="">src</code> attribute's value, relative to the element's <span>node
document</span>, at the time the attribute is set, or the empty string if there is no such
attribute or the result is failure.</p>
</dd>
<dt>If the element is an <code>a</code>, <code>area</code>, or <code>link</code> element</dt>
<dd>
<p>The value is the result of <span>encoding-parsing-and-serializing a URL</span> given the
element's <code data-x="">href</code> attribute's value, relative to the element's <span>node
document</span>, at the time the attribute is set, or the empty string if there is no such
attribute or the result is failure.</p>
</dd>
<dt>If the element is an <code>object</code> element</dt>
<dd>
<p>The value is the result of <span>encoding-parsing-and-serializing a URL</span> given the
element's <code data-x="">data</code> attribute's value, relative to the element's <span>node
document</span>, at the time the attribute is set, or the empty string if there is no such
attribute or the result is failure.</p>
</dd>
<dt>If the element is a <code>data</code> element</dt>
<dd>
<p>The value is the value of the element's <code data-x="attr-data-value">value</code> attribute,
if it has one, or the empty string otherwise.</p>
</dd>
<dt>If the element is a <code>meter</code> element</dt>
<dd>
<p>The value is the value of the element's <code data-x="attr-meter-value">value</code> attribute,
if it has one, or the empty string otherwise.</p>
</dd>
<dt>If the element is a <code>time</code> element</dt>
<dd>
<p>The value is the element's <span>datetime value</span>.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>The value is the element's <span>descendant text content</span>.</p>
</dd>
</dl>
<p>The <dfn>URL property elements</dfn> are the <code>a</code>, <code>area</code>,
<code>audio</code>, <code>embed</code>, <code>iframe</code>, <code>img</code>, <code>link</code>,
<code>object</code>, <code>source</code>, <code>track</code>, and <code>video</code> elements.</p>
<p>If a property's <span data-x="concept-property-value">value</span>, as defined by the property's
definition, is an <span>absolute URL</span>, the property must be specified using a <span
data-x="URL property elements">URL property element</span>.</p>
<p class="note">These requirements do not apply just because a property value happens to match the
syntax for a URL. They only apply if the property is explicitly defined as taking such a
value.</p>
<p class="example">For example, a book about the first moon landing <!-- 1969-07-20 --> could be
called "mission:moon". A "title" property from a vocabulary that defines a title as being a string
would not expect the title to be given in an <code>a</code> element, even though it looks like a
<span>URL</span>. On the other hand, if there was a (rather narrowly scoped!) vocabulary for
"books whose titles look like URLs" which had a "title" property defined to take a URL, then the
property <em>would</em> expect the title to be given in an <code>a</code> element (or one of the
other <span>URL property elements</span>), because of the requirement above.</p>
<div w-nodev>
<h4>Associating names with items</h4>
<p>To find <dfn>the properties of an item</dfn> defined by the element <var>root</var>,
the user agent must run the following steps. These steps are also used to flag <span
data-x="microdata error">microdata errors</span>.</p>
<ol>
<li><p>Let <var>results</var>, <var>memory</var>, and <var>pending</var> be empty lists of elements.</p></li>
<li><p>Add the element <var>root</var> to <var>memory</var>.</p></li>
<li><p>Add the child elements of <var>root</var>, if any, to <var>pending</var>.</p></li>
<li><p>If <var>root</var> has an <code data-x="attr-itemref">itemref</code> attribute, <span
data-x="split a string on ASCII whitespace">split the value of that <code
data-x="attr-itemref">itemref</code> attribute on ASCII whitespace</span>. For each resulting
token <var>ID</var>, if there is an element in the <span>tree</span> of <var>root</var> with the
<span data-x="concept-ID">ID</span> <var>ID</var>, then add the first such element to
<var>pending</var>.</p></li>
<li>
<p>While <var>pending</var> is not empty:</p>
<ol>
<li><p>Remove an element from <var>pending</var> and let <var>current</var> be that
element.</p></li>
<li><p>If <var>current</var> is already in <var>memory</var>, there is a
<span>microdata error</span>; <span>continue</span>.</p></li>
<li><p>Add <var>current</var> to <var>memory</var>.</p></li>
<li><p>If <var>current</var> does not have an <code data-x="attr-itemscope">itemscope</code>
attribute, then: add all the child elements of <var>current</var> to
<var>pending</var>.</p></li>
<li><p>If <var>current</var> has an <code data-x="attr-itemprop">itemprop</code> attribute
specified and has one or more <span>property names</span>, then add <var>current</var> to
<var>results</var>.</p></li>
</ol>
<li><p>Sort <var>results</var> in <span>tree order</span>.</p></li>
<li><p>Return <var>results</var>.</p></li>
</ol>
<p>A document must not contain any <span data-x="concept-item">items</span> for which the algorithm
to find <span>the properties of an item</span> finds any <dfn data-x="microdata error">microdata
errors</dfn>.</p>
<p>An <span data-x="concept-item">item</span> is a <dfn data-x="top-level microdata items">top-level
microdata item</dfn> if its element does not have an <code data-x="attr-itemprop">itemprop</code>
attribute.</p>
<!--(this is currently redundant with "requirement itemprop" below)
<p>An <span data-x="concept-item">item</span> is a <dfn data-x="used microdata items">used microdata
item</dfn> if it is a <span data-x="top-level microdata items">top-level microdata item</span>, or
if it has an <code data-x="attr-itemprop">itemprop</code> attribute and would be <span data-x="the
properties of an item">found to be the property</span> of an <span
data-x="concept-item">item</span> that is itself a <span data-x="used microdata items">used
microdata item</span>.</p>
<p>All <span data-x="concept-item">items</span> in a document must be <span>used microdata
items</span>.</p>
-->
<p>All <code data-x="attr-itemref">itemref</code> attributes in a <code>Document</code> must be
such that there are no cycles in the graph formed from representing each <span
data-x="concept-item">item</span> in the <code>Document</code> as a node in the graph and each
<span data-x="the properties of an item">property</span> of an item whose <span
data-x="concept-property-value">value</span> is another item as an edge in the graph connecting
those two items.</p>
<!-- "requirement itemprop" (see above) -->
<p>A document must not contain any elements that have an <code
data-x="attr-itemprop">itemprop</code> attribute that would not be found to be a property of any of
the <span data-x="concept-item">items</span> in that document were their <span data-x="the
properties of an item">properties</span> all to be determined.</p>
<div class="example">
<p>In this example, a single license statement is applied to two works, using <code
data-x="attr-itemref">itemref</code> from the items representing the works:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Photo gallery</title>
</head>
<body>
<h1>My photos</h1>
<figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses">
<img itemprop="work" src="images/house.jpeg" alt="A white house, boarded up, sits in a forest.">
<figcaption itemprop="title">The house I found.</figcaption>
</figure>
<figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses">
<img itemprop="work" src="images/mailbox.jpeg" alt="Outside the house is a mailbox. It has a leaflet inside.">
<figcaption itemprop="title">The mailbox.</figcaption>
</figure>
<footer>
<p id="licenses">All images licensed under the <a itemprop="license"
href="http://www.opensource.org/licenses/mit-license.php">MIT
license</a>.</p>
</footer>
</body>
</html></code></pre>
<p>The above results in two items with the type "<code data-x="">http://n.whatwg.org/work</code>",
one with:</p>
<dl class="brief">
<dt>work
<dd><code data-x="">images/house.jpeg</code>
<dt>title
<dd>The house I found.
<dt>license
<dd><code data-x="">http://www.opensource.org/licenses/mit-license.php</code>
</dl>
<p>...and one with:</p>
<dl class="brief">
<dt>work
<dd><code data-x="">images/mailbox.jpeg</code>
<dt>title
<dd>The mailbox.
<dt>license
<dd><code data-x="">http://www.opensource.org/licenses/mit-license.php</code>
</dl>
</div>
</div> <!-- see comment above -->
<h4>Microdata and other namespaces</h4>
<p>Currently, the <code data-x="attr-itemscope">itemscope</code>, <code
data-x="attr-itemprop">itemprop</code>, and other microdata attributes are only defined for
<span>HTML elements</span>. This means that attributes with the literal names "<code
data-x="">itemscope</code>", "<code data-x="">itemprop</code>", etc, do not cause microdata
processing to occur on elements in other namespaces, such as SVG.</p>
<div class="example">
<p>Thus, in the following example there is only one item, not
two.</p>
<pre class="bad"><code class="html"><p itemscope></p> <!-- this is an item (with no properties and no type) -->
<svg itemscope></svg> <!-- this is not, it's just an <span>SVG <code>svg</code></span> element with an invalid unknown attribute --></code></pre>
</div>
<h3 id="mdvocabs">Sample microdata vocabularies</h3>
<p>The vocabularies in this section are primarily intended to demonstrate how a vocabulary is
specified, though they are also usable in their own right.</p>
<h4>vCard</h4>
<p>An item with the <span data-x="item types">item type</span> <dfn><code data-x="md-vcard">http://microformats.org/profile/hcard</code></dfn> represents a person's or
organization's contact information.</p>
<p>This vocabulary does not <span>support global identifiers for items</span>.</p>
<p>The following are the type's <span data-x="defined property name">defined property
names</span>. They are based on the vocabulary defined in <cite>vCard Format Specification</cite>
(<cite>vCard</cite>) and its extensions, where more information on how to interpret the values can
be found. <ref>RFC6350</ref></p>
<dl>
<dt><dfn><code data-x="md-vcard-kind">kind</code></dfn></dt>
<dd>
<p>Describes what kind of contact the item represents.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is <span>identical
to</span> one of the <span>kind strings</span>.</p>
<p>A single property with the name <code data-x="md-vcard-kind">kind</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<!-- XML not included since there's no good way to do it here -->
<!-- Note: vCard->microdata->vCard doesn't count as "propagating vCards" according to Tantek, so
we're not non-conforming when we drop it, despite vCard's requirement -->
<dt><dfn><code data-x="md-vcard-fn">fn</code></dfn></dt>
<dd>
<p>Gives the formatted text corresponding to the name of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Exactly one property with the name <code data-x="md-vcard-fn">fn</code> must be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n">n</code></dfn></dt>
<dd>
<p>Gives the structured name of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span
data-x="concept-item">item</span> with zero or more of each of the <code
data-x="md-vcard-n-family-name">family-name</code>, <code
data-x="md-vcard-n-given-name">given-name</code>, <code
data-x="md-vcard-n-additional-name">additional-name</code>, <code
data-x="md-vcard-n-honorific-prefix">honorific-prefix</code>, and <code
data-x="md-vcard-n-honorific-suffix">honorific-suffix</code> properties.</p>
<p>Exactly one property with the name <code data-x="md-vcard-n">n</code> must be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n-family-name">family-name</code></dfn> (inside <code data-x="md-vcard-n">n</code>)</dt>
<dd>
<p>Gives the family name of the person, or the full name of the organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-n-family-name">family-name</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-n">n</code> property of
an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n-given-name">given-name</code></dfn> (inside <code data-x="md-vcard-n">n</code>)</dt>
<dd>
<p>Gives the given-name of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-n-given-name">given-name</code>
may be present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-n">n</code> property of
an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n-additional-name">additional-name</code></dfn> (inside <code data-x="md-vcard-n">n</code>)</dt>
<dd>
<p>Gives the any additional names of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-n-additional-name">additional-name</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-n">n</code> property of
an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n-honorific-prefix">honorific-prefix</code></dfn> (inside <code data-x="md-vcard-n">n</code>)</dt>
<dd>
<p>Gives the honorific prefix of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-n-honorific-prefix">honorific-prefix</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-n">n</code> property of
an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-n-honorific-suffix">honorific-suffix</code></dfn> (inside <code data-x="md-vcard-n">n</code>)</dt>
<dd>
<p>Gives the honorific suffix of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-n-honorific-suffix">honorific-suffix</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-n">n</code> property of
an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-nickname">nickname</code></dfn></dt>
<dd>
<p>Gives the nickname of the person or organization.</p>
<!-- copied from vCard -->
<p class="note">The nickname is the descriptive name given instead of or in addition to the one
belonging to a person, place, or thing. It can also be used to specify a familiar form of a
proper name specified by the <code data-x="md-vcard-fn">fn</code> or <code
data-x="md-vcard-n">n</code> properties.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-nickname">nickname</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-photo">photo</code></dfn></dt>
<dd>
<p>Gives a photograph of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-photo">photo</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-bday">bday</code></dfn></dt>
<dd>
<p>Gives the birth date of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be a <span>valid date
string</span>.</p>
<p>A single property with the name <code data-x="md-vcard-bday">bday</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-anniversary">anniversary</code></dfn></dt>
<dd>
<p>Gives the birth date of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be a <span>valid date
string</span>.</p>
<p>A single property with the name <code data-x="md-vcard-anniversary">anniversary</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-sex">sex</code></dfn></dt>
<dd>
<p>Gives the biological sex of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be one of
<code data-x="">F</code>, meaning "female",
<code data-x="">M</code>, meaning "male",
<code data-x="">N</code>, meaning "none or not applicable",
<code data-x="">O</code>, meaning "other", or
<code data-x="">U</code>, meaning "unknown".</p>
<p>A single property with the name <code data-x="md-vcard-sex">sex</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-gender-identity">gender-identity</code></dfn></dt>
<dd>
<p>Gives the gender identity of the person.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-gender-identity">gender-identity</code>
may be present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr">adr</code></dfn></dt>
<dd>
<p>Gives the delivery address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span
data-x="concept-item">item</span> with zero or more <code data-x="md-vcard-adr-type">type</code>,
<code data-x="md-vcard-adr-post-office-box">post-office-box</code>, <code
data-x="md-vcard-adr-extended-address">extended-address</code>, and <code
data-x="md-vcard-adr-street-address">street-address</code> properties, and optionally a <code
data-x="md-vcard-adr-locality">locality</code> property, optionally a <code
data-x="md-vcard-adr-region">region</code> property, optionally a <code
data-x="md-vcard-adr-postal-code">postal-code</code> property, and optionally a <code
data-x="md-vcard-adr-country-name">country-name</code> property.</p>
<p>If no <code data-x="md-vcard-adr-type">type</code> properties are present within an <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, then the <span data-x="address
type strings">address type string</span> <code data-x="md-vcard-type-adr-work">work</code> is
implied.</p>
<p>Any number of properties with the name <code data-x="md-vcard-adr">adr</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-type">type</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the type of delivery address.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is <span>identical
to</span> one of the <span>address type strings</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-adr-type">type</code> may be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, but within each such <code
data-x="md-vcard-adr">adr</code> property <span data-x="concept-item">item</span> there must only
be one <code data-x="md-vcard-adr-type">type</code> property per distinct value.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-post-office-box">post-office-box</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the post office box component of the delivery address of the person or
organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-adr-post-office-box">post-office-box</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
<p class="note"><cite>vCard</cite> urges authors not to use this field.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-extended-address">extended-address</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives an additional component of the delivery address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-adr-extended-address">extended-address</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
<p class="note"><cite>vCard</cite> urges authors not to use this field.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-street-address">street-address</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the street address component of the delivery address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-adr-street-address">street-address</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-locality">locality</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the locality component (e.g. city) of the delivery address of the person or
organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-adr-locality">locality</code> may be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-region">region</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the region component (e.g. state or province) of the delivery address of the person or
organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-adr-region">region</code> may be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-postal-code">postal-code</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the postal code component of the delivery address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-adr-postal-code">postal-code</code> may
be present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-adr-country-name">country-name</code></dfn> (inside <code data-x="md-vcard-adr">adr</code>)</dt>
<dd>
<p>Gives the country name component of the delivery address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-adr-country-name">country-name</code>
may be present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-adr">adr</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-tel">tel</code></dfn></dt>
<dd>
<p>Gives the telephone number of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be either text that can be
interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121, or an
<span data-x="concept-item">item</span> with zero or more <code
data-x="md-vcard-tel-type">type</code> properties and exactly one <code
data-x="md-vcard-tel-value">value</code> property. <ref>E163</ref> <ref>X121</ref></p>
<p>If no <code data-x="md-vcard-tel-type">type</code> properties are present within an <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of a <code data-x="md-vcard-tel">tel</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, or if the <span
data-x="concept-property-value">value</span> of such a <code data-x="md-vcard-tel">tel</code>
property is text, then the <span data-x="telephone type strings">telephone type string</span>
<code data-x="md-vcard-type-tel-voice">voice</code> is implied.</p>
<p>Any number of properties with the name <code data-x="md-vcard-tel">tel</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-tel-type">type</code></dfn> (inside <code data-x="md-vcard-tel">tel</code>)</dt>
<dd>
<p>Gives the type of telephone number.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is <span>identical
to</span> one of the <span>telephone type strings</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-tel-type">type</code> may be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of a <code data-x="md-vcard-tel">tel</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, but within each such <code
data-x="md-vcard-tel">tel</code> property <span data-x="concept-item">item</span> there must only
be one <code data-x="md-vcard-tel-type">type</code> property per distinct value.</p>
</dd>
<dt><dfn><code data-x="md-vcard-tel-value">value</code></dfn> (inside <code data-x="md-vcard-tel">tel</code>)</dt>
<dd>
<p>Gives the actual telephone number of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that can be interpreted
as a telephone number as defined in the CCITT specifications E.163 and X.121. <ref>E163</ref>
<ref>X121</ref></p>
<p>Exactly one property with the name <code data-x="md-vcard-tel-value">value</code> must be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of a <code data-x="md-vcard-tel">tel</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-email">email</code></dfn></dt>
<dd>
<p>Gives the email address of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-email">email</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-impp">impp</code></dfn></dt>
<dd>
<p>Gives a <span>URL</span> for instant messaging and presence protocol communications with the
person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-impp">impp</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-lang">lang</code></dfn></dt>
<dd>
<p>Gives a language understood by the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be a valid BCP 47 language tag.
<ref>BCP47</ref></p>
<p>Any number of properties with the name <code data-x="md-vcard-lang">lang</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-tz">tz</code></dfn></dt>
<dd>
<p>Gives the time zone of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text and must match the
following syntax:</p>
<ol>
<li>Either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).</li>
<li>A <span>valid non-negative integer</span> that is exactly two digits long and that
represents a number in the range 00..23.</li>
<li>A U+003A COLON character (:).</li>
<li>A <span>valid non-negative integer</span> that is exactly two digits long and that
represents a number in the range 00..59.</li>
</ol>
<p>Any number of properties with the name <code data-x="md-vcard-tz">tz</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-geo">geo</code></dfn></dt>
<dd>
<p>Gives the geographical position of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text and must match the
following syntax:</p>
<ol>
<li>Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character
(-).</li>
<li>One or more <span>ASCII digits</span>.</li>
<li>Optionally*, a U+002E FULL STOP character (.) followed by one or more <span>ASCII
digits</span>.</li>
<li>A U+003B SEMICOLON character (;).</li>
<li>Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character
(-).</li>
<li>One or more <span>ASCII digits</span>.</li>
<li>Optionally*, a U+002E FULL STOP character (.) followed by one or more <span>ASCII
digits</span>.</li>
</ol>
<p>The optional components marked with an asterisk (*) should be included, and should have six
digits each.</p>
<!-- copied from vCard -->
<p class="note">The value specifies latitude and longitude, in that order (i.e., "LAT LON"
ordering), in decimal degrees. The longitude represents the location east and west of the prime
meridian as a positive or negative real number, respectively. The latitude represents the
location north and south of the equator as a positive or negative real number, respectively.</p>
<p>Any number of properties with the name <code data-x="md-vcard-geo">geo</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-title">title</code></dfn></dt>
<dd>
<p>Gives the job title, functional position or function of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-title">title</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-role">role</code></dfn></dt>
<dd>
<p>Gives the role, occupation, or business category of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-role">role</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-logo">logo</code></dfn></dt>
<dd>
<p>Gives the logo of the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-logo">logo</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-agent">agent</code></dfn></dt>
<dd>
<p>Gives the contact information of another person who will act on behalf of the person or
organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be either an <span
data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, or an <span>absolute URL</span>,
or text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-agent">agent</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-org">org</code></dfn></dt>
<dd>
<p>Gives the name and units of the organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be either text or an <span
data-x="concept-item">item</span> with one <code
data-x="md-vcard-org-organization-name">organization-name</code> property and zero or more <code
data-x="md-vcard-org-organization-unit">organization-unit</code> properties.</p>
<p>Any number of properties with the name <code data-x="md-vcard-org">org</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-org-organization-name">organization-name</code></dfn> (inside <code data-x="md-vcard-org">org</code>)</dt>
<dd>
<p>Gives the name of the organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Exactly one property with the name <code
data-x="md-vcard-org-organization-name">organization-name</code> must be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of an <code data-x="md-vcard-org">org</code> property
of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-org-organization-unit">organization-unit</code></dfn> (inside <code data-x="md-vcard-org">org</code>)</dt>
<dd>
<p>Gives the name of the organization unit.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code
data-x="md-vcard-org-organization-unit">organization-unit</code> may be present within the <span
data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of the <code data-x="md-vcard-org">org</code>
property of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-member">member</code></dfn></dt>
<dd>
<p>Gives a <span>URL</span> that represents a member of the group.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-member">member</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code> if the <span
data-x="concept-item">item</span> also has a property with the name <code
data-x="md-vcard-kind">kind</code> whose value is "<code
data-x="md-vcard-kind-group">group</code>".</p>
</dd>
<dt><dfn><code data-x="md-vcard-related">related</code></dfn></dt>
<dd>
<p>Gives a relationship to another entity.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span
data-x="concept-item">item</span> with one <code data-x="md-vcard-related-url">url</code>
property and one <code data-x="md-vcard-related-rel">rel</code> properties.</p>
<p>Any number of properties with the name <code data-x="md-vcard-related">related</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-related-url">url</code></dfn> (inside <code data-x="md-vcard-related">related</code>)</dt>
<dd>
<p>Gives the <span>URL</span> for the related entity.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Exactly one property with the name <code data-x="md-vcard-related-url">url</code> must be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of a <code data-x="md-vcard-related">related</code>
property of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-related-rel">rel</code></dfn> (inside <code data-x="md-vcard-related">related</code>)</dt>
<dd>
<p>Gives the relationship between the entity and the related entity.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is <span>identical
to</span> one of the <span>relationship strings</span>.</p>
<p>Exactly one property with the name <code data-x="md-vcard-related-rel">rel</code> must be
present within the <span data-x="concept-item">item</span> that forms the <span
data-x="concept-property-value">value</span> of a <code data-x="md-vcard-related">related</code>
property of an <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-categories">categories</code></dfn></dt>
<dd>
<p>Gives the name of a category or tag that the person or organization could be classified
as.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-categories">categories</code>
may be present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-note">note</code></dfn></dt>
<dd>
<p>Gives supplemental information or a comment about the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vcard-note">note</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<!-- PRODID not included -->
<dt><dfn><code data-x="md-vcard-rev">rev</code></dfn></dt>
<dd>
<p>Gives the revision date and time of the contact information.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is a <span>valid
global date and time string</span>.</p>
<!-- copied from vCard -->
<p class="note">The value distinguishes the current revision of the information for other
renditions of the information.</p>
<p>Any number of properties with the name <code data-x="md-vcard-rev">rev</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-sound">sound</code></dfn></dt>
<dd>
<p>Gives a sound file relating to the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-sound">sound</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<dt><dfn><code data-x="md-vcard-uid">uid</code></dfn></dt>
<dd>
<p>Gives a globally unique identifier corresponding to the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vcard-uid">uid</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<!-- CLIENTPIDMAP not included since the global parameters are not included -->
<dt><dfn><code data-x="md-vcard-url">url</code></dfn></dt>
<dd>
<p>Gives a <span>URL</span> relating to the person or organization.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vcard-url">url</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p>
</dd>
<!-- VERSION not included - always 4.0 -->
<!-- KEY not included - no way to include binary data at this time -->
<!-- FBURL, CALADRURI, CALURI not included - unclear how calendars would be exposed on the web -->
</dl>
<p>The <dfn>kind strings</dfn> are:</p>
<dl>
<dt><dfn><code data-x="md-vcard-kind-individual">individual</code></dfn></dt>
<dd>
<p>Indicates a single entity (e.g. a person).</p>
</dd>
<dt><dfn><code data-x="md-vcard-kind-group">group</code></dfn></dt>
<dd>
<p>Indicates multiple entities (e.g. a mailing list).</p>
</dd>
<dt><dfn><code data-x="md-vcard-kind-org">org</code></dfn></dt>
<dd>
<p>Indicates a single entity that is not a person (e.g. a company).</p>
</dd>
<dt><dfn><code data-x="md-vcard-kind-location">location</code></dfn></dt>
<dd>
<p>Indicates a geographical place (e.g. an office building).</p>
</dd>
<!-- update this when https://www.iana.org/assignments/vcard-elements/vcard-elements.xml#property-values is updated -->
</dl>
<p>The <dfn>address type strings</dfn> are:</p>
<dl>
<dt><dfn><code data-x="md-vcard-type-adr-home">home</code></dfn></dt>
<dd>
<p>Indicates a delivery address for a residence.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-adr-work">work</code></dfn></dt>
<dd>
<p>Indicates a delivery address for a place of work.</p>
</dd>
</dl>
<p>The <dfn>telephone type strings</dfn> are:</p>
<dl>
<dt><dfn><code data-x="md-vcard-type-tel-home">home</code></dfn></dt>
<dd>
<p>Indicates a residential number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-work">work</code></dfn></dt>
<dd>
<p>Indicates a telephone number for a place of work.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-text">text</code></dfn></dt>
<dd>
<p>Indicates that the telephone number supports text messages (SMS).</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-voice">voice</code></dfn></dt>
<dd>
<p>Indicates a voice telephone number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-fax">fax</code></dfn></dt>
<dd>
<p>Indicates a facsimile telephone number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-cell">cell</code></dfn></dt>
<dd>
<p>Indicates a cellular telephone number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-video">video</code></dfn></dt>
<dd>
<p>Indicates a video conferencing telephone number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-pager">pager</code></dfn></dt>
<dd>
<p>Indicates a paging device telephone number.</p>
</dd>
<dt><dfn><code data-x="md-vcard-type-tel-textphone">textphone</code></dfn></dt>
<dd>
<p>Indicates a telecommunication device for people with hearing or speech difficulties.</p>
</dd>
</dl>
<p>The <dfn>relationship strings</dfn> are:</p>
<dl>
<dt><dfn><code data-x="md-vcard-rel-emergency">emergency</code></dfn></dt>
<dd>
<p>An emergency contact.</p>
</dd>
<dt><dfn><code data-x="md-vcard-rel-agent">agent</code></dfn></dt>
<dd>
<p>Another entity that acts on behalf of this entity.</p>
</dd>
<dt><dfn data-x="md-vcard-rel-contact">contact</dfn></dt>
<dt><dfn data-x="md-vcard-rel-acquaintance">acquaintance</dfn></dt>
<dt><dfn data-x="md-vcard-rel-friend">friend</dfn></dt>
<dt><dfn data-x="md-vcard-rel-met">met</dfn></dt>
<dt><dfn data-x="md-vcard-rel-co-worker">worker</dfn></dt>
<dt><dfn data-x="md-vcard-rel-colleague">colleague</dfn></dt>
<dt><dfn data-x="md-vcard-rel-co-resident">resident</dfn></dt>
<dt><dfn data-x="md-vcard-rel-neighbor">neighbor</dfn></dt>
<dt><dfn data-x="md-vcard-rel-child">child</dfn></dt>
<dt><dfn data-x="md-vcard-rel-parent">parent</dfn></dt>
<dt><dfn data-x="md-vcard-rel-sibling">sibling</dfn></dt>
<dt><dfn data-x="md-vcard-rel-spouse">spouse</dfn></dt>
<dt><dfn data-x="md-vcard-rel-kin">kin</dfn></dt>
<dt><dfn data-x="md-vcard-rel-muse">muse</dfn></dt>
<dt><dfn data-x="md-vcard-rel-crush">crush</dfn></dt>
<dt><dfn data-x="md-vcard-rel-date">date</dfn></dt>
<dt><dfn data-x="md-vcard-rel-sweetheart">sweetheart</dfn></dt>
<dt><dfn data-x="md-vcard-rel-me">me</dfn></dt>
<dd>
<p>Has the meaning defined in XFN. <ref>XFN</ref></p>
</dd>
<!-- update this when https://www.iana.org/assignments/vcard-elements/vcard-elements.xml#parameter-values is updated -->
</dl>
<h5>Conversion to vCard</h5>
<p>Given a list of nodes <var>nodes</var> in a <code>Document</code>, a user agent must
run the following algorithm to <dfn data-x="extracting a vCard">extract any vCard data represented
by those nodes</dfn> (only the first vCard is returned):</p>
<ol>
<li><p>If none of the nodes in <var>nodes</var> are <span
data-x="concept-item">items</span> with the <span data-x="item types">item type</span> <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, then there is no vCard. Abort the
algorithm, returning nothing.</p></li>
<li><p>Let <var>node</var> be the first node in <var>nodes</var> that is an
<span data-x="concept-item">item</span> with the <span data-x="item types">item type</span> <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>.</p></li>
<li><p>Let <var>output</var> be an empty string.</p></li>
<li><p><span>Add a vCard line</span> with the type "<code data-x="">BEGIN</code>" and the value
"<code data-x="">VCARD</code>" to <var>output</var>.</p></li>
<li><p><span>Add a vCard line</span> with the type "<code data-x="">PROFILE</code>" and the value
"<code data-x="">VCARD</code>" to <var>output</var>.</p></li>
<li><p><span>Add a vCard line</span> with the type "<code data-x="">VERSION</code>" and the value
"<code data-x="">4.0</code>" to <var>output</var>.</p></li>
<li><p><span>Add a vCard line</span> with the type "<code data-x="">SOURCE</code>" and the result
of <span>escaping the vCard text string</span> that is the document's <span
data-x="concept-document-url">URL</span> as the value to <var>output</var>.</p></li>
<li><p>If <span>the <code>title</code> element</span> is not null, <span>add a vCard line</span>
with the type "<code data-x="">NAME</code>" and with the result of <span>escaping the vCard text
string</span> obtained from <span>the <code>title</code> element</span>'s <span>descendant
text content</span> as the value to <var>output</var>.</p></li>
<li><p>Let <var>sex</var> be the empty string.</p></li>
<li><p>Let <var>gender-identity</var> be the empty string.</p></li>
<li>
<p>For each element <var>element</var> that is <span data-x="the properties of an
item">a property of the item</span> <var>node</var>: for each name <var>name</var> in <var>element</var>'s <span>property names</span>, run the
following substeps:</p>
<ol>
<li><p>Let <var>parameters</var> be an empty set of name-value pairs.</p></li>
<li>
<p>Run the appropriate set of substeps from the following list. The steps will set a variable
<var>value</var>, which is used in the next step.</p>
<dl>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span> <var>subitem</var> and <var>name</var> is
<code data-x="md-vcard-n">n</code></dt>
<dd>
<ol>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-n-family-name">family-name</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-n-given-name">given-name</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-n-additional-name">additional-name</code> in
<var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-n-honorific-prefix">honorific-prefix</code>
in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-n-honorific-suffix">honorific-suffix</code>
in <var>subitem</var>.</p>
</ol>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span> <var>subitem</var> and <var>name</var> is
<code data-x="md-vcard-adr">adr</code></dt>
<dd>
<ol>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li><p>Append to <var>value</var> the result of <span>collecting vCard
subproperties</span> named <code
data-x="md-vcard-adr-post-office-box">post-office-box</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting vCard
subproperties</span> named <code
data-x="md-vcard-adr-extended-address">extended-address</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting vCard
subproperties</span> named <code data-x="md-vcard-adr-street-address">street-address</code>
in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-adr-locality">locality</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-adr-region">region</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-adr-postal-code">postal-code</code> in <var>subitem</var>.</p>
<li>Append a U+003B SEMICOLON character (;) to <var>value</var>.</li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code data-x="md-vcard-adr-country-name">country-name</code> in
<var>subitem</var>.</p>
<li><p>If there is a property named <code data-x="md-vcard-adr-type">type</code> in
<var>subitem</var>, and the first such property has a <span
data-x="concept-property-value">value</span> that is not an <span
data-x="concept-item">item</span> and whose value consists only of <span data-x="ASCII
alphanumeric">ASCII alphanumerics</span>, then add a parameter named "<code
data-x="">TYPE</code>" whose value is the <span
data-x="concept-property-value">value</span> of that property to
<var>parameters</var>.</p></li>
</ol>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span> <var>subitem</var> and <var>name</var> is
<code data-x="md-vcard-org">org</code></dt>
<dd>
<ol>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li><p>Append to <var>value</var> the result of <span>collecting the first vCard
subproperty</span> named <code
data-x="md-vcard-org-organization-name">organization-name</code> in <var>subitem</var>.</p>
<li>
<p>For each property named <code
data-x="md-vcard-org-organization-unit">organization-unit</code> in <var>subitem</var>, run the following steps:</p>
<ol>
<li><p>If the <span data-x="concept-property-value">value</span> of the property is an
<span data-x="concept-item">item</span>, then skip this property.</p></li>
<li><p>Append a U+003B SEMICOLON character (;) to <var>value</var>.</p></li>
<li><p>Append the result of <span>escaping the vCard text string</span> given by the
<span data-x="concept-property-value">value</span> of the property to <var>value</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span> <var>subitem</var> with the <span data-x="item
types">item type</span> <code data-x="md-vcard">http://microformats.org/profile/hcard</code>
and <var>name</var> is <code data-x="md-vcard-related">related</code></dt>
<dd>
<ol>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li><p>If there is a property named <code data-x="md-vcard-related-url">url</code> in
<var>subitem</var>, and its element is a <span data-x="URL property elements">URL property
element</span>, then append the result of <span>escaping the vCard text string</span> given
by the <span data-x="concept-property-value">value</span> of the first such property to
<var>value</var>, and add a parameter with the name "<code data-x="">VALUE</code>" and the
value "<code data-x="">URI</code>" to <var>parameters</var>.</p></li>
<li><p>If there is a property named <code data-x="md-vcard-related-rel">rel</code> in
<var>subitem</var>, and the first such property has a <span
data-x="concept-property-value">value</span> that is not an <span
data-x="concept-item">item</span> and whose value consists only of <span data-x="ASCII
alphanumeric">ASCII alphanumerics</span>, then add a parameter named "<code
data-x="">RELATION</code>" whose value is the <span
data-x="concept-property-value">value</span> of that property to
<var>parameters</var>.</p></li>
</ol>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span> and <var>name</var> is none of the above</dt>
<!-- tel, adr -->
<dd>
<ol>
<li><p>Let <var>value</var> be the result of <span>collecting the first vCard
subproperty</span> named <code data-x="">value</code> in <var>subitem</var>.</p>
<li><p>If there is a property named <code data-x="">type</code> in <var>subitem</var>, and
the first such property has a <span data-x="concept-property-value">value</span> that is
not an <span data-x="concept-item">item</span> and whose value consists only of <span
data-x="ASCII alphanumeric">ASCII alphanumerics</span>, then add a parameter named "<code
data-x="">TYPE</code>" whose value is the <span
data-x="concept-property-value">value</span> of that property to
<var>parameters</var>.</p></li>
</ol>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is not an <span
data-x="concept-item">item</span> and its <var>name</var> is <code
data-x="md-vcard-sex">sex</code></dt>
<dd>
<p>If this is the first such property to be found, set <var>sex</var> to the
property's <span data-x="concept-property-value">value</span>.</p>
</dd>
<dt>If the property's <span data-x="concept-property-value">value</span> is not an <span
data-x="concept-item">item</span> and its <var>name</var> is <code
data-x="md-vcard-gender-identity">gender-identity</code></dt>
<dd>
<p>If this is the first such property to be found, set <var>gender-identity</var>
to the property's <span data-x="concept-property-value">value</span>.</p>
</dd>
<dt>Otherwise (the property's <span data-x="concept-property-value">value</span> is not an
<span data-x="concept-item">item</span>)</dt>
<dd>
<ol>
<li><p>Let <var>value</var> be the property's <span
data-x="concept-property-value">value</span>.</p></li>
<li><p>If <var>element</var> is one of the <span>URL property elements</span>, add
a parameter with the name "<code data-x="">VALUE</code>" and the value "<code
data-x="">URI</code>" to <var>parameters</var>.</p></li>
<li><p>Otherwise, if <var>name</var> is <code data-x="md-vcard-bday">bday</code> or
<code data-x="md-vcard-anniversary">anniversary</code> and the <var>value</var> is
a <span>valid date string</span>, add a parameter with the name "<code
data-x="">VALUE</code>" and the value "<code data-x="">DATE</code>" to <var>parameters</var>.</p></li>
<li><p>Otherwise, if <var>name</var> is <code data-x="md-vcard-rev">rev</code> and
the <var>value</var> is a <span>valid global date and time string</span>, add a
parameter with the name "<code data-x="">VALUE</code>" and the value "<code
data-x="">DATE-TIME</code>" to <var>parameters</var>.</p></li>
<li><p>Prefix every U+005C REVERSE SOLIDUS character (\) in <var>value</var> with
another U+005C REVERSE SOLIDUS character (\).</p></li>
<li><p>Prefix every U+002C COMMA character (,) in <var>value</var> with a U+005C
REVERSE SOLIDUS character (\).</p></li>
<li><p>Unless <var>name</var> is <code data-x="md-vcard-geo">geo</code>, prefix
every U+003B SEMICOLON character (;) in <var>value</var> with a U+005C REVERSE
SOLIDUS character (\).</p></li>
<li><p>Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in <var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN
SMALL LETTER N character (n).</p></li>
<li><p>Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF)
character in <var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed
by a U+006E LATIN SMALL LETTER N character (n).</p></li>
</ol>
</dd>
</dl>
</li>
<li>
<p><span>Add a vCard line</span> with the type <var>name</var>, the parameters <var>parameters</var>, and the value <var>value</var> to <var>output</var>.</p>
</li>
</ol>
</li>
<li><p>If either <var>sex</var> or <var>gender-identity</var> has a value that
is not the empty string, <span>add a vCard line</span> with the type "<code
data-x="">GENDER</code>" and the value consisting of the concatenation of <var>sex</var>,
a U+003B SEMICOLON character (;), and <var>gender-identity</var> to <var>output</var>.</p></li>
<li><p><span>Add a vCard line</span> with the type "<code data-x="">END</code>" and the value
"<code data-x="">VCARD</code>" to <var>output</var>.</p></li>
</ol>
<p>When the above algorithm says that the user agent is to <dfn>add a vCard line</dfn> consisting
of a type <var>type</var>, optionally some parameters, and a value <var>value</var> to a string <var>output</var>, it must run the following steps:</p>
<ol>
<li><p>Let <var>line</var> be an empty string.
<li><p>Append <var>type</var>, <span>converted to ASCII uppercase</span>, to <var>line</var>.</p></li>
<li>
<p>If there are any parameters, then for each parameter, in the order that they were added, run
these substeps:</p>
<ol>
<li><p>Append a U+003B SEMICOLON character (;) to <var>line</var>.</p></li>
<li><p>Append the parameter's name to <var>line</var>.</p></li>
<li><p>Append a U+003D EQUALS SIGN character (=) to <var>line</var>.</p></li>
<li><p>Append the parameter's value to <var>line</var>.</p></li>
</ol>
</li>
<li><p>Append a U+003A COLON character (:) to <var>line</var>.</p></li>
<li><p>Append <var>value</var> to <var>line</var>.</p></li>
<li><p>Let <var>maximum length</var> be 75.</p></li>
<li>
<p>While <var>line</var>'s <span>code point length</span> is greater than <var>maximum
length</var>:</p>
<ol>
<li><p>Append the first <var>maximum length</var> code points of <var>line</var> to
<var>output</var>.</p></li>
<li><p>Remove the first <var>maximum length</var> code points from <var>line</var>.</p></li>
<li><p>Append a U+000D CARRIAGE RETURN character (CR) to <var>output</var>.</p></li>
<li><p>Append a U+000A LINE FEED character (LF) to <var>output</var>.</p></li>
<li><p>Append a U+0020 SPACE character to <var>output</var>.</p></li>
<li><p>Let <var>maximum length</var> be 74.</p></li>
</ol>
</li>
<li><p>Append (what remains of) <var>line</var> to <var>output</var>.</p></li>
<li><p>Append a U+000D CARRIAGE RETURN character (CR) to <var>output</var>.</p></li>
<li><p>Append a U+000A LINE FEED character (LF) to <var>output</var>.</p></li>
</ol>
<p>When the steps above require the user agent to obtain the result of <dfn>collecting vCard
subproperties</dfn> named <var>subname</var> in <var>subitem</var>, the user
agent must run the following steps:</p>
<ol>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li>
<p>For each property named <var>subname</var> in the item <var>subitem</var>,
run the following substeps:</p>
<ol>
<li><p>If the <span data-x="concept-property-value">value</span> of the property is itself an
<span data-x="concept-item">item</span>, then skip this property.</p></li>
<li><p>If this is not the first property named <var>subname</var> in <var>subitem</var> (ignoring any that were skipped by the previous step), then append a
U+002C COMMA character (,) to <var>value</var>.</p></li>
<li><p>Append the result of <span>escaping the vCard text string</span> given by the <span
data-x="concept-property-value">value</span> of the property to <var>value</var>.</p></li>
</ol>
</li>
<li><p>Return <var>value</var>.</p></li>
</ol>
<p>When the steps above require the user agent to obtain the result of <dfn>collecting the first
vCard subproperty</dfn> named <var>subname</var> in <var>subitem</var>, the user
agent must run the following steps:</p>
<ol>
<li><p>If there are no properties named <var>subname</var> in <var>subitem</var>, then return the
empty string.</p></li>
<li><p>If the <span data-x="concept-property-value">value</span> of the first property named
<var>subname</var> in <var>subitem</var> is an <span data-x="concept-item">item</span>, then
return the empty string.</p></li>
<li><p>Return the result of <span>escaping the vCard text string</span> given by the <span
data-x="concept-property-value">value</span> of the first property named <var>subname</var> in
<var>subitem</var>.</p></li>
</ol>
<p>When the above algorithms say the user agent is to <dfn data-x="escaping the vCard text
string">escape the vCard text string</dfn> <var>value</var>, the user agent must use the
following steps:</p>
<ol>
<li><p>Prefix every U+005C REVERSE SOLIDUS character (\) in <var>value</var> with
another U+005C REVERSE SOLIDUS character (\).</p></li>
<li><p>Prefix every U+002C COMMA character (,) in <var>value</var> with a U+005C REVERSE
SOLIDUS character (\).</p></li>
<li><p>Prefix every U+003B SEMICOLON character (;) in <var>value</var> with a U+005C
REVERSE SOLIDUS character (\).</p></li>
<li><p>Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in <var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL
LETTER N character (n).</p></li>
<li><p>Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in
<var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN
SMALL LETTER N character (n).</p></li>
<li><p>Return the mutated <var>value</var>.</p></li>
</ol>
<p class="note">This algorithm can generate invalid vCard output, if the input does not conform to
the rules described for the <code data-x="md-vcard">http://microformats.org/profile/hcard</code>
<span data-x="item types">item type</span> and <span data-x="defined property name">defined property
names</span>.</p> <!-- of course since vcard doesn't define error handling, this is somewhat
problematic. -->
<h5>Examples</h5>
<!-- NON-NORMATIVE SECTION -->
<div class="example">
<p>Here is a long example vCard for a fictional character called "Jack Bauer":</p>
<pre><code class="html"><section id="jack" itemscope itemtype="http://microformats.org/profile/hcard">
<h1 itemprop="fn">
<span itemprop="n" itemscope>
<span itemprop="given-name">Jack</span>
<span itemprop="family-name">Bauer</span>
</span>
</h1>
<img itemprop="photo" alt="" src="jack-bauer.jpg">
<p itemprop="org" itemscope>
<span itemprop="organization-name">Counter-Terrorist Unit</span>
(<span itemprop="organization-unit">Los Angeles Division</span>)
</p>
<p>
<span itemprop="adr" itemscope>
<span itemprop="street-address">10201 W. Pico Blvd.</span><br>
<span itemprop="locality">Los Angeles</span>,
<span itemprop="region">CA</span>
<span itemprop="postal-code">90064</span><br>
<span itemprop="country-name">United States</span><br>
</span>
<span itemprop="geo">34.052339;-118.410623</span>
</p>
<h2>Assorted Contact Methods</h2>
<ul>
<li itemprop="tel" itemscope>
<span itemprop="value">+1 (310) 597 3781</span> <span itemprop="type">work</span>
<meta itemprop="type" content="voice">
</li>
<li><a itemprop="url" href="https://en.wikipedia.org/wiki/Jack_Bauer">I'm on Wikipedia</a>
so you can leave a message on my user talk page.</li>
<li><a itemprop="url" href="http://www.jackbauerfacts.com/">Jack Bauer Facts</a></li>
<li itemprop="email"><a href="mailto:j.bauer@la.ctu.gov.invalid">j.bauer@la.ctu.gov.invalid</a></li>
<li itemprop="tel" itemscope>
<span itemprop="value">+1 (310) 555 3781</span> <span>
<meta itemprop="type" content="cell">mobile phone</span>
</li>
</ul>
<ins datetime="2008-07-20 21:00:00+01:00">
<meta itemprop="rev" content="2008-07-20 21:00:00+01:00">
<p itemprop="tel" itemscope><strong>Update!</strong>
My new <span itemprop="type">home</span> phone number is
<span itemprop="value">01632 960 123</span>.</p>
</ins>
</section></code></pre>
<p>The odd line wrapping is needed because newlines are meaningful in microdata: newlines would
be preserved in a conversion to, for example, the vCard format.</p>
</div>
<div class="example">
<p>This example shows a site's contact details (using the <code>address</code> element)
containing an address with two street components:</p>
<pre><code class="html"><address itemscope itemtype="http://microformats.org/profile/hcard">
<strong itemprop="fn"><span itemprop="n" itemscope><span itemprop="given-name">Alfred</span>
<span itemprop="family-name">Person</span></span></strong> <br>
<span itemprop="adr" itemscope>
<span itemprop="street-address">1600 Amphitheatre Parkway</span> <br>
<span itemprop="street-address">Building 43, Second Floor</span> <br>
<span itemprop="locality">Mountain View</span>,
<span itemprop="region">CA</span> <span itemprop="postal-code">94043</span>
</span>
</address></code></pre>
</div>
<div class="example">
<p>The vCard vocabulary can be used to just mark up people's names:</p>
<pre><code class="html"><span itemscope itemtype="http://microformats.org/profile/hcard"
><span itemprop=fn><span itemprop="n" itemscope><span itemprop="given-name"
>George</span> <span itemprop="family-name">Washington</span></span
></span></span></code></pre>
<p>This creates a single item with a two name-value pairs, one with the name "fn" and the value
"George Washington", and the other with the name "n" and a second item as its value, the second
item having the two name-value pairs "given-name" and "family-name" with the values "George" and
"Washington" respectively. This is defined to map to the following vCard:</p>
<pre>BEGIN:VCARD
PROFILE:VCARD
VERSION:4.0
SOURCE:<var>document's address</var>
FN:George Washington
N:Washington;George;;;
END:VCARD</pre>
</div>
<h4>vEvent</h4>
<p>An item with the <span data-x="item types">item type</span> <dfn><code data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code></dfn> represents
an event.</p>
<p>This vocabulary does not <span>support global identifiers for items</span>.</p>
<p>The following are the type's <span data-x="defined property name">defined property
names</span>. They are based on the vocabulary defined in <cite>Internet Calendaring and
Scheduling Core Object Specification</cite> (<cite>iCalendar</cite>), where more information on
how to interpret the values can be found. <ref>RFC5545</ref></p>
<p class="note">Only the parts of the iCalendar vocabulary relating to events are used here; this
vocabulary cannot express a complete iCalendar instance.</p>
<dl>
<dt><dfn><code data-x="md-vevent-attach">attach</code></dfn></dt>
<dd>
<p>Gives the address of an associated document for the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-vevent-attach">attach</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-categories">categories</code></dfn></dt>
<dd>
<p>Gives the name of a category or tag that the event could be classified as.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vevent-categories">categories</code>
may be present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-class">class</code></dfn></dt>
<dd>
<p>Gives the access classification of the information regarding the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text with one of the following
values:</p>
<ul class="brief">
<li><code data-x="">public</code></li>
<li><code data-x="">private</code></li>
<li><code data-x="">confidential</code></li>
</ul>
<p class="warning">This is merely advisory and cannot be considered a confidentiality
measure.</p>
<p>A single property with the name <code data-x="md-vevent-class">class</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-comment">comment</code></dfn></dt>
<dd>
<p>Gives a comment regarding the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>Any number of properties with the name <code data-x="md-vevent-comment">comment</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-description">description</code></dfn></dt>
<dd>
<p>Gives a detailed description of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vevent-description">description</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-geo">geo</code></dfn></dt>
<dd>
<p>Gives the geographical position of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text and must match the
following syntax:</p>
<ol>
<li>Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character
(-).</li>
<li>One or more <span>ASCII digits</span>.</li>
<li>Optionally*, a U+002E FULL STOP character (.) followed by one or more <span>ASCII
digits</span>.</li>
<li>A U+003B SEMICOLON character (;).</li>
<li>Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character
(-).</li>
<li>One or more <span>ASCII digits</span>.</li>
<li>Optionally*, a U+002E FULL STOP character (.) followed by one or more <span>ASCII
digits</span>.</li>
</ol>
<p>The optional components marked with an asterisk (*) should be included, and should have six
digits each.</p> <!-- iCalendar actually limits the range to -91.0 < lat < 91.0; -181.0 < long <
181.0, which seems weird. It also gives special meanings to +90/-90 lat, and +180 long. -->
<!-- copied from vcard (not icalendar!) -->
<p class="note">The value specifies latitude and longitude, in that order (i.e., "LAT LON"
ordering), in decimal degrees. The longitude represents the location east and west of the prime
meridian as a positive or negative real number, respectively. The latitude represents the
location north and south of the equator as a positive or negative real number, respectively.</p>
<p>A single property with the name <code data-x="md-vevent-geo">geo</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-location">location</code></dfn></dt>
<dd>
<p>Gives the location of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p> <!-- v2: support
vcard here -->
<p>A single property with the name <code data-x="md-vevent-location">location</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<!-- PRIORITY not included - always 0 - doesn't make sense for single events -->
<dt><dfn><code data-x="md-vevent-resources">resources</code></dfn></dt>
<dd>
<p>Gives a resource that will be needed for the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p> <!-- v2: support
vcard here -->
<p>Any number of properties with the name <code data-x="md-vevent-resources">resources</code> may
be present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-status">status</code></dfn></dt>
<dd>
<p>Gives the confirmation status of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text with one of the following
values:</p>
<ul class="brief">
<li><code data-x="">tentative</code></li>
<li><code data-x="">confirmed</code></li>
<li><code data-x="">canceled</code></li> <!-- two Ls as per iCalendar spec -->
</ul>
<p>A single property with the name <code data-x="md-vevent-status">status</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-summary">summary</code></dfn></dt>
<dd>
<p>Gives a short summary of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>User agents should replace U+000A LINE FEED (LF) characters in the <span
data-x="concept-property-value">value</span> by U+0020 SPACE characters when using the value.</p>
<p>A single property with the name <code data-x="md-vevent-summary">summary</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-dtend">dtend</code></dfn></dt>
<dd>
<p>Gives the date and time by which the event ends.</p>
<p>If the property with the name <code data-x="md-vevent-dtend">dtend</code> is present within an
<span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code> that has a property
with the name <code data-x="md-vevent-dtstart">dtstart</code> whose value is a <span>valid date
string</span>, then the <span data-x="concept-property-value">value</span> of the property with
the name <code data-x="md-vevent-dtend">dtend</code> must be text that is a <span>valid date
string</span> also. Otherwise, the <span data-x="concept-property-value">value</span> of the
property must be text that is a <span>valid global date and time string</span>.</p>
<p>In either case, the <span data-x="concept-property-value">value</span> be later in time than
the value of the <code data-x="md-vevent-dtstart">dtstart</code> property of the same <span
data-x="concept-item">item</span>.</p>
<p class="note">The time given by the <code data-x="md-vevent-dtend">dtend</code> property is not
inclusive. For day-long events, therefore, the <code data-x="md-vevent-dtend">dtend</code>
property's <span data-x="concept-property-value">value</span> will be the day <em>after</em> the
end of the event.</p>
<p>A single property with the name <code data-x="md-vevent-dtend">dtend</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>, so long as that <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code> does not have a
property with the name <code data-x="md-vevent-duration">duration</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-dtstart">dtstart</code></dfn></dt>
<dd>
<p>Gives the date and time at which the event starts.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is either a
<span>valid date string</span> or a <span>valid global date and time string</span>.</p>
<p>Exactly one property with the name <code data-x="md-vevent-dtstart">dtstart</code> must be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-duration">duration</code></dfn></dt>
<dd>
<p>Gives the duration of the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is a <span>valid
vevent duration string</span>.</p>
<p>The duration represented is the sum of all the durations represented by integers in the
value.</p>
<p>A single property with the name <code data-x="md-vevent-duration">duration</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>, so long as that <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code> does not have a
property with the name <code data-x="md-vevent-dtend">dtend</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-transp">transp</code></dfn></dt>
<dd>
<p>Gives whether the event is to be considered as consuming time on a calendar, for the purpose
of free-busy time searches.</p>
<p>The <span data-x="concept-property-value">value</span> must be text with one of the following
values:</p>
<ul class="brief">
<li><code data-x="">opaque</code></li>
<li><code data-x="">transparent</code></li>
</ul>
<p>A single property with the name <code data-x="md-vevent-transp">transp</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<!-- ATTENDEE not included; iCalendar says MUST NOT be included in
published events -->
<dt><dfn><code data-x="md-vevent-contact">contact</code></dfn></dt>
<dd>
<p>Gives the contact information for the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p> <!-- v2: support
vcard here -->
<p>Any number of properties with the name <code data-x="md-vevent-contact">contact</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<!-- ORGANIZER not included, as it is calendar-system-specific (gives a CAL-ADDRESS value); use
CONTACT instead -->
<!-- RECURRENCE-ID not included... unclear how to make it usefully work here -->
<!-- RELATED-TO not included, as it only makes sense for complete calendars -->
<dt><dfn><code data-x="md-vevent-url">url</code></dfn></dt>
<dd>
<p>Gives a <span>URL</span> for the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>A single property with the name <code data-x="md-vevent-url">url</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-uid">uid</code></dfn></dt>
<dd>
<p>Gives a globally unique identifier corresponding to the event.</p>
<p>The <span data-x="concept-property-value">value</span> must be text.</p>
<p>A single property with the name <code data-x="md-vevent-uid">uid</code> may be present within
each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-exdate">exdate</code></dfn></dt>
<dd>
<p>Gives a date and time at which the event does not occur despite the recurrence rules.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is either a
<span>valid date string</span> or a <span>valid global date and time string</span>.</p>
<p>Any number of properties with the name <code data-x="md-vevent-exdate">exdate</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-rdate">rdate</code></dfn></dt>
<dd>
<p>Gives a date and time at which the event recurs.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is one of the
following:
<ul>
<li>A <span>valid date string</span>.</li>
<li>A <span>valid global date and time string</span>.</li>
<li>A <span>valid global date and time string</span> followed by a U+002F SOLIDUS character (/)
followed by a second <span>valid global date and time string</span> representing a later
time.</li>
<li>A <span>valid global date and time string</span> followed by a U+002F SOLIDUS character (/)
followed by a <span>valid vevent duration string</span>.</li>
</ul>
<p>Any number of properties with the name <code data-x="md-vevent-rdate">rdate</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-rrule">rrule</code></dfn></dt>
<dd>
<p>Gives a rule for finding dates and times at which the event occurs.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that matches the RECUR
value type defined in <cite>iCalendar</cite>. <ref>RFC5545</ref></p>
<p>A single property with the name <code data-x="md-vevent-rrule">rrule</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-created">created</code></dfn></dt>
<dd>
<p>Gives the date and time at which the event information was first created in a calendaring
system.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is a <span>valid
global date and time string</span>.</p>
<p>A single property with the name <code data-x="md-vevent-created">created</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<!-- DTSTAMP not included, it gets added when serializing -->
<dt><dfn><code data-x="md-vevent-last-modified">last-modified</code></dfn></dt>
<dd>
<p>Gives the date and time at which the event information was last modified in a calendaring
system.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is a <span>valid
global date and time string</span>.</p>
<p>A single property with the name <code data-x="md-vevent-last-modified">last-modified</code>
may be present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<dt><dfn><code data-x="md-vevent-sequence">sequence</code></dfn></dt>
<dd>
<p>Gives a revision number for the event information.</p>
<p>The <span data-x="concept-property-value">value</span> must be text that is a <span>valid
non-negative integer</span>.</p>
<p>A single property with the name <code data-x="md-vevent-sequence">sequence</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>.</p>
</dd>
<!-- REQUEST-STATUS not included, calendaring system interop
feature -->
</dl>
<p>A string is a <dfn>valid vevent duration string</dfn> if it matches the following pattern:</p>
<ol>
<li><p>A U+0050 LATIN CAPITAL LETTER P character (P).</p></li>
<li>
<p>One of the following:</p>
<ul>
<li><p>A <span>valid non-negative integer</span> followed by a U+0057 LATIN CAPITAL LETTER W
character (W). The integer represents a duration of that number of weeks.</p></li>
<li>
<p>At least one, and possible both in this order, of the following:</p>
<ol>
<li><p>A <span>valid non-negative integer</span> followed by a U+0044 LATIN CAPITAL LETTER D
character (D). The integer represents a duration of that number of days.</p></li>
<li>
<p>A U+0054 LATIN CAPITAL LETTER T character (T) followed by any one of the following, or
the first and second of the following in that order, or the second and third of the
following in that order, or all three of the following in this order:</p>
<ol>
<li><p>A <span>valid non-negative integer</span> followed by a U+0048 LATIN CAPITAL LETTER
H character (H). The integer represents a duration of that number of hours.</p></li>
<li><p>A <span>valid non-negative integer</span> followed by a U+004D LATIN CAPITAL LETTER
M character (M). The integer represents a duration of that number of minutes.</p></li>
<li><p>A <span>valid non-negative integer</span> followed by a U+0053 LATIN CAPITAL LETTER
S character (S). The integer represents a duration of that number of seconds.</p></li>
</ol>
</ol>
</li>
</ul>
</li>
</ol>
<h5>Conversion to iCalendar</h5>
<p>Given a list of nodes <var>nodes</var> in a <code>Document</code>, a user agent must
run the following algorithm to <dfn data-x="extracting vEvent data">extract any vEvent data
represented by those nodes</dfn>:</p>
<ol>
<li><p>If none of the nodes in <var>nodes</var> are <span
data-x="concept-item">items</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>, then there is no
vEvent data. Abort the algorithm, returning nothing.</p></li>
<li><p>Let <var>output</var> be an empty string.</p></li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">BEGIN</code>" and the
value "<code data-x="">VCALENDAR</code>" to <var>output</var>.</p></li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">PRODID</code>" and the
value equal to a user-agent-specific string representing the user agent to <var>output</var>.</p></li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">VERSION</code>" and the
value "<code data-x="">2.0</code>" to <var>output</var>.</p></li>
<li>
<p>For each node <var>node</var> in <var>nodes</var> that is an <span
data-x="concept-item">item</span> with the type <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code>, run the following
steps:</p>
<ol>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">BEGIN</code>" and the
value "<code data-x="">VEVENT</code>" to <var>output</var>.</p></li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">DTSTAMP</code>" and a
value consisting of an iCalendar DATE-TIME string representing the current date and time, with
the annotation "<code data-x="">VALUE=DATE-TIME</code>", to <var>output</var>.
<ref>RFC5545</ref></p></li>
<li>
<p>For each element <var>element</var> that is <span data-x="the properties of an
item">a property of the item</span> <var>node</var>: for each name <var>name</var> in <var>element</var>'s <span>property names</span>, run the
appropriate set of substeps from the following list:</p>
<dl>
<dt>If the property's <span data-x="concept-property-value">value</span> is an <span
data-x="concept-item">item</span></dt>
<dd>
<p>Skip the property.</p>
</dd>
<dt>If the property is <code data-x="md-vevent-dtend">dtend</code></dt>
<dt>If the property is <code data-x="md-vevent-dtstart">dtstart</code></dt>
<dt>If the property is <code data-x="md-vevent-exdate">exdate</code></dt>
<dt>If the property is <code data-x="md-vevent-rdate">rdate</code></dt>
<dt>If the property is <code data-x="md-vevent-created">created</code></dt>
<dt>If the property is <code data-x="md-vevent-last-modified">last-modified</code></dt>
<dd>
<p>Let <var>value</var> be the result of stripping all U+002D HYPHEN-MINUS (-) and
U+003A COLON (:) characters from the property's <span
data-x="concept-property-value">value</span>.</p>
<p>If the property's <span data-x="concept-property-value">value</span> is a <span>valid date
string</span> then <span>add an iCalendar line</span> with the type <var>name</var>
and the value <var>value</var> to <var>output</var>, with the annotation
"<code data-x="">VALUE=DATE</code>".</p>
<p>Otherwise, if the property's <span data-x="concept-property-value">value</span> is a
<span>valid global date and time string</span> then <span>add an iCalendar line</span> with
the type <var>name</var> and the value <var>value</var> to <var>output</var>, with the annotation "<code data-x="">VALUE=DATE-TIME</code>".</p>
<p>Otherwise, skip the property.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p><span>Add an iCalendar line</span> with the type <var>name</var> and the
property's <span data-x="concept-property-value">value</span> to <var>output</var>.</p>
</dd>
</dl>
</li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">END</code>" and the
value "<code data-x="">VEVENT</code>" to <var>output</var>.</p></li>
</ol>
</li>
<li><p><span>Add an iCalendar line</span> with the type "<code data-x="">END</code>" and the value
"<code data-x="">VCALENDAR</code>" to <var>output</var>.</p></li>
</ol>
<p>When the above algorithm says that the user agent is to <dfn>add an iCalendar line</dfn>
consisting of a type <var>type</var>, a value <var>value</var>, and optionally
an annotation, to a string <var>output</var>, it must run the following steps:</p>
<ol>
<li><p>Let <var>line</var> be an empty string.</p></li>
<li><p>Append <var>type</var>, <span>converted to ASCII uppercase</span>, to <var>line</var>.</p></li>
<li>
<p>If there is an annotation:</p>
<ol>
<li><p>Append a U+003B SEMICOLON character (;) to <var>line</var>.</p></li>
<li><p>Append the annotation to <var>line</var>.</p></li>
</ol>
</li>
<li><p>Append a U+003A COLON character (:) to <var>line</var>.</p></li>
<li><p>Prefix every U+005C REVERSE SOLIDUS character (\) in <var>value</var> with
another U+005C REVERSE SOLIDUS character (\).</p></li>
<li><p>Prefix every U+002C COMMA character (,) in <var>value</var> with a U+005C REVERSE
SOLIDUS character (\).</p></li>
<li><p>Prefix every U+003B SEMICOLON character (;) in <var>value</var> with a U+005C
REVERSE SOLIDUS character (\).</p></li>
<li><p>Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in <var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL
LETTER N character (n).</p></li>
<li><p>Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in
<var>value</var> with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN
SMALL LETTER N character (n).</p></li>
<li><p>Append <var>value</var> to <var>line</var>.</p></li>
<li><p>Let <var>maximum length</var> be 75.</p></li>
<li>
<p>While <var>line</var>'s <span>code point length</span> is greater than <var>maximum
length</var>:</p>
<ol>
<li><p>Append the first <var>maximum length</var> code points of <var>line</var> to
<var>output</var>.</p></li>
<li><p>Remove the first <var>maximum length</var> code points from <var>line</var>.</p></li>
<li><p>Append a U+000D CARRIAGE RETURN character (CR) to <var>output</var>.</p></li>
<li><p>Append a U+000A LINE FEED character (LF) to <var>output</var>.</p></li>
<li><p>Append a U+0020 SPACE character to <var>output</var>.</p></li>
<li><p>Let <var>maximum length</var> be 74.</p></li>
</ol>
</li>
<li><p>Append (what remains of) <var>line</var> to <var>output</var>.</p></li>
<li><p>Append a U+000D CARRIAGE RETURN character (CR) to <var>output</var>.</p></li>
<li><p>Append a U+000A LINE FEED character (LF) to <var>output</var>.</p></li>
</ol>
<p class="note">This algorithm can generate invalid iCalendar output, if the input does not
conform to the rules described for the <code
data-x="md-vevent">http://microformats.org/profile/hcalendar#vevent</code> <span data-x="item
types">item type</span> and <span data-x="defined property name">defined property names</span>.</p>
<!-- of course since iCalendar doesn't define error handling, this is somewhat problematic. -->
<h5>Examples</h5>
<!-- NON-NORMATIVE SECTION -->
<!-- get more from https://www.rfc-editor.org/rfc/rfc5545 -->
<div class="example">
<p>Here is an example of a page that uses the vEvent vocabulary to mark up an event:</p>
<pre><code class="html"><body itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
...
<h1 itemprop="summary">Bluesday Tuesday: Money Road</h1>
...
<time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th @ 7pm</time>
(until <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>)
...
<a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
rel="bookmark" itemprop="url">Link to this page</a>
...
<p>Location: <span itemprop="location">The RoadHouse</span></p>
...
<p><input type=button value="Add to Calendar"
onclick="location = getCalendar(this)"></p>
...
<meta itemprop="description" content="via livebrum.co.uk">
</body></code></pre>
<p>The <code data-x="">getCalendar()</code> function is left as an exercise for the reader.</p>
<p>The same page could offer some markup, such as the following,
for copy-and-pasting into blogs:</p>
<pre><code class="html"><div itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
<p>I'm going to
<strong itemprop="summary">Bluesday Tuesday: Money Road</strong>,
<time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th at 7pm</time>
to <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>,
at <span itemprop="location">The RoadHouse</span>!</p>
<p><a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
itemprop="url">See this event on livebrum.co.uk</a>.</p>
<meta itemprop="description" content="via livebrum.co.uk">
</div></code></pre>
</div>
<h4>Licensing works</h4>
<p>An item with the <span data-x="item types">item type</span> <dfn><code data-x="md-work">http://n.whatwg.org/work</code></dfn> represents a work (e.g. an article, an
image, a video, a song, etc.). This type is primarily intended to allow authors to include
licensing information for works.</p>
<p>The following are the type's <span data-x="defined property name">defined property
names</span>.</p>
<dl>
<dt><dfn><code data-x="md-work-work">work</code></dfn></dt>
<dd>
<p>Identifies the work being described.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Exactly one property with the name <code data-x="md-work-work">work</code> must be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-work">http://n.whatwg.org/work</code>.</p>
</dd>
<dt><dfn><code data-x="md-work-title">title</code></dfn></dt>
<dd>
<p>Gives the name of the work.</p>
<p>A single property with the name <code data-x="md-work-title">title</code> may be present
within each <span data-x="concept-item">item</span> with the type <code
data-x="md-work">http://n.whatwg.org/work</code>.</p>
</dd>
<dt><dfn><code data-x="md-work-author">author</code></dfn></dt>
<dd>
<p>Gives the name or contact information of one of the authors or creators of the work.</p>
<p>The <span data-x="concept-property-value">value</span> must be either an <span
data-x="concept-item">item</span> with the type <code
data-x="md-vcard">http://microformats.org/profile/hcard</code>, or text.</p>
<p>Any number of properties with the name <code data-x="md-work-author">author</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-work">http://n.whatwg.org/work</code>.</p>
</dd>
<dt><dfn><code data-x="md-work-license">license</code></dfn></dt>
<dd>
<p>Identifies one of the licenses under which the work is available.</p>
<p>The <span data-x="concept-property-value">value</span> must be an <span>absolute
URL</span>.</p>
<p>Any number of properties with the name <code data-x="md-work-license">license</code> may be
present within each <span data-x="concept-item">item</span> with the type <code
data-x="md-work">http://n.whatwg.org/work</code>.</p>
</dd>
</dl>
<h5>Examples</h5>
<!-- NON-NORMATIVE SECTION -->
<div class="example">
<p>This example shows an embedded image entitled <cite>My Pond</cite>, licensed under the
Creative Commons Attribution-Share Alike 4.0 International License and the MIT license
simultaneously.</p>
<pre><code class="html"><figure <strong>itemscope itemtype="http://n.whatwg.org/work"</strong>>
<img <strong>itemprop="work"</strong> src="mypond.jpeg">
<figcaption>
<p><cite <strong>itemprop="title"</strong>>My Pond</cite></p>
<p><small>Licensed under the <a <strong>itemprop="license"</strong>
href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
Commons Attribution-Share Alike 4.0 International License</a>
and the <a <strong>itemprop="license"</strong>
href="http://www.opensource.org/licenses/mit-license.php">MIT
license</a>.</small>
</figcaption>
</figure></code></pre>
</div>
<div w-nodev>
<h3>Converting HTML to other formats</h3>
<h4>JSON</h4>
<p>Given a list of nodes <var>nodes</var> in a <code>Document</code>, a user agent must
run the following algorithm to <dfn data-x="extracting JSON">extract the microdata from those nodes
into a JSON form</dfn>:</p>
<ol>
<li><p>Let <var>result</var> be an empty object.</p></li>
<li><p>Let <var>items</var> be an empty array.</p></li>
<li><p>For each <var>node</var> in <var>nodes</var>, check if the element is a
<span data-x="top-level microdata items">top-level microdata item</span>, and if it is then
<span>get the object</span> for that element and add it to <var>items</var>.</p></li>
<li><p>Add an entry to <var>result</var> called "<code data-x="">items</code>" whose
value is the array <var>items</var>.</p></li>
<li><p>Return the result of serializing <var>result</var> to JSON in the shortest
possible way (meaning no whitespace between tokens, no unnecessary zero digits in numbers, and
only using Unicode escapes in strings for characters that do not have a dedicated escape
sequence), and with a lowercase "<code data-x="">e</code>" used, when appropriate, in the
representation of any numbers. <ref>JSON</ref></p></li>
</ol>
<p class="note">This algorithm returns an object with a single property that is an array, instead
of just returning an array, so that it is possible to extend the algorithm in the future if
necessary.</p>
<p>When the user agent is to <dfn>get the object</dfn> for an item <var>item</var>,
optionally with a list of elements <var>memory</var>, it must run the following
substeps:</p>
<ol>
<li><p>Let <var>result</var> be an empty object.</p></li>
<li><p>If no <var>memory</var> was passed to the algorithm, let <var>memory</var> be an empty list.</p></li>
<li><p>Add <var>item</var> to <var>memory</var>.</p></li>
<li><p>If the <var>item</var> has any <span>item types</span>, add an entry to <var>result</var> called "<code data-x="">type</code>" whose value is an array listing the
<span>item types</span> of <var>item</var>, in the order they were specified on the
<code data-x="attr-itemtype">itemtype</code> attribute.</p>
<li><p>If the <var>item</var> has a <span>global identifier</span>, add an entry to <var>result</var> called "<code data-x="">id</code>" whose value is the <span>global
identifier</span> of <var>item</var>.</p></li>
<li><p>Let <var>properties</var> be an empty object.</p></li>
<li>
<p>For each element <var>element</var> that has one or more <span>property names</span>
and is one of <span data-x="the properties of an item">the properties of the item</span> <var>item</var>, in the order those elements are given by the algorithm that returns
<span>the properties of an item</span>, run the following substeps:</p>
<ol>
<li><p>Let <var>value</var> be the <span data-x="concept-property-value">property
value</span> of <var>element</var>.</p></li>
<li><p>If <var>value</var> is an <span data-x="concept-item">item</span>, then: If <var>value</var> is in <var>memory</var>, then let <var>value</var> be
the string "<code data-x="">ERROR</code>". Otherwise, <span>get the object</span> for <var>value</var>, passing a copy of <var>memory</var>, and then replace <var>value</var> with the object returned from those steps.</p></li>
<li>
<p>For each name <var>name</var> in <var>element</var>'s <span>property
names</span>, run the following substeps:</p>
<ol>
<li><p>If there is no entry named <var>name</var> in <var>properties</var>,
then add an entry named <var>name</var> to <var>properties</var> whose
value is an empty array.</p></li>
<li><p>Append <var>value</var> to the entry named <var>name</var> in <var>properties</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Add an entry to <var>result</var> called "<code data-x="">properties</code>" whose
value is the object <var>properties</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<div class="example">
<p>For example, take this markup:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<title>My Blog</title>
<article itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h1 itemprop="headline">Progress report</h1>
<p><time itemprop="datePublished" datetime="2013-08-29">today</time></p>
<link itemprop="url" href="?comments=0">
</header>
<p>All in all, he's doing well with his swim lessons. The biggest thing was he had trouble
putting his head in, but we got it down.</p>
<section>
<h1>Comments</h1>
<article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c1">
<link itemprop="url" href="#c1">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Greg</span>
</span></p>
<p><time itemprop="commentTime" datetime="2013-08-29">15 minutes ago</time></p>
</footer>
<p>Ha!</p>
</article>
<article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c2">
<link itemprop="url" href="#c2">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Charlotte</span>
</span></p>
<p><time itemprop="commentTime" datetime="2013-08-29">5 minutes ago</time></p>
</footer>
<p>When you say "we got it down"...</p>
</article>
</section>
</article></code></pre>
<p>It would be turned into the following JSON by the algorithm above (supposing that the page's
URL was <code data-x="">https://blog.example.com/progress-report</code>):</p>
<pre><code data-x="" class="json">{
"items": [
{
"type": [ "http://schema.org/BlogPosting" ],
"properties": {
"headline": [ "Progress report" ],
"datePublished": [ "2013-08-29" ],
"url": [ "https://blog.example.com/progress-report?comments=0" ],
"comment": [
{
"type": [ "http://schema.org/UserComments" ],
"properties": {
"url": [ "https://blog.example.com/progress-report#c1" ],
"creator": [
{
"type": [ "http://schema.org/Person" ],
"properties": {
"name": [ "Greg" ]
}
}
],
"commentTime": [ "2013-08-29" ]
}
},
{
"type": [ "http://schema.org/UserComments" ],
"properties": {
"url": [ "https://blog.example.com/progress-report#c2" ],
"creator": [
{
"type": [ "http://schema.org/Person" ],
"properties": {
"name": [ "Charlotte" ]
}
}
],
"commentTime": [ "2013-08-29" ]
}
}
]
}
}
]
}</code></pre>
</div>
</div>
<h2 split-filename="interaction" id="editing"><dfn>User interaction</dfn></h2>
<h3>The <code data-x="attr-hidden">hidden</code> attribute</h3>
<p>All <span>HTML elements</span> may have the <dfn element-attr for="html-global"><code
data-x="attr-hidden">hidden</code></dfn> content attribute set. The <code
data-x="attr-hidden">hidden</code> attribute is an <span>enumerated attribute</span> with the
following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/hidden"><code data-x="attr-hidden-hidden">hidden</code></dfn>
<td rowspan=2><dfn data-x="attr-hidden-hidden-state">hidden</dfn>
<td rowspan=2>Will not be rendered.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/hidden"><code data-x="attr-hidden-until-found">until-found</code></dfn>
<td><dfn data-x="attr-hidden-until-found-state">hidden until found</dfn>
<td>Will not be rendered, but content inside will be accessible to <span>find-in-page</span>
and <span data-x="navigate-fragid">fragment navigation</span>.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <dfn
data-x="attr-hidden-not-hidden-state">not hidden</dfn> state, and its <i data-x="invalid value
default">invalid value default</i> is the <span data-x="attr-hidden-hidden-state">hidden</span>
state.</p>
<p>When an element has the <code data-x="attr-hidden">hidden</code> attribute in the <span
data-x="attr-hidden-hidden-state">hidden</span> state, it indicates that the element is not yet, or
is no longer, directly relevant to the page's current state, or that it is being used to declare
content to be reused by other parts of the page as opposed to being directly accessed by the user.
User agents should not render elements that are in the <span
data-x="attr-hidden-hidden-state">hidden</span> state.</p>
<div w-nodev>
<p class="note">The requirement for user agents not to render elements that are in the <span
data-x="attr-hidden-hidden-state">hidden</span> state can be implemented indirectly through the
style layer. For example, a web browser could implement these requirements <a
href="#hiddenCSS">using the rules suggested in the Rendering section</a>.</p>
</div>
<p>When an element has the <code data-x="attr-hidden">hidden</code> attribute in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state, it indicates that the
element is hidden like the <span data-x="attr-hidden-hidden-state">hidden</span> state but the
content inside the element will be accessible to <span>find-in-page</span> and <span
data-x="navigate-fragid">fragment navigation</span>. When these features attempt to scroll to a
target which is in the element's subtree, the user agent will remove the <code
data-x="attr-hidden">hidden</code> attribute in order to reveal the content before scrolling to
it by running the <span>ancestor hidden-until-found revealing algorithm</span> on the target
node.</p>
<div w-nodev>
<p class="note">Web browsers will use 'content-visibility: hidden' instead of 'display: none'
when the <code data-x="attr-hidden">hidden</code> attribute is in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state, as specified in the <a
href="#hiddenCSS">Rendering section</a>.</p>
</div>
<div class="note">
<p>Because this attribute is typically implemented using CSS, it's also possible to override it
using CSS. For instance, a rule that applies 'display: block' to all elements will cancel the
effects of the <span data-x="attr-hidden-hidden-state">hidden</span> state. Authors therefore
have to take care when writing their style sheets to make sure that the attribute is still styled
as expected. In addition, legacy user agents which don't support the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state will have 'display: none'
instead of 'content-visibility: hidden', so authors are encouraged to make sure that their style
sheets don't change the 'display' or 'content-visibility' properties of <span
data-x="attr-hidden-until-found-state">hidden until found</span> elements.</p>
<p>Since elements with the <code data-x="attr-hidden">hidden</code> attribute in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state use 'content-visibility:
hidden' instead of 'display: none', there are two caveats of the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state that make it different
from the <span data-x="attr-hidden-hidden-state">hidden</span> state:</p>
<ol>
<li><p>The element needs to be affected by <span>layout containment</span> in order to be
revealed by find-in-page. This means that if the element in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state has a 'display' value of
'none', 'contents', or 'inline', then the element will not be revealed by find-in-page.</p></li>
<li><p>The element will still have a <span data-x="'visibility'">generated box</span> when in
the <span data-x="attr-hidden-until-found-state">hidden until found</span> state, which means
that borders, margin, and padding will still be rendered around the element.</p></li>
</ol>
</div>
<div class="example">
<p>In the following skeletal example, the attribute is used to hide the web game's main screen
until the user logs in:</p>
<pre><code class="html"> <h1>The Example Game</h1>
<section id="login">
<h2>Login</h2>
<form>
...
<!-- calls login() once the user's credentials have been checked -->
</form>
<script>
function login() {
// switch screens
document.getElementById('login').hidden = true;
document.getElementById('game').hidden = false;
}
</script>
</section>
<section id="game" hidden>
...
</section></code></pre>
</div>
<p>The <code data-x="attr-hidden">hidden</code> attribute must not be used to hide content that
could legitimately be shown in another presentation. For example, it is incorrect to use <code
data-x="attr-hidden">hidden</code> to hide panels in a tabbed dialog, because the tabbed interface
is merely a kind of overflow presentation — one could equally well just show all the form
controls in one big page with a scrollbar. It is similarly incorrect to use this attribute to hide
content just from one presentation — if something is marked <code
data-x="attr-hidden">hidden</code>, it is hidden from all presentations, including, for instance,
screen readers.</p>
<!-- for example, "<a hidden href=#content>Skip to content</a>" would be inappropriate. -->
<!-- (but only add that example if you first add some more good valid examples -->
<p>Elements that are not themselves <code data-x="attr-hidden">hidden</code> must not
<span>hyperlink</span> to elements that are <code data-x="attr-hidden">hidden</code>. The <code
data-x="">for</code> attributes of <code>label</code> and <code>output</code> elements that are not
themselves <code data-x="attr-hidden">hidden</code> must similarly not refer to elements that are
<code data-x="attr-hidden">hidden</code>. In both cases, such references would cause user
confusion.</p>
<p>Elements and scripts may, however, refer to elements that are <code
data-x="attr-hidden">hidden</code> in other contexts.</p>
<div class="example">
<p>For example, it would be incorrect to use the <code data-x="attr-hyperlink-href">href</code>
attribute to link to a section marked with the <code data-x="attr-hidden">hidden</code> attribute.
If the content is not applicable or relevant, then there is no reason to link to it.</p>
<p>It would be fine, however, to use the ARIA <code
data-x="attr-aria-describedby">aria-describedby</code> attribute to refer to descriptions that are
themselves <code data-x="attr-hidden">hidden</code>. While hiding the descriptions implies that
they are not useful alone, they could be written in such a way that they are useful in the
specific context of being referenced from the elements that they describe.</p>
<p>Similarly, a <code>canvas</code> element with the <code data-x="attr-hidden">hidden</code>
attribute could be used by a scripted graphics engine as an off-screen buffer, and a form control
could refer to a hidden <code>form</code> element using its <code
data-x="attr-fae-form">form</code> attribute.</p>
</div>
<p>Elements in a section hidden by the <code data-x="attr-hidden">hidden</code> attribute are still
active, e.g. scripts and form controls in such sections still execute and submit respectively.
Only their presentation to the user changes.</p>
<div w-nodev>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-hidden">hidden</code></dfn> getter steps
are:</p>
<ol>
<li><p>If the <code data-x="attr-hidden">hidden</code> attribute is in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state, then return "<code
data-x="attr-hidden-until-found">until-found</code>".</p></li>
<li><p>If the <code data-x="attr-hidden">hidden</code> attribute is set, then return
true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>The <code data-x="dom-hidden">hidden</code> setter steps are:</p>
<ol>
<li><p>If the given value is a string that is an <span>ASCII case-insensitive</span> match for
"<code data-x="attr-hidden-until-found">until-found</code>", then set the <code
data-x="attr-hidden">hidden</code> attribute to "<code
data-x="attr-hidden-until-found">until-found</code>".</p></li>
<li><p>Otherwise, if the given value is false, then remove the <code
data-x="attr-hidden">hidden</code> attribute.</p></li>
<li><p>Otherwise, if the given value is the empty string, then remove the <code
data-x="attr-hidden">hidden</code> attribute.</p></li>
<li><p>Otherwise, if the given value is null, then remove the <code
data-x="attr-hidden">hidden</code> attribute.</p></li>
<li><p>Otherwise, if the given value is 0, then remove the <code
data-x="attr-hidden">hidden</code> attribute.</p></li>
<li><p>Otherwise, if the given value is NaN, then remove the <code
data-x="attr-hidden">hidden</code> attribute.</p></li>
<li><p>Otherwise, set the <code data-x="attr-hidden">hidden</code> attribute to the empty
string.</p></li>
</ol>
<p>The <dfn>ancestor hidden-until-found revealing algorithm</dfn> is to run the following steps on
<var>currentNode</var>:</p>
<ol>
<li>
<p>While <var>currentNode</var> has a parent node within the <span>flat tree</span>:</p>
<ol>
<li>
<p>If <var>currentNode</var> has the <code data-x="attr-hidden">hidden</code> attribute in the
<span data-x="attr-hidden-until-found-state">hidden until found</span> state, then:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-beforematch">beforematch</code> at <var>currentNode</var> with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
<li><p>Remove the <code data-x="attr-hidden">hidden</code> attribute from
<var>currentNode</var>.</p></li>
</ol>
</li>
<li><p>Set <var>currentNode</var> to the parent node of <var>currentNode</var> within the
<span>flat tree</span>.</p></li>
</ol>
</li>
</ol>
</div>
<h3>Page visibility</h3>
<p>A <span>traversable navigable</span>'s <span>system visibility state</span>, including its
initial value upon creation, is determined by the user agent. It represents, for example, whether
the browser window is minimized, a browser tab is currently in the background, or a system
element such as a task switcher obscures the page.</p>
<p>When a user-agent determines that the <span>system visibility state</span> for
<span>traversable navigable</span> <var>traversable</var> has changed to <var>newState</var>, it
must run the following steps:</p>
<ol>
<li><p>Let <var>navigables</var> be the <span>inclusive descendant navigables</span> of
<var>traversable</var>'s <span data-x="nav-document">active document</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of <var>navigables</var>
<span data-x="" class="XXX">in what order?</span>:</p>
<ol>
<li><p>Let <var>document</var> be <var>navigable</var>'s <span data-x="nav-document">active
document</span>.</p></li>
<li><p><span>Queue a global task</span> on the <span>user interaction task source</span> given
<var>document</var>'s <span>relevant global object</span> to <span>update the visibility
state</span> of <var>document</var> with <var>newState</var>.</p></li>
</ol>
</li>
</ol>
<p>A <code>Document</code> has a <dfn for="Document" export>visibility state</dfn>, which is
either "<code data-x="">hidden</code>" or "<code data-x="">visible</code>", initially set to
"<code data-x="">hidden</code>".</p>
<p>The <dfn attribute for="Document"><code
data-x="dom-document-visibilityState">visibilityState</code></dfn> getter steps are to return
<span>this</span>'s <span>visibility state</span>.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-hidden">hidden</code></dfn> getter
steps are to return true if <span>this</span>'s <span>visibility state</span> is
"<code data-x="">hidden</code>", otherwise false.</p>
<p>To <dfn>update the visibility state</dfn> of <code>Document</code> <var>document</var> to
<var>visibilityState</var>:</p>
<ol>
<li><p>If <var>document</var>'s <span>visibility state</span> equals <var>visibilityState</var>,
then return.</p></li>
<li><p>Set <var>document</var>'s <span>visibility state</span> to
<var>visibilityState</var>.</p></li>
<li><p><span data-x="queue a performance entry">Queue</span> a new
<code>VisibilityStateEntry</code> whose
<span data-x="VisibilityStateEntry-state">visibility state</span> is
<var>visibilityState</var> and whose <span
data-x="VisibilityStateEntry-timestamp">timestamp</span> is
the <span>current high resolution time</span> given <var>document</var>'s
<span>relevant global object</span>.</p>
<li><p>Run the <span>screen orientation change steps</span> with <var>document</var>.
<ref>SCREENORIENTATION</ref></p></li>
<li><p>Run the <span>view transition page visibility change steps</span> with
<var>document</var>.</p></li>
<li>
<p>Run any <dfn export>page visibility change steps</dfn> which may be defined in other
specifications, with <span>visibility state</span> and <var>document</var>.</p>
<p class="XXX">It would be better if specification authors sent a pull request to add calls
from here into their specifications directly, instead of using the <span>page visibility change
steps</span> hook, to ensure well-defined cross-specification call order. As of the time of
this writing the following specifications are known to have <span>page visibility change
steps</span>, which will be run in an unspecified order: <cite>Device Posture API</cite> and
<cite>Web NFC</cite>. <ref>DEVICEPOSTURE</ref> <ref>WEBNFC</ref></p>
</li>
<li><p>Fire an event named <code data-x="event-visibilitychange">visibilitychange</code> at
<var>document</var>, with its <code data-x="dom-Event-bubbles">bubbles</code> attribute
initialized to true.</p></li>
</ol>
<h4>The <code>VisibilityStateEntry</code> interface</h4>
<p>The <code>VisibilityStateEntry</code> interface exposes visibility changes to the document,
from the moment the document becomes active.</p>
<div class="example">For example, this allows JavaScript code in the page to examine correlation
between visibility changes and paint timing:
<pre><code class="js">function wasHiddenBeforeFirstContentfulPaint() {
const fcpEntry = performance.getEntriesByName("first-contentful-paint")[0];
const visibilityStateEntries = performance.getEntriesByType("visibility-state");
return visibilityStateEntries.some(e =>
e.startTime < fcpEntry.startTime &&
e.name === "hidden");
}</code></pre>
</div>
<p class="note">Since hiding a page can cause throttling of rendering and other user-agent
operations, it is common to use visibility changes as an indication that such throttling has
occurred. However, other things could also cause throttling in different browsers, such as
long periods of inactivity.</p>
<pre><code class="idl">[Exposed=(Window)]
interface <dfn interface>VisibilityStateEntry</dfn> : <span>PerformanceEntry</span> {
readonly attribute DOMString <span data-x="VisibilityStateEntry-name">name</span>; // shadows inherited <span data-x="PerformanceEntry-name">name</span>
readonly attribute DOMString <span data-x="VisibilityStateEntry-entryType">entryType</span>; // shadows inherited <span data-x="PerformanceEntry-entryType">entryType</span>
readonly attribute DOMHighResTimeStamp <span data-x="VisibilityStateEntry-startTime">startTime</span>; // shadows inherited <span data-x="PerformanceEntry-startTime">startTime</span>
readonly attribute unsigned long <span data-x="VisibilityStateEntry-duration">duration</span>; // shadows inherited <span data-x="PerformanceEntry-duration">duration</span>
};</code></pre>
<p>The <code>VisibilityStateEntry</code> has an associated
<span><code>DOMHighResTimeStamp</code></span>
<dfn data-x="VisibilityStateEntry-timestamp">timestamp</dfn>.</p>
<p>The <code>VisibilityStateEntry</code> has an associated "<code data-x="">visible</code>" or
"<code data-x="">hidden</code>" <dfn data-x="VisibilityStateEntry-state">visibility
state</dfn>.</p>
<p>The <dfn attribute for="VisibilityStateEntry"
data-x="VisibilityStateEntry-name"><code>name</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="VisibilityStateEntry-state">visibility state</span>.</p>
<p>The <dfn attribute for="VisibilityStateEntry"
data-x="VisibilityStateEntry-entryType"><code>entryType</code></dfn> getter steps are to return
"<code data-x="">visibility-state</code>".</p>
<p>The <dfn attribute for="VisibilityStateEntry"
data-x="VisibilityStateEntry-startTime"><code>startTime</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="VisibilityStateEntry-timestamp">timestamp</span>.</p>
<p>The <dfn attribute for="VisibilityStateEntry"
data-x="VisibilityStateEntry-duration"><code>duration</code></dfn> getter steps are to return
zero.</p>
<h3>Inert subtrees</h3>
<p class="note">See also <code data-x="attr-inert">inert</code> for an explanation of the
attribute of the same name.</p>
<p>A node (in particular elements and text nodes) can be <dfn>inert</dfn>. When a node is
<span>inert</span>:</p>
<ul>
<li><p>Hit-testing must act as if the <span>'pointer-events'</span> CSS property were set to
'none'.</p></li>
<li><p>Text selection functionality must act as if the <span>'user-select'</span> CSS property
were set to 'none'.</p></li>
<li><p>If it is <span>editable</span>, the node behaves as if it were non-editable.</p></li>
<li><p>The user agent should ignore the node for the purposes of <span>find-in-page</span>.</p></li>
</ul>
<p class="note">Inert nodes generally cannot be focused, and user agents do not expose the inert
nodes to accessibility APIs or assistive technologies. Inert nodes that are <span
data-x="concept-command">commands</span> will become inoperable to users, in the manner described
above.</p>
<p>User agents may allow the user to override the restrictions on <span>find-in-page</span> and
text selection, however.</p>
<p>By default, a node is not <span>inert</span>.</p>
<h4>Modal dialogs and inert subtrees</h4>
<p>A <code>Document</code> <var>document</var> is <dfn>blocked by a modal dialog</dfn>
<var>subject</var> if <var>subject</var> is the topmost <code>dialog</code> element in
<var>document</var>'s <span>top layer</span>. While <var>document</var> is so blocked, every node
that is <span>connected</span> to <var>document</var>, with the exception of the
<var>subject</var> element and its <span>flat tree</span> descendants, must become
<span>inert</span>.</p>
<p><var>subject</var> can additionally become <span>inert</span> via the <code
data-x="attr-inert">inert</code> attribute, but only if specified on <var>subject</var> itself
(i.e., <var>subject</var> escapes inertness of ancestors); <var>subject</var>'s <span>flat
tree</span> descendants can become <span>inert</span> in a similar fashion.</p>
<p class="note">The <code>dialog</code> element's <code
data-x="dom-dialog-showModal">showModal()</code> method causes this mechanism to trigger, by <span
data-x="add an element to the top layer">adding</span> the <code>dialog</code> element to its
<span>node document</span>'s <span>top layer</span>.</p>
<h4>The <dfn data-x="attr-inert"><code>inert</code></dfn> attribute</h4>
<p>The <code data-x="attr-inert">inert</code> attribute is a <span>boolean attribute</span> that
indicates, by its presence, that the element and all its <span>flat tree</span> descendants which
don't otherwise escape inertness (such as modal dialogs) are to be made <span>inert</span> by the
user agent.</p>
<p>An inert subtree should not contain any content or controls which are critical to
understanding or using aspects of the page which are not in the inert state. Content in an inert
subtree will not be perceivable by all users, or interactive. Authors should not specify elements
as inert unless the content they represent are also visually obscured in some way. In most cases,
authors should not specify the <code>inert</code> attribute on individual form controls. In these
instances, the <code data-x="attr-fe-disabled">disabled</code> attribute is probably more
appropriate.</p>
<div class="example">
<p>The following example shows how to mark partially loaded content, visually obscured by a
"loading" message, as inert.</p>
<pre><code class="html"><section aria-labelledby=s1>
<h3 id=s1>Population by City</h3>
<div class=container>
<div class=loading><p>Loading...</p></div>
<div inert>
<form>
<fieldset>
<legend>Date range</legend>
<div>
<label for=start>Start</label>
<input type=date id=start>
</div>
<div>
<label for=end>End</label>
<input type=date id=end>
</div>
<div>
<button>Apply</button>
</div>
</fieldset>
</form>
<table>
<caption>From 20-- to 20--</caption>
<thead>
<tr>
<th>City</th>
<th>State</th>
<th>20-- Population</th>
<th>20-- Population</th>
<th>Percentage change</th>
</tr>
</thead>
<tbody>
<!-- ... -->
</tbody>
</table>
</div>
</div>
</section></code></pre>
<img src="/images/inert-example-loading-section.png" width="947" height="243" alt="Screenshot of Population by City content with an overlaid loading message which visually obscures the form controls and data table which have not fully rendered, and thus are in the inert state.">
<p>The "loading" overlay obscures the inert content, making it visually apparent that the inert
content is not presently accessible. Notice that the heading and "loading" text are not
descendants of the element with the <code>inert</code> attribute. This will ensure this text is
accessible to all users, while the inert content cannot be interacted with by anyone.</p>
</div>
<div class="note">
<p>By default, there is no persistent visual indication of an element or its subtree being
inert. Appropriate visual styles for such content is often context-dependent. For instance, an
inert off-screen navigation panel would not require a default style, as its off-screen position
visually obscures the content. Similarly, a modal <code>dialog</code> element's backdrop will
serve as the means to visually obscure the inert content of the web page, rather than styling
the inert content specifically.</p>
<p>However, for many other situations authors are strongly encouraged to clearly mark what parts
of their document are active and which are inert, to avoid user confusion. In particular, it is
worth remembering that not all users can see all parts of a page at once; for example, users of
screen readers, users on small devices or with magnifiers, and even users using particularly
small windows might not be able to see the active part of a page and might get frustrated if
inert sections are not obviously inert.</p>
</div>
<p>The <dfn attribute for="HTMLElement" data-x="dom-inert"><code>inert</code></dfn> IDL attribute
must <span>reflect</span> the content attribute of the same name.</p>
<h3>Tracking <dfn export>user activation</dfn></h3>
<p>To prevent abuse of certain APIs that could be annoying to users (e.g., opening popups or
vibrating phones), user agents allow these APIs only when the user is actively interacting with
the web page or has interacted with the page at least once. This "active interaction" state is
maintained through the mechanisms defined in this section.</p>
<div w-nodev>
<h4 id="user-activation-data-model">Data model</h4>
<p>For the purpose of tracking user activation, each <code>Window</code> <var>W</var> has two
relevant values:</p>
<ul>
<li><p>A <dfn>last activation timestamp</dfn>, which is either a
<code>DOMHighResTimeStamp</code>, positive infinity (indicating that <var>W</var> has never been
activated), or negative infinity (indicating that the activation has been <span data-x="consume
user activation">consumed</span>). Initially positive infinity.</p></li>
<li><p>A <dfn>last history-action activation timestamp</dfn>, which is either a
<code>DOMHighResTimeStamp</code> or positive infinity, initially positive infinity.</p></li>
</ul>
<p>A user agent also defines a <dfn>transient activation duration</dfn>, which is a constant
number indicating how long a user activation is available for certain <a
href="#user-activation-gated-apis">user activation-gated APIs</a> (e.g., for opening popups).</p>
<p class="note">The <span>transient activation duration</span> is expected be at most a few
seconds, so that the user can possibly perceive the link between an interaction with the page and
the page calling the activation-gated API.</p>
<p>We then have the following boolean user activation states for <var>W</var>:</p>
<dl>
<dt><dfn export>Sticky activation</dfn></dt>
<dd>
<p>When the <span>current high resolution time</span> given <var>W</var> is greater than or
equal to the <span>last activation timestamp</span> in <var>W</var>, <var>W</var> is said to
have <span>sticky activation</span>.</p>
<p>This is <var>W</var>'s historical activation state, indicating whether the user has ever
interacted in <var>W</var>. It starts false, then changes to true (and never changes back to
false) when <var>W</var> gets the very first <span>activation notification</span>.</p>
</dd>
<dt><dfn export>Transient activation</dfn></dt>
<dd>
<p>When the <span>current high resolution time</span> given <var>W</var> is greater than or
equal to the <span>last activation timestamp</span> in <var>W</var>, and less than the
<span>last activation timestamp</span> in <var>W</var> plus the <span>transient activation
duration</span>, then <var>W</var> is said to have <span>transient activation</span>.</p>
<p>This is <var>W</var>'s current activation state, indicating whether the user has interacted
in <var>W</var> recently. This starts with a false value, and remains true for a limited time
after every <span>activation notification</span> <var>W</var> gets.</p>
<p>The <span>transient activation</span> state is considered <dfn
data-x="activation-expiry">expired</dfn> if it becomes false because the <span>transient
activation duration</span> time has elapsed since the last user activation. Note that it can
become false even before the expiry time through an <span data-x="consume user
activation">activation consumption</span>.</p>
</dd>
<dt><dfn>History-action activation</dfn></dt>
<dd>
<p>When the <span>last history-action activation timestamp</span> of <var>W</var> is not equal
to the <span>last activation timestamp</span> of <var>W</var>, then <var>W</var> is said to have
<span>history-action activation</span>.</p>
<p>This is a special variant of user activation, used to allow access to certain session history
APIs which, if used too frequently, would make it harder for the user to traverse back using <a
href="#nav-traversal-ui">browser UI</a>. It starts with a false value, and becomes true whenever
the user interacts with <var>W</var>, but is reset to false through <span data-x="consume
history-action user activation">history-action activation consumption</span>. This ensures such
APIs cannot be used multiple times in a row without an intervening user activation. But unlike
<span>transient activation</span>, there is no time limit within which such APIs must be
used.</p>
</dd>
</dl>
<p class="note">The <span>last activation timestamp</span> and <span>last history-action
activation timestamp</span> are retained even after the <code>Document</code> changes its
<span>fully active</span> status (e.g., after navigating away from a <code>Document</code>, or
navigating to a cached <code>Document</code>). This means <span>sticky activation</span> state
spans multiple navigations as long as the same <code>Document</code> gets reused. For the
transient activation state, the original <span data-x="activation-expiry">expiry</span> time
remains unchanged (i.e., the state still expires within the <span>transient activation
duration</span> limit from the original <span>activation triggering input event</span>). It is
important to consider this when deciding whether to base certain things off <span>sticky
activation</span> or <span>transient activation</span>.</p>
<h4 id="user-activation-processing-model">Processing model</h4>
<p>When a user interaction causes firing of an <span>activation triggering input
event</span> in a <code>Document</code> <var>document</var>, the user agent must perform the
following <dfn>activation notification</dfn> steps <em>before</em> <span
data-x="concept-event-dispatch">dispatching</span> the event:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var> is <span>fully active</span>.</p></li>
<li><p>Let <var>windows</var> be « <var>document</var>'s <span>relevant global object</span>
».</p></li>
<li><p><span data-x="list extend">Extend</span> <var>windows</var> with the <span
data-x="nav-window">active window</span> of each of <var>document</var>'s <span>ancestor
navigables</span>.</p></li>
<li><p><span data-x="list extend">Extend</span> <var>windows</var> with the <span
data-x="nav-window">active window</span> of each of <var>document</var>'s <span>descendant
navigables</span>, filtered to include only those <span data-x="navigable">navigables</span>
whose <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin</span> with
<var>document</var>'s <span data-x="concept-document-origin">origin</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>window</var> in <var>windows</var>:</p>
<ol>
<li><p>Set <var>window</var>'s <span>last activation timestamp</span> to the <span>current
high resolution time</span>.</p></li>
<li><p><span>Notify the close watcher manager about user activation</span> given
<var>window</var>.</p></li>
</ol>
</li>
</ol>
<p>An <dfn>activation triggering input event</dfn> is any event whose <code
data-x="dom-Event-isTrusted">isTrusted</code> attribute is true and whose <code
data-x="dom-Event-type">type</code> is one of:</p>
<ul>
<li><p>"<code data-x="event-keydown">keydown</code>", provided the key is neither the
<kbd>Esc</kbd> key nor a shortcut key reserved by the user agent;</li>
<li><p>"<code data-x="event-mousedown">mousedown</code>";</p></li>
<li><p>"<code data-x="event-pointerdown">pointerdown</code>", provided the event's
<code>pointerType</code> is "<code data-x="">mouse</code>";</p></li>
<li><p>"<code data-x="event-pointerup">pointerup</code>", provided the event's
<code>pointerType</code> is not "<code data-x="">mouse</code>"; or</p></li>
<li><p>"<code data-x="event-touchend">touchend</code>".</p></li>
</ul>
<p><span data-x="activation consuming API">Activation consuming APIs</span> defined in this and
other specifications can <dfn export>consume user activation</dfn> by performing the following
steps, given a <code>Window</code> <var>W</var>:</p>
<ol>
<li><p>If <var>W</var>'s <span data-x="window navigable">navigable</span> is null, then
return.</p></li>
<li><p>Let <var>top</var> be <var>W</var>'s <span data-x="window navigable">navigable</span>'s
<span data-x="nav-top">top-level traversable</span>.</p></li>
<li><p>Let <var>navigables</var> be the <span>inclusive descendant navigables</span> of
<var>top</var>'s <span data-x="nav-document">active document</span>.</p></li>
<li><p>Let <var>windows</var> be the list of <code>Window</code> objects constructed by taking
the <span data-x="nav-window">active window</span> of each item in
<var>navigables</var>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>window</var> in <var>windows</var>, if
<var>window</var>'s <span>last activation timestamp</span> is not positive infinity, then set
<var>window</var>'s <span>last activation timestamp</span> to negative infinity.</p></li>
</ol>
<p><span data-x="history-action activation-consuming API">History-action activation-consuming
APIs</span> can <dfn>consume history-action user activation</dfn> by performing the following
steps, given a <code>Window</code> <var>W</var>:</p>
<ol>
<li><p>If <var>W</var>'s <span data-x="window navigable">navigable</span> is null, then
return.</p></li>
<li><p>Let <var>top</var> be <var>W</var>'s <span data-x="window navigable">navigable</span>'s
<span data-x="nav-top">top-level traversable</span>.</p></li>
<li><p>Let <var>navigables</var> be the <span>inclusive descendant navigables</span> of
<var>top</var>'s <span data-x="nav-document">active document</span>.</p></li>
<li><p>Let <var>windows</var> be the list of <code>Window</code> objects constructed by taking
the <span data-x="nav-window">active window</span> of each item in
<var>navigables</var>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>window</var> in <var>windows</var>, set
<var>window</var>'s <span>last history-action activation timestamp</span> to <var>window</var>'s
<span>last activation timestamp</span>.</p></li>
</ol>
<p class="note">Note the asymmetry in the sets of <span data-x="browsing context">browsing
contexts</span> in the page that are affected by an <span>activation notification</span> vs an
<span data-x="consume user activation">activation consumption</span>: an activation consumption
changes (to false) the <span>transient activation</span> states for all browsing contexts in the
page, but an activation notification changes (to true) the states for a subset of those browsing
contexts. The exhaustive nature of consumption here is deliberate: it prevents malicious sites
from making multiple calls to an <span>activation consuming API</span> from a single user
activation (possibly by exploiting a deep hierarchy of <code>iframe</code>s).</p>
<h4 id="user-activation-gated-apis">APIs gated by user activation</h4>
</div>
<p>APIs that are dependent on user activation are classified into different levels:</p>
<dl>
<dt><dfn export data-x="sticky activation gated api" data-lt="sticky activation-gated API">Sticky activation-gated APIs</dfn></dt>
<dd><p>These APIs require the <span>sticky activation</span> state to be true, so they are
blocked until the very first user activation.</p></dd>
<dt><dfn export data-x="transient activation gated api" data-lt="transient activation-gated
API">Transient activation-gated APIs</dfn></dt>
<dd><p>These APIs require the <span>transient activation</span> state to be true, but they don't
<span data-x="consume user activation">consume</span> it, so multiple calls are allowed per user
activation until the transient state <span data-x="activation-expiry">expires</span>.</p></dd>
<dt><dfn export data-x="activation consuming api" data-lt="transient activation-consuming API">Transient activation-consuming APIs</dfn></dt>
<dd><p>These APIs require the <span>transient activation</span> state to be true, and they
<span>consume user activation</span> in each call to prevent multiple calls per user
activation.</p></dd>
<dt><dfn export data-x="history-action activation-consuming API" data-lt="history-action activation-consuming API">History-action activation-consuming APIs</dfn></dt>
<dd><p>These APIs require the <span>history-action activation</span> state to be true, and they
<span>consume history-action user activation</span> in each call to prevent multiple calls per
user activation.</p></dd>
</dl>
<h4>The <code>UserActivation</code> interface</h4>
<p>Each <code>Window</code> has an <dfn>associated <code>UserActivation</code></dfn>, which is a
<code>UserActivation</code> object. Upon creation of the <code>Window</code> object, its
<span>associated <code>UserActivation</code></span> must be set to a <span>new</span>
<code>UserActivation</code> object created in the <code>Window</code> object's <span
data-x="concept-relevant-realm">relevant realm</span>.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>UserActivation</dfn> {
readonly attribute boolean <span data-x="dom-UserActivation-hasBeenActive">hasBeenActive</span>;
readonly attribute boolean <span data-x="dom-UserActivation-isActive">isActive</span>;
};
partial interface <span id="NavigatorUserActivation-partial">Navigator</span> {
[SameObject] readonly attribute <code>UserActivation</code> <span data-x="dom-Navigator-userActivation">userActivation</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-Navigator-userActivation">userActivation</span>.<span subdfn data-x="dom-UserActivation-hasBeenActive">hasBeenActive</span></code></dt>
<dd>
<p>Returns whether the window has <span>sticky activation</span>.</p>
</dd>
<dt><code data-x=""><span data-x="dom-navigator">navigator</span>.<span data-x="dom-Navigator-userActivation">userActivation</span>.<span subdfn data-x="dom-UserActivation-isActive">isActive</span></code></dt>
<dd>
<p>Returns whether the window has <span>transient activation</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Navigator"><code
data-x="dom-Navigator-userActivation">userActivation</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant global object</span>'s <span>associated
<code>UserActivation</code></span>.</p>
<p>The <dfn attribute for="UserActivation"><code
data-x="dom-UserActivation-hasBeenActive">hasBeenActive</code></dfn> getter steps are to return
true if <span>this</span>'s <span>relevant global object</span> has <span>sticky
activation</span>, and false otherwise.</p>
<p>The <dfn attribute for="UserActivation"><code
data-x="dom-UserActivation-isActive">isActive</code></dfn> getter steps are to return true if
<span>this</span>'s <span>relevant global object</span> has <span>transient activation</span>,
and false otherwise.</p>
<h4 id="user-activation-user-agent-automation">User agent automation</h4>
<p>For the purposes of user-agent automation and application testing, this specification defines
the following <span>extension command</span> for the <cite>Web Driver</cite> specification. It is
optional for a user agent to support the following <span>extension command</span>.
<ref>WEBDRIVER</ref></p>
<table class="data">
<thead>
<tr>
<th>HTTP Method</th>
<th>URI Template</th>
</tr>
</thead>
<tbody>
<tr>
<td>`<code data-x="">POST</code>`</td>
<td><code data-x="">/session/{<var>session id</var>}/window/consume-user-activation</code></td>
</tr>
</tbody>
</table>
<p>The <span>remote end steps</span> are:</p>
<ol>
<li><p>Let <var>window</var> be <span data-x="webdriver-current-browsing-context">current
browsing context</span>'s <span>active window</span>.</p></li>
<li><p>Let <var>consume</var> be true if <var>window</var> has <span>transient activation</span>;
otherwise false.</p></li>
<li><p>If <var>consume</var> is true, then <span>consume user activation</span> of
<var>window</var>.</p></li>
<li><p>Return <span data-x="success-value">success</span> with data <var>consume</var>.</p></li>
</ol>
</div>
<h3 id="activation">Activation behavior of elements</h3>
<p>Certain elements in HTML have an <span>activation behavior</span>, which means that the user
can activate them. This is always caused by a <code data-x="event-click">click</code> event.</p>
<div w-nodev>
<p>The user agent should allow the user to manually trigger elements that have an <span>activation
behavior</span>, for instance using keyboard or voice input, or through mouse clicks. When the
user triggers an element with a defined <span>activation behavior</span> in a manner other than
clicking it, the default action of the interaction event must be to <span>fire a <code
data-x="event-click">click</code> event</span> at the element.</p>
</div>
<!-- v2 idea: HTMLImageElement.click(x, y); or clickPoint(), if click() can't be done in IE; can
this be emulated in IE by posting a synthetic pointer click event with those X and Y coords?
(ack Csaba Gabor)
-->
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-click">click</span>()</code></dt>
<dd><p>Acts as if the element was clicked.</p></dd>
</dl>
<div w-nodev>
<p>Each element has an associated <dfn>click in progress flag</dfn>, which is initially unset.</p>
<p>The <dfn method for="HTMLElement"><code data-x="dom-click">click()</code></dfn> method must run
the following steps:</p>
<ol>
<li><p>If this element is a form control that is <span
data-x="concept-fe-disabled">disabled</span>, then return.</p></li>
<li><p>If this element's <span>click in progress flag</span> is set, then return.</p></li>
<li><p>Set this element's <span>click in progress flag</span>.</p></li>
<li><p><span>Fire a synthetic pointer event</span> named <code data-x="event-click">click</code>
at this element, with the <var>not trusted flag</var> set.</p></li>
<li><p>Unset this element's <span>click in progress flag</span>.</p></li>
</ol>
</div>
<h4>The <code>ToggleEvent</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>ToggleEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>ToggleEventInit</span> eventInitDict = {});
readonly attribute DOMString <span data-x="dom-ToggleEvent-oldState">oldState</span>;
readonly attribute DOMString <span data-x="dom-ToggleEvent-newState">newState</span>;
};
dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
DOMString oldState = "";
DOMString newState = "";
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn
data-x="dom-ToggleEvent-oldState">oldState</span></code></dt>
<dd>
<p>Set to "<code data-x="">closed</code>" when transitioning from closed to open, or set to
"<code data-x="">open</code>" when transitioning from open to closed.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn
data-x="dom-ToggleEvent-newState">newState</span></code></dt>
<dd>
<p>Set to "<code data-x="">open</code>" when transitioning from closed to open, or set to "<code
data-x="">closed</code>" when transitioning from open to closed.</p>
</dd>
</dl>
<p>The <dfn attribute for="ToggleEvent"><code
data-x="dom-ToggleEvent-oldState">oldState</code></dfn> and <dfn attribute for="ToggleEvent"><code
data-x="dom-ToggleEvent-newState">newState</code></dfn> attributes must return the values they are
initialized to.</p>
<p>A <dfn>toggle task tracker</dfn> is a <span>struct</span> which has:</p>
<dl>
<dt><dfn data-x="toggle-task-task">task</dfn></dt>
<dd>A <span data-x="concept-task">task</span> which fires a <code>ToggleEvent</code>.</dd>
<dt><dfn data-x="toggle-task-old-state">old state</dfn></dt>
<dd>A string which represents the <span data-x="toggle-task-task">task</span>'s event's value for
the <code data-x="dom-ToggleEvent-oldState">oldState</code> attribute.</dd>
</dl>
<h4>The <code>CommandEvent</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>CommandEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>CommandEventInit</span> eventInitDict = {});
readonly attribute Element? <span data-x="dom-CommandEvent-source">source</span>;
readonly attribute DOMString <span data-x="dom-CommandEvent-command">command</span>;
};
dictionary <dfn dictionary>CommandEventInit</dfn> : <span>EventInit</span> {
Element? source = null;
DOMString command = "";
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn
data-x="dom-CommandEvent-command">command</span></code></dt>
<dd>
<p>Returns what action the element can take.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn
data-x="dom-CommandEvent-source">source</span></code></dt>
<dd>
<p>Returns the <code>Element</code> that was interacted with in order to cause this event.</p>
</dd>
</dl>
<p>The <dfn attribute for="CommandEvent"><code
data-x="dom-CommandEvent-command">command</code></dfn> attribute must return the value it was
initialized to.</p>
<p>The <dfn attribute
for="CommandEvent"><code data-x="dom-CommandEvent-source">source</code></dfn> getter steps are to
return the result of <span data-x="dom-retarget">retargeting</span> <code
data-x="dom-CommandEvent-source">source</code> against <span>this</span>'s <code
data-x="dom-Event-currentTarget">currentTarget</code>.</p>
<p class="XXX"><a href="https://github.com/whatwg/dom/issues/1328">DOM standard issue #1328</a>
tracks how to better standardize associated event data in a way which makes sense on Events.
Currently an event attribute initialized to a value cannot also have a getter, and so an internal
slot (or map of additional fields) is required to properly specify this.</p>
<h3>Focus</h3>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2807 -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2811 -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2809 -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2812 -->
<!-- v2: more things to define, if no other specs define them:
- define onfocus/onblur behavior for Window
- Other things to look at are IE's focus APIs (HTMLElement.setActive(),
onBeforeActivate, onActivate, onBeforeDeactivate, onDeactivate):
https://bugzilla.mozilla.org/show_bug.cgi?id=296471
https://bugzilla.mozilla.org/show_bug.cgi?id=296469
http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/setactive.asp
http://msdn.microsoft.com/workshop/author/dhtml/reference/events/onbeforeactivate.asp
-->
<h4>Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>An HTML user interface typically consists of multiple interactive widgets, such as form
controls, scrollable regions, links, dialog boxes, browser tabs, and so forth. These widgets form
a hierarchy, with some (e.g. browser tabs, dialog boxes) containing others (e.g. links, form
controls).</p>
<p>When interacting with an interface using a keyboard, key input is channeled from the system,
through the hierarchy of interactive widgets, to an active widget, which is said to be
<span>focused</span>.</p>
<div class="example">
<p>Consider an HTML application running in a browser tab running in a graphical environment.
Suppose this application had a page with some text controls and links, and was currently showing
a modal dialog, which itself had a text control and a button.</p>
<p>The hierarchy of focusable widgets, in this scenario, would include the browser window, which
would have, amongst its children, the browser tab containing the HTML application. The tab itself
would have as its children the various links and text controls, as well as the dialog. The dialog
itself would have as its children the text control and the button.</p>
<p><img src="/images/focus-tree.png" alt="" width=800 height=450> <!-- purely decorative: it repeats the previous
paragraph, in graphical form -->
<p>If the widget with <span data-x="focused">focus</span> in this example was the text control in
the dialog box, then key input would be channeled from the graphical system to ① the web
browser, then to ② the tab, then to ③ the dialog, and finally to ④ the text
control.</p>
</div>
<p>Keyboard <em>events</em> are always targeted at this <span>focused</span> element.</p>
<h4>Data model</h4>
<p id="tlbc-system-focus">A <span>top-level traversable</span> has <dfn export for="top-level
traversable">system focus</dfn> when it can receive keyboard input channeled from the operating
system, possibly targeted at one of its <span data-x="nav-document">active document</span>'s
<span>descendant navigables</span>.</p>
<p>A <span>top-level traversable</span> has <dfn for="top-level traversable">user attention</dfn>
when its <span>system visibility state</span> is "<code data-x="">visible</code>", and it either
has <span>system focus</span> or user agent widgets directly related to it can receive keyboard
input channeled from the operating system.</p>
<!-- This language is borrowed from system focus -->
<p class="note">User attention is lost when a browser window loses focus, whereas system focus
might also be lost to other system widgets in the browser window such as a location bar.</p>
<p>A <code>Document</code> <var>d</var> is a <dfn export for="Document">fully active descendant of
a top-level traversable with user attention</dfn> when <var>d</var> is <span>fully active</span>
and <var>d</var>'s <span>node navigable</span>'s <span data-x="nav-top">top-level
traversable</span> has <span>user attention</span>.</p>
<p>The term <dfn>focusable area</dfn> is used to refer to regions of the interface that can further become
the target of such keyboard input. Focusable areas can be elements, parts of elements, or other regions
managed by the user agent.</p>
<p>Each <span>focusable area</span> has a <dfn>DOM anchor</dfn>, which is a <code>Node</code> object
that represents the position of the <span>focusable area</span> in the DOM. (When the <span>focusable
area</span> is itself a <code>Node</code>, it is its own <span>DOM anchor</span>.) The <span>DOM anchor</span> is
used in some APIs as a substitute for the <span>focusable area</span> when there is no other DOM object
to represent the <span>focusable area</span>.</p>
<p>The following table describes what objects can be <span data-x="focusable area">focusable
areas</span>. The cells in the left column describe objects that can be <span data-x="focusable
area">focusable areas</span>; the cells in the right column describe the <span data-x="DOM anchor">DOM
anchors</span> for those elements. (The cells that span both columns are non-normative examples.)</p>
<table id="table-fa">
<thead>
<tr>
<th id="th-fa-area"><span>Focusable area</span>
<th id="th-fa-dom-rep"><span>DOM anchor</span>
<tr>
<th id="th-fa-examples" colspan=2>Examples
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-1">
Elements that meet all the following criteria:
<ul class="brief">
<li>the element's <span>tabindex value</span> is non-null, or the element is determined by the
user agent to be focusable;</li>
<li>the element is either not a <span>shadow host</span>, or has a <span
data-x="concept-element-shadow-root">shadow root</span> whose <span>delegates focus</span> is
false;</li>
<li>the element is not <span data-x="concept-element-disabled">actually disabled</span>;</li>
<li>the element is not <span>inert</span>;</li>
<li>the element is either <span>being rendered</span>, <span>delegating its rendering to its
children</span>, or <span>being used as relevant canvas fallback content</span>.</li>
</ul>
<td headers="td-fa-1 th-fa-dom-rep">
The element itself.
<tr>
<td headers="td-fa-1 th-fa-examples" colspan=2>
<p class="example"><code>iframe</code>, <code>dialog</code>, <code
data-x="attr-input-type-text"><input type=text></code>, sometimes <code data-x="a"><a
href=""></code> (depending on platform conventions).
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-2">
The shapes of <code>area</code> elements in an <span>image map</span> associated with an
<code>img</code> element that is <span>being rendered</span> and is not <span>inert</span>.
<td headers="td-fa-2 th-fa-dom-rep">
The <code>img</code> element.
<tr>
<td headers="td-fa-2 th-fa-examples" colspan=2>
<div class="example">
<p>In the following example, the <code>area</code> element creates two shapes, one on each
image. The <span>DOM anchor</span> of the first shape is the first <code>img</code> element, and the
<span>DOM anchor</span> of the second shape is the second <code>img</code> element.</p>
<pre><code class="html"><map id=wallmap><area alt="Enter Door" coords="10,10,100,200" href="door.html"></map>
...
<img src="images/innerwall.jpeg" alt="There is a white wall here, with a door." usemap="#wallmap">
...
<img src="images/outerwall.jpeg" alt="There is a red wall here, with a door." usemap="#wallmap"></code></pre>
</div>
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-3">
The user-agent provided subwidgets of elements that are <span>being rendered</span> and are not
<span data-x="concept-element-disabled">actually disabled</span> or <span>inert</span>.
<td headers="td-fa-3 th-fa-dom-rep">
The element for which the <span>focusable area</span> is a subwidget.
<tr>
<td headers="td-fa-3 th-fa-examples" colspan=2>
<p class="example">The <span data-x="expose a user interface to the user">controls in the user
interface</span> for a <code>video</code> element, the up and down buttons in a spin-control
version of <code data-x="attr-input-type-number"><input type=number></code>, the part of a
<code>details</code> element's rendering that enables the element to be opened or closed using
keyboard input.</p>
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-4">
The scrollable regions of elements that are <span>being rendered</span> and are not
<span>inert</span>. <!-- the being rendered part is kinda redundant, a scrollable region is a
box generated for the element so by definition if the element has a scrollable region it is
being rendered -->
<td headers="td-fa-4 th-fa-dom-rep">
The element for which the box that the scrollable region scrolls was created.
<tr>
<td headers="td-fa-4 th-fa-examples" colspan=2>
<p class="example">The CSS <span>'overflow'</span> property's 'scroll' value typically creates
a scrollable region.</p>
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-5">
The <span>viewport</span> of a <code>Document</code> that has a non-null <span
data-x="concept-document-bc">browsing context</span> and is not <span>inert</span>.
<td headers="td-fa-5 th-fa-dom-rep">
The <code>Document</code> for which the <span>viewport</span> was created.
<tr>
<td headers="td-fa-5 th-fa-examples" colspan=2>
<p class="example">The contents of an <code>iframe</code>.</p>
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-6">
Any other element or part of an element determined by the user agent to be a focusable area,
especially to aid with accessibility or to better match platform conventions.
<td headers="td-fa-6 th-fa-dom-rep">
The element.
<tr>
<td headers="td-fa-6 th-fa-examples" colspan=2>
<p class="example">A user agent could make all list item bullets <span>sequentially
focusable</span>, so that a user can more easily navigate lists.</p>
<p class="example">Similarly, a user agent could make all elements with <code
data-x="attr-title">title</code> attributes <span>sequentially focusable</span>, so that their
advisory information can be accessed.</p>
</table>
<p id="bc-focus-ergo-bcc-focus" class="note">A <span>navigable container</span> (e.g. an
<code>iframe</code>) is a <span>focusable area</span>, but key events routed to a <span>navigable
container</span> get immediately routed to its <span>content navigable</span>'s <span
data-x="nav-document">active document</span>. Similarly, in sequential focus navigation a
<span>navigable container</span> essentially acts merely as a placeholder for its <span>content
navigable</span>'s <span data-x="nav-document">active document</span>.</p>
<hr>
<p>One <span>focusable area</span> in each <code>Document</code> is designated the <dfn>focused
area of the document</dfn>. Which control is so designated changes over time, based on algorithms
in this specification.</p>
<p class="note">Even if a document is not <span>fully active</span> and not shown to the user, it
can still have a <span>focused area of the document</span>. If a document's <span>fully
active</span> state changes, its <span>focused area of the document</span> will stay the same.</p>
<p id="currently-focused-area-of-a-top-level-browsing-context">The <dfn>currently focused area of
a top-level traversable</dfn> <var>traversable</var> is the <span>focusable area</span>-or-null
returned by this algorithm:</p>
<ol>
<li><p>If <var>traversable</var> does not have <span>system focus</span>, then return
null.</p></li>
<li><p>Let <var>candidate</var> be <var>traversable</var>'s <span data-x="nav-document">active
document</span>.</p></li>
<li><p>While <var>candidate</var>'s <span data-x="focused area of the document">focused
area</span> is a <span>navigable container</span> with a non-null <span>content
navigable</span>: set <var>candidate</var> to the <span data-x="nav-document">active
document</span> of that <span>navigable container</span>'s <span>content
navigable</span>.</p></li>
<li><p>If <var>candidate</var>'s <span data-x="focused area of the document">focused area</span>
is non-null, set <var>candidate</var> to <var>candidate</var>'s <span data-x="focused area of
the document">focused area</span>.</p></li>
<!-- Can it be null though? See https://github.com/whatwg/html/issues/5835. -->
<li><p>Return <var>candidate</var>.</p></li>
</ol>
<p id="current-focus-chain-of-a-top-level-browsing-context">The <dfn>current focus chain of a
top-level traversable</dfn> <var>traversable</var> is the <span>focus chain</span> of the <span
data-x="currently focused area of a top-level traversable">currently focused area</span> of
<var>traversable</var>, if <var>traversable</var> is non-null, or an empty list otherwise.</p>
<p>An element that is the <span>DOM anchor</span> of a <span>focusable area</span> is said to
<dfn data-x="gains focus">gain focus</dfn> when that <span>focusable area</span> becomes the
<span>currently focused area of a top-level traversable</span>. When an element is the <span>DOM
anchor</span> of a <span>focusable area</span> of the <span>currently focused area of a top-level
traversable</span>, it is <dfn>focused</dfn>.</p>
<div w-nodev>
<p>The <dfn>focus chain</dfn> of a <span>focusable area</span> <var>subject</var> is the ordered
list constructed as follows:</p>
<ol>
<li><p>Let <var>output</var> be an empty <span>list</span>.</p></li>
<li><p>Let <var>currentObject</var> be <var>subject</var>.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>currentObject</var> to
<var>output</var>.</p></li>
<li>
<p>If <var>currentObject</var> is an <code>area</code> element's shape, then <span
data-x="list append">append</span> that <code>area</code> element to <var>output</var>.</p>
<p>Otherwise, if <var>currentObject</var>'s <span>DOM anchor</span> is an element that is not
<var>currentObject</var> itself, then <span data-x="list append">append</span>
<var>currentObject</var>'s <span>DOM anchor</span> to <var>output</var>.</p>
</li>
<li>
<p>If <var>currentObject</var> is a <span>focusable area</span>, then set
<var>currentObject</var> to <var>currentObject</var>'s <span>DOM anchor</span>'s <span>node
document</span>.</p>
<p>Otherwise, if <var>currentObject</var> is a <code>Document</code> whose <span>node
navigable</span>'s <span data-x="nav-parent">parent</span> is non-null, then set
<var>currentObject</var> to <var>currentObject</var>'s <span>node navigable</span>'s <span
data-x="nav-parent">parent</span>.</p>
<p>Otherwise, <span>break</span>.</p>
</li>
</ol>
</li>
<li>
<p>Return <var>output</var>.</p>
<p class="note">The chain starts with <var>subject</var> and (if <var>subject</var> is or can be
the <span>currently focused area of a top-level traversable</span>) continues up the focus
hierarchy up to the <code>Document</code> of the <span>top-level traversable</span>.</p>
</li>
</ol>
<p>All elements that are <span data-x="focusable area">focusable areas</span> are said to be
<dfn>focusable</dfn>.</p>
<p>There are two special types of focusability for <span data-x="focusable area">focusable
areas</span>:</p>
<ul>
<li>
<p>A <span>focusable area</span> is said to be <dfn>sequentially focusable</dfn> if it is
included in its <code>Document</code>'s <span>sequential focus navigation order</span> and
the user agent determines that it is sequentially focusable.</p>
</li>
<li>
<p>A <span>focusable area</span> is said to be <dfn>click focusable</dfn> if the user agent
determines that it is click focusable. User agents should consider focusable areas with non-null
<span data-x="tabindex value">tabindex values</span> to be click focusable.</p>
</li>
</ul>
<p class="note">Elements which are not <span>focusable</span> are not <span data-x="focusable
area">focusable areas</span>, and thus not <span>sequentially focusable</span> and not <span>click
focusable</span>.</p>
<div class="note">
<p>Being <span>focusable</span> is a statement about whether an element can be focused
programmatically, e.g. via the <code data-x="dom-focus">focus()</code> method or <code
data-x="attr-fe-autofocus">autofocus</code> attribute. In contrast, <span>sequentially
focusable</span> and <span>click focusable</span> govern how the user agent responds to user
interaction: respectively, to <span>sequential focus navigation</span> and as
<span>activation behavior</span>.</p>
<p>The user agent might determine that an element is not <span>sequentially focusable</span> even
if it is <span>focusable</span> and is included in its <code>Document</code>'s <span>sequential
focus navigation order</span>, according to user preferences. For example, macOS users can set
the user agent to skip non-form control elements, or can skip links when doing <span>sequential
focus navigation</span> with just the <kbd>Tab</kbd> key (as opposed to using both the
<kbd>Option</kbd> and <kbd>Tab</kbd> keys).</p>
<p>Similarly, the user agent might determine that an element is not <span>click focusable</span>
even if it is <span>focusable</span>. For example, in some user agents, clicking on a
non-editable form control does not focus it, i.e. the user agent has determined that such
controls are not click focusable.</p>
<p>Thus, an element can be <span>focusable</span>, but neither <span>sequentially
focusable</span> nor <span>click focusable</span>. For example, in some user agents, a
non-editable form-control with a negative-integer <span>tabindex value</span> would not be
focusable via user interaction, only via programmatic APIs.</p>
</div>
<p>When a user <a href="#activation">activates</a> a <span>click focusable</span> <span>focusable
area</span>, the user agent must run the <span>focusing steps</span> on the <span>focusable
area</span> with <var>focus trigger</var> set to "<code data-x="">click</code>".</p>
<p class="note">Note that focusing is not an <span>activation behavior</span>, i.e. calling the
<code data-x="dom-click">click()</code> method on an element or dispatching a synthetic <code
data-x="event-click">click</code> event on it won't cause the element to get focused.</p>
<hr>
<p>A node is a <dfn>focus navigation scope owner</dfn> if it is a <code>Document</code>, a
<span>shadow host</span>, a <span>slot</span>, or an element which is the <span>popover
invoker</span> of an element in the <span data-x="popover-showing-state">popover showing
state</span>.</p>
<p>Each <span>focus navigation scope owner</span> has a <dfn>focus navigation scope</dfn>, which
is a list of elements. Its contents are determined as follows:</p>
<p>Every element <var>element</var> has an <dfn>associated focus navigation owner</dfn>, which is
either null or a <span>focus navigation scope owner</span>. It is determined by the following
algorithm:</p>
<ol>
<li><p>If <var>element</var>'s parent is null, then return null.</p></li>
<li><p>If <var>element</var>'s parent is a <span>shadow host</span>, then return
<var>element</var>'s <span>assigned slot</span>.</p></li>
<li><p>If <var>element</var>'s parent is a <span>shadow root</span>, then return the parent's
<span data-x="concept-DocumentFragment-host">host</span>.</p></li>
<li><p>If <var>element</var>'s parent is the <span>document element</span>, then return the
parent's <span>node document</span>.</p></li>
<li><p>If <var>element</var> is in the <span data-x="popover-showing-state">popover showing
state</span> and has a <span>popover invoker</span> set, then return <var>element</var>'s
<span>popover invoker</span>.</p></li>
<li><p>Return <var>element</var>'s parent's <span>associated focus navigation owner</span>.</p></li>
</ol>
<p>Then, the contents of a given <span>focus navigation scope owner</span> <var>owner</var>'s
<span>focus navigation scope</span> are all elements whose <span>associated focus navigation
owner</span> is <var>owner</var>.</p>
<p class="note">The order of elements within a <span>focus navigation scope</span> does not impact
any of the algorithms in this specification. Ordering only becomes important for the
<span>tabindex-ordered focus navigation scope</span> and <span>flattened tabindex-ordered focus
navigation scope</span> concepts defined below.</p>
<p>A <dfn>tabindex-ordered focus navigation scope</dfn> is a list of <span data-x="focusable
area">focusable areas</span> and <span data-x="focus navigation scope owner">focus navigation
scope owners</span>. Every <span>focus navigation scope owner</span> <var>owner</var> has
<span>tabindex-ordered focus navigation scope</span>, whose contents are determined as
follows:</p>
<ul>
<li><p>It contains all elements in <var>owner</var>'s <span>focus navigation scope</span> that
are themselves <span data-x="focus navigation scope owner">focus navigation scope owners</span>,
except the elements whose <span>tabindex value</span> is a negative integer.</p></li>
<li><p>It contains all of the <span data-x="focusable area">focusable areas</span> whose
<span>DOM anchor</span> is an element in <var>owner</var>'s <span>focus navigation scope</span>,
except the <span data-x="focusable area">focusable areas</span> whose <span>tabindex value</span>
is a negative integer.</p></li>
</ul>
<p>The order within a <span>tabindex-ordered focus navigation scope</span> is determined by each
element's <span>tabindex value</span>, as described in the section below.</p>
<p class="note">The rules there do not give a precise ordering, as they are composed mostly of
"<!--non-normative-->should" statements and relative orderings.</p>
<p>A <dfn>flattened tabindex-ordered focus navigation scope</dfn> is a list of <span
data-x="focusable area">focusable areas</span>. Every <span>focus navigation scope owner</span>
<var>owner</var> owns a distinct <span>flattened tabindex-ordered focus navigation scope</span>,
whose contents are determined by the following algorithm:</p>
<ol>
<li><p>Let <var>result</var> be a <span data-x="list clone">clone</span> of <var>owner</var>'s
<span>tabindex-ordered focus navigation scope</span>.</p></li>
<li>
<p>For each <var>item</var> of <var>result</var>:</p>
<ol>
<li><p>If <var>item</var> is not a <span>focus navigation scope owner</span>, then
<span>continue</span>.</p></li>
<li><p>If <var>item</var> is not a <span>focusable area</span>, then replace <var>item</var>
with all of the items in <var>item</var>'s <span>flattened tabindex-ordered focus navigation
scope</span>.</p></li>
<li><p>Otherwise, insert the contents of <var>item</var>'s <span>flattened tabindex-ordered
focus navigation scope</span> after <var>item</var>.</p></li>
</ol>
</li>
</ol>
</div>
<h4>The <code data-x="attr-tabindex">tabindex</code> attribute</h4>
<p>The <dfn element-attr for="htmlsvg-global"><code data-x="attr-tabindex">tabindex</code></dfn>
content attribute allows authors to make an element and regions that have the element as its
<span>DOM anchor</span> be <span data-x="focusable area">focusable areas</span>, allow or prevent
them from being <span>sequentially focusable</span>, and determine their relative ordering for
<span>sequential focus navigation</span>.</p>
<p>The name "tab index" comes from the common use of the <kbd>Tab</kbd> key to navigate through
the focusable elements. The term "tabbing" refers to moving forward through <span>sequentially
focusable</span> <span data-x="focusable area">focusable areas</span>.</p>
<p>The <code data-x="attr-tabindex">tabindex</code> attribute, if specified, must have a value
that is a <span>valid integer</span>. Positive numbers specify the relative position of the
element's <span data-x="focusable area">focusable areas</span> in the <span>sequential focus
navigation order</span>, and negative numbers indicate that the control is not
<span>sequentially focusable</span>.</p>
<p>Developers should use caution when using values other than 0 or −1 for their <code
data-x="attr-tabindex">tabindex</code> attributes as this is complicated to do correctly.</p>
<div class="note">
<p>The following provides a <span w-nodev>non-normative</span> summary of the behaviors of the
possible <code data-x="attr-tabindex">tabindex</code> attribute values.<span w-nodev> The below
processing model gives the more precise rules.</span></p>
<dl>
<dt>omitted (or non-integer values)</dt>
<dd>The user agent will decide whether the element is <span>focusable</span>, and if it is,
whether it is <span>sequentially focusable</span> or <span>click focusable</span> (or both).</dd>
<dt>−1 (or other negative integer values)</dt>
<dd>Causes the element to be <span>focusable</span>, and indicates that the author would prefer
the element to be <span>click focusable</span> but not <span>sequentially focusable</span>. The
user agent might ignore this preference for click and sequential focusability, e.g., for
specific element types according to platform conventions, or for keyboard-only users.</dd>
<dt>0</dt>
<dd>Causes the element to be <span>focusable</span>, and indicates that the author would prefer
the element to be both <span>click focusable</span> and <span>sequentially focusable</span>. The
user agent might ignore this preference for click and sequential focusability.</dd>
<dt>positive integer values</dt>
<dd>Behaves the same as 0, but in addition creates a relative ordering within a
<span>tabindex-ordered focus navigation scope</span>, so that elements with higher <code
data-x="attr-tabindex">tabindex</code> attribute value come later.</dd>
</dl>
<p>Note that the <code data-x="attr-tabindex">tabindex</code> attribute cannot be used to make
an element non-focusable. The only way a page author can do that is by <span
data-x="concept-element-disabled">disabling</span> the element, or making it
<span>inert</span>.</p>
</div>
<div w-nodev>
<hr>
<p>The <dfn>tabindex value</dfn> of an element is the value of its <code
data-x="attr-tabindex">tabindex</code> attribute, parsed using the <span>rules for parsing
integers</span>. If parsing fails or the attribute is not specified, then the <span>tabindex
value</span> is null.</p>
<p>The <span>tabindex value</span> of a <span>focusable area</span> is the <span>tabindex
value</span> of its <span>DOM anchor</span>.</p>
<p>The <span>tabindex value</span> of an element must be interpreted as follows:</p>
<dl>
<dt>If the value is null</dt>
<dd>
<p>The user agent should follow platform conventions to determine if the element should be
considered as a <span>focusable area</span> and if so, whether the element and any <span
data-x="focusable area">focusable areas</span> that have the element as their
<span>DOM anchor</span> are <span>sequentially focusable</span>, and if so, what their relative
position in their <span>tabindex-ordered focus navigation scope</span> is to be. If the element
is a <span>focus navigation scope owner</span>, it must be included in its
<span>tabindex-ordered focus navigation scope</span> even if it is not a <span>focusable
area</span>.</p>
<p>The relative ordering within a <span>tabindex-ordered focus navigation scope</span> for
elements and <span data-x="focusable area">focusable areas</span> that belong to the same
<span>focus navigation scope</span> and whose <span>tabindex value</span> is null should be in
<span>shadow-including tree order</span>.</p>
<p>Modulo platform conventions, it is suggested that the following elements should be considered
as <span data-x="focusable area">focusable areas</span> and be <span>sequentially
focusable</span>:</p>
<ul>
<li><code>a</code> elements that have an <code data-x="attr-hyperlink-href">href</code>
attribute</li>
<li><code>button</code> elements</li>
<li><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute are
not in the <span data-x="attr-input-type-hidden">Hidden</span> state</li>
<li><code>select</code> elements</li>
<li><code>textarea</code> elements</li>
<li><code>summary</code> elements that are the first <code>summary</code> element child of a
<code>details</code> element</li>
<li>Elements with a <code data-x="attr-draggable">draggable</code> attribute set, if that would
enable the user agent to allow the user to begin drag operations for those elements without
the use of a pointing device</li>
<li><span data-x="editing host">Editing hosts</span></li>
<li><span data-x="navigable container">Navigable containers</span></li>
</ul>
</dd>
<dt id="negative-tabindex">If the value is a negative integer</dt>
<dd>
<p>The user agent must consider the element as a <span>focusable area</span>, but should omit
the element from any <span>tabindex-ordered focus navigation scope</span>.</p>
<p class="note">One valid reason to ignore the requirement that sequential focus navigation not
allow the author to lead to the element would be if the user's only mechanism for moving the
focus is sequential focus navigation. For instance, a keyboard-only user would be unable to
click on a text control with a negative <code data-x="attr-tabindex">tabindex</code>, so that
user's user agent would be well justified in allowing the user to tab to the control
regardless.</p>
</dd>
<dt>If the value is a zero</dt>
<dd>
<p>The user agent must allow the element to be considered as a <span>focusable area</span> and
should allow the element and any <span data-x="focusable area">focusable areas</span> that have
the element as their <span>DOM anchor</span> to be <span>sequentially focusable</span>.</p>
<p>The relative ordering within a <span>tabindex-ordered focus navigation scope</span> for
elements and <span data-x="focusable area">focusable areas</span> that belong to the same
<span>focus navigation scope</span> and whose <span>tabindex value</span> is zero should be in
<span>shadow-including tree order</span>.</p>
</dd>
<dt>If the value is greater than zero</dt>
<dd>
<p>The user agent must allow the element to be considered as a <span>focusable area</span> and
should allow the element and any <span data-x="focusable area">focusable areas</span> that have
the element as their <span>DOM anchor</span> to be <span>sequentially focusable</span>, and
should place the element — referenced as <var>candidate</var> below — and the
aforementioned <span data-x="focusable area">focusable areas</span> in the
<span>tabindex-ordered focus navigation scope</span> where the element is a part of so that,
relative to other elements and <span data-x="focusable area">focusable areas</span> that belong
to the same <span>focus navigation scope</span>, they are:</p>
<ul>
<li>before any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has been omitted or whose value, when parsed,
returns an error,</li>
<li>before any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has a value less than or equal to zero,</li>
<li>after any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has a value greater than zero but less than
the value of the <code data-x="attr-tabindex">tabindex</code> attribute on <var>candidate</var>,</li>
<li>after any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has a value equal to the value of the <code
data-x="attr-tabindex">tabindex</code> attribute on <var>candidate</var> but that is
located earlier than <var>candidate</var> in <span>shadow-including tree order</span>,</li>
<li>before any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has a value equal to the value of the <code
data-x="attr-tabindex">tabindex</code> attribute on <var>candidate</var> but that is
located later than <var>candidate</var> in <span>shadow-including tree order</span>, and</li>
<li>before any <span>focusable area</span> whose <span>DOM anchor</span> is an element whose <code
data-x="attr-tabindex">tabindex</code> attribute has a value greater than the value of the
<code data-x="attr-tabindex">tabindex</code> attribute on <var>candidate</var>.</li>
</ul>
</dd>
</dl>
<p>The <dfn attribute for="HTMLOrSVGElement"><code data-x="dom-tabIndex">tabIndex</code></dfn> IDL
attribute must <span>reflect</span> the value of the <code data-x="attr-tabindex">tabindex</code>
content attribute. The <span>default value</span> is 0 if the element is an <code>a</code>,
<code>area</code>, <code>button</code>, <code>frame</code>, <code>iframe</code>,
<code>input</code>, <code>object</code>, <code>select</code>, <code>textarea</code>, or <span>SVG
<code>a</code></span> element, or is a <code>summary</code> element that is a <span>summary for
its parent details</span>. The <span>default value</span> is −1 otherwise.</p>
<p class="note">The varying default value based on element type is a historical artifact.</p>
</div>
<div w-nodev>
<h4 id="focus-processing-model"><span id="processing-model-5"></span>Processing model</h4>
<p>To <dfn>get the focusable area</dfn> for a <var>focus target</var> that is either an element
that is not a <span>focusable area</span>, or is a <span>navigable</span>, given an
optional string <var>focus trigger</var> (default "<code data-x="">other</code>"), run the first
matching set of steps from the following list:</p>
<dl class="switch">
<dt>If <var>focus target</var> is an <code>area</code> element with one or more shapes that are
<span data-x="focusable area">focusable areas</span></dt>
<dd><p>Return the shape corresponding to the first <code>img</code> element in <span>tree
order</span> that uses the image map to which the <code>area</code> element belongs.</p></dd>
<dt>If <var>focus target</var> is an element with one or more scrollable regions that are <span
data-x="focusable area">focusable areas</span></dt>
<dd><p>Return the element's first scrollable region, according to a pre-order, depth-first
traversal of the <span>flat tree</span>. <ref>CSSSCOPING</ref></p></dd>
<dt>If <var>focus target</var> is the <span>document element</span> of its
<code>Document</code></dt>
<dd><p>Return the <code>Document</code>'s <span>viewport</span>.</p></dd>
<dt>If <var>focus target</var> is a <span>navigable</span></dt>
<dd><p>Return the <span>navigable</span>'s <span data-x="nav-document">active
document</span>.</p></dd>
<dt>If <var>focus target</var> is a <span>navigable container</span> with a non-null
<span>content navigable</span></dt>
<dd><p>Return the <span>navigable container</span>'s <span>content navigable</span>'s <span
data-x="nav-document">active document</span>.</p></dd>
<dt>If <var>focus target</var> is a <span>shadow host</span> whose <span
data-x="concept-element-shadow-root">shadow root</span>'s <span>delegates focus</span> is
true</dt>
<dd>
<ol>
<li><p>Let <var>focusedElement</var> be the <span>currently focused area of a top-level
traversable</span>'s <span>DOM anchor</span>.</p></li>
<li><p>If <var>focus target</var> is a <span>shadow-including inclusive ancestor</span> of
<var>focusedElement</var>, then return <var>focusedElement</var>.</p></li>
<li><p>Return the <span>focus delegate</span> for <var>focus target</var> given <var>focus
trigger</var>.</p></li>
</ol>
<p class="note">For <span data-x="sequentially focusable">sequential focusability</span>, the
handling of <span data-x="shadow host">shadow hosts</span> and <span>delegates focus</span> is
done when constructing the <span>sequential focus navigation order</span>. That is, the
<span>focusing steps</span> will never be called on such <span data-x="shadow host">shadow
hosts</span> as part of sequential focus navigation.</p>
</dd>
<dt>Otherwise</dt>
<dd><p>Return null.</p></dd>
</dl>
<p>The <dfn>focus delegate</dfn> for a <var>focusTarget</var>, given an optional string
<var>focusTrigger</var> (default "<code data-x="">other</code>"), is given by the following steps:</p>
<ol>
<li><p>If <var>focusTarget</var> is a <span>shadow host</span> and its <span
data-x="concept-element-shadow-root">shadow root</span>'s <span>delegates focus</span> is false,
then return null.</p></li>
<li><p>Let <var>whereToLook</var> be <var>focusTarget</var>.</p></li>
<li><p>If <var>whereToLook</var> is a <span>shadow host</span>, then set <var>whereToLook</var>
to <var>whereToLook</var>'s <span data-x="concept-element-shadow-root">shadow
root</span>.</p></li>
<li><p>Let <var>autofocusDelegate</var> be the <span>autofocus delegate</span> for
<var>whereToLook</var> given <var>focusTrigger</var>.</p></li>
<li><p>If <var>autofocusDelegate</var> is not null, then return
<var>autofocusDelegate</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>descendant</var> of
<var>whereToLook</var>'s <span data-x="descendant">descendants</span>, in <span>tree
order</span>:</p>
<ol>
<li><p>Let <var>focusableArea</var> be null.</p></li>
<li><p>If <var>focusTarget</var> is a <code>dialog</code> element and <var>descendant</var> is
<span>sequentially focusable</span>, then set <var>focusableArea</var> to
<var>descendant</var>.</p></li>
<li><p>Otherwise, if <var>focusTarget</var> is not a <code>dialog</code> and
<var>descendant</var> is a <span>focusable area</span>, set <var>focusableArea</var> to
<var>descendant</var>.</p></li>
<li>
<p>Otherwise, set <var>focusableArea</var> to the result of <span data-x="get the focusable
area">getting the focusable area</span> for <var>descendant</var> given
<var>focusTrigger</var>.</p>
<p class="note">This step can end up recursing, i.e., the <span>get the focusable area</span>
steps might return the <span>focus delegate</span> of <var>descendant</var>.</p>
</li>
<li><p>If <var>focusableArea</var> is not null, then return <var>focusableArea</var>.</p></li>
</ol>
<p class="note">It's important that we are <em>not</em> looking at the <span
data-x="shadow-including descendant">shadow-including descendants</span> here, but instead only
at the <span data-x="descendant">descendants</span>. <span data-x="shadow host">Shadow
hosts</span> are instead handled by the recursive case mentioned above.</p>
</li>
<li><p>Return null.</p></li>
</ol>
<p class="note">The above algorithm essentially returns the first suitable <span>focusable
area</span> where the path between its <span>DOM anchor</span> and <var>focusTarget</var>
delegates focus at any shadow tree boundaries.</p>
<p>The <dfn>autofocus delegate</dfn> for a <var>focus target</var> given a <var>focus
trigger</var> is given by the following steps:</p>
<ol>
<li>
<p>For each <span>descendant</span> <var>descendant</var> of <var>focus target</var>, in
<span>tree order</span>:</p>
<ol>
<li><p>If <var>descendant</var> does not have an <code
data-x="attr-fe-autofocus">autofocus</code> content attribute, then
<span>continue</span>.</p></li>
<li><p>Let <var>focusable area</var> be <var>descendant</var>, if <var>descendant</var> is a
<span>focusable area</span>; otherwise let <var>focusable area</var> be the result of <span
data-x="get the focusable area">getting the focusable area</span> for <var>descendant</var>
given <var>focus trigger</var>.</p></li>
<li><p>If <var>focusable area</var> is null, then <span>continue</span>.</p></li>
<li><p>If <var>focusable area</var> is not <span>click focusable</span> and <var>focus
trigger</var> is "<code data-x="">click</code>", then <span>continue</span>.</p></li>
<li><p>Return <var>focusable area</var>.</p></li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<p>The <dfn export>focusing steps</dfn> for an object <var>new focus target</var> that is either a
<span>focusable area</span>, or an element that is not a <span>focusable area</span>, or a
<span>navigable</span>, are as follows. They can optionally be run with a <var>fallback
target</var> and a string <var>focus trigger</var>.</p>
<ol>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2816 div.focus() when it's got a scroll region -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2817 img.focus() when it's got an image map -->
<li><p>If <var>new focus target</var> is not a <span>focusable area</span>, then set <var>new
focus target</var> to the result of <span data-x="get the focusable area">getting the focusable
area</span> for <var>new focus target</var>, given <var>focus trigger</var> if it was
passed.</p></li>
<li>
<p>If <var>new focus target</var> is null, then:</p>
<ol>
<li><p>If no <var>fallback target</var> was specified, then return.</p></li>
<li><p>Otherwise, set <var>new focus target</var> to the <var>fallback
target</var>.</p></li>
</ol>
</li>
<li><p>If <var>new focus target</var> is a <span>navigable container</span> with non-null
<span>content navigable</span>, then set <var>new focus target</var> to the <span>content
navigable</span>'s <span data-x="nav-document">active document</span>.</p></li>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2818 -->
<li><p>If <var>new focus target</var> is a <span>focusable area</span> and its <span>DOM
anchor</span> is <span>inert</span>, then return.</p></li>
<li><p>If <var>new focus target</var> is the <span>currently focused area of a top-level
traversable</span>, then return.</p></li>
<li><p>Let <var>old chain</var> be the <span data-x="current focus chain of a top-level
traversable">current focus chain of the top-level traversable</span> in which <var>new focus
target</var> finds itself.</p></li>
<li><p>Let <var>new chain</var> be the <span>focus chain</span> of <var>new
focus target</var>.</p></li>
<li><p>Run the <span>focus update steps</span> with <var>old chain</var>, <var>new chain</var>,
and <var>new focus target</var> respectively.</p></li>
</ol>
<p>User agents must <span>immediately</span> run the <span>focusing steps</span> for a
<span>focusable area</span> or <span>navigable</span> <var>candidate</var> whenever the
user attempts to move the focus to <var>candidate</var>.</p>
<p>The <dfn>unfocusing steps</dfn> for an object <var>old focus target</var> that is
either a <span>focusable area</span> or an element that is not a <span>focusable area</span> are as
follows:</p>
<ol>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2819 -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2822 -->
<li><p>If <var>old focus target</var> is a <span>shadow host</span> whose <span
data-x="concept-element-shadow-root">shadow root</span>'s <span>delegates focus</span> is true,
and <var>old focus target</var>'s <span data-x="concept-element-shadow-root">shadow root</span>
is a <span>shadow-including inclusive ancestor</span> of the <span>currently focused area of a
top-level traversable</span>'s <span>DOM anchor</span>, then set <var>old focus target</var> to
that <span>currently focused area of a top-level traversable</span>.</p></li>
<li><p>If <var>old focus target</var> is <span>inert</span>, then return.</p></li>
<li><p>If <var>old focus target</var> is an <code>area</code> element and one of its shapes is
the <span>currently focused area of a top-level traversable</span>, or, if <var>old focus
target</var> is an element with one or more scrollable regions, and one of them is the
<span>currently focused area of a top-level traversable</span>, then let <var>old focus
target</var> be that <span>currently focused area of a top-level traversable</span>.</p></li>
<li><p>Let <var>old chain</var> be the <span data-x="current focus chain of a top-level
traversable">current focus chain of the top-level traversable</span> in which <var>old focus
target</var> finds itself.</p></li>
<li><p>If <var>old focus target</var> is not one of the entries in <var>old
chain</var>, then return.</p></li>
<li><p>If <var>old focus target</var> is not a <span>focusable area</span>, then return.</p></li>
<li><p>Let <var>topDocument</var> be <var>old chain</var>'s last entry.</p></li>
<li>
<p>If <var>topDocument</var>'s <span>node navigable</span> has <span>system focus</span>, then
run the <span>focusing steps</span> for <var>topDocument</var>'s <span>viewport</span>.</p>
<p>Otherwise, apply any relevant platform-specific conventions for removing <span>system
focus</span> from <var>topDocument</var>'s <span>node navigable</span>, and run the <span>focus
update steps</span> given <var>old chain</var>, an empty list, and null.</p>
</li>
</ol>
<p class="note">The <span>unfocusing steps</span> do not always result in the focus changing, even
when applied to the <span>currently focused area of a top-level traversable</span>. For
example, if the <span>currently focused area of a top-level traversable</span> is a
<span>viewport</span>, then it will usually keep its focus regardless until another
<span>focusable area</span> is explicitly focused with the <span>focusing steps</span>.</p>
<hr>
<p>The <dfn>focus update steps</dfn>, given an <var>old chain</var>, a <var>new chain</var>, and a <var>new focus target</var> respectively, are as
follows:</p>
<ol>
<!-- focusin/focusout?: https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=723 -->
<li><p>If the last entry in <var>old chain</var> and the last entry in <var>new chain</var> are the same, pop the last entry from <var>old chain</var>
and the last entry from <var>new chain</var> and redo this step.</p></li>
<li>
<p>For each entry <var>entry</var> in <var>old chain</var>, in order, run
these substeps:</p>
<ol>
<li>
<p>If <var>entry</var> is an <code>input</code> element, and the <code
data-x="event-change">change</code> event <span data-x="concept-input-apply">applies</span>
to the element, and the element does not have a defined <span>activation behavior</span>, and
the user has changed the element's <span data-x="concept-fe-value">value</span> or its list
of <span data-x="concept-input-type-file-selected">selected files</span> while the control
was focused without committing that change (such that it is different to what it was when the
control was first focused), then:</p>
<ol>
<li><p>Set <var>entry</var>'s <span>user validity</span> to true.</p></li>
<li id="unfocus-causes-change-event"><p><span data-x="concept-event-fire">Fire an
event</span> named <code data-x="event-change">change</code> at the element, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>
</ol>
</li>
<li>
<p>If <var>entry</var> is an element, let <var>blur event target</var> be
<var>entry</var>.</p>
<p>If <var>entry</var> is a <code>Document</code> object, let <var>blur event target</var> be
that <code>Document</code> object's <span>relevant global object</span>.</p>
<p>Otherwise, let <var>blur event target</var> be null.</p>
</li>
<li><p>If <var>entry</var> is the last entry in <var>old chain</var>, and
<var>entry</var> is an <code>Element</code>, and the last entry in <var>new
chain</var> is also an <code>Element</code>, then let <var>related blur target</var>
be the last entry in <var>new chain</var>. Otherwise, let <var>related blur
target</var> be null.</p></li>
<li>
<p>If <var>blur event target</var> is not null, <span>fire a focus event</span>
named <code data-x="event-blur">blur</code> at <var>blur event target</var>, with
<var>related blur target</var> as the related target.</p>
<p class="note" id="note-sometimes-no-blur-event">In some cases, e.g., if <var>entry</var> is
an <code>area</code> element's shape, a scrollable region, or a <span>viewport</span>, no
event is fired.</p>
</li>
</ol>
</li>
<li><p>Apply any relevant platform-specific conventions for focusing <var>new focus target</var>.
(For example, some platforms select the contents of a text control when that control is
focused.)</p></li>
<li>
<p>For each entry <var>entry</var> in <var>new chain</var>, in reverse
order, run these substeps:</p>
<ol>
<li>
<p>If <var>entry</var> is a <span>focusable area</span>, and the <span>focused area of the
document</span> is not <var>entry</var>:</p>
<ol>
<li><p>Set <var>document</var>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>'s <span>focus changed during ongoing
navigation</span> to true.</p></li>
<li><p>Designate <var>entry</var> as the <span>focused area of the document</span>.</p>
</ol>
</li>
<li>
<p>If <var>entry</var> is an element, let <var>focus event target</var> be
<var>entry</var>.</p>
<p>If <var>entry</var> is a <code>Document</code> object, let <var>focus event target</var> be
that <code>Document</code> object's <span>relevant global object</span>.</p>
<p>Otherwise, let <var>focus event target</var> be null.</p>
</li>
<li><p>If <var>entry</var> is the last entry in <var>new chain</var>, and
<var>entry</var> is an <code>Element</code>, and the last entry in <var>old
chain</var> is also an <code>Element</code>, then let <var>related focus target</var>
be the last entry in <var>old chain</var>. Otherwise, let <var>related
focus target</var> be null.</p></li>
<li>
<p>If <var>focus event target</var> is not null, <span>fire a focus event</span>
named <code data-x="event-focus">focus</code> at <var>focus event target</var>, with
<var>related focus target</var> as the related target.</p>
<p class="note">In some cases, e.g. if <var>entry</var> is an <code>area</code>
element's shape, a scrollable region, or a <span>viewport</span>, no event is fired.</p>
</li>
</ol>
</li>
</ol>
<p>To <dfn>fire a focus event</dfn> named <var>e</var> at an element <var>t</var> with a given
related target <var>r</var>, <span data-x="concept-event-fire">fire an event</span> named
<var>e</var> at <var>t</var>, using <code>FocusEvent</code>, with the <code
data-x="dom-FocusEvent-relatedTarget">relatedTarget</code> attribute initialized to <var>r</var>,
the <code data-x="dom-UIEvent-view">view</code> attribute initialized to <var>t</var>'s
<span>node document</span>'s <span>relevant global object</span>, and the <span>composed
flag</span> set.</p>
<hr>
<p>When a key event is to be routed in a <span>top-level traversable</span>, the user agent must
run the following steps:</p>
<!-- interaction event spec point -->
<ol>
<li><p>Let <var>target area</var> be the <span data-x="currently focused area of a top-level
traversable">currently focused area of the top-level traversable</span>.</p></li>
<li><p><span>Assert</span>: <var>target area</var> is not null, since key events are only routed
to <span data-x="top-level traversable">top-level traversables</span> that have <span>system
focus</span>. Therefore, <var>target area</var> is a <span>focusable area</span>.</p></li>
<li><p>Let <var>target node</var> be <var>target area</var>'s <span>DOM anchor</span>.</p></li>
<li>
<p>If <var>target node</var> is a <code>Document</code> that has a <span data-x="the
body element">body element</span>, then let <var>target node</var> be <span>the body
element</span> of that <code>Document</code>.</p>
<p>Otherwise, if <var>target node</var> is a <code>Document</code> object that has a non-null
<span>document element</span>, then let <var>target node</var> be that <span>document
element</span>.</p>
</li>
<li>
<p>If <var>target node</var> is not <span>inert</span>, then:</p>
<ol>
<li><p>Let <var>canHandle</var> be the result of <span
data-x="concept-event-dispatch">dispatching</span> the key event at <var>target
node</var>.</p></li>
<li><p>If <var>canHandle</var> is true, then let <var>target area</var> handle the key event.
This might include <span data-x="fire a click event">firing a <code
data-x="event-click">click</code> event</span> at <var>target node</var>.</p></li>
</ol>
</li>
</ol>
<hr>
<p>The <dfn export>has focus steps</dfn>, given a <code>Document</code> object <var>target</var>,
are as follows:</p>
<ol>
<li><p>If <var>target</var>'s <span>node navigable</span>'s <span data-x="nav-top">top-level
traversable</span> does not have <span>system focus</span>, then return false.</p></li>
<li><p>Let <var>candidate</var> be <var>target</var>'s <span>node navigable</span>'s <span
data-x="nav-top">top-level traversable</span>'s <span>active document</span>.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>If <var>candidate</var> is <var>target</var>, then return true.</p></li>
<li><p>If the <span data-x="focused area of the document">focused area</span> of
<var>candidate</var> is a <span>navigable container</span> with a non-null <span>content
navigable</span>, then set <var>candidate</var> to the <span data-x="nav-document">active
document</span> of that <span>navigable container</span>'s <span>content
navigable</span>.</p></li>
<li><p>Otherwise, return false.</p></li>
</ol>
</li>
</ol>
<h4><dfn>Sequential focus navigation</dfn></h4>
<p>Each <code>Document</code> has a <dfn>sequential focus navigation order</dfn>, which orders
some or all of the <span data-x="focusable area">focusable areas</span> in the
<code>Document</code> relative to each other. Its contents and ordering are given by the
<span>flattened tabindex-ordered focus navigation scope</span> of the <code>Document</code>.</p>
<p class="note">Per the rules defining the <span>flattened tabindex-ordered focus navigation
scope</span>, the ordering is not necessarily related to the <span>tree order</span> of the
<code>Document</code>.</p>
<p>If a <span>focusable area</span> is omitted from the <span>sequential focus navigation
order</span> of its <code>Document</code>, then it is unreachable via <span>sequential focus
navigation</span>.</p>
<p>There can also be a <dfn>sequential focus navigation starting point</dfn>. It is initially
unset. The user agent may set it when the user indicates that it should be moved.</p>
<p class="example">For example, the user agent could set it to the position of the user's click if
the user clicks on the document contents.</p>
<p class="note">User agents are required to set the <span>sequential focus navigation starting
point</span> to the <span>target element</span> when <span data-x="navigate-fragid">navigating
to a fragment</span>.</p>
<p>A <dfn>sequential focus direction</dfn> is one of two possible values: "<dfn><code
data-x="sequential-focus-forward">forward</code></dfn>", or "<dfn><code
data-x="sequential-focus-backward">backward</code></dfn>". They are used in the below algorithms
to describe the direction in which sequential focus travels at the user's request.</p>
<p>A <dfn>selection mechanism</dfn> is one of two possible values: "<dfn><code
data-x="selection-mechanism-DOM">DOM</code></dfn>", or
"<dfn><code data-x="selection-mechanism-sequential">sequential</code></dfn>". They are used to
describe how the <span>sequential navigation search algorithm</span> finds the <span>focusable
area</span> it returns.</p>
<p>When the user requests that focus move from the <span>currently focused area of a top-level
traversable</span> to the next or previous <span>focusable area</span> (e.g., as the default
action of pressing the <kbd><kbd>tab</kbd></kbd> key), or when the user requests that focus
sequentially move to a <span>top-level traversable</span> in the first place (e.g., from the
browser's location bar), the user agent must use the following algorithm:</p>
<ol>
<li><p>Let <var>starting point</var> be the <span>currently focused area of a top-level
traversable</span>, if the user requested to move focus sequentially from there, or else the
<span>top-level traversable</span> itself, if the user instead requested to move focus from
outside the <span>top-level traversable</span>.</p></li>
<li><p>If there is a <span>sequential focus navigation starting point</span> defined and it is
inside <var>starting point</var>, then let <var>starting point</var> be the <span>sequential
focus navigation starting point</span> instead.</p></li>
<li>
<p>Let <var>direction</var> be "<code data-x="sequential-focus-forward">forward</code>" if the
user requested the next control, and "<code
data-x="sequential-focus-backward">backward</code>" if the user requested the previous
control.</p>
<p class="note">Typically, pressing <kbd><kbd>tab</kbd></kbd> requests the next control, and
pressing <kbd><kbd>shift</kbd> + <kbd>tab</kbd></kbd> requests the previous control.</p>
</li>
<li>
<p><i>Loop</i>: Let <var>selection mechanism</var> be "<code
data-x="selection-mechanism-sequential">sequential</code>" if <var>starting point</var> is a
<span>navigable</span> or if <var>starting point</var> is in its <code>Document</code>'s
<span>sequential focus navigation order</span>.</p>
<p>Otherwise, <var>starting point</var> is not in its <code>Document</code>'s <span>sequential
focus navigation order</span>; let <var>selection mechanism</var> be "<code
data-x="selection-mechanism-DOM">DOM</code>".</p>
</li>
<li><p>Let <var>candidate</var> be the result of running the <span>sequential navigation search
algorithm</span> with <var>starting point</var>, <var>direction</var>, and <var>selection
mechanism</var>.</p></li>
<li><p>If <var>candidate</var> is not null, then run the <span>focusing steps</span> for
<var>candidate</var> and return.</p></li>
<li><p>Otherwise, unset the <span>sequential focus navigation starting point</span>.</p></li>
<li>
<p>If <var>starting point</var> is a <span>top-level traversable</span>, or a
<span>focusable area</span> in the <span>top-level traversable</span>, the user agent
should transfer focus to its own controls appropriately (if any), honouring
<var>direction</var>, and then return.</p>
<p class="example">For example, if <var>direction</var> is <i>backward</i>, then the last
<span>sequentially focusable</span> control before the browser's rendering area would be the
control to focus.</p>
<p>If the user agent has no <span>sequentially focusable</span> controls — a kiosk-mode
browser, for instance — then the user agent may instead restart these steps with the
<var>starting point</var> being the <span>top-level traversable</span> itself.</p>
<!-- in theory, the top-level traversable _always_ has at least one focusable area: the
viewport. Even a "blocked by a modal dialog" doesn't disable the viewport (since the Document is
its DOM anchor, and the Document isn't made inert by "blocked by a modal dialog"). Note that
child navigables can have inert viewports, though (if the navigable container
itself is inert, for example) -->
</li>
<li><p>Otherwise, <var>starting point</var> is a <span>focusable area</span> in a <span>child
navigable</span>. Set <var>starting point</var> to that <span>child navigable</span>'s <span
data-x="nav-parent">parent</span> and return to the step labeled <i>loop</i>.</p></li>
<!--
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2856
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2857
-->
</ol>
<p>The <dfn>sequential navigation search algorithm</dfn>, given a <span>focusable area</span>
<var>starting point</var>, <span>sequential focus direction</span> <var>direction</var>, and
<span>selection mechanism</span> <var>selection mechanism</var>, consists of the following steps.
They return a <span>focusable area</span>-or-null.</p>
<ol>
<li>
<p>Pick the appropriate cell from the following table, and follow the instructions in that
cell.</p>
<p>The appropriate cell is the one that is from the column whose header describes
<var>direction</var> and from the first row whose header describes <var>starting point</var> and
<var>selection mechanism</var>.</p>
<table>
<thead>
<tr>
<th>
<th><var>direction</var> is "<code data-x="sequential-focus-forward">forward</code>"
<th><var>direction</var> is "<code data-x="sequential-focus-backward">backward</code>"
<tbody>
<tr>
<th><var>starting point</var> is a <span>navigable</span>
<td>Let <var>candidate</var> be the first <span>suitable sequentially focusable area</span>
in <var>starting point</var>'s <span data-x="nav-document">active document</span>, if any; or
else null
<td>Let <var>candidate</var> be the last <span>suitable sequentially focusable area</span>
in <var>starting point</var>'s <span data-x="nav-document">active document</span>, if any; or
else null
<tr>
<th><var>selection mechanism</var> is "<code data-x="selection-mechanism-DOM">DOM</code>"
<td>
<p>Let <var>candidate</var> be the <span>suitable sequentially focusable area</span>, that
appears nearest after <var>starting point</var> in <var>starting point</var>'s
<code>Document</code>, in <span>shadow-including tree order</span>, if any; or else null</p>
<p class="note">In this case, <var>starting point</var> does not necessarily belong to its
<code>Document</code>'s <span>sequential focus navigation order</span>, so we'll select the
<span data-x="suitable sequentially focusable area">suitable</span> <span data-x="list
item">item</span> from that list that comes <em>after</em> <var>starting point</var> in
<span>shadow-including tree order</span>.</p>
</td>
<td>Let <var>candidate</var> be the <span>suitable sequentially focusable area</span>, that
appears nearest before <var>starting point</var> in <var>starting point</var>'s
<code>Document</code>, in <span>shadow-including tree order</span>, if any; or else null
<tr>
<th><var>selection mechanism</var> is "<code
data-x="selection-mechanism-sequential">sequential</code>"
<td>Let <var>candidate</var> be the first <span>suitable sequentially focusable area</span>
after <var>starting point</var>, in <var>starting point</var>'s <code>Document</code>'s
<span>sequential focus navigation order</span>, if any; or else null
<td>Let <var>candidate</var> be the last <span>suitable sequentially focusable area</span>
before <var>starting point</var>, in <var>starting point</var>'s <code>Document</code>'s
<span>sequential focus navigation order</span>, if any; or else null
</table>
<p>A <dfn>suitable sequentially focusable area</dfn> is a <span>focusable area</span> whose
<span>DOM anchor</span> is not <span>inert</span> and is <span>sequentially
focusable</span>.</p>
</li>
<li>
<p>If <var>candidate</var> is a <span>navigable container</span> with a non-null <span>content
navigable</span>, then:</p>
<ol>
<li><p>Let <var>recursive candidate</var> be the result of running the <span>sequential
navigation search algorithm</span> with <var>candidate</var>'s <span>content navigable</span>,
<var>direction</var>, and "<code
data-x="selection-mechanism-sequential">sequential</code>".<!-- shift-tab from the end in
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2855 --></p></li>
<li><p>If <var>recursive candidate</var> is null, then return the result of running the
<span>sequential navigation search algorithm</span> with <var>candidate</var>,
<var>direction</var>, and <var>selection mechanism</var>.</p></li>
<li><p>Otherwise, set <var>candidate</var> to <var>recursive candidate</var>.</p></li>
</ol>
</li>
<li><p>Return <var>candidate</var>.</p></li>
</ol>
</div>
<h4>Focus management APIs</h4>
<pre><code class="idl">dictionary <dfn dictionary>FocusOptions</dfn> {
boolean <span data-x="dom-focusoptions-preventscroll">preventScroll</span> = false;
boolean <span data-x="dom-focusoptions-focusvisible">focusVisible</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>documentOrShadowRoot</var>.<span subdfn data-x="dom-documentorshadowroot-activeElement">activeElement</span></code></dt>
<dd>
<p>Returns the deepest element in the document through which or to which key events are being
routed. This is, roughly speaking, the focused element in the document.</p>
<p>For the purposes of this API, when a <span>child navigable</span> is focused, its <span
data-x="nav-container">container</span> is <a href="#bc-focus-ergo-bcc-focus">focused</a>
within its <span data-x="nav-parent">parent</span>'s <span data-x="nav-document">active
document</span>. For example, if the user moves the focus to a text control in an
<code>iframe</code>, the <code>iframe</code> is the element returned by the <code
data-x="dom-documentorshadowroot-activeElement">activeElement</code> API in the
<code>iframe</code>'s <span>node document</span>.</p>
<p>Similarly, when the focused element is in a different <span>node tree</span> than
<var>documentOrShadowRoot</var>, the element returned will be the <span
data-x="concept-DocumentFragment-host">host</span> that's located in the same <span>node
tree</span> as <var>documentOrShadowRoot</var> if <var>documentOrShadowRoot</var> is a
<span>shadow-including inclusive ancestor</span> of the focused element, and null if not.</p>
</dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-hasFocus">hasFocus</span>()</code></dt>
<dd>
<p>Returns true if key events are being routed through or to the document; otherwise, returns
false. Roughly speaking, this corresponds to the document, or a document nested inside this one,
being focused.</p>
</dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-focus">focus</span>()</code></dt>
<dd>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2823 -->
<p>Moves the focus to the window's <span data-x="window navigable">navigable</span>, if any.</p>
</dd>
<!--
<dt><var>window</var>.<code subdfn data-x="dom-window-blur">blur</code>()</dt>
<dd><p>No effect.</p></dd>
-->
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-focus">focus</span>([ { <span data-x="dom-focusoptions-preventscroll">preventScroll</span>: true } ])</code></dt>
<dd>
<p>Moves the focus to the element.</p>
<p>If the element is a <span>navigable container</span>, moves the focus to its <span>content
navigable</span> instead.</p>
<p>By default, this method also scrolls the element into view. Providing the <code
data-x="dom-focusoptions-preventscroll">preventScroll</code> option and setting it to true
prevents this behavior.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-blur">blur</span>()</code></dt>
<dd>
<p>Moves the focus to the <span>viewport</span>. Use of this method is discouraged; if you want
to focus the <span>viewport</span>, call the <code data-x="dom-focus">focus()</code> method on
the <code>Document</code>'s <span>document element</span>.</p>
<p>Do not use this method to hide the focus ring if you find the focus ring unsightly. Instead,
use the <code>:focus-visible</code> pseudo-class to override the <span>'outline'</span>
property, and provide a different way to show what element is focused. Be aware that if an
alternative focusing style isn't made available, the page will be significantly less usable for
people who primarily navigate pages using a keyboard, or those with reduced vision who use focus
outlines to help them navigate the page.</p>
<!-- we suggest using CSS here because users can override CSS, so it's no the end of the world,
unlike using .blur(), which cannot be easily overridden by users and completely breaks tab
navigation. -->
<div class="example">
<p>For example, to hide the outline from <code>textarea</code> elements and instead use a
yellow background to indicate focus, you could use:</p>
<pre><code class="css">textarea:focus-visible { outline: none; background: yellow; color: black; }</code></pre>
</div>
</dd>
</dl>
<div w-nodev>
<p id="dom-document-activeelement">The <dfn attribute for="DocumentOrShadowRoot"><code
data-x="dom-documentorshadowroot-activeElement">activeElement</code></dfn> attribute's getter must
run these steps:</p>
<ol>
<li><p>Let <var>candidate</var> be the <span>DOM anchor</span> of the <span data-x="focused area
of the document">focused area</span> of this <code>DocumentOrShadowRoot</code>'s <span>node
document</span>.</p></li>
<li><p>Set <var>candidate</var> to the result of <span data-x="dom-retarget">retargeting</span>
<var>candidate</var> against this <code>DocumentOrShadowRoot</code>.</p></li>
<li><p>If <var>candidate</var>'s <span>root</span> is not this <code>DocumentOrShadowRoot</code>,
then return null.</p></li>
<li><p>If <var>candidate</var> is not a <code>Document</code> object, then return
<var>candidate</var>.</p></li>
<li><p>If <var>candidate</var> has a <span data-x="the body element">body element</span>, then
return that <span data-x="the body element">body element</span>.</p></li>
<li><p>If <var>candidate</var>'s <span>document element</span> is non-null, then return that
<span>document element</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <dfn method for="Document"><code data-x="dom-document-hasFocus">hasFocus()</code></dfn>
method on the <code>Document</code> object, when invoked, must return the result of running the
<span>has focus steps</span> with the <code>Document</code> object as the argument.</p>
<p>The <dfn method for="Window"><code data-x="dom-window-focus">focus()</code></dfn> method, when
invoked, must run these steps:</p>
<ol>
<li><p>Let <var>current</var> be this <code>Window</code> object's <span data-x="window
navigable">navigable</span>.</p></li>
<li><p>If <var>current</var> is null, then return.</p></li>
<li><p>If the <span>allow focus steps</span> given <var>current</var>'s <span
data-x="nav-document">active document</span> return false, then return.</p></li>
<li><p>Run the <span>focusing steps</span> with <var>current</var>.</p></li>
<li><p>If <var>current</var> is a <span>top-level traversable</span>, user agents are encouraged
to trigger some sort of notification to indicate to the user that the page is attempting to gain
focus.</p></li>
</ol>
<p>The <dfn method for="Window"><code data-x="dom-window-blur">blur()</code></dfn> method steps
are to do nothing.</p>
<p class="note">Historically, the <code data-x="dom-window-focus">focus()</code> and <code
data-x="dom-window-blur">blur()</code> methods actually affected the system-level focus of the
system widget (e.g., tab or window) that contained the <span>navigable</span>, but hostile sites
widely abuse this behavior to the user's detriment.</p>
<p>The <dfn method for="HTMLOrSVGElement"><code data-x="dom-focus">focus(<var>options</var>)</code></dfn>
method on elements, when invoked, must run the following steps:</p>
<ol>
<li><p>If the <span>allow focus steps</span> given the element's <span>node document</span>
return false, then return.</p></li>
<li><p>If the element is marked as <i data-x="locked for focus">locked for focus</i>, then return.</p></li>
<li><p>Mark the element as <dfn>locked for focus</dfn>.</p></li>
<li><p>Run the <span>focusing steps</span> for the element.</p></li>
<li><p>If the value of the <dfn dict-member for="FocusOptions"><code
data-x="dom-focusoptions-focusvisible">focusVisible</code></dfn> dictionary member of
<var>options</var> is true, or is not present but in an <span>implementation-defined</span> way
the user agent determines it would be best to do so, then <span>indicate focus</span>.</p></li>
<li><p>If the value of the <dfn dict-member for="FocusOptions"><code
data-x="dom-focusoptions-preventscroll">preventScroll</code></dfn> dictionary member of
<var>options</var> is false, then <span data-x="scroll a target into view">scroll the element
into view</span> given "auto", "center", and "center".</p></li>
<li><p>Unmark the element as <i data-x="locked for focus">locked for focus</i>.</p></li>
</ol>
<p>The <dfn method for="HTMLOrSVGElement"><code data-x="dom-blur">blur()</code></dfn> method, when
invoked, should run the <span>unfocusing steps</span> for the element on which the method was
called. User agents may selectively or uniformly ignore calls to this method for usability
reasons.</p>
<p class="example">For example, if the <code data-x="dom-blur">blur()</code> method is unwisely
being used to remove the focus ring for aesthetics reasons, the page would become unusable by
keyboard users. Ignoring calls to this method would thus allow keyboard users to interact with the
page.</p>
<p>The <dfn export>allow focus steps</dfn>, given a <code>Document</code> object <var>target</var>,
are as follows:</p>
<ol>
<li><p>If <var>target</var> is <span>allowed to use</span> the "<code
data-x="focus-without-user-activation-feature">focus-without-user-activation</code>" feature,
then return true.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>target</var>'s <span>relevant global object</span> has <span data-x="transient
activation">transient user activation</span>; or</p></li>
<li><p><var>target</var>'s <span>node navigable</span>'s <span data-x="nav-container">container</span>,
if any, is marked as <i data-x="locked for focus">locked for focus</i>,</p></li>
</ul>
<p>then return true.</p>
</li>
<li><p>Return false.</p></li>
</ol>
</div>
<h4><span id="autofocusing-a-form-control:-the-autofocus-attribute"></span>The <code
data-x="attr-fe-autofocus">autofocus</code> attribute</h4>
<p>The <dfn element-attr for="html-global"><code data-x="attr-fe-autofocus">autofocus</code></dfn>
content attribute allows the author to indicate that an element is to be focused as soon as the
page is loaded, allowing the user to just start typing without having to manually focus the main
element.</p>
<p>When the <code data-x="attr-fe-autofocus">autofocus</code> attribute is specified on an element
inside <code>dialog</code> elements or <span>HTML elements</span> whose <code
data-x="attr-popover">popover</code> attribute is set, then it will be focused when the dialog or
popover becomes shown.</p>
<p>The <code data-x="attr-fe-autofocus">autofocus</code> attribute is a <span>boolean
attribute</span>.</p>
<p>To find the <dfn>nearest ancestor autofocus scoping root element</dfn> given an
<code>Element</code> <var>element</var>:</p>
<ol>
<li><p>If <var>element</var> is a <code>dialog</code> element, then return
<var>element</var>.</p></li>
<li><p>If <var>element</var>'s <code data-x="attr-popover">popover</code> attribute is not in the
<span data-x="attr-popover-none-state">no popover state</span>, then return
<var>element</var>.</p></li>
<li><p>Let <var>ancestor</var> be <var>element</var>.</p></li>
<li>
<p>While <var>ancestor</var> has a <span>parent element</span>:</p>
<ol>
<li><p>Set <var>ancestor</var> to <var>ancestor</var>'s <span>parent element</span>.</p></li>
<li><p>If <var>ancestor</var> is a <code>dialog</code> element, then return
<var>ancestor</var>.</p></li>
<li><p>If <var>ancestor</var>'s <code data-x="attr-popover">popover</code> attribute is not in
the <span data-x="attr-popover-none-state">no popover state</span>, then return
<var>ancestor</var>.</p></li>
</ol>
</li>
<li><p>Return <var>ancestor</var>.</p></li>
</ol>
<p>There must not be two elements with the same <span>nearest ancestor autofocus scoping root
element</span> that both have the <code data-x="attr-fe-autofocus">autofocus</code> attribute
specified.</p>
<div w-nodev>
<p>Each <code>Document</code> has an <dfn>autofocus candidates</dfn> <span>list</span>,
initially empty.</p>
<p>Each <code>Document</code> has an <dfn>autofocus processed flag</dfn> boolean, initially
false.</p>
<p>When an element with the <code data-x="attr-fe-autofocus">autofocus</code> attribute specified
is <span data-x="node is inserted into a document">inserted into a document</span>, run the
following steps:</p>
<ol>
<li><p>If the user has indicated (for example, by starting to type in a form control) that they
do not wish focus to be changed, then optionally return.</p></li>
<li><p>Let <var>target</var> be the element's <span>node document</span>.</p></li>
<li><p>If <var>target</var> is not <span>fully active</span>, then return.</p></li>
<li><p>If <var>target</var>'s <span>active sandboxing flag set</span> has the
<span>sandboxed automatic features browsing context flag</span>, then return.</p></li>
<li><p>If the <span>allow focus steps</span> given <var>target</var> return false, then
return.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>ancestorNavigable</var> of
<var>target</var>'s <span>ancestor navigables</span>: if <var>ancestorNavigable</var>'s <span
data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin</span> with
<var>target</var>'s <span data-x="concept-document-origin">origin</span>, then return.</p></li>
<li><p>Let <var>topDocument</var> be <var>target</var>'s <span>node navigable</span>'s <span
data-x="nav-top">top-level traversable</span>'s <span data-x="nav-document">active
document</span>.</p></li>
<li><p>If <var>topDocument</var>'s <span>autofocus processed flag</span> is false, then
<span data-x="list remove">remove</span> the element from <var>topDocument</var>'s
<span>autofocus candidates</span>, and <span data-x="list append">append</span> the element to
<var>topDocument</var>'s <span>autofocus candidates</span>.</p></li>
</ol>
<p class="note">We do not check if an element is a <span>focusable area</span> before storing it
in the <span>autofocus candidates</span> list, because even if it is not a focusable area when it
is inserted, it could become one by the time <span>flush autofocus candidates</span> sees it.</p>
<p>To <dfn>flush autofocus candidates</dfn> for a document <var>topDocument</var>, run these
steps:</p>
<ol>
<li><p>If <var>topDocument</var>'s <span>autofocus processed flag</span> is true, then
return.</p></li>
<li><p>Let <var>candidates</var> be <var>topDocument</var>'s <span>autofocus
candidates</span>.</p></li>
<li><p>If <var>candidates</var> <span data-x="list is empty">is empty</span>, then
return.</p></li>
<li>
<p>If <var>topDocument</var>'s <span data-x="focused area of the document">focused area</span>
is not <var>topDocument</var> itself, or <var>topDocument</var> has non-null
<span>target element</span>, then:</p>
<ol>
<li><p><span data-x="list empty">Empty</span> <var>candidates</var>.</p></li>
<li><p>Set <var>topDocument</var>'s <span>autofocus processed flag</span> to true.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p>While <var>candidates</var> is not <span data-x="list is empty">empty</span>:</p>
<ol>
<li><p>Let <var>element</var> be <var>candidates</var>[0].</p></li>
<li><p>Let <var>doc</var> be <var>element</var>'s <span>node document</span>.</p></li>
<li><p>If <var>doc</var> is not <span>fully active</span>, then
<span data-x="list remove">remove</span> <var>element</var> from <var>candidates</var>, and
<span>continue</span>.</p></li>
<li><p>If <var>doc</var>'s <span>node navigable</span>'s <span data-x="nav-top">top-level
traversable</span> is not the same as <var>topDocument</var>'s <span>node navigable</span>,
then <span data-x="list remove">remove</span> <var>element</var> from <var>candidates</var>,
and <span>continue</span>.</p></li>
<li>
<p>If <var>doc</var>'s <span>script-blocking style sheet set</span> is not <span data-x="list
empty">empty</span>, then return.</p>
<p class="note">In this case, <var>element</var> is the currently-best candidate, but
<var>doc</var> is not ready for autofocusing. We'll try again next time <span>flush
autofocus candidates</span> is called.</p>
</li>
<li><p><span data-x="list remove">Remove</span> <var>element</var> from
<var>candidates</var>.</p></li>
<li><p>Let <var>inclusiveAncestorDocuments</var> be a <span>list</span> consisting of the
<span data-x="nav-document">active document</span> of <var>doc</var>'s <span>inclusive
ancestor navigables</span>.</p></li>
<li><p>If any <code>Document</code> in <var>inclusiveAncestorDocuments</var> has non-null
<span>target element</span>, then <span>continue</span>.</p></li>
<li><p>Let <var>target</var> be <var>element</var>.</p></li>
<li>
<p>If <var>target</var> is not a <span>focusable area</span>, then set <var>target</var> to
the result of <span data-x="get the focusable area">getting the focusable area</span> for
<var>target</var>.</p>
<p class="note"><span>Autofocus candidates</span> can <span data-x="list
contains">contain</span> elements which are not <span data-x="focusable area">focusable
areas</span>. In addition to the special cases handled in the <span>get the focusable
area</span> algorithm, this can happen because a non-<span>focusable area</span> element with
an <code data-x="attr-fe-autofocus">autofocus</code> attribute was <span data-x="node is
inserted into a document">inserted into a document</span> and it never became focusable, or
because the element was focusable but its status changed while it was stored in
<span>autofocus candidates</span>.</p>
</li>
<li>
<p>If <var>target</var> is not null, then:</p>
<ol>
<li><p><span data-x="list empty">Empty</span> <var>candidates</var>.</p></li>
<li><p>Set <var>topDocument</var>'s <span>autofocus processed flag</span> to true.</p></li>
<li><p>Run the <span>focusing steps</span> for <var>target</var>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p class="note">This handles the automatic focusing during document load. The <code
data-x="dom-dialog-show">show()</code> and <code data-x="dom-dialog-showModal">showModal()</code>
methods of <code>dialog</code> elements also processes the <code
data-x="attr-fe-autofocus">autofocus</code> attribute.</p>
<p class="note">Focusing the element does not imply that the user agent has to focus the browser
window if it has lost focus.</p>
<p>The <dfn attribute for="HTMLOrSVGElement"><code
data-x="dom-fe-autofocus">autofocus</code></dfn> IDL attribute must <span>reflect</span> the
content attribute of the same name.</p>
</div>
<div class="example">
<p>In the following snippet, the text control would be focused when
the document was loaded.</p>
<pre><code class="html"><input maxlength="256" name="q" value="" autofocus>
<input type="submit" value="Search"></code></pre>
</div>
<div class="example">
<p>The <code data-x="attr-fe-autofocus">autofocus</code> attribute applies to all elements, not
just to form controls. This allows examples such as the following:</p>
<pre><code class="html"><div contenteditable autofocus>Edit <strong>me!</strong><div></code></pre>
</div>
<h3>Assigning keyboard shortcuts</h3>
<h4>Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Each element that can be activated or focused can be assigned a single key combination to
activate it, using the <code data-x="attr-accesskey">accesskey</code> attribute.</p>
<p>The exact shortcut is determined by the user agent, based on information about the user's
keyboard, what keyboard shortcuts already exist on the platform, and what other shortcuts have
been specified on the page, using the information provided in the <code
data-x="attr-accesskey">accesskey</code> attribute as a guide.</p>
<p>In order to ensure that a relevant keyboard shortcut is available on a wide variety of input
devices, the author can provide a number of alternatives in the <code
data-x="attr-accesskey">accesskey</code> attribute.</p>
<p>Each alternative consists of a single character, such as a letter or digit.</p>
<p>User agents can provide users with a list of the keyboard shortcuts, but authors are encouraged
to do so also. The <code data-x="dom-accessKeyLabel">accessKeyLabel</code> IDL attribute returns a
string representing the actual key combination assigned by the user agent.</p>
<div class="example">
<p>In this example, an author has provided a button that can be invoked using a shortcut key. To
support full keyboards, the author has provided "C" as a possible key. To support devices
equipped only with numeric keypads, the author has provided "1" as another possible key.</p>
<pre><code class="html"><input type=button value=Collect onclick="collect()"
<strong>accesskey="C 1"</strong> id=c></code></pre>
</div>
<div class="example">
<p>To tell the user what the shortcut key is, the author has this script here opted to explicitly
add the key combination to the button's label:</p>
<pre><code class="js">function addShortcutKeyLabel(button) {
<strong> if (button.accessKeyLabel != '')
button.value += ' (' + button.accessKeyLabel + ')';</strong>
}
addShortcutKeyLabel(document.getElementById('c'));</code></pre>
<p>Browsers on different platforms will show different labels, even for the same key combination,
based on the convention prevalent on that platform. For example, if the key combination is the
Control key, the Shift key, and the letter C, a Windows browser might display
"<samp>Ctrl+Shift+C</samp>", whereas a Mac browser might display "<samp>^⇧C</samp>", while
an Emacs browser might just display "<samp>C-C</samp>". Similarly, if the key combination is the
Alt key and the Escape key, Windows might use "<samp>Alt+Esc</samp>", Mac might use
"<samp>⌥⎋</samp>", and an Emacs browser might use "<samp>M-ESC</samp>" or
"<samp>ESC ESC</samp>".</p>
<p>In general, therefore, it is unwise to attempt to parse the value returned from the <code
data-x="dom-accessKeyLabel">accessKeyLabel</code> IDL attribute.</p>
</div>
<h4>The <dfn element-attr for="html-global"><code data-x="attr-accesskey">accesskey</code></dfn>
attribute</h4>
<p>All <span>HTML elements</span> may have the <code data-x="attr-accesskey">accesskey</code>
content attribute set. The <code data-x="attr-accesskey">accesskey</code> attribute's value is used
by the user agent as a guide for creating a keyboard shortcut that activates or focuses the
element.</p>
<p>If specified, the value must be an <span>ordered set of unique space-separated tokens</span>
none of which are <span>identical to</span> another token and each of which must be exactly one
code point in length.</p>
<div class="example">
<p>In the following example, a variety of links are given with access keys so that keyboard users
familiar with the site can more quickly navigate to the relevant pages:</p>
<pre><code class="html"><nav>
<p>
<a title="Consortium Activities" accesskey="A" href="/Consortium/activities">Activities</a> |
<a title="Technical Reports and Recommendations" accesskey="T" href="/TR/">Technical Reports</a> |
<a title="Alphabetical Site Index" accesskey="S" href="/Consortium/siteindex">Site Index</a> |
<a title="About This Site" accesskey="B" href="/Consortium/">About Consortium</a> |
<a title="Contact Consortium" accesskey="C" href="/Consortium/contact">Contact</a>
</p>
</nav></code></pre>
</div>
<div class="example">
<p>In the following example, the search field is given two possible access keys, "s" and "0" (in
that order). A user agent on a device with a full keyboard might pick <kbd><kbd>Ctrl</kbd> +
<kbd>Alt</kbd> + <kbd>S</kbd></kbd> as the shortcut key, while a user agent on a small device
with just a numeric keypad might pick just the plain unadorned key <kbd><kbd>0</kbd></kbd>:</p>
<pre><code class="html"><form action="/search">
<label>Search: <input type="search" name="q" accesskey="s 0"></label>
<input type="submit">
</form></code></pre>
</div>
<div class="example">
<p>In the following example, a button has possible access keys described. A script then tries to
update the button's label to advertise the key combination the user agent selected.</p>
<pre><code class="html"><input type=submit accesskey="N @ 1" value="Compose">
...
<script>
function labelButton(button) {
if (button.accessKeyLabel)
button.value += ' (' + button.accessKeyLabel + ')';
}
var inputs = document.getElementsByTagName('input');
for (var i = 0; i < inputs.length; i += 1) {
if (inputs[i].type == "submit")
labelButton(inputs[i]);
}
</script></code></pre>
<p>On one user agent, the button's label might become "<samp>Compose (⌘N)</samp>". On
another, it might become "<samp>Compose (Alt+⇧+1)</samp>". If the user agent doesn't
assign a key, it will be just "<samp>Compose</samp>". The exact string depends on what the
<span>assigned access key</span> is, and on how the user agent represents that key
combination.</p>
</div>
<div w-nodev>
<h4 id="keyboard-shortcuts-processing-model"><span id="processing-model-6"></span>Processing
model</h4>
<p>An element's <dfn>assigned access key</dfn> is a key combination derived from the element's
<code data-x="attr-accesskey">accesskey</code> content attribute. Initially, an element must not
have an <span>assigned access key</span>.</p>
<p>Whenever an element's <code data-x="attr-accesskey">accesskey</code> attribute is set, changed,
or removed, the user agent must update the element's <span>assigned access key</span> by running
the following steps:</p>
<ol>
<li><p>If the element has no <code data-x="attr-accesskey">accesskey</code> attribute, then skip
to the <i>fallback</i> step below.</p></li>
<li><p>Otherwise, <span data-x="split a string on ASCII whitespace">split the attribute's value
on ASCII whitespace</span>, and let <var>keys</var> be the resulting tokens.</p></li>
<li>
<p>For each value in <var>keys</var> in turn, in the order the tokens appeared in the
attribute's value, run the following substeps:</p>
<ol>
<li><p>If the value is not a string exactly one code point in length, then skip the remainder
of these steps for this value.</p></li>
<li><p>If the value does not correspond to a key on the system's keyboard, then skip the
remainder of these steps for this value.</p></li>
<li><p>
<!--INSERT TRACKING-->
If the user agent can find a mix of zero or more modifier keys that, combined with the key that
corresponds to the value given in the attribute, can be used as the access key, then the user
agent may assign that combination of keys as the element's <span>assigned access key</span> and
return.</p></li>
</ol>
</li>
<li><p><i>Fallback</i>: Optionally, the user agent may assign a key combination of its choosing
as the element's <span>assigned access key</span> and then return.</p></li>
<li><p>If this step is reached, the element has no <span>assigned access key</span>.</p></li>
</ol>
<p>Once a user agent has selected and assigned an access key for an element, the user agent should
not change the element's <span>assigned access key</span> unless the <code
data-x="attr-accesskey">accesskey</code> content attribute is changed or the element is moved to
another <code>Document</code>.</p>
<p>When the user presses the key combination corresponding to the <span>assigned access key</span>
for an element, if the element <span data-x="concept-command">defines a command</span>, the
command's <span data-x="command-facet-HiddenState">Hidden State</span> facet is false (visible),
the command's <span data-x="command-facet-DisabledState">Disabled State</span> facet is also false
(enabled), the element is <span>in a document</span> that has a non-null <span
data-x="concept-document-bc">browsing context</span>, and neither the element nor any of its
ancestors has a <code data-x="attr-hidden">hidden</code> attribute specified, then the user agent
must trigger the <span data-x="command-facet-Action">Action</span> of the command.</p>
<p class="note">User agents <a href="#expose-commands-in-ui">might expose</a> elements that have
an <code data-x="attr-accesskey">accesskey</code> attribute in other ways as well, e.g. in a menu
displayed in response to a specific key combination.</p> <!-- the actual conformance criteria for
this is in the section that defines commands -->
<hr>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-accessKey">accessKey</code></dfn> IDL
attribute must <span>reflect</span> the <code data-x="attr-accesskey">accesskey</code> content
attribute.</p>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-accessKeyLabel">accessKeyLabel</code></dfn> IDL attribute must return a string that
represents the element's <span>assigned access key</span>, if any. If the element does not have
one, then the IDL attribute must return the empty string.</p>
</div>
<h3>Editing</h3>
<h4 id="contenteditable">Making document regions editable: The <code
data-x="attr-contenteditable">contenteditable</code> content attribute</h4>
<pre><code class="idl">interface mixin <dfn interface>ElementContentEditable</dfn> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-contentEditable">contentEditable</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-enterKeyHint">enterKeyHint</span>;
readonly attribute boolean <span data-x="dom-isContentEditable">isContentEditable</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-inputMode">inputMode</span>;
};</code></pre>
<p>The <dfn element-attr for="html-global"><code
data-x="attr-contenteditable">contenteditable</code></dfn> content attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/contenteditable"><code
data-x="attr-contenteditable-true">true</code></dfn>
<td rowspan=2><dfn data-x="attr-contenteditable-true-state">true</dfn>
<td rowspan=2>The element is editable.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/contenteditable"><code
data-x="attr-contenteditable-false">false</code></dfn>
<td><dfn data-x="attr-contenteditable-false-state">false</dfn>
<td>The element is not editable.
<tr>
<td><dfn attr-value for="html-global/contenteditable"><code
data-x="attr-contenteditable-plaintextonly">plaintext-only</code></dfn>
<td><dfn data-x="attr-contenteditable-plaintextonly-state">plaintext-only</dfn>
<td>Only the element's raw text content is editable; rich formatting is disabled.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-contenteditable-inherit-state">inherit</dfn> state. The inherit state indicates that
the element is editable (or not) based on the parent element's state.</p>
<div class="example">
<p>For example, consider a page that has a <code>form</code> and a <code>textarea</code> to
publish a new article, where the user is expected to write the article using HTML:</p>
<pre><code class="html"><form method=POST>
<fieldset>
<legend>New article</legend>
<textarea name=article>&lt;p>Hello world.&lt;/p></textarea>
</fieldset>
<p><button>Publish</button></p>
</form></code></pre>
<p>When scripting is enabled, the <code>textarea</code> element could be replaced with a rich
text control instead, using the <code data-x="attr-contenteditable">contenteditable</code>
attribute:</p>
<pre><code class="html"><form method=POST>
<fieldset>
<legend>New article</legend>
<textarea id=textarea name=article>&lt;p>Hello world.&lt;/p></textarea>
<div id=div style="white-space: pre-wrap" hidden><p>Hello world.</p></div>
<script>
let textarea = document.getElementById("textarea");
let div = document.getElementById("div");
textarea.hidden = true;
div.hidden = false;
div.contentEditable = "true";
div.oninput = (e) => {
textarea.value = div.innerHTML;
};
</script>
</fieldset>
<p><button>Publish</button></p>
</form></code></pre>
<p>Features to enable, e.g., inserting links, can be implemented using the <code
data-x="dom-document-execCommand">document.execCommand()</code> API, or using
<code>Selection</code> APIs and other DOM APIs. <ref>EXECCOMMAND</ref> <ref>SELECTION</ref>
<ref>DOM</ref></p>
</div>
<div class="example">
<p>The <code data-x="attr-contenteditable">contenteditable</code> attribute can also be used to
great effect:</p>
<pre><code class="html"><!doctype html>
<html lang=en>
<title>Live CSS editing!</title>
<style style=white-space:pre contenteditable>
html { margin:.2em; font-size:2em; color:lime; background:purple }
head, title, style { display:block }
body { display:none }
</style></code></pre>
</div>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-contentEditable">contentEditable</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns "<code data-x="">true</code>", "<code data-x="">plaintext-only</code>", "<code
data-x="">false</code>", or "<code data-x="attr-contenteditable-inherit-state">inherit</code>",
based on the state of the <code data-x="attr-contenteditable">contenteditable</code>
attribute.</p>
<p>Can be set, to change that state.</p>
<p>Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if the new value
isn't one of those strings.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-isContentEditable">isContentEditable</span></code></dt>
<dd><p>Returns true if the element is editable; otherwise, returns false.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="ElementContentEditable"><code
data-x="dom-contentEditable">contentEditable</code></dfn> IDL attribute, on getting, must return
the string "<code data-x="">true</code>" if the content attribute is set to the <span
data-x="attr-contenteditable-true-state">true</span> state, "<code
data-x="">plaintext-only</code>" if the content attribute is set to the <span
data-x="attr-contenteditable-plaintextonly-state">plaintext-only</span> state, "<code
data-x="">false</code>" if the content attribute is set to the <span
data-x="attr-contenteditable-false-state">false</span> state, and "<code
data-x="attr-contenteditable-inherit-state">inherit</code>" otherwise. On setting, if the new
value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">inherit</code>" then the content attribute must be removed, if the new value is an
<span>ASCII case-insensitive</span> match for the string "<code data-x="">true</code>" then the
content attribute must be set to the string "<code data-x="">true</code>", if the new value is an
<span>ASCII case-insensitive</span> match for the string "<code data-x="">plaintext-only</code>"
then the content attribute must be set to the string "<code data-x="">plaintext-only</code>", if
the new value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">false</code>" then the content attribute must be set to the string "<code
data-x="">false</code>", and otherwise the attribute setter must throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p>
<p>The <dfn attribute for="ElementContentEditable"><code
data-x="dom-isContentEditable">isContentEditable</code></dfn> IDL attribute, on getting, must
return true if the element is either an <span>editing host</span> or <span>editable</span>, and
false otherwise.</p>
</div>
<h4 id="making-entire-documents-editable:-the-designmode-idl-attribute">Making entire documents
editable: the <code data-x="dom-document-designMode">designMode</code> getter and setter</h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-designMode">designMode</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns "<code data-x="">on</code>" if the document is editable, and "<code
data-x="">off</code>" if it isn't.</p>
<p>Can be set, to change the document's current state. This focuses the document and resets the
selection in that document.</p>
</dd>
</dl>
<div w-nodev>
<p><code>Document</code> objects have an associated <dfn>design mode enabled</dfn>, which is a
boolean. It is initially false.</p>
<p>The <dfn attribute for="Document" id="designMode"><code
data-x="dom-document-designMode">designMode</code></dfn> getter steps are to return "<code
data-x="">on</code>" if <span>this</span>'s <span>design mode enabled</span> is true; otherwise
"<code data-x="">off</code>".</p>
<p>The <code data-x="dom-document-designMode">designMode</code> setter steps are:</p>
<ol>
<li><p>Let <var>value</var> be the given value, <span>converted to ASCII
lowercase</span>.</p></li>
<li>
<p>If <var>value</var> is "<code data-x="">on</code>" and <span>this</span>'s <span>design mode
enabled</span> is false, then:</p>
<ol>
<li><p>Set <span>this</span>'s <span>design mode enabled</span> to true.</p></li>
<li><p>Reset <span>this</span>'s <span>active range</span>'s start and end boundary points to
be at the start of <span>this</span>.</p></li>
<li><p>Run the <span>focusing steps</span> for <span>this</span>'s <span>document
element</span>, if non-null.</p></li>
</ol>
</li>
<li><p>If <var>value</var> is "<code data-x="">off</code>", then set <span>this</span>'s
<span>design mode enabled</span> to false.</p></li>
</ol>
</div>
<h4>Best practices for in-page editors</h4>
<p>Authors are encouraged to set the <span>'white-space'</span> property on <span data-x="editing
host">editing hosts</span> and on markup that was originally created through these editing
mechanisms to the value 'pre-wrap'. Default HTML whitespace handling is not well suited to WYSIWYG
editing, and line wrapping will not work correctly in some corner cases if
<span>'white-space'</span> is left at its default value.</p>
<div class="example">
<p>As an example of problems that occur if the default 'normal' value is used instead, consider
the case of the user typing "<kbd>yellow␣␣ball</kbd>", with two spaces (here
represented by "␣") between the words. With the editing rules in place for the default
value of <span>'white-space'</span> ('normal'), the resulting markup will either consist of
"<samp>yellow&nbsp; ball</samp>" or "<samp>yellow &nbsp;ball</samp>"; i.e.,
there will be a non-breaking space between the two words in addition to the regular space. This
is necessary because the 'normal' value for <span>'white-space'</span> requires adjacent regular
spaces to be collapsed together.</p>
<p>In the former case, "<samp>yellow⍽</samp>" might wrap to the next line ("⍽"
being used here to represent a non-breaking space) even though "<samp>yellow</samp>" alone might
fit at the end of the line; in the latter case, "<samp>⍽ball</samp>", if wrapped to the
start of the line, would have visible indentation from the non-breaking space.</p>
<p>When <span>'white-space'</span> is set to 'pre-wrap', however, the editing rules will instead
simply put two regular spaces between the words, and should the two words be split at the end of
a line, the spaces would be neatly removed from the rendering.</p>
</div>
<div w-nodev>
<h4>Editing APIs</h4>
<p>An <dfn export>editing host</dfn> is either an <span data-x="HTML elements">HTML element</span>
with its <code data-x="attr-contenteditable">contenteditable</code> attribute in the <i>true</i>
state or <i>plaintext-only</i> state, or a <span data-x="concept-tree-child">child</span> <span
data-x="HTML elements">HTML element</span> of a <code>Document</code> whose <span>design mode
enabled</span> is true.</p>
<p>The definition of the terms <dfn
data-x-href="https://w3c.github.io/editing/docs/execCommand/#active-range">active range</dfn>, <dfn
data-x-href="https://w3c.github.io/editing/docs/execCommand/#editing-host-of">editing host
of</dfn>, and <dfn
data-x-href="https://w3c.github.io/editing/docs/execCommand/#editable">editable</dfn>, the user
interface requirements of elements that are <span data-x="editing host">editing hosts</span> or
<span>editable</span>, the
<dfn data-x="dom-document-execCommand" id="execCommand" data-x-href="https://w3c.github.io/editing/docs/execCommand/#execcommand%28%29"><code>execCommand()</code></dfn>,
<dfn data-x-href="https://w3c.github.io/editing/docs/execCommand/#querycommandenabled%28%29"><code data-x="dom-document-queryCommandEnabled">queryCommandEnabled()</code></dfn>,
<dfn data-x-href="https://w3c.github.io/editing/docs/execCommand/#querycommandindeterm%28%29"><code data-x="dom-document-queryCommandIndeterm">queryCommandIndeterm()</code></dfn>,
<dfn data-x-href="https://w3c.github.io/editing/docs/execCommand/#querycommandstate%28%29"><code data-x="dom-document-queryCommandState">queryCommandState()</code></dfn>,
<dfn data-x-href="https://w3c.github.io/editing/docs/execCommand/#querycommandsupported%28%29"><code data-x="dom-document-queryCommandSupported">queryCommandSupported()</code></dfn>, and
<dfn data-x-href="https://w3c.github.io/editing/docs/execCommand/#querycommandvalue%28%29"><code data-x="dom-document-queryCommandValue">queryCommandValue()</code></dfn>
methods, text selections, and the <dfn
data-x-href="https://w3c.github.io/editing/docs/execCommand/#delete-the-selection">delete the
selection</dfn> algorithm are defined in <cite>execCommand</cite>. <ref>EXECCOMMAND</ref></p>
</div>
<h4>Spelling and grammar checking</h4>
<div w-nodev>
<p>User agents can support the checking of spelling and grammar of editable text, either in form
controls (such as the value of <code>textarea</code> elements), or in elements in an <span>editing
host</span> (e.g. using <code data-x="attr-contenteditable">contenteditable</code>).</p>
<p>For each element, user agents must establish a <dfn data-x="concept-spellcheck-default">default
behavior</dfn>, either through defaults or through preferences expressed by the user. There are
three possible default behaviors for each element:</p>
<dl>
<dt><dfn data-x="concept-spellcheck-default-true">true-by-default</dfn>
<dd>The element will be checked for spelling and grammar if its contents are editable and
spellchecking is not explicitly disabled through the <code
data-x="attr-spellcheck">spellcheck</code> attribute.
<dt><dfn data-x="concept-spellcheck-default-false">false-by-default</dfn>
<dd>The element will never be checked for spelling and grammar unless spellchecking is
explicitly enabled through the <code data-x="attr-spellcheck">spellcheck</code> attribute.
<dt><dfn data-x="concept-spellcheck-default-inherit">inherit-by-default</dfn>
<dd>The element's default behavior is the same as its parent element's. Elements that have no
parent element cannot have this as their default behavior.
</dl>
<hr>
</div>
<p>The <dfn element-attr for="html-global"><code data-x="attr-spellcheck">spellcheck</code></dfn>
attribute is an <span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/spellcheck"><code
data-x="attr-spellcheck-true">true</code></dfn>
<td rowspan=2><dfn data-x="attr-spellcheck-true-state">true</dfn>
<td rowspan=2>Spelling and grammar will be checked.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/spellcheck"><code
data-x="attr-spellcheck-false">false</code></dfn>
<td><dfn data-x="attr-spellcheck-false-state">false</dfn>
<td>Spelling and grammar will not be checked.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-spellcheck-default-state">default</dfn> state. The default state indicates that the
element is to act according to a default behavior, possibly based on the parent element's own
<code data-x="attr-spellcheck">spellcheck</code> state, as defined below.</p>
<div w-nodev>
<hr>
</div>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-spellcheck">spellcheck</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if the element is to have its spelling and grammar checked; otherwise, returns
false.</p>
<p>Can be set, to override the default and set the <code
data-x="attr-spellcheck">spellcheck</code> content attribute.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-spellcheck">spellcheck</code></dfn> IDL
attribute, on getting, must return true if the element's <code
data-x="attr-spellcheck">spellcheck</code> content attribute is in the <span
data-x="attr-spellcheck-true-state">true</span> state, or if the element's <code
data-x="attr-spellcheck">spellcheck</code> content attribute is in the <span
data-x="attr-spellcheck-default-state">default</span> state and the element's <span
data-x="concept-spellcheck-default">default behavior</span> is <span
data-x="concept-spellcheck-default-true">true-by-default</span>, or if the element's <code
data-x="attr-spellcheck">spellcheck</code> content attribute is in the <span
data-x="attr-spellcheck-default-state">default</span> state and the element's <span
data-x="concept-spellcheck-default">default behavior</span> is <span
data-x="concept-spellcheck-default-inherit">inherit-by-default</span> and the element's parent
element's <code data-x="dom-spellcheck">spellcheck</code> IDL attribute would return true;
otherwise, if none of those conditions applies, then the attribute must instead return false.</p>
<p class="note">The <code data-x="dom-spellcheck">spellcheck</code> IDL attribute is not affected
by user preferences that override the <code data-x="attr-spellcheck">spellcheck</code> content
attribute, and therefore might not reflect the actual spellchecking state.</p>
<p>On setting, if the new value is true, then the element's <code
data-x="attr-spellcheck">spellcheck</code> content attribute must be set to
"<code data-x="">true</code>", otherwise it must be set to "<code data-x="">false</code>".
<hr>
<p>User agents should only consider the following pieces of text as checkable for the purposes of
this feature:</p>
<ul>
<li>The <span data-x="concept-fe-value">value</span> of <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attributes are in the <span
data-x="attr-input-type-text">Text</span>, <span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-url">URL</span>, or <span
data-x="attr-input-type-email">Email</span> states and that are <i
data-x="concept-fe-mutable">mutable</i> (i.e. that do not have the <code
data-x="attr-input-readonly">readonly</code> attribute specified and that are not <span
data-x="concept-fe-disabled">disabled</span>).</li>
<li>The <span data-x="concept-fe-value">value</span> of <code>textarea</code> elements that do not
have a <code data-x="attr-textarea-readonly">readonly</code> attribute and that are not <span
data-x="concept-fe-disabled">disabled</span>.</li>
<li>Text in <code>Text</code> nodes that are children of <span data-x="editing host">editing
hosts</span> or <span>editable</span> elements.</li>
<li>Text in attributes of <span>editable</span> elements.</li>
</ul>
<p>For text that is part of a <code>Text</code> node, the element with which the text is
associated is the element that is the immediate parent of the first character of the word,
sentence, or other piece of text. For text in attributes, it is the attribute's element. For the
values of <code>input</code> and <code>textarea</code> elements, it is the element itself.</p>
<p>To determine if a word, sentence, or other piece of text in an applicable element (as defined
above) is to have spelling- and grammar-checking enabled, the UA must use the following
algorithm:</p>
<ol>
<!-- user override -->
<li>If the user has disabled the checking for this text, then the checking is disabled.</li>
<li>Otherwise, if the user has forced the checking for this text to always be enabled, then the
checking is enabled.</li>
<!-- content attribute: on, off -->
<li>Otherwise, if the element with which the text is associated has a <code
data-x="attr-spellcheck">spellcheck</code> content attribute, then: if that attribute is in the
<span data-x="attr-spellcheck-true-state">true</span> state, then checking is enabled; otherwise, if that attribute is in the <span data-x="attr-spellcheck-false-state">false</span>
state, then checking is disabled.</li>
<!-- inherit, if there is one to inherit from -->
<li>Otherwise, if there is an ancestor element with a <code
data-x="attr-spellcheck">spellcheck</code> content attribute that is not in the <span
data-x="attr-spellcheck-default-state">default</span>
state, then: if the nearest such ancestor's <code data-x="attr-spellcheck">spellcheck</code>
content attribute is in the <span data-x="attr-spellcheck-true-state">true</span> state, then
checking is enabled; otherwise, checking is disabled.</li>
<!-- default -->
<li>Otherwise, if the element's <span data-x="concept-spellcheck-default">default behavior</span>
is <span data-x="concept-spellcheck-default-true">true-by-default</span>, then checking is
enabled.</li>
<li>Otherwise, if the element's <span data-x="concept-spellcheck-default">default behavior</span>
is <span data-x="concept-spellcheck-default-false">false-by-default</span>, then checking is
disabled.</li>
<!-- default inheritance -->
<li>Otherwise, if the element's parent element has <em>its</em> checking enabled, then checking
is enabled.</li>
<li>Otherwise, checking is disabled.</li>
</ol>
<p>If the checking is enabled for a word/sentence/text, the user agent should indicate spelling
and grammar errors in that text. User agents should take into account the other semantics given in
the document when suggesting spelling and grammar corrections. User agents may use the language of
the element to determine what spelling and grammar rules to use, or may use the user's preferred
language settings. UAs should use <code>input</code> element attributes such as <code
data-x="attr-input-pattern">pattern</code> to ensure that the resulting value is valid, where
possible.</p>
<p>If checking is disabled, the user agent should not indicate spelling or grammar errors for that
text.</p>
<div class="example">
<p>The element with ID "a" in the following example would be the one used to determine if the
word "Hello" is checked for spelling errors. In this example, it would not be.</p>
<pre><code class="html"><div contenteditable="true">
<span spellcheck="false" id="a">Hell</span><em>o!</em>
</div></code></pre>
<p>The element with ID "b" in the following example would have checking enabled (the leading
space character in the attribute's value on the <code>input</code> element causes the attribute
to be ignored, so the ancestor's value is used instead, regardless of the default).</p>
<pre class="bad"><code class="html"><p spellcheck="true">
<label>Name: <input spellcheck=" false" id="b"></label>
</p></code></pre>
</div>
</div>
<p class="note">This specification does not define the user interface for spelling and grammar
checkers. A user agent could offer on-demand checking, could perform continuous checking while the
checking is enabled, or could use other interfaces.</p>
<h4>Writing suggestions</h4>
<p>User agents offer writing suggestions as users type into editable regions, either in form
controls (e.g., the <code>textarea</code> element) or in elements in an <span data-x="editing
host"> editing host</span>.</p>
<p>The <dfn element-attr for="html-global"><code
data-x="attr-writingsuggestions">writingsuggestions</code></dfn> content attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/writingsuggestions"><code
data-x="attr-writingsuggestions-true">true</code></dfn>
<td rowspan="2"><dfn data-x="attr-writingsuggestions-true-state">true</dfn>
<td rowspan="2">Writing suggestions should be offered on this element.
</tr>
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/writingsuggestions"><code
data-x="attr-writingsuggestions-false">false</code></dfn>
<td><dfn data-x="attr-writingsuggestions-false-state">false</dfn>
<td>Writing suggestions should not be offered on this element.
</tr>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <dfn
data-x="attr-writingsuggestions-default-state">default</dfn> state. The default state indicates
that the element is to act according to a default behavior, possibly based on the parent
element's own <code data-x="attr-writingsuggestions">writingsuggestions</code> state, as defined
below.</p>
<p>The attribute's <i data-x="invalid value default">invalid value default</i> is the <span
data-x="attr-writingsuggestions-true-state">true</span> state.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-writingSuggestions">writingSuggestions</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns "<code data-x="">true</code>" if the user agent is to offer writing suggestions under
the scope of the element; otherwise, returns "<code data-x="">false</code>".</p>
<p>Can be set, to override the default and set the <code data-x="attr-writingsuggestions">
writingsuggestions</code> content attribute.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn>computed writing suggestions value</dfn> of a given <var>element</var> is
determined by running the following steps:</p>
<ol>
<li><p>If <var>element</var>'s <code data-x="attr-writingsuggestions">writingsuggestions</code>
content attribute is in the <span data-x="attr-writingsuggestions-false-state">false</span>
state, return "<code data-x="">false</code>".</p></li>
<li><p>If <var>element</var>'s <code
data-x="attr-writingsuggestions">writingsuggestions</code> content attribute is in the <span
data-x="attr-writingsuggestions-default-state">default</span> state, <var>element</var> has a
parent element, and the <span>computed writing suggestions value</span> of
<var>element</var>'s parent element is "<code data-x="">false</code>", then return
"<code data-x="">false</code>".</p></li>
<li><p>Return "<code data-x="">true</code>".</p></li>
</ol>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-writingSuggestions">writingSuggestions</code></dfn> getter steps are:</p>
<ol>
<li><p>Return <span>this</span>'s <span>computed writing suggestions value</span>.</p></li>
</ol>
<p class="note">The <code data-x="dom-writingSuggestions">writingSuggestions</code> IDL
attribute is not affected by user preferences that override the <code
data-x="attr-writingsuggestions">writingsuggestions</code> content attribute, and therefore
might not reflect the actual writing suggestions state.</p>
<p>The <code data-x="dom-writingSuggestions">writingSuggestions</code> setter steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <code data-x="attr-writingsuggestions">writingsuggestions</code>
content attribute to the given value.</p></li>
</ol>
</div>
<hr>
<p>User agents should only offer suggestions within an element's scope if the
result of running the following algorithm given <var>element</var> returns true:</p>
<ol>
<!-- user override -->
<li><p>If the user has disabled writing suggestions, then return false.</p></li>
<!-- element type -->
<li>
<p>If none of the following conditions are true:</p>
<ul>
<li><p><var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in either the <span
data-x="attr-input-type-text">Text</span>, <span
data-x="attr-input-type-search">Search</span>, <span
data-x="attr-input-type-tel">Telephone</span>, <span data-x="attr-input-type-url">URL</span>,
or <span data-x="attr-input-type-email">Email</span> state and is <i
data-x="concept-fe-mutable">mutable</i>;</p></li>
<li><p><var>element</var> is a <code>textarea</code> element that is <i
data-x="concept-fe-mutable">mutable</i>; or</p></li>
<li><p><var>element</var> is an <span data-x="editing host">editing host</span> or is
<span>editable</span>,</p></li>
</ul>
<p>then return false.</p>
</li>
<!--
content attribute: false on this element, or inherit if there is an ancestor to inherit from
-->
<li><p>If <var>element</var> has an <span>inclusive ancestor</span> with a <code
data-x="attr-writingsuggestions">writingsuggestions</code> content attribute that's not in the
<span data-x="attr-writingsuggestions-default-state">default</span> and the nearest such
ancestor's <code data-x="attr-writingsuggestions">writingsuggestions</code> content attribute is
in the <span data-x="attr-writingsuggestions-false-state">false</span> state, then return
false.</p></li>
<li><p>Otherwise, return true.</p></li>
</ol>
<p class="note">This specification does not define the user interface for writing suggestions.
A user agent could offer on-demand suggestions, continuous suggestions as the user types, inline
suggestions, autofill-like suggestions in a popup, or could use other interfaces.</p>
<h4>Autocapitalization</h4>
<p>Some methods of entering text, for example virtual keyboards on mobile devices, and also voice
input, often assist users by automatically capitalizing the first letter of sentences (when
composing text in a language with this convention). A virtual keyboard that implements
autocapitalization might automatically switch to showing uppercase letters (but allow the user to
toggle it back to lowercase) when a letter that should be autocapitalized is about to be typed.
Other types of input, for example voice input, may perform autocapitalization in a way that does
not give users an option to intervene first. The <code
data-x="attr-autocapitalize">autocapitalize</code> attribute allows authors to control such
behavior.</p>
<p>The <code data-x="attr-autocapitalize">autocapitalize</code> attribute, as typically
implemented, does not affect behavior when typing on a physical keyboard. (For this reason, as
well as the ability for users to override the autocapitalization behavior in some cases or edit
the text after initial input, the attribute must not be relied on for any sort of input
validation.)</p>
<p>The <code data-x="attr-autocapitalize">autocapitalize</code> attribute can be used on an <span
data-x="editing host">editing host</span> to control autocapitalization behavior for the hosted
editable region, on an <code>input</code> or <code>textarea</code> element to control the behavior
for inputting text into that element, or on a <code>form</code> element to control the default
behavior for all <span
data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting
elements</span> associated with the <code>form</code> element.
<p>The <code data-x="attr-autocapitalize">autocapitalize</code> attribute never causes
autocapitalization to be enabled for <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in one of the <span
data-x="attr-input-type-url">URL</span>, <span
data-x="attr-input-type-email">Email</span>, or <span
data-x="attr-input-type-password">Password</span> states.<span w-nodev> (This behavior is included
in the <span data-x="used autocapitalization hint">used autocapitalization hint</span> algorithm
below.)</span></p>
<p>The autocapitalization processing model is based on selecting among five
<dfn data-x="autocapitalization hint">autocapitalization hints</dfn>, defined as follows:</p>
<dl>
<dt><dfn data-x="autocap-hint-default">default</dfn></dt>
<dd><p>The user agent and input method should make their own determination of whether or not to
enable autocapitalization.</p></dd>
<dt><dfn data-x="autocap-hint-none">none</dfn></dt>
<dd><p>No autocapitalization should be applied (all letters should default to
lowercase).</p></dd>
<dt><dfn data-x="autocap-hint-sentences">sentences</dfn></dt>
<dd><p>The first letter of each sentence should default to a capital letter; all other letters
should default to lowercase.</p></dd>
<dt><dfn data-x="autocap-hint-words">words</dfn></dt>
<dd><p>The first letter of each word should default to a capital letter; all other letters should
default to lowercase.</p></dd>
<dt><dfn data-x="autocap-hint-characters">characters</dfn></dt>
<dd><p>All letters should default to uppercase.</p></dd>
</dl>
<p>The <dfn element-attr for="html-global"><code
data-x="attr-autocapitalize">autocapitalize</code></dfn> attribute is an <span>enumerated
attribute</span> whose states are the possible <span data-x="autocapitalization
hint">autocapitalization hints</span>. The <span>autocapitalization hint</span> specified by the
attribute's state combines with other considerations to form the <span>used autocapitalization
hint</span>, which informs the behavior of the user agent. The keywords for this attribute and
their state mappings are as follows:</p>
<table>
<thead>
<tr>
<th> Keyword
<th> State
<tbody>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-off">off</code></dfn>
<td rowspan="2"><span data-x="autocap-hint-none">none</span>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-none">none</code></dfn>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-on">on</code></dfn>
<td rowspan="2"><span data-x="autocap-hint-sentences">sentences</span>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-sentences">sentences</code></dfn>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-words">words</code></dfn>
<td><span data-x="autocap-hint-words">words</span>
<tr>
<td><dfn attr-value for="html-global/autocapitalize"><code
data-x="attr-autocapitalize-characters">characters</code></dfn>
<td><span data-x="autocap-hint-characters">characters</span>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <span
data-x="autocap-hint-default">default</span> state, and its <i data-x="invalid value
default">invalid value default</i> is the <span data-x="autocap-hint-sentences">sentences</span>
state.
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-autocapitalize">autocapitalize</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current autocapitalization state for the element, or an empty string if it hasn't
been set. Note that for <code>input</code> and <code>textarea</code> elements that inherit their
state from a <code>form</code> element, this will return the autocapitalization state of the
<code>form</code> element, but for an element in an editable region, this will not return the
autocapitalization state of the editing host (unless this element is, in fact, the <span>editing
host</span>).</p>
<p>Can be set, to set the <code data-x="attr-autocapitalize">autocapitalize</code> content
attribute (and thereby change the autocapitalization behavior for the element).</p>
</dd>
</dl>
<div w-nodev>
<p>To compute the <dfn>own autocapitalization hint</dfn> of an element <var>element</var>, run the
following steps:</p>
<ol>
<li><p>If the <code data-x="attr-autocapitalize">autocapitalize</code> content attribute is
present on <var>element</var>, and its value is not the empty string, return the state of the
attribute.</p></li>
<li><p>If <var>element</var> is an <span
data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting
element</span> and has a non-null <span>form owner</span>, return the <span>own
autocapitalization hint</span> of <var>element</var>'s <span>form owner</span>.</p></li>
<li><p>Return <span data-x="autocap-hint-default">default</span>.</p></li>
</ol>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-autocapitalize">autocapitalize</code></dfn> getter steps are to:</p>
<ol>
<li><p>Let <var>state</var> be the <span>own autocapitalization hint</span> of
<span>this</span>.</p></li>
<li><p>If <var>state</var> is <span data-x="autocap-hint-default">default</span>, then return the
empty string.</p></li>
<li><p>If <var>state</var> is <span data-x="autocap-hint-none">none</span>, then return "<code
data-x="attr-autocapitalize-none">none</code>".</p></li>
<li><p>If <var>state</var> is <span data-x="autocap-hint-sentences">sentences</span>, then return
"<code data-x="attr-autocapitalize-sentences">sentences</code>".</p></li>
<li><p>Return the keyword value corresponding to <var>state</var>.</p></li>
</ol>
<p>The <code data-x="dom-autocapitalize">autocapitalize</code> setter steps are to set the <code
data-x="attr-autocapitalize">autocapitalize</code> content attribute to the given value.</p>
<hr>
<p>User agents that support customizable autocapitalization behavior for a text input method and
wish to allow web developers to control this functionality should, during text input into an
element, compute the <dfn>used autocapitalization hint</dfn> for the element. This will be an
<span>autocapitalization hint</span> that describes the recommended autocapitalization behavior
for text input into the element.</p>
<p>User agents or input methods may choose to ignore or override the <span>used autocapitalization
hint</span> in certain circumstances.</p>
<p>The <span>used autocapitalization hint</span> for an element <var>element</var> is computed
using the following algorithm:</p>
<ol>
<li><p>If <var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in one of the <span
data-x="attr-input-type-url">URL</span>, <span data-x="attr-input-type-email">Email</span>, or
<span data-x="attr-input-type-password">Password</span> states, then return <span
data-x="autocap-hint-default">default</span>.</p></li>
<li><p>If <var>element</var> is an <code>input</code> element or a <code>textarea</code> element,
then return <var>element</var>'s <span>own autocapitalization hint</span>.</p></li>
<li><p>If <var>element</var> is an <span>editing host</span> or an <span>editable</span> element,
then return the <span>own autocapitalization hint</span> of the <span>editing host of</span>
<var>element</var>.</p></li>
<li><p><span>Assert</span>: this step is never reached, since text input only occurs in elements
that meet one of the above criteria.</p></li>
</ol>
</div>
<h4>Autocorrection</h4>
<p>Some methods of entering text assist users by automatically correcting misspelled words while
typing, a process also known as autocorrection. User agents can support autocorrection of editable
text, either in form controls (such as the value of <code>textarea</code> elements), or in
elements in an <span>editing host</span> (e.g., using <code
data-x="attr-contenteditable">contenteditable</code>). Autocorrection may be accompanied by user
interfaces indicating that text is about to be autocorrected or has been autocorrected, and is
commonly performed when inserting punctuation characters, spaces, or new paragraphs after
misspelled words. The <code data-x="attr-autocorrect">autocorrect</code> attribute allows authors
to control such behavior.</p>
<p>The <code data-x="attr-autocorrect">autocorrect</code> attribute can be used on an editing host
to control autocorrection behavior for the hosted editable region, on an <code>input</code> or
<code>textarea</code> element to control the behavior when inserting text into that element, or on
a <code>form</code> element to control the default behavior for all <span
data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting
elements</span> associated with the <code>form</code> element.</p>
<p>The <code data-x="attr-autocorrect">autocorrect</code> attribute never causes autocorrection to
be enabled for <code>input</code> elements whose <code data-x="attr-input-type">type</code>
attribute is in one of the <span data-x="attr-input-type-url">URL</span>, <span
data-x="attr-input-type-email">E-mail</span>, or <span
data-x="attr-input-type-password">Password</span> states.<span w-nodev> (This behavior is included
in the <span>used autocorrection state</span> algorithm below.)</span></p>
<p>The <dfn element-attr for="html-global"><code
data-x="attr-autocorrect">autocorrect</code></dfn> attribute is an enumerated attribute with the
following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/autocorrect"><code
data-x="attr-autocorrect-on">on</code></dfn>
<td rowspan="2"><dfn data-x="concept-autocorrection-on">on</dfn>
<td rowspan="2">The user agent is permitted to automatically correct spelling errors while the user types.
Whether spelling is automatically corrected while typing left is for the user agent to decide,
and may depend on the element as well as the user's preferences.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/autocorrect"><code data-x="attr-autocorrect-off">off</code></dfn>
<td><dfn data-x="concept-autocorrection-off">off</dfn>
<td>The user agent is not allowed to automatically correct spelling while the user types.
</table>
<p>The attribute's <i data-x="invalid value default">invalid value default</i> and <i
data-x="missing value default">missing value default</i> are both the <span
data-x="concept-autocorrection-on">on</span> state.</p>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-autocorrect">autocorrect</code></dfn>
getter steps are: return true if the element's <span>used autocorrection state</span> is <span
data-x="concept-autocorrection-on">on</span> and false if the element's <span>used autocorrection
state</span> is <span data-x="concept-autocorrection-off">off</span>. The setter steps are: if the
given value is true, then the element's <code data-x="attr-autocorrect">autocorrect</code>
attribute must be set to "<code data-x="">on</code>"; otherwise it must be set to "<code
data-x="">off</code>".</p>
<p>To compute the <dfn>used autocorrection state</dfn> of an element <var>element</var>, run these
steps:</p>
<ol>
<li><p>If <var>element</var> is an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in one of the <span
data-x="attr-input-type-url">URL</span>, <span data-x="attr-input-type-email">E-mail</span>, or
<span data-x="attr-input-type-password">Password</span> states, then return <span
data-x="concept-autocorrection-off">off</span>.</p></li>
<li><p>If the <code data-x="attr-autocorrect">autocorrect</code> content attribute is present on
<var>element</var>, then return the state of the attribute.</p></li>
<li><p>If <var>element</var> is an <span
data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting
element</span> and has a non-null <span>form owner</span>, then return the state of
<var>element</var>'s <span>form owner</span>'s <code data-x="attr-autocorrect">autocorrect</code>
attribute.</p></li>
<li><p>Return <span data-x="concept-autocorrection-on">on</span>.</p></li>
</ol>
<dl class="domintro">
<dt><var>element</var> . <code subdfn data-x="dom-autocorrect">autocorrect</code></dt>
<dd><p>Returns the autocorrection behavior of the element. Note that for <span
data-x="category-autocapitalize-and-autocorrect">autocapitalize-and-autocorrect inheriting
elements</span> that inherit their state from a <code>form</code> element, this will return the
autocorrection behavior of the <code>form</code> element, but for an element in an editable
region, this will not return the autocorrection behavior of the <span>editing host</span> (unless
this element is, in fact, the <span>editing host</span>).</p></dd>
<dt><var>element</var> . <code data-x="dom-autocorrect">autocorrect</code> =
<var>value</var></dt>
<dd><p>Updates the <code data-x="attr-autocorrect">autocorrect</code> content attribute (and
thereby changes the autocorrection behavior of the element).</p></dd>
</dl>
<div class="example">
<p>The <code>input</code> element in the following example would not allow autocorrection, since
it does not have an <code data-x="attr-autocorrect">autocorrect</code> content attribute and
therefore inherits from the <code>form</code> element, which has an attribute of "<code
data-x="attr-autocorrect-off">off</code>". However, the <code>textarea</code> element would allow
autocorrection, since it has an <code data-x="attr-autocorrect">autocorrect</code> content
attribute with a value of "<code data-x="attr-autocorrect-on">on</code>".</p>
<pre><code class="html" data-x=""><form autocorrect="off">
<input type="search">
<textarea autocorrect="on"></textarea>
</form></code></pre>
</div>
<h4>Input modalities: the <code data-x="attr-inputmode">inputmode</code> attribute</h4>
<p>User agents can support the <code data-x="attr-inputmode">inputmode</code> attribute on form
controls (such as the value of <code>textarea</code> elements), or in elements in an <span>editing
host</span> (e.g., using <code data-x="attr-contenteditable">contenteditable</code>).</p>
<p>The <dfn element-attr for="html-global"><code data-x="attr-inputmode">inputmode</code></dfn>
content attribute is an <span>enumerated attribute</span> that specifies what kind of input
mechanism would be most helpful for users entering content.</p>
<table>
<thead>
<tr>
<th> Keyword
<th> Description
<tbody>
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-none">none</code></dfn>
<td>The user agent should not display a virtual keyboard. This keyword is useful for content
that renders its own keyboard control.
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-text">text</code></dfn>
<td>The user agent should display a virtual keyboard capable of text input in the user's locale.
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-tel">tel</code></dfn>
<td> The user agent should display a virtual keyboard capable of telephone number input. This
should including keys for the digits 0 to 9, the "#" character, and the "*" character. In some
locales, this can also include alphabetic mnemonic labels (e.g., in the US, the key labeled
"2" is historically also labeled with the letters A, B, and C).
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-url">url</code></dfn>
<td>The user agent should display a virtual keyboard capable of text input in the user's locale,
with keys for aiding in the input of <span data-x="URL">URLs</span>, such as that for the "/"
and "." characters and for quick input of strings commonly found in domain names such as
"www." or ".com".
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-email">email</code></dfn>
<td>The user agent should display a virtual keyboard capable of text input in the user's locale,
with keys for aiding in the input of email addresses, such as that for the "@" character
and the "." character.
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-numeric">numeric</code></dfn>
<td> The user agent should display a virtual keyboard capable of numeric input. This keyword
is useful for PIN entry.
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-decimal">decimal</code></dfn>
<td> The user agent should display a virtual keyboard capable of fractional numeric input.
Numeric keys and the format separator for the locale should be shown.
<tr>
<td><dfn attr-value for="html-global/inputmode"><code
data-x="attr-inputmode-keyword-search">search</code></dfn>
<td>The user agent should display a virtual keyboard optimized for search.
</table>
<div w-nodev>
<p>The <dfn attribute for="ElementContentEditable"><code
data-x="dom-inputMode">inputMode</code></dfn> IDL attribute must <span>reflect</span> the <code
data-x="attr-inputmode">inputmode</code> content attribute, <span>limited to only known
values</span>.</p>
<p>When <code data-x="attr-inputmode">inputmode</code> is unspecified (or is in a state not
supported by the user agent), the user agent should determine the default virtual keyboard to be
shown. Contextual information such as the input <code data-x="attr-input-type">type</code> or
<code data-x="attr-input-pattern">pattern</code> attributes should be used to determine which type
of virtual keyboard should be presented to the user.</p>
</div>
<h4>Input modalities: the <code data-x="attr-enterkeyhint">enterkeyhint</code>
attribute</h4>
<p>User agents can support the <code data-x="attr-enterkeyhint">enterkeyhint</code>
attribute on form controls (such as the value of <code>textarea</code> elements), or in elements
in an <span>editing host</span> (e.g., using <code
data-x="attr-contenteditable">contenteditable</code>).</p>
<p>The <dfn element-attr for="html-global"><code
data-x="attr-enterkeyhint">enterkeyhint</code></dfn> content attribute is an <span>enumerated
attribute</span> that specifies what action label (or icon) to present for the enter key on
virtual keyboards. This allows authors to customize the presentation of the enter key in order to
make it more helpful for users.</p>
<table>
<thead>
<tr>
<th> Keyword
<th> Description
<tbody>
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-enter">enter</code></dfn>
<td>The user agent should present a cue for the operation 'enter', typically
inserting a new line.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-done">done</code></dfn>
<td>The user agent should present a cue for the operation 'done', typically
meaning there is nothing more to input and the input method editor (IME)
will be closed.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-go">go</code></dfn>
<td> The user agent should present a cue for the operation 'go', typically
meaning to take the user to the target of the text they typed.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-next">next</code></dfn>
<td>The user agent should present a cue for the operation 'next', typically
taking the user to the next field that will accept text.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-previous">previous</code></dfn>
<td>The user agent should present a cue for the operation 'previous', typically
taking the user to the previous field that will accept text.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-search">search</code></dfn>
<td>The user agent should present a cue for the operation 'search', typically
taking the user to the results of searching for the text they have typed.
<tr>
<td><dfn attr-value for="html-global/enterkeyhint"><code
data-x="attr-enterkeyhint-keyword-send">send</code></dfn>
<td> The user agent should present a cue for the operation 'send', typically
delivering the text to its target.
</table>
<div w-nodev>
<p>The <dfn attribute for="ElementContentEditable"><code
data-x="dom-enterKeyHint">enterKeyHint</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-enterkeyhint">enterkeyhint</code> content attribute, <span>limited to only
known values</span>.</p>
<p>When <code data-x="attr-enterkeyhint">enterkeyhint</code> is unspecified (or is in a state not
supported by the user agent), the user agent should determine the default action label (or icon)
to present. Contextual information such as the <code data-x="attr-inputmode">inputmode</code>,
<code data-x="attr-input-type">type</code>, or <code data-x="attr-input-pattern">pattern</code>
attributes should be used to determine which action label (or icon) to present on the virtual
keyboard.</p>
</div>
<h3>Find-in-page</h3>
<h4>Introduction</h4>
<p>This section defines <dfn>find-in-page</dfn> — a common user-agent mechanism which allows users
to search through the contents of the page for particular information.</p>
<p>Access to the <span>find-in-page</span> feature is provided via a <dfn>find-in-page
interface</dfn>. This is a user-agent provided user interface, which allows the user to specify
input and the parameters of the search. This interface can appear as a result of a shortcut or a
menu selection.</p>
<p>A combination of text input and settings in the <span>find-in-page interface</span> represents
the user <dfn data-x="fip-query">query</dfn>. This typically includes the text that the user wants
to search for, as well as optional settings (e.g., the ability to restrict the search to whole
words only).</p>
<p>The user-agent processes page contents for a given <span data-x="fip-query">query</span>, and
identifies zero or more <dfn data-x="fip-matches">matches</dfn>, which are content ranges that
satisfy the user <span data-x="fip-query">query</span>.</p>
<p>One of the <span data-x="fip-matches">matches</span> is identified to the user as the <dfn
data-x="fip-active-match">active match</dfn>. It is highlighted and scrolled into view. The user
can navigate through the <span data-x="fip-matches">matches</span> by advancing the <span
data-x="fip-active-match">active match</span> using the <span>find-in-page interface</span>.</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/3539">Issue #3539</a> tracks
standardizing how <span>find-in-page</span> underlies the currently-unspecified <code
data-x="">window.find()</code> API.</p>
<h4>Interaction with <code>details</code> and <code
data-x="attr-hidden-until-found-state">hidden=until-found</code></h4>
<p>When find-in-page begins searching for matches, all <code>details</code> elements in the page
which do not have their <code data-x="attr-details-open">open</code> attribute set should have the
<span data-x="skips its contents">skipped contents</span> of their second slot become accessible,
without modifying the <code data-x="attr-details-open">open</code> attribute, in order to make
find-in-page able to search through it. Similarly, all HTML elements with the <code
data-x="attr-hidden">hidden</code> attribute in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state should have their <span
data-x="skips its contents">skipped contents</span> become accessible without modifying the <code
data-x="attr-hidden">hidden</code> attribute in order to make find-in-page able to search through
them. After find-in-page finishes searching for matches, the <code>details</code> elements and the
elements with the <code data-x="attr-hidden">hidden</code> attribute in the <span
data-x="attr-hidden-until-found-state">hidden until found</span> state should have their contents
become skipped again. This entire process must happen synchronously (and so is not observable to
users or to author code). <ref>CSSCONTAIN</ref></p>
<p>When find-in-page chooses a new <span data-x="fip-active-match">active match</span>, perform
the following steps:</p>
<ol>
<li><p>Let <var>node</var> be the first node in the <span data-x="fip-active-match">active
match</span>.</p></li>
<li><p><span>Queue a global task</span> on the <span>user interaction task source</span> given
<var>node</var>'s <span>relevant global object</span> to run the following steps:</p>
<ol>
<li><p>Run the <span>ancestor details revealing algorithm</span> on <var>node</var>.</p></li>
<li><p>Run the <span>ancestor hidden-until-found revealing algorithm</span> on
<var>node</var>.</p></li>
</ol>
</li>
</ol>
<p class="warning">
<!--INSERT TRACKING-->
When find-in-page auto-expands a <code>details</code> element like this, it will fire a <code
data-x="event-toggle">toggle</code> event. As with the separate <code
data-x="event-scroll">scroll</code> event that find-in-page fires, this event could be used by the
page to discover what the user is typing into the find-in-page dialog. If the page creates a tiny
scrollable area with the current search term and every possible next character the user could type
separated by a gap, and observes which one the browser scrolls to, it can add that character to
the search term and update the scrollable area to incrementally build the search term. By wrapping
each possible next match in a closed <code>details</code> element, the page could listen to <code
data-x="event-toggle">toggle</code> events instead of <code data-x="event-scroll">scroll</code>
events. This attack could be addressed for both events by not acting on every character the user
types into the find-in-page dialog.</p>
<h4>Interaction with selection</h4>
<p>The find-in-page process is invoked in the context of a document, and may have an effect on
the <span data-x="document-selection">selection</span> of that document. Specifically, the range
that defines the <span data-x="fip-active-match">active match</span> can dictate the current
selection. These selection updates, however, can happen at different times during the
find-in-page process (e.g. upon the <span>find-in-page interface</span> dismissal or upon a change
in the <span data-x="fip-active-match">active match</span> range).
<!-- TODO: Define scroll and highlight timing, as well as algorithms (what is and isn't found) -->
<h3>Close requests and close watchers</h3>
<h4>Close requests</h4>
<p>In an <span>implementation-defined</span> (and likely device-specific) manner, a user can send
a <dfn export>close request</dfn> to the user agent. This indicates that the user wishes to close
something that is currently being shown on the screen, such as a popover, menu, dialog, picker, or
display mode.</p>
<div class="example">
<p>Some example close requests are:</p>
<ul>
<li><p>The <kbd>Esc</kbd> key on desktop platforms.</p></li>
<li><p>The back button or gesture on certain mobile platforms such as Android.</p></li>
<li><p>Any assistive technology's dismiss gesture, such as iOS VoiceOver's two-finger scrub "z"
gesture.</p></li>
<li><p>A game controller's canonical "back" button, such as the circle button on a DualShock
gamepad.</p></li>
</ul>
</div>
<div w-nodev>
<p>Whenever the user agent receives a potential close request targeted at a <code>Document</code>
<var>document</var>, it must <span>queue a global task</span> on the <span>user interaction task
source</span> given <var>document</var>'s <span>relevant global object</span> to perform the
following <dfn export>close request steps</dfn>:</p>
<ol>
<li>
<p>If <var>document</var>'s <span>fullscreen element</span> is not null, then:</p>
<ol>
<li><p><span>Fully exit fullscreen</span> given <var>document</var>'s <span>node
navigable</span>'s <span data-x="nav-top">top-level traversable</span>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p>Return.</p>
</ol>
<p class="note">This does <em>not</em> fire any relevant event, such as <code
data-x="event-keydown">keydown</code>; it only causes <code
data-x="event-fullscreenchange">fullscreenchange</code> to be eventually fired.</p>
</li>
<li>
<p>Optionally, skip to the step labeled <a href="#close-request-fallback">alternative
processing</a>.</p>
<p class="note">For example, if the user agent detects user frustration at repeated close
request interception by the current web page, it might take this path.</p>
</li>
<li>
<p>Fire any relevant events, per <cite>UI Events</cite> or other relevant specifications.
<ref>UIEVENTS</ref></p>
<p class="example">An example of a relevant event in the <cite>UI Events</cite> model would be
the <code data-x="event-keydown">keydown</code> event that <cite>UI Events</cite> <a
href="https://w3c.github.io/uievents/#events-keyboard-event-order">suggests</a> firing when the
user presses the <kbd>Esc</kbd> key on their keyboard. On most platforms with keyboards, this
is treated as a <span>close request</span>, and so would trigger these <span>close request
steps</span>.</p>
<p class="example">An example of relevant events that are outside of the model given in
<cite>UI Events</cite> would be assistive technology synthesizing an <kbd>Esc</kbd> <code
data-x="event-keydown">keydown</code> event when the user sends a <span>close request</span> by
using a dismiss gesture.</p>
</li>
<li><p>Let <var>event</var> be null if no such events are fired, or the <code>Event</code>
object representing one of the fired events otherwise. If multiple events are fired, which one
is chosen is <span>implementation-defined</span>.</p></li>
<li><p>If <var>event</var> is not null, and its <span>canceled flag</span> is set, then
return.</p></li>
<li>
<p>If <var>document</var> is not <span>fully active</span>, then return.</p>
<p class="note">This step is necessary because, if <var>event</var> is not null, then an event
listener might have caused <var>document</var> to no longer be <span>fully active</span>.</p>
</li>
<li><p>Let <var>closedSomething</var> be the result of <span data-x="process close
watchers">processing close watchers</span> on <var>document</var>'s <span>relevant global
object</span>.</p></li>
<li><p>If <var>closedSomething</var> is true, then return.</p></li>
<li id="close-request-fallback"><p><i>Alternative processing</i>: Otherwise, there was nothing
watching for a <span>close request</span>. The user agent may instead interpret this interaction
as some other action, instead of interpreting it as a close request.</p></li>
</ol>
</div>
<p>On platforms where pressing the <kbd>Esc</kbd> key is interpreted as a <span>close
request</span>, the user agent must interpret the key being pressed <em>down</em> as the close
request, instead of the key being released. Thus, in the above algorithm, the "relevant events"
that are fired must be the single <code data-x="event-keydown">keydown</code> event.</p>
<p class="example">On platforms where <kbd>Esc</kbd> is the <span>close request</span>, the user
agent will first fire an appropriately-initialized <code data-x="event-keydown">keydown</code>
event. If the web developer cancels the event by calling <code
data-x="dom-Event-preventDefault">preventDefault()</code>, then nothing further happens. But if
the event fires without being canceled, then the user agent proceeds to <span>process close
watchers</span>.</p>
<p class="example">On platforms where a back button is a potential <span>close request</span>, no
event is involved, so when the back button is pressed, the user agent proceeds directly to
<span>process close watchers</span>. If there is an <span
data-x="close-watcher-active">active</span> <span>close watcher</span>, then that will get
triggered. If there is not, then the user agent can interpret the back button press in another
way, for example as a request to <span>traverse the history by a delta</span> of −1.</p>
<div w-nodev>
<h4>Close watcher infrastructure</h4>
<p>Each <code>Window</code> has a <dfn>close watcher manager</dfn>, which is a
<span>struct</span> with the following <span data-x="struct item">items</span>:</p>
<ul>
<li><p><dfn data-x="close watcher manager groups">Groups</dfn>, a <span>list</span> of <span
data-x="list">lists</span> of <span data-x="close watcher">close watchers</span>, initially
empty.</p></li>
<li><p><dfn data-x="close watcher manager allowed number of groups">Allowed number of
groups</dfn>, a number, initially 1.</p></li>
<li><p><dfn data-x="close watcher manager next">Next user interaction allows a new group</dfn>,
a boolean, initially true.</p></li>
</ul>
<p>Most of the complexity of the <span>close watcher manager</span> comes from anti-abuse
protections designed to prevent developers from disabling users' history traversal abilities, for
platforms where a <span>close request</span>'s <a href="#close-request-fallback">fallback
action</a> is the main mechanism of history traversal. In particular:</p>
<p>The grouping of <span data-x="close watcher">close watchers</span> is designed so that if
multiple close watchers are created without <span>history-action activation</span>, they are
grouped together, so that a user-triggered <span>close request</span> will close all of the close
watchers in a group. This ensures that web developers can't intercept an unlimited number of
close requests by creating close watchers; instead they can create a number equal to at most 1 +
the number of times the <span data-x="user activation">user activates the page</span>.</p>
<p>The <span data-x="close watcher manager next">next user interaction allows a new group</span>
boolean encourages web developers to create <span data-x="close watcher">close watchers</span> in
a way that is tied to individual <span data-x="user activation">user activations</span>. Without
it, each user activation would increase the <span data-x="close watcher manager allowed number of
groups">allowed number of groups</span>, even if the web developer isn't "using" those user
activations to create close watchers. In short:</p>
<ul>
<li><p>Allowed: user interaction; create a close watcher in its own group; user interaction;
create a close watcher in a second independent group.</p></li>
<li><p>Disallowed: user interaction; user interaction; create a close watcher in its own group;
create a close watcher in a second independent group.</p></li>
<li><p>Allowed: user interaction; user interaction; create a close watcher in its own group;
create a close watcher grouped with the previous one.</p></li>
</ul>
<p>This protection is <em>not</em> important for upholding our desired invariant of creating at
most (1 + the number of times the <span data-x="user activation">user activates the page</span>)
groups. A determined abuser will just create one close watcher per user interaction, "banking"
them for future abuse. But this system causes more predictable behavior for the normal case, and
encourages non-abusive developers to create close watchers directly in response to user
interactions.</p>
<p>To <dfn>notify the close watcher manager about user activation</dfn> given a
<code>Window</code> <var>window</var>:</p>
<ol>
<li><p>Let <var>manager</var> be <var>window</var>'s <span>close watcher manager</span>.</p></li>
<li><p>If <var>manager</var>'s <span data-x="close watcher manager next">next user interaction
allows a new group</span> is true, then increment <var>manager</var>'s <span data-x="close
watcher manager allowed number of groups">allowed number of groups</span>.</p></li>
<li><p>Set <var>manager</var>'s <span data-x="close watcher manager next">next user interaction
allows a new group</span> to false.</p></li>
</ol>
<hr>
<p>A <dfn export>close watcher</dfn> is a <span>struct</span> with the following <span
data-x="struct item">items</span>:</p>
<ul>
<li><p>A <dfn data-x="close-watcher-window">window</dfn>, a <code>Window</code>.</p></li>
<li><p>A <dfn data-x="close-watcher-cancel-action">cancel action</dfn>, an algorithm accepting a
boolean argument and returning a boolean. The argument indicates whether or not the cancel
action algorithm can prevent the close request from proceeding via the algorithm's return value.
If the boolean argument is true, then the algorithm can return either true to indicate that the
caller will proceed to the <span data-x="close-watcher-close-action">close action</span>, or
false to indicate that the caller will bail out. If the argument is false, then the return value
is always false. This algorithm can never throw an exception.</p></li>
<li><p>A <dfn data-x="close-watcher-close-action">close action</dfn>, an algorithm accepting no
arguments and returning nothing. This algorithm can never throw an exception.</p></li>
<li><p>An <dfn data-x="close-watcher-is-running-cancel">is running cancel action</dfn>
boolean.</p></li>
<li><p>A <dfn data-x="close-watcher-get-enabled-state">get enabled state</dfn>, an algorithm
accepting no arguments and returning a boolean. This algorithm can never throw an
exception.</p></li>
</ul>
<p>A <span>close watcher</span> <var>closeWatcher</var> <dfn data-x="close-watcher-active">is
active</dfn> if <var>closeWatcher</var>'s <span data-x="close-watcher-window">window</span>'s
<span>close watcher manager</span> <span data-x="list contains">contains</span> any list which
<span data-x="list contains">contains</span> <var>closeWatcher</var>.</p>
<hr>
<p>To <dfn>establish a close watcher</dfn> given a <code>Window</code> <var>window</var>, a list
of steps <dfn data-x="create-close-watcher-cancelAction"><var>cancelAction</var></dfn>, a
list of steps <dfn data-x="create-close-watcher-closeAction"><var>closeAction</var></dfn>,
and an algorithm that returns a boolean <dfn
data-x="create-close-watcher-getEnabledState"><var>getEnabledState</var></dfn>:</p>
<ol>
<li><p><span>Assert</span>: <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is <span>fully
active</span>.</p></li>
<li>
<p>Let <var>closeWatcher</var> be a new <span>close watcher</span>, with</p>
<dl class="props">
<dt><span data-x="close-watcher-window">window</span></dt>
<dd><var>window</var></dd>
<dt><span data-x="close-watcher-cancel-action">cancel action</span></dt>
<dd><var>cancelAction</var></dd>
<dt><span data-x="close-watcher-close-action">close action</span></dt>
<dd><var>closeAction</var></dd>
<dt><span data-x="close-watcher-is-running-cancel">is running cancel action</span></dt>
<dd>false</dd>
<dt><span data-x="close-watcher-get-enabled-state">get enabled state</span></dt>
<dd><var>getEnabledState</var></dd>
</dl>
</li>
<li><p>Let <var>manager</var> be <var>window</var>'s <span>close watcher manager</span>.</p></li>
<li><p>If <var>manager</var>'s <span data-x="close watcher manager groups">groups</span>'s <span
data-x="list size">size</span> is less than <var>manager</var>'s <span data-x="close watcher
manager allowed number of groups">allowed number of groups</span>, then <span data-x="list
append">append</span> « <var>closeWatcher</var> » to <var>manager</var>'s <span data-x="close
watcher manager groups">groups</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>manager</var>'s <span data-x="close watcher manager
groups">groups</span>'s <span data-x="list size">size</span> is at least 1 in this branch,
since <var>manager</var>'s <span data-x="close watcher manager allowed number of
groups">allowed number of groups</span> is always at least 1.</p></li>
<li><p><span data-x="list append">Append</span> <var>closeWatcher</var> to
<var>manager</var>'s <span data-x="close watcher manager groups">groups</span>'s last <span
data-x="list item">item</span>.</p></li>
</ol>
</li>
<li><p>Set <var>manager</var>'s <span data-x="close watcher manager next">next user interaction
allows a new group</span> to true.</p></li>
<li><p>Return <var>closeWatcher</var>.</p></li>
</ol>
<p>To <dfn data-x="close-watcher-request-close">request to close</dfn> a <span>close
watcher</span> <var>closeWatcher</var> with boolean <var>requireHistoryActionActivation</var>:</p>
<ol>
<li><p>If <var>closeWatcher</var> <span data-x="close-watcher-active">is not active</span>, then
return true.</p></li>
<li><p>If the result of running <var>closeWatcher</var>'s <span
data-x="close-watcher-get-enabled-state">get enabled state</span> is false, then return
true.</p></li>
<li><p>If <var>closeWatcher</var>'s <span data-x="close-watcher-is-running-cancel">is running
cancel action</span> is true, then return true.</p></li>
<li><p>Let <var>window</var> be <var>closeWatcher</var>'s <span
data-x="close-watcher-window">window</span>.</p></li>
<li><p>If <var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span> is not <span>fully active</span>, then return true.</p></li>
<!-- Help me here - I never know how to add logical parenthesis, but in spec English. This should be:
canPreventClose = ((A || B) && C) -->
<li><p>Let <var>canPreventClose</var> be true if <var>requireHistoryActionActivation</var> is
false, or if <var>window</var>'s <span>close watcher manager</span>'s <span
data-x="close watcher manager groups">groups</span>'s <span data-x="list size">size</span> is
less than <var>window</var>'s <span>close watcher manager</span>'s <span
data-x="close watcher manager allowed number of groups">allowed number of groups</span>, and
<var>window</var> has <span>history-action activation</span>; otherwise false.</p></li>
<li><p>Set <var>closeWatcher</var>'s <span data-x="close-watcher-is-running-cancel">is running
cancel action</span> to true.</p></li>
<li><p>Let <var>shouldContinue</var> be the result of running <var>closeWatcher</var>'s <span
data-x="close-watcher-cancel-action">cancel action</span> given
<var>canPreventClose</var>.</p></li>
<li><p>Set <var>closeWatcher</var>'s <span data-x="close-watcher-is-running-cancel">is running
cancel action</span> to false.</p></li>
<li>
<p>If <var>shouldContinue</var> is false, then:</p>
<ol>
<li><p><span>Assert</span>: <var>canPreventClose</var> is true.</p></li>
<li><p><span>Consume history-action user activation</span> given <var>window</var>.</p></li>
<li><p>Return false.</p></li>
</ol>
<p class="note">Note that since these substeps <span>consume history-action user
activation</span>, <span data-x="close-watcher-request-close">requesting to close</span> a
<span>close watcher</span> twice without any intervening <span>user activation</span> will
result in <var>canPreventClose</var> being false the second time.</p>
</li>
<li><p><span data-x="close-watcher-close">Close</span> <var>closeWatcher</var>.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>To <dfn data-x="close-watcher-close">close</dfn> a <span>close watcher</span>
<var>closeWatcher</var>:</p>
<ol>
<li><p>If <var>closeWatcher</var> <span data-x="close-watcher-active">is not active</span>, then
return.</p></li>
<li><p>If the result of running <var>closeWatcher</var>'s <span
data-x="close-watcher-get-enabled-state">get enabled state</span> is false, then return.</p></li>
<li><p>If <var>closeWatcher</var>'s <span data-x="close-watcher-window">window</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then return.</p></li>
<li><p><span data-x="close-watcher-destroy">Destroy</span> <var>closeWatcher</var>.</p></li>
<li><p>Run <var>closeWatcher</var>'s <span data-x="close-watcher-close-action">close
action</span>.</p></li>
</ol>
<p>To <dfn data-x="close-watcher-destroy">destroy</dfn> a <span>close watcher</span>
<var>closeWatcher</var>:</p>
<ol>
<li><p>Let <var>manager</var> be <var>closeWatcher</var>'s <span
data-x="close-watcher-window">window</span>'s <span>close watcher manager</span>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>group</var> of <var>manager</var>'s
<span data-x="close watcher manager groups">groups</span>: <span data-x="list
remove">remove</span> <var>closeWatcher</var> from <var>group</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> any item from <var>manager</var>'s <span
data-x="close watcher manager groups">groups</span> that <span data-x="list is empty">is
empty</span>.</p></li>
</ol>
<hr>
<p>To <dfn>process close watchers</dfn> given a <code>Window</code> <var>window</var>:</p>
<ol>
<li><p>Let <var>processedACloseWatcher</var> be false.</p></li>
<li>
<p>If <var>window</var>'s <span>close watcher manager</span>'s <span data-x="close watcher
manager groups">groups</span> is not empty:</p>
<ol>
<li><p>Let <var>group</var> be the last <span data-x="list item">item</span> in
<var>window</var>'s <span>close watcher manager</span>'s <span data-x="close watcher manager
groups">groups</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>closeWatcher</var> of <var>group</var>,
in reverse order:</p>
<ol>
<li><p>If the result of running <var>closeWatcher</var>'s <span
data-x="close-watcher-get-enabled-state">get enabled state</span> is true, set
<var>processedACloseWatcher</var> to true.</p></li>
<li><p>Let <var>shouldProceed</var> be the result of <span
data-x="close-watcher-request-close">requesting to close</span>
<var>closeWatcher</var> with true.</p></li>
<li><p>If <var>shouldProceed</var> is false, then <span>break</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If <var>window</var>'s <span>close watcher manager</span>'s <span data-x="close watcher
manager allowed number of groups">allowed number of groups</span> is greater than 1, decrement
it by 1.</p></li>
<li><p>Return <var>processedACloseWatcher</var>.</p></li>
</ol>
</div>
<h4>The <code>CloseWatcher</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>CloseWatcher</dfn> : <span>EventTarget</span> {
<span data-x="dom-CloseWatcher">constructor</span>(optional <span>CloseWatcherOptions</span> options = {});
undefined <span data-x="dom-CloseWatcher-requestClose">requestClose</span>();
undefined <span data-x="dom-CloseWatcher-close">close</span>();
undefined <span data-x="dom-CloseWatcher-destroy">destroy</span>();
attribute <span>EventHandler</span> <span data-x="handler-CloseWatcher-oncancel">oncancel</span>;
attribute <span>EventHandler</span> <span data-x="handler-CloseWatcher-onclose">onclose</span>;
};
dictionary <dfn dictionary>CloseWatcherOptions</dfn> {
<span>AbortSignal</span> <dfn dict-member for="CloseWatcherOptions" data-x="dom-CloseWatcherOptions-signal">signal</dfn>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>watcher</var> = new <span subdfn data-x="dom-CloseWatcher">CloseWatcher</span>()</code></dt>
<dt><code data-x=""><var>watcher</var> = new <span data-x="dom-CloseWatcher">CloseWatcher</span>({ <span subdfn data-x="dom-CloseWatcherOptions-signal">signal</span> })</code></dt>
<dd>
<p>Creates a new <code>CloseWatcher</code> instance.</p>
<p>If the <code data-x="dom-CloseWatcherOptions-signal">signal</code> option is provided, then
<var>watcher</var> can be destroyed (as if by <code
data-x="dom-CloseWatcher-destroy">watcher.destroy()</code>) by aborting the given
<code>AbortSignal</code>.</p>
<p>If any <span>close watcher</span> is already active, and the <code>Window</code> does not
have <span>history-action activation</span>, then the resulting <code>CloseWatcher</code> will
be closed together with that already-active <span>close watcher</span> in response to any
<span>close request</span>. (This already-active <span>close watcher</span> does not
necessarily have to be a <code>CloseWatcher</code> object; it could be a modal
<code>dialog</code> element, or a popover generated by an element with the <code
data-x="attr-popover">popover</code> attribute.)</p>
</dd>
<dt><code data-x=""><var>watcher</var>.<span subdfn data-x="dom-CloseWatcher-requestClose">requestClose</span>()</code></dt>
<dd>
<p>Acts as if a <span>close request</span> was sent targeting <var>watcher</var>, by first
firing a <code data-x="event-cancel">cancel</code> event, and if that event is not canceled
with <code data-x="dom-Event-preventDefault">preventDefault()</code>, proceeding to fire a
<code data-x="event-close">close</code> event before deactivating the close watcher as if <code
data-x="dom-CloseWatcher-destroy">watcher.destroy()</code> was called.</p>
<p>This is a helper utility that can be used to consolidate cancelation and closing logic into
the <code data-x="event-cancel">cancel</code> and <code data-x="event-close">close</code> event
handlers, by having all non-<span>close request</span> closing affordances call this method.</p>
</dd>
<dt><code data-x=""><var>watcher</var>.<span subdfn data-x="dom-CloseWatcher-close">close</span>()</code></dt>
<dd>
<p>Immediately fires the <code data-x="event-close">close</code> event, and then deactivates
the close watcher as if <code data-x="dom-CloseWatcher-destroy">watcher.destroy()</code> was
called.</p>
<p>This is a helper utility that can be used trigger the closing logic into the <code
data-x="event-close">close</code> event handler, skipping any logic in the <code
data-x="event-cancel">cancel</code> event handler.</p>
</dd>
<dt><code data-x=""><var>watcher</var>.<span subdfn data-x="dom-CloseWatcher-destroy">destroy</span>()</code></dt>
<dd>
<p>Deactivates <var>watcher</var>, so that it will no longer receive <code
data-x="event-close">close</code> events and so that new independent <code>CloseWatcher</code>
instances can be constructed.</p>
<p>This is intended to be called if the relevant UI element is torn down in some other way than
being closed.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <code>CloseWatcher</code> instance has an <dfn>internal close watcher</dfn>, which is a
<span>close watcher</span>.</p>
<p>The <dfn><code data-x="dom-CloseWatcher">new CloseWatcher(<var>options</var>)</code></dfn>
constructor steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li>
<p>Let <var>closeWatcher</var> be the result of <span data-x="establish a close
watcher">establishing a close watcher</span> given <span>this</span>'s <span>relevant global
object</span>, with:</p>
<ul>
<li><p><i data-x="create-close-watcher-cancelAction">cancelAction</i> given
<var>canPreventClose</var> being to return the result of <span
data-x="concept-event-fire">firing an event</span> named <code
data-x="event-cancel">cancel</code> at <span>this</span>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to
<var>canPreventClose</var>.</p></li>
<li><p><i data-x="create-close-watcher-closeAction">closeAction</i> being to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-close">close</code>
at <span>this</span>.</p></li>
<li><p><i data-x="close-watcher-get-enabled-state">getEnabledState</i> being to return
true.</li>
</ul>
</li>
<li>
<p>If <var>options</var>["<code data-x="dom-CloseWatcherOptions-signal">signal</code>"] <span
data-x="map exists">exists</span>, then:</p>
<ol>
<li><p>If <var>options</var>["<code data-x="dom-CloseWatcherOptions-signal">signal</code>"] is
<span data-x="AbortSignal-aborted">aborted</span>, then <span
data-x="close-watcher-destroy">destroy</span> <var>closeWatcher</var>.</p></li>
<li>
<p><span data-x="AbortSignal-add">Add</span> the following steps to <var>options</var>["<code
data-x="dom-CloseWatcherOptions-signal">signal</code>"]:</p>
<ol>
<li><p><span data-x="close-watcher-destroy">Destroy</span> <var>closeWatcher</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Set <span>this</span>'s <span>internal close watcher</span> to
<var>closeWatcher</var>.</p></li>
</ol>
<p>The <dfn method for="CloseWatcher"><code
data-x="dom-CloseWatcher-requestClose">requestClose()</code></dfn> method steps are to <span
data-x="close-watcher-request-close">request to close</span> <span>this</span>'s <span>internal
close watcher</span> with false.</p>
<p>The <dfn method for="CloseWatcher"><code data-x="dom-CloseWatcher-close">close()</code></dfn>
method steps are to <span data-x="close-watcher-close">close</span> <span>this</span>'s
<span>internal close watcher</span>.</p>
<p>The <dfn method for="CloseWatcher"><code
data-x="dom-CloseWatcher-destroy">destroy()</code></dfn> method steps are to <span
data-x="close-watcher-destroy">destroy</span> <span>this</span>'s <span>internal close
watcher</span>.</p>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>CloseWatcher</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="CloseWatcher"><code data-x="handler-CloseWatcher-oncancel">oncancel</code></dfn> <td> <code data-x="event-cancel">cancel</code>
<tr><td><dfn attribute for="CloseWatcher"><code data-x="handler-CloseWatcher-onclose">onclose</code></dfn> <td> <code data-x="event-close">close</code>
</table>
<div class="example" id="example-CloseWatcher-basic">
<p>If one wanted to implement a custom picker control, which closed itself on a user-provided
<span>close request</span> as well as when a close button is pressed, the following code shows how
one would use the <code>CloseWatcher</code> API to process close requests:</p>
<pre><code class="js">const watcher = new CloseWatcher();
const picker = setUpAndShowPickerDOMElement();
let chosenValue = null;
watcher.onclose = () => {
chosenValue = picker.querySelector('input').value;
picker.remove();
};
picker.querySelector('.close-button').onclick = () => watcher.requestClose();</code></pre>
<p>Note how the logic to gather the chosen value is centralized in the <code>CloseWatcher</code>
object's <code data-x="event-close">close</code> event handler, with the <code
data-x="event-click">click</code> event handler for the close button delegating to that logic by
calling <code data-x="dom-CloseWatcher-requestClose">requestClose()</code>.</p>
</div>
<div class="example" id="example-CloseWatcher-cancel">
<p>The <code data-x="event-cancel">cancel</code> event on <code>CloseWatcher</code> objects can
be used to prevent the <code data-x="event-close">close</code> event from firing, and the
<code>CloseWatcher</code> from being destroying. A typical use case is as follows:</p>
<pre><code class="js">watcher.oncancel = async (e) => {
if (hasUnsavedData && e.cancelable) {
e.preventDefault();
const userReallyWantsToClose = await askForConfirmation("Are you sure you want to close?");
if (userReallyWantsToClose) {
hasUnsavedData = false;
watcher.close();
}
}
};</code></pre>
<p>For abuse prevention purposes, this event is only <code
data-x="dom-Event-cancelable">cancelable</code> if the page has <span>history-action
activation</span>, which will be lost after any given <span>close request</span>. This ensures
that if the user sends a close request twice in a row without any intervening user activation,
the request definitely succeeds; the second request ignores any <code
data-x="event-cancel">cancel</code> event handler's attempt to call <code
data-x="dom-Event-preventDefault">preventDefault()</code> and proceeds to close the
<code>CloseWatcher</code>.</p>
</div>
<p>Combined, the above two examples show how <code
data-x="dom-CloseWatcher-requestClose">requestClose()</code> and <code
data-x="dom-CloseWatcher-close">close()</code> differ. Because we used <code
data-x="dom-CloseWatcher-requestClose">requestClose()</code> in the <code
data-x="event-click">click</code> event handler for the close button, clicking that button will
trigger the <code>CloseWatcher</code>'s <code data-x="event-cancel">cancel</code> event, and thus
potentially ask the user for confirmation if there is unsaved data. If we had used <code
data-x="dom-CloseWatcher-close">close()</code>, then this check would be skipped. Sometimes that
is appropriate, but usually <code data-x="dom-CloseWatcher-requestClose">requestClose()</code> is
the better option for user-triggered close requests.</p>
<div class="example" id="example-CloseWatcher-grouping">
<p>In addition to the <span>user activation</span> restrictions for <code
data-x="event-cancel">cancel</code> events, there is a more subtle form of user activation gating
for <code>CloseWatcher</code> construction. If one creates more than one
<code>CloseWatcher</code> without user activation, then the newly-created one will get grouped
together with the most-recently-created <span>close watcher</span>, so that a single <span>close
request</span> will close them both:</p>
<pre><code class="js">window.onload = () => {
// This will work as normal: it is the first close watcher created without user activation.
(new CloseWatcher()).onclose = () => { /* ... */ };
};
button1.onclick = () => {
// This will work as normal: the button click counts as user activation.
(new CloseWatcher()).onclose = () => { /* ... */ };
};
button2.onclick = () => {
// These will be grouped together, and both will close in response to a single close request.
(new CloseWatcher()).onclose = () => { /* ... */ };
(new CloseWatcher()).onclose = () => { /* ... */ };
};</code></pre>
<p>This means that calling <code data-x="dom-CloseWatcher-destroy">destroy()</code>, <code
data-x="dom-CloseWatcher-close">close()</code>, or <code
data-x="dom-CloseWatcher-requestClose">requestClose()</code> properly is important. Doing so is
the only way to get back the "free" ungrouped close watcher slot. Such close watchers created
without user activation are useful for cases like session inactivity timeout dialogs or urgent
notifications of server-triggered events, which are not generated in response to user
activation.</p>
</div>
<h3 split-filename="dnd" id="dnd"><dfn>Drag and drop</dfn></h3>
<!-- v2: ideas for drag and drop:
* being able to animate a drop target:
> To implement this with simple interface I've proposed, events should be handled either by
> existing elements (like list items that compare their size and position of dragged element
> to decide whether element should be dropped before or after) or handled by container that
> would probably need to calculate positions of it's children and create new element to show
> drop target. Smooth Mac-like drag'n'drop can be implemented by animating drop target's
> padding/margin. So that's quite a bit of code that's going to be reinvented each time
> someone implements reordering.
<hyatt> :droptarget
<hyatt> or something
<hyatt> we don't support a pseudo-class for the drop target but that's a great idea
<Hixie_> yeah, thinking about that too
<Hixie_> :drop-target, :drop-target(above), :drop-target(below) and having ondragover be able to say "not on me, but next to me maybe"
- some way to be able to match an element that is being dragged over.
- some way to be able to animate an element as it goes into and out of this state (CSS
transitions?), e.g. to be able to animate something "getting out of the way" to let you
drop an item between others.
- as an extension to the previous feature, a way to distinguish being dragged above or to the
left of the drag target vs below or to the right of the drag target.
* We should let drop targets communicate back to drag sources if they want to communicate.
(e.g. expose Window, and thus postMessage(), on the dataTransfer object on drop.) Or maybe
just use a MessagePort!
We should let drag sources provide a set of options via a context menu when the drop happens.
(So that, e.g., the source can know whether a capabilities URI that it is passing along is
supposed to be read-write access or read-only access to the object being dragged.)
We should let potential drop targets see the types (but not the contents!) of dragged data so
they can establish if they care or not. (dataTransfer.hasType())
Ack: Ben Laurie (@g)
* Interop with native apps. In particular, we probably want to safelist the list of types that
a web page can see, since otherwise we'll end up exposing things like the username (if a user
drags a file from their desktop, the path is exposed on some OSes).
* Alex Velkov suggests that drags to and from the same origin should be able to read the data
even before the drop.
Other things listed below:
DND-v2: more native support: text/html from selections, etc
DND-v3: add Blob support
DND-v4: add structured clone support
DND-v5: add promises (should be able to say "if you accept this
drop, then I can provide the File object that
corresponds to it eventually")
DataTransferPromise.type = 'string' or 'file' or 'blob' or 'data'
.onneeddata - can wait until this fires to provide data
.setData() - call this once you have data, must be the right type
-->
<p>This section defines an event-based drag-and-drop mechanism.</p>
<p>This specification does not define exactly what a <em>drag-and-drop operation</em> actually
is.</p>
<p>On a visual medium with a pointing device, a drag operation could be the default action of a
<code data-x="event-mousedown">mousedown</code> event that is followed by a series of <code
data-x="event-mousemove">mousemove</code> events, and the drop could be triggered by the mouse
being released.</p>
<p>When using an input modality other than a pointing device, users would probably have to
explicitly indicate their intention to perform a drag-and-drop operation, stating what they wish
to drag and where they wish to drop it, respectively.</p>
<div w-nodev>
<p>However it is implemented, drag-and-drop operations must have a starting point (e.g. where the
mouse was clicked, or the start of the selection or element that was selected for the drag), may
have any number of intermediate steps (elements that the mouse moves over during a drag, or
elements that the user picks as possible drop points as they cycle through possibilities), and must
either have an end point (the element above which the mouse button was released, or the element
that was finally selected), or be canceled. The end point must be the last element selected as a
possible drop point before the drop occurs (so if the operation is not canceled, there must be at
least one element in the middle step).</p>
</div>
<h4 id="event-drag">Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>To make an element draggable, give the element a <code data-x="attr-draggable">draggable</code>
attribute, and set an event listener for <code data-x="event-dnd-dragstart">dragstart</code> that
stores the data being dragged.</p>
<p>The event handler typically needs to check that it's not a text selection that is being
dragged, and then needs to store data into the <code>DataTransfer</code> object and set the
allowed effects (copy, move, link, or some combination).</p>
<p>For example:</p>
<pre><code class="html"><p>What fruits do you like?</p>
<ol ondragstart="dragStartHandler(event)">
<li draggable="true" data-value="fruit-apple">Apples</li>
<li draggable="true" data-value="fruit-orange">Oranges</li>
<li draggable="true" data-value="fruit-pear">Pears</li>
</ol>
<script>
var internalDNDType = 'text/x-example'; // set this to something specific to your site
function dragStartHandler(event) {
if (event.target instanceof HTMLLIElement) {
// use the element's data-value="" attribute as the value to be moving:
event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
event.dataTransfer.effectAllowed = 'move'; // only allow moves
} else {
event.preventDefault(); // don't allow selection to be dragged
}
}
</script></code></pre>
<hr>
<p>To accept a drop, the drop target has to listen to the following events:</p>
<ol>
<li>The <code data-x="event-dnd-dragenter">dragenter</code> event handler reports
whether or not the drop target is potentially willing to accept the drop, by canceling the
event.</li>
<li>The <code data-x="event-dnd-dragover">dragover</code> event handler specifies what feedback
will be shown to the user, by setting the <code
data-x="dom-DataTransfer-DropEffect">dropEffect</code> attribute of the
<code>DataTransfer</code> associated with the event. This event also needs to be canceled.</li>
<li>The <code data-x="event-dnd-drop">drop</code> event handler has a final chance to accept or
reject the drop. If the drop is accepted, the event handler must perform the drop operation on
the target. This event needs to be canceled, so that the <code
data-x="dom-DataTransfer-DropEffect">dropEffect</code> attribute's value can be used by the
source. Otherwise, the drop operation is rejected.</li>
</ol>
<p>For example:</p>
<pre><code class="html"><p>Drop your favorite fruits below:</p>
<ol ondragenter="dragEnterHandler(event)" ondragover="dragOverHandler(event)"
ondrop="dropHandler(event)">
</ol>
<script>
var internalDNDType = 'text/x-example'; // set this to something specific to your site
function dragEnterHandler(event) {
var items = event.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
var item = items[i];
if (item.kind == 'string' && item.type == internalDNDType) {
event.preventDefault();
return;
}
}
}
function dragOverHandler(event) {
event.dataTransfer.dropEffect = 'move';
event.preventDefault();
}
function dropHandler(event) {
var li = document.createElement('li');
var data = event.dataTransfer.getData(internalDNDType);
if (data == 'fruit-apple') {
li.textContent = 'Apples';
} else if (data == 'fruit-orange') {
li.textContent = 'Oranges';
} else if (data == 'fruit-pear') {
li.textContent = 'Pears';
} else {
li.textContent = 'Unknown Fruit';
}
event.target.appendChild(li);
}
</script></code></pre>
<hr>
<p>To remove the original element (the one that was dragged) from the display, the <code
data-x="event-dnd-dragend">dragend</code> event can be used.</p>
<p>For our example here, that means updating the original markup to handle that event:</p>
<pre><code class="html"><p>What fruits do you like?</p>
<ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)">
<em>...as before...</em>
</ol>
<script>
function dragStartHandler(event) {
// <em>...as before...</em>
}
function dragEndHandler(event) {
if (event.dataTransfer.dropEffect == 'move') {
// remove the dragged element
event.target.parentNode.removeChild(event.target);
}
}
</script></code></pre>
<h4>The drag data store</h4>
<p>The data that underlies a drag-and-drop operation, known as the <dfn>drag data store</dfn>,
consists of the following information:</p>
<ul>
<li><p>A <dfn>drag data store item list</dfn>, which is a list of items representing the dragged
data, each consisting of the following information:</p>
<dl>
<dt><dfn>The drag data item kind</dfn></dt>
<dd>
<p>The kind of data:</p>
<dl>
<dt><i>Text</i></dt>
<dd>
<p>Text.</p>
</dd>
<!-- DND-v3:
<dt><i>Blob</i></dt>
<dd>
<p>Binary data.</p>
</dd>
-->
<dt><i>File</i></dt>
<dd>
<p>Binary data with a filename.</p>
</dd>
<!-- DND-v4:
<dt><i>Structured object</i></dt>
<dd>
<p>An object that will be cloned using the <span>structured clone</span> algorithm.</p>
</dd>
-->
</dl>
</dd>
<dt><dfn>The drag data item type string</dfn></dt>
<dd>
<p>A Unicode string giving the type or format of the data, generally given by a <span>MIME
type</span>. Some values that are not <span data-x="MIME type">MIME types</span> are
special-cased for legacy reasons. The API does not enforce the use of <span data-x="MIME
type">MIME types</span>; other values can be used as well. In all cases, however, the values
are all <span>converted to ASCII lowercase</span> by the API.</p>
<p>There is a limit of one <i>text</i> item per <span data-x="The drag data
item type string">item type string</span>.</p> <!-- DND-v4: consider limiting the structured
objects too -->
</dd>
<dt>The actual data</dt>
<dd><p>A Unicode or binary string, in some cases with a filename (itself a Unicode string),
<!-- (DND-v4:) or an object, --> as per <span>the drag data item kind</span>.</p></dd>
</dl>
<p>The <span>drag data store item list</span> is ordered in the order that the items were added
to the list; most recently added last.</p>
</li>
<li>
<p>The following information, used to generate the UI feedback during the drag:</p>
<ul>
<li>User-agent-defined default feedback information, known as the <dfn>drag data store default
feedback</dfn>.</li>
<li>Optionally, a bitmap image and the coordinate of a point within that image, known as the
<dfn>drag data store bitmap</dfn> and <dfn>drag data store hot spot coordinate</dfn>.</li>
</ul>
</li>
<li>
<p>A <dfn>drag data store mode</dfn>, which is one of the following:</p>
<dl>
<dt><dfn data-x="concept-dnd-rw">Read/write mode</dfn></dt>
<dd>
<p>For the <code data-x="event-dnd-dragstart">dragstart</code> event. New data can be added to the
<span>drag data store</span>.</p>
</dd>
<dt><dfn data-x="concept-dnd-ro">Read-only mode</dfn></dt>
<dd>
<p>For the <code data-x="event-dnd-drop">drop</code> event. The list of items representing dragged
data can be read, including the data. No new data can be added.</p>
</dd>
<dt><dfn data-x="concept-dnd-p">Protected mode</dfn></dt>
<dd>
<p>For all other events. The formats and kinds in the <span>drag data store</span> list of
items representing dragged data can be enumerated, but the data itself is unavailable and no
new data can be added.</p>
</dd>
</dl>
</li>
<li>
<p>A <dfn>drag data store allowed effects state</dfn>, which is a string.</p>
</li>
</ul>
<p>When a <span>drag data store</span> is <dfn data-x="create a drag data store">created</dfn>, it
must be initialized such that its <span>drag data store item list</span> is empty, it has no
<span>drag data store default feedback</span>, it has no <span>drag data store bitmap</span> and
<span>drag data store hot spot coordinate</span>, its <span>drag data store mode</span> is <span
data-x="concept-dnd-p">protected mode</span>, and its <span>drag data store allowed effects
state</span> is the string "<code
data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>".</p>
<h4>The <code>DataTransfer</code> interface</h4>
<p><code>DataTransfer</code> objects are used to expose the <span>drag data store</span> that
underlies a drag-and-drop operation.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>DataTransfer</dfn> {
<span data-x="dom-DataTransfer">constructor</span>();
attribute DOMString <span data-x="dom-DataTransfer-dropEffect">dropEffect</span>;
attribute DOMString <span data-x="dom-DataTransfer-effectAllowed">effectAllowed</span>;
[SameObject] readonly attribute <span>DataTransferItemList</span> <span data-x="dom-DataTransfer-items">items</span>;
undefined <span data-x="dom-DataTransfer-setDragImage">setDragImage</span>(Element image, long x, long y);
/* old interface */
readonly attribute FrozenArray<DOMString> <span data-x="dom-DataTransfer-types">types</span>;
DOMString <span data-x="dom-DataTransfer-getData">getData</span>(DOMString format);
undefined <span data-x="dom-DataTransfer-setData">setData</span>(DOMString format, DOMString data);
undefined <span data-x="dom-DataTransfer-clearData">clearData</span>(optional DOMString format);
[SameObject] readonly attribute <span>FileList</span> <span data-x="dom-DataTransfer-files">files</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>dataTransfer</var> = new <span subdfn data-x="dom-DataTransfer">DataTransfer</span>()</code></dt>
<dd>
<p>Creates a new <code>DataTransfer</code> object with an empty <span>drag data
store</span>.</p>
</dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-dropEffect">dropEffect</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the kind of operation that is currently selected. If the kind of operation isn't one
of those that is allowed by the <code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> attribute, then the operation will
fail.</p>
<p>Can be set, to change the selected operation.</p>
<p>The possible values are "<code data-x="dom-DataTransfer-dropEffect-none">none</code>", "<code
data-x="dom-DataTransfer-dropEffect-copy">copy</code>", "<code
data-x="dom-DataTransfer-dropEffect-link">link</code>", and "<code
data-x="dom-DataTransfer-dropEffect-move">move</code>".</p>
</dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-effectAllowed">effectAllowed</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the kinds of operations that are to be allowed.</p>
<p>Can be set (during the <code data-x="event-dnd-dragstart">dragstart</code> event), to change
the allowed operations.</p>
<p>The possible values are "<code data-x="dom-DataTransfer-effectAllowed-none">none</code>",
"<code data-x="dom-DataTransfer-effectAllowed-copy">copy</code>", "<code
data-x="dom-DataTransfer-effectAllowed-copyLink">copyLink</code>", "<code
data-x="dom-DataTransfer-effectAllowed-copyMove">copyMove</code>", "<code
data-x="dom-DataTransfer-effectAllowed-link">link</code>", "<code
data-x="dom-DataTransfer-effectAllowed-linkMove">linkMove</code>", "<code
data-x="dom-DataTransfer-effectAllowed-move">move</code>", "<code
data-x="dom-DataTransfer-effectAllowed-all">all</code>", and "<code
data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>",</p>
</dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-items">items</span></code></dt>
<dd><p>Returns a <code>DataTransferItemList</code> object, with the drag data.</p></dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-setDragImage">setDragImage</span>(<var>element</var>, <var>x</var>, <var>y</var>)</code></dt>
<dd>
<p>Uses the given element to update the drag feedback, replacing any previously specified
feedback.</p>
</dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-types">types</span></code></dt>
<dd>
<p>Returns a <span>frozen array</span> listing the formats that were set in the <code
data-x="event-dnd-dragstart">dragstart</code> event. In addition, if any files are being
dragged, then one of the types will be the string "<code data-x="">Files</code>".</p>
</dd>
<dt><code data-x=""><var>data</var> = <var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-getData">getData</span>(<var>format</var>)</code></dt>
<dd><p>Returns the specified data. If there is no such data, returns the empty string.</p></dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-setData">setData</span>(<var>format</var>, <var>data</var>)</code></dt>
<dd><p>Adds the specified data.</p></dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-clearData">clearData</span>([ <var>format</var> ])</code></dt>
<dd><p>Removes the data of the specified formats. Removes all data if the argument is
omitted.</p></dd>
<dt><code data-x=""><var>dataTransfer</var>.<span subdfn data-x="dom-DataTransfer-files">files</span></code></dt>
<dd><p>Returns a <code>FileList</code> of the files being dragged, if any.</p></dd>
</dl>
<p><code>DataTransfer</code> objects that are created as part of <a
href="#dndevents">drag-and-drop events</a> are only valid while those events are being fired.</p>
<div w-nodev>
<p>A <code>DataTransfer</code> object is associated with a <span>drag data store</span> while it
is valid.</p>
<p>A <code>DataTransfer</code> object has an associated <dfn
data-x="concept-DataTransfer-types">types array</dfn>, which is a
<code data-x="frozen array">FrozenArray<DOMString></code>, initially empty. When the contents
of the <code>DataTransfer</code> object's <span>drag data store item list</span> change, or when
the <code>DataTransfer</code> object becomes no longer associated with a <span>drag data
store</span>, run the following steps:</p>
<ol>
<li><p>Let <var>L</var> be an empty sequence.</p></li>
<li>
<p>If the <code>DataTransfer</code> object is still associated with a <span>drag data
store</span>, then:</p>
<ol>
<li><p>For each item in the <code>DataTransfer</code> object's <span>drag data store item
list</span> <!-- in some order...? --> whose <span data-x="the drag data item kind">kind</span>
is <i>text</i>, add an entry to <var>L</var> consisting of the item's <span
data-x="the drag data item type string">type string</span>.</p></li>
<li><p>If there are any items in the <code>DataTransfer</code> object's <span>drag data store
item list</span> whose <span data-x="the drag data item kind">kind</span> is <i>File</i>, then
add an entry to <var>L</var> consisting of the string "<code data-x="">Files</code>". (This
value can be distinguished from the other values because it is not lowercase.)</p></li>
<!-- <li><p>Sort the list...?</p></li> -->
</ol>
</li>
<li><p>Set the <code>DataTransfer</code> object's <span data-x="concept-DataTransfer-types">types
array</span> to the result of <span>creating a frozen array</span> from <var>L</var>.</p></li>
</ol>
<p>The <dfn constructor for="DataTransfer"><code
data-x="dom-DataTransfer">DataTransfer()</code></dfn> constructor, when invoked, must return a
newly created <code>DataTransfer</code> object initialized as follows:</p>
<ol>
<li><p>Set the <span>drag data store</span>'s <span data-x="drag data store item list">item
list</span> to be an empty list.</p></li>
<li><p>Set the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> to
<span data-x="concept-dnd-rw">read/write mode</span>.</p></li>
<li><p>Set the <code data-x="dom-DataTransfer-dropEffect">dropEffect</code> and
<code data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> to "none".</p></li>
</ol>
<p>The <dfn attribute for="DataTransfer"><code
data-x="dom-DataTransfer-dropEffect">dropEffect</code></dfn> attribute controls the drag-and-drop
feedback that the user is given during a drag-and-drop operation. When the
<code>DataTransfer</code> object is created, the <code
data-x="dom-DataTransfer-dropEffect">dropEffect</code> attribute is set to a string value. On
getting, it must return its current value. On setting, if the new value is one of "<dfn><code
data-x="dom-DataTransfer-dropEffect-none">none</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-dropEffect-copy">copy</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-dropEffect-link">link</code></dfn>", or "<dfn><code
data-x="dom-DataTransfer-dropEffect-move">move</code></dfn>", then the attribute's current value
must be set to the new value. Other values must be ignored.</p>
<p>The <dfn attribute for="DataTransfer"><code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code></dfn> attribute is used in the
drag-and-drop processing model to initialize the <code
data-x="dom-DataTransfer-dropEffect">dropEffect</code> attribute during the <code
data-x="event-dnd-dragenter">dragenter</code> and <code
data-x="event-dnd-dragover">dragover</code> events. When the <code>DataTransfer</code> object is
created, the <code data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> attribute is set
to a string value. On getting, it must return its current value. On setting, if <span>drag data
store</span>'s <span data-x="drag data store mode">mode</span> is the <span
data-x="concept-dnd-rw">read/write mode</span> and the new value is one of "<dfn><code
data-x="dom-DataTransfer-effectAllowed-none">none</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-copy">copy</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-copyLink">copyLink</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-copyMove">copyMove</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-link">link</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-linkMove">linkMove</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-move">move</code></dfn>", "<dfn><code
data-x="dom-DataTransfer-effectAllowed-all">all</code></dfn>", or "<dfn><code
data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code></dfn>", then the attribute's
current value must be set to the new value. Otherwise, it must be left unchanged.</p>
<p>The <dfn attribute for="DataTransfer"><code data-x="dom-DataTransfer-items">items</code></dfn>
attribute must return a <code>DataTransferItemList</code> object associated with the
<code>DataTransfer</code> object.</p>
<p>The <dfn method for="DataTransfer"><code
data-x="dom-DataTransfer-setDragImage">setDragImage(<var>image</var>, <var>x</var>,
<var>y</var>)</code></dfn> method must run the following steps:</p>
<ol>
<li><p>If the <code>DataTransfer</code> object is no longer associated with a <span>drag data
store</span>, return. Nothing happens.</p></li>
<li><p>If the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> is
not the <span data-x="concept-dnd-rw">read/write mode</span>, return. Nothing
happens.</p></li>
<li><p>If <var>image</var> is an <code>img</code> element, then set the <span>drag data store
bitmap</span> to the element's image (at its <span data-x="natural dimensions">natural
size</span>); otherwise, set the <span>drag data store bitmap</span> to an image generated from
the given element (the exact mechanism for doing so is not currently specified).</p></li>
<li><p>Set the <span>drag data store hot spot coordinate</span> to the given <var>x</var>,
<var>y</var> coordinate.</p></li>
</ol>
<p>The <dfn attribute for="DataTransfer"><code data-x="dom-DataTransfer-types">types</code></dfn>
attribute must return this <code>DataTransfer</code> object's <span
data-x="concept-DataTransfer-types">types array</span>.</p>
<p>The <dfn method for="DataTransfer"><code
data-x="dom-DataTransfer-getData">getData(<var>format</var>)</code></dfn> method must run the
following steps:</p>
<ol>
<li><p>If the <code>DataTransfer</code> object is no longer associated with a <span>drag data
store</span>, then return the empty string.</p></li>
<li><p>If the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> is
the <span data-x="concept-dnd-p">protected mode</span>, then return the empty string.</p></li>
<li><p>Let <var>format</var> be the first argument, <span>converted to ASCII
lowercase</span>.</p></li>
<li><p>Let <var>convert-to-URL</var> be false.</p></li>
<li><p>If <var>format</var> equals "<code data-x="">text</code>", change it to "<code
data-x="">text/plain</code>".</p></li>
<li><p>If <var>format</var> equals "<code data-x="">url</code>", change it to "<code
data-x="">text/uri-list</code>" and set <var>convert-to-URL</var> to true.</p></li>
<li><p>If there is no item in the <span>drag data store item list</span> whose <span data-x="the
drag data item kind">kind</span> is <i>text</i> and whose <span data-x="the drag
data item type string">type string</span> is equal to <var>format</var>, return the empty string.</p></li>
<li><p>Let <var>result</var> be the data of the item in the <span>drag data store item
list</span> whose <span data-x="the drag data item kind">kind</span> is <i>Plain Unicode
string</i> and whose <span data-x="the drag data item type string">type string</span> is equal to
<var>format</var>.</p></li>
<li><p>If <var>convert-to-URL</var> is true, then parse <var>result</var> as appropriate for
<code data-x="">text/uri-list</code> data, and then set <var>result</var> to the first URL from
the list, if any, or the empty string otherwise. <ref>RFC2483</ref></p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p>The <dfn method for="DataTransfer"><code
data-x="dom-DataTransfer-setData">setData(<var>format</var>, <var>data</var>)</code></dfn> method
must run the following steps:</p>
<ol>
<li><p>If the <code>DataTransfer</code> object is no longer associated with a <span>drag data
store</span>, return. Nothing happens.</p></li>
<li><p>If the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> is
not the <span data-x="concept-dnd-rw">read/write mode</span>, return. Nothing
happens.</p></li>
<li><p>Let <var>format</var> be the first argument, <span>converted to ASCII
lowercase</span>.</p></li>
<li>
<p>If <var>format</var> equals "<code data-x="">text</code>", change it to "<code
data-x="">text/plain</code>".</p>
<p>If <var>format</var> equals "<code data-x="">url</code>", change it to "<code
data-x="">text/uri-list</code>".</p>
</li>
<li><p>Remove the item in the <span>drag data store item list</span> whose <span data-x="the drag
data item kind">kind</span> is <i>text</i> and whose <span data-x="the drag data
item type string">type string</span> is equal to <var>format</var>, if there is
one.</p></li>
<li><p>Add an item to the <span>drag data store item list</span> whose <span data-x="the drag data
item kind">kind</span> is <i>text</i>, whose <span data-x="the drag data item type
string">type string</span> is equal to <var>format</var>, and whose data is the string
given by the method's second argument.</p></li>
</ol>
<p>The <dfn method for="DataTransfer"><code
data-x="dom-DataTransfer-clearData">clearData(<var>format</var>)</code></dfn> method must run the
following steps:</p>
<ol>
<li><p>If the <code>DataTransfer</code> object is no longer associated with a <span>drag data
store</span>, return. Nothing happens.</p></li>
<li><p>If the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> is
not the <span data-x="concept-dnd-rw">read/write mode</span>, return. Nothing
happens.</p></li>
<li><p>If the method was called with no arguments, remove each item in the <span>drag data store
item list</span> whose <span data-x="the drag data item kind">kind</span> is <i>Plain Unicode
string</i>, and return.</p></li>
<li><p>Set <var>format</var> to <var>format</var>, <span>converted to ASCII
lowercase</span>.</p></li>
<li>
<p>If <var>format</var> equals "<code data-x="">text</code>", change it to "<code
data-x="">text/plain</code>".</p>
<p>If <var>format</var> equals "<code data-x="">url</code>", change it to "<code
data-x="">text/uri-list</code>".</p>
</li>
<li><p>Remove the item in the <span>drag data store item list</span> whose <span data-x="the drag
data item kind">kind</span> is <i>text</i> and whose <span data-x="the drag data
item type string">type string</span> is equal to <var>format</var>, if there is
one.</p></li>
</ol>
<p class="note">The <code data-x="dom-DataTransfer-clearData">clearData()</code> method does not
affect whether any files were included in the drag, so the <code
data-x="dom-DataTransfer-types">types</code> attribute's list might still not be empty after
calling <code data-x="dom-DataTransfer-clearData">clearData()</code> (it would still contain the
"<code data-x="">Files</code>" string if any files were included in the drag).</p>
<p>The <dfn attribute for="DataTransfer"><code data-x="dom-DataTransfer-files">files</code></dfn>
attribute must return a <span>live</span> <code>FileList</code> sequence consisting of
<code>File</code> objects representing the files found by the following steps. Furthermore, for a
given <code>FileList</code> object and a given underlying file, the same <code>File</code> object
must be used each time.</p>
<ol>
<li><p>Start with an empty list <var>L</var>.</p></li>
<li><p>If the <code>DataTransfer</code> object is no longer associated with a <span>drag data
store</span>, the <code>FileList</code> is empty. Return the empty list <var>L</var>.</p></li>
<li><p>If the <span>drag data store</span>'s <span data-x="drag data store mode">mode</span> is
the <span data-x="concept-dnd-p">protected mode</span>, return the empty list
<var>L</var>.</p></li>
<li><p>For each item in the <span>drag data store item list</span> <!-- in some order...? -->
whose <span data-x="the drag data item kind">kind</span> is <i>File</i><!-- DND-v3: (not
<i>Blob</i>) -->, add the item's data (the file, in particular its name and contents, as well as
its <span data-x="the drag data item type string">type</span>) to the list <var>L</var>.</p></li>
<!-- <li><p>Sort the list...?</p></li> -->
<li><p>The files found by these steps are those in the list <var>L</var>.</p></li>
</ol>
<p class="note">This version of the API does not expose the types of the files during the
drag.</p>
</div>
<h5>The <code>DataTransferItemList</code> interface</h5>
<p>Each <code>DataTransfer</code> object is associated with a <code>DataTransferItemList</code>
object.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>DataTransferItemList</dfn> {
readonly attribute unsigned long <span data-x="dom-DataTransferItemList-length">length</span>;
<a href="#dom-datatransferitemlist-item">getter</a> <span>DataTransferItem</span> (unsigned long index);
<span>DataTransferItem</span>? <span data-x="dom-DataTransferItemList-add">add</span>(DOMString data, DOMString type);<!--
DND-v3: <span>DataTransferItem</span>? <span data-x="dom-DataTransferItemList-add">add</span>(<span>Blob</span> data);-->
<span>DataTransferItem</span>? <span data-x="dom-DataTransferItemList-add">add</span>(<span>File</span> data);<!--
DND-v4: <span>DataTransferItem</span>? <span data-x="dom-DataTransferItemList-add">add</span>(any data, DOMString type);--><!--
DND-v5: <span>DataTransferItem</span>? <span data-x="dom-DataTransferItemList-add">add</span>(<span>DataTransferPromise</span> data);-->
undefined <span data-x="dom-DataTransferItemList-remove">remove</span>(unsigned long index);
undefined <span data-x="dom-DataTransferItemList-clear">clear</span>();
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>items</var>.<span subdfn data-x="dom-DataTransferItemList-length">length</span></code></dt>
<dd><p>Returns the number of items in the <span>drag data store</span>.</p></dd>
<dt><code data-x=""><var>items</var>[<var>index</var>]</code></dt>
<dd>
<p>Returns the <code>DataTransferItem</code> object representing the <var>index</var>th entry in
the <span>drag data store</span>.</p>
</dd>
<dt><code data-x=""><var>items</var>.<span subdfn data-x="dom-DataTransferItemList-remove">remove</span>(<var>index</var>)</code></dt>
<dd><p>Removes the <var>index</var>th entry in the <span>drag data store</span>.</p></dd>
<dt><code data-x=""><var>items</var>.<span subdfn data-x="dom-DataTransferItemList-clear">clear</span>()</code></dt>
<dd><p>Removes all the entries in the <span>drag data store</span>.</p></dd>
<dt><code data-x=""><var>items</var>.<span subdfn data-x="dom-DataTransferItemList-add">add</span>(<var>data</var>)</code></dt>
<dt><code data-x=""><var>items</var>.<span data-x="dom-DataTransferItemList-add">add</span>(<var>data</var>, <var>type</var>)</code></dt>
<dd>
<p>Adds a new entry for the given data to the <span>drag data store</span>. If the data is plain
text <!-- DND-v4: or an object --> then a <var>type</var> string has to be provided also.</p>
</dd>
</dl>
<div w-nodev>
<p>While the <code>DataTransferItemList</code> object's <code>DataTransfer</code> object is
associated with a <span>drag data store</span>, the <code>DataTransferItemList</code> object's
<i>mode</i> is the same as the <span>drag data store mode</span>. When the
<code>DataTransferItemList</code> object's <code>DataTransfer</code> object is <em>not</em>
associated with a <span>drag data store</span>, the <code>DataTransferItemList</code> object's
<i>mode</i> is the <i>disabled mode</i>. The <span>drag data store</span> referenced in this
section (which is used only when the <code>DataTransferItemList</code> object is not in the
<i>disabled mode</i>) is the <span>drag data store</span> with which the
<code>DataTransferItemList</code> object's <code>DataTransfer</code> object is associated.</p>
<p>The <dfn attribute for="DataTransferItemList"><code
data-x="dom-DataTransferItemList-length">length</code></dfn> attribute must return zero if the
object is in the <i>disabled mode</i>; otherwise it must return the number of items in the
<span>drag data store item list</span>.</p>
<p>When a <code>DataTransferItemList</code> object is not in the <i>disabled mode</i>, its
<span>supported property indices</span> are the <span>indices</span> of the <span>drag data store
item list</span>.</p>
<p id="dom-datatransferitemlist-item">To <span>determine the value of an indexed property</span>
<var>i</var> of a <code>DataTransferItemList</code> object, the user agent must return a
<code>DataTransferItem</code> object representing the <var>i</var>th item in the
<span>drag data store</span>. The same object must be returned each time a particular item is
obtained from this <code>DataTransferItemList</code> object. The <code>DataTransferItem</code>
object must be associated with the same <code>DataTransfer</code> object as the
<code>DataTransferItemList</code> object when it is first created.</p>
<p>The <dfn method for="DataTransferItemList"><code
data-x="dom-DataTransferItemList-add">add()</code></dfn> method must run the following steps:</p>
<ol>
<li><p>If the <code>DataTransferItemList</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i>, return null.</p></li>
<li>
<p>Jump to the appropriate set of steps from the following list:</p>
<dl class="switch">
<dt>If the first argument to the method is a string</dt>
<dd>
<p>If there is already an item in the <span>drag data store item list</span> whose <span
data-x="the drag data item kind">kind</span> is <i>text</i> and whose <span
data-x="the drag data item type string">type string</span> is equal to the value of the
method's second argument, <span>converted to ASCII lowercase</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p>
<p>Otherwise, add an item to the <span>drag data store item list</span> whose <span data-x="the
drag data item kind">kind</span> is <i>text</i>, whose <span data-x="the drag
data item type string">type string</span> is equal to the value of the method's second
argument, <span>converted to ASCII lowercase</span>, and whose data is the string given by the
method's first argument.</p>
</dd>
<!--DND-v3:
<dt>If the first argument to the method is a <code>Blob</code></dt>
<dd>
<p>Add an item to the <span>drag data store item list</span> whose <span data-x="the drag data
item kind">kind</span> is <i>Blob</i>, whose <span data-x="the drag data item type string">type
string</span> is the <code data-x="dom-Blob-type">type</code> of the <code>Blob</code>,
<span>converted to ASCII lowercase</span>, and whose data is the same as the
<code>Blob</code>'s data.</p>
</dd>
-->
<dt>If the first argument to the method is a <code>File</code></dt>
<dd>
<p>Add an item to the <span>drag data store item list</span> whose <span data-x="the drag data
item kind">kind</span> is <i>File</i>, whose <span data-x="the drag data item type string">type
string</span> is the <code data-x="dom-Blob-type">type</code> of the <code>File</code>,
<span>converted to ASCII lowercase</span>, and whose data is the same as the
<code>File</code>'s data.</p>
</dd>
<!--DND-v4: (might want to prevent duplicates like for strings; see above)
[make sure that the cloning happens before any side-effects can happen]
<dt>Otherwise
<dd>
<p>Add an item to the <span>drag data store item list</span> whose <span data-x="the drag data
item kind">kind</span> is <i>Object</i>, whose <span data-x="the drag data item type
string">type string</span> is equal to the value of the method's second argument,
<span>converted to ASCII lowercase</span>, and whose data is a <span>structured clone</span>
of the method's first argument. If creating the clone throws an exception, then throw that
exception.</p>
</dd>
-->
</dl>
</li>
<li><p><a href="#dom-datatransferitemlist-item">Determine the value of the indexed property</a>
corresponding to the newly added item, and return that value (a newly created
<code>DataTransferItem</code> object).</p></li>
</ol>
<p>The <dfn method for="DataTransferItemList"><code
data-x="dom-DataTransferItemList-remove">remove(<var>index</var>)</code></dfn> method must run
these steps:</p>
<ol>
<li><p>If the <code>DataTransferItemList</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i>, throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the <span>drag data store</span> does not contain an <var>index</var>th item, then
return.</p></li>
<li><p>Remove the <var>index</var>th item from the <span>drag data store</span>.</p></li>
</ol>
<p>The <dfn method for="DataTransferItemList"><code
data-x="dom-DataTransferItemList-clear">clear()</code></dfn> method, if the
<code>DataTransferItemList</code> object is in the <i data-x="concept-dnd-rw">read/write mode</i>,
must remove all the items from the <span>drag data store</span>. Otherwise, it must do
nothing.</p>
</div>
<h5>The <code>DataTransferItem</code> interface</h5>
<p>Each <code>DataTransferItem</code> object is associated with a <code>DataTransfer</code>
object.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>DataTransferItem</dfn> {
readonly attribute DOMString <span data-x="dom-DataTransferItem-kind">kind</span>;
readonly attribute DOMString <span data-x="dom-DataTransferItem-type">type</span>;
undefined <span data-x="dom-DataTransferItem-getAsString">getAsString</span>(<span>FunctionStringCallback</span>? _callback);<!--
DND-v3: <span>Blob</span> <span data-x="dom-DataTransferItem-getAsBlob">getAsBlob</span>();-->
<span>File</span>? <span data-x="dom-DataTransferItem-getAsFile">getAsFile</span>();<!--
DND-v4: undefined <span data-x="dom-DataTransferItem-getAsObject">getAsObject</span>(<span>FunctionObjectCallback</span> _callback);-->
};
callback <dfn callback>FunctionStringCallback</dfn> = undefined (DOMString data);<!--
// DND-v4:
callback <dfn>FunctionObjectCallback</dfn> = undefined (any data);--></code></pre>
<dl class="domintro">
<dt><code data-x=""><var>item</var>.<span subdfn data-x="dom-DataTransferItem-kind">kind</span></code></dt>
<dd>
<p>Returns <span>the drag data item kind</span>, one of: "string", <!-- DND-v3: "blob", -->
"file"<!-- DND-v4: , "object" -->.</p>
</dd>
<dt><code data-x=""><var>item</var>.<span subdfn data-x="dom-DataTransferItem-type">type</span></code></dt>
<dd><p>Returns <span>the drag data item type string</span>.</p></dd>
<dt><code data-x=""><var>item</var>.<span subdfn data-x="dom-DataTransferItem-getAsString">getAsString</span>(<var>callback</var>)</code></dt>
<dd>
<p>Invokes the callback with the string data as the argument, if <span>the drag data item
kind</span> is <i>text</i>.</p>
</dd>
<!-- DND-v3:
<dt><var>file</var> = <var>item</var>.<code subdfn data-x="dom-DataTransferItem-getAsBlob">getAsBlob</code>()</dt>
<dd>
<p>Returns a <code>Blob</code> object, if <span>the drag data item kind</span> is <i>Blob</i> or
<i>File</i>.</p>
</dd>
-->
<dt><code data-x=""><var>file</var> = <var>item</var>.<span subdfn data-x="dom-DataTransferItem-getAsFile">getAsFile</span>()</code></dt>
<dd>
<p>Returns a <code>File</code> object, if <span>the drag data item kind</span> is
<i>File</i>.</p>
</dd>
<!-- DND-v4:
<dt><var>file</var> = <var>item</var>.<code subdfn data-x="dom-DataTransferItem-getAsObject">getAsObject</code>()</dt>
<dd>
<p>Invokes the callback with the cloned object data as the argument, if <span>the drag data item
kind</span> is <i>text</i> or <i>Object</i>.</p>
</dd>
-->
</dl>
<div w-nodev>
<p>While the <code>DataTransferItem</code> object's <code>DataTransfer</code> object is associated
with a <span>drag data store</span> and that <span>drag data store</span>'s <span>drag data store
item list</span> still contains the item that the <code>DataTransferItem</code> object represents,
the <code>DataTransferItem</code> object's <i>mode</i> is the same as the <span>drag data store
mode</span>. When the <code>DataTransferItem</code> object's <code>DataTransfer</code> object is
<em>not</em> associated with a <span>drag data store</span>, or if the item that the
<code>DataTransferItem</code> object represents has been removed from the relevant <span>drag data
store item list</span>, the <code>DataTransferItem</code> object's <i>mode</i> is the <i>disabled
mode</i>. The <span>drag data store</span> referenced in this section (which is used only when the
<code>DataTransferItem</code> object is not in the <i>disabled mode</i>) is the <span>drag data
store</span> with which the <code>DataTransferItem</code> object's <code>DataTransfer</code>
object is associated.</p>
<p>The <dfn attribute for="DataTransferItem"><code
data-x="dom-DataTransferItem-kind">kind</code></dfn> attribute must return the empty string if the
<code>DataTransferItem</code> object is in the <i>disabled mode</i>; otherwise it must return the
string given in the cell from the second column of the following table from the row whose cell in
the first column contains <span>the drag data item kind</span> of the item represented by the
<code>DataTransferItem</code> object:</p>
<table>
<thead>
<tr> <th> Kind <th> String
<tbody>
<tr> <td> <i>Text</i> <td> "<code data-x="">string</code>"
<!-- DND-v3: <tr> <td> <i>Blob</i> <td> "<code data-x="">blob</code>"-->
<tr> <td> <i>File</i> <td> "<code data-x="">file</code>"
<!-- DND-v4: <tr> <td> <i>Object</i> <td> "<code data-x="">object</code>"-->
</table>
<p>The <dfn attribute for="DataTransferItem"><code
data-x="dom-DataTransferItem-type">type</code></dfn> attribute must return the empty string if the
<code>DataTransferItem</code> object is in the <i>disabled mode</i>; otherwise it must return
<span>the drag data item type string</span> of the item represented by the
<code>DataTransferItem</code> object.</p>
<p>The <dfn method for="DataTransferItem"><code
data-x="dom-DataTransferItem-getAsString">getAsString(<var>callback</var>)</code></dfn> method
must run the following steps:</p>
<ol>
<li><p>If the <var>callback</var> is null, return.</p></li>
<li><p>If the <code>DataTransferItem</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i> or the <i data-x="concept-dnd-ro">read-only mode</i>,
return. The callback is never invoked.</p></li>
<li><p>If <span>the drag data item kind</span> is not <i>text</i>, then return.
The callback is never invoked.</p></li>
<li><p>Otherwise, <span>queue a task</span> to invoke <var>callback</var>, passing the
actual data of the item represented by the <code>DataTransferItem</code> object as the
argument.</p></li>
</ol>
<!--DND-v3:
<p>The <dfn><code data-x="dom-DataTransferItem-getAsBlob">getAsBlob()</code></dfn> method must run
the following steps:</p>
<ol>
<li><p>If the <code>DataTransferItem</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i> or the <i data-x="concept-dnd-ro">read-only mode</i>,
return null.</p></li>
<li>
--><!--DND-v4:
<p>If <span>the drag data item kind</span> is <i>Object</i>, return null.</p></li>
--><!--DND-v3:
<p>If <span>the drag data item kind</span> is <i>File</i>, then return a new <code>File</code>
object representing the actual data of the item represented by the <code>DataTransferItem</code>
object.</p>
<p>If <span>the drag data item kind</span> is <i>Unicode Data string</i>, then return a new
<code>Blob</code> object representing the actual data of the item represented by the
<code>DataTransferItem</code> object, with the <code data-x="dom-Blob-type">type</code> of the
<code>Blob</code> being <span>the drag data item type string</span> and with the binary data of
the <code>Blob</code> object being the Unicode string encoded as UTF-8. <ref>ENCODING</ref></p>
<p>Otherwise, <span>the drag data item kind</span> is <i>Blob</i>; return a new
<code>Blob</code> object representing the actual data of the item represented by the
<code>DataTransferItem</code> object.</p>
</li>
</ol>
-->
<p>The <dfn method for="DataTransferItem"><code
data-x="dom-DataTransferItem-getAsFile">getAsFile()</code></dfn> method must run the following
steps:</p>
<ol>
<li><p>If the <code>DataTransferItem</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i> or the <i data-x="concept-dnd-ro">read-only mode</i>,
then return null.</p></li>
<li><p>If <span>the drag data item kind</span> is not <i>File</i>, then return null.</p></li>
<li><p>Return a new <code>File</code> object representing the actual data of the item represented
by the <code>DataTransferItem</code> object.</p>
</ol>
<!--DND-v4:
<p>The <dfn><code data-x="dom-DataTransferItem-getAsObject">getAsObject(<var>callback</var>)</code></dfn> method must run the following steps:</p>
<ol>
<li><p>If the <code>DataTransferItem</code> object is not in the <i
data-x="concept-dnd-rw">read/write mode</i> or the <i data-x="concept-dnd-ro">read-only mode</i>,
return null.</p></li>
<li>
<p>Let <var>data</var> be the actual data of the item represented by the
<code>DataTransferItem</code> object.</p>
<p>If <span>the drag data item kind</span> is <i>Unicode Data string</i>, then <var>data</var>
is a <code data-x="idl-DOMString">DOMString</code> containing the actual data.</p>
<p>If <span>the drag data item kind</span> is <i>Blob</i>, then <var>data</var> is a
<code>Blob</code> representing the actual data.</p>
<p>If <span>the drag data item kind</span> is <i>File</i>, then <var>data</var> is a
<code>File</code> representing the actual data.</p>
<p>If <span>the drag data item kind</span> is <i>Object</i>, then <var>data</var> is the object
that is the actual data.</p>
</li>
<li><span>Queue a task</span> to invoke <var>callback</var>, passing a <span>structured
clone</span> of <var>data</var> as the argument.</p></li>
</ol>
-->
</div>
<h4>The <code>DragEvent</code> interface</h4>
<p>The drag-and-drop processing model involves several events. They all use the
<code>DragEvent</code> interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>DragEvent</dfn> : <span>MouseEvent</span> {
constructor(DOMString type, optional <span>DragEventInit</span> eventInitDict = {});
readonly attribute <span>DataTransfer</span>? <span data-x="dom-DragEvent-dataTransfer">dataTransfer</span>;
};
dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
<span>DataTransfer</span>? dataTransfer = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-DragEvent-dataTransfer">dataTransfer</span></code></dt>
<dd><p>Returns the <code>DataTransfer</code> object for the event.</p></dd>
</dl>
<p class="note">Although, for consistency with other event interfaces, the <code>DragEvent</code>
interface has a constructor, it is not particularly useful. In particular, there's no way to
create a useful <code>DataTransfer</code> object from script, as <code>DataTransfer</code> objects
have a processing and security model that is coordinated by the browser during drag-and-drops.</p>
<div w-nodev>
<p>The <dfn attribute for="DragEvent"><code
data-x="dom-DragEvent-dataTransfer">dataTransfer</code></dfn> attribute of the
<code>DragEvent</code> interface must return the value it was initialized to. It represents the
context information for the event.</p>
</div>
<div w-nodev>
<p>When a user agent is required to <dfn>fire a DND event</dfn> named <var>e</var> at an element,
using a particular <span>drag data store</span>, and optionally with a specific <var>related
target</var>, the user agent must run the following steps:</p>
<ol>
<li>Let <var>dataDragStoreWasChanged</var> be false.</li>
<li><p>If no specific <var>related target</var> was provided, set <var>related target</var> to
null.</p></li>
<li><p>Let <var>window</var> be the <span>relevant global object</span> of the
<code>Document</code> object of the specified target element.</p></li>
<li>
<p>If <var>e</var> is <code data-x="event-dnd-dragstart">dragstart</code>, then set the
<span>drag data store mode</span> to the <span data-x="concept-dnd-rw">read/write mode</span>
and set <var>dataDragStoreWasChanged</var> to true.</p>
<p>If <var>e</var> is <code data-x="event-dnd-drop">drop</code>, set the <span>drag data store
mode</span> to the <span data-x="concept-dnd-ro">read-only mode</span>.</p>
</li>
<li><p>Let <var>dataTransfer</var> be a newly created <code>DataTransfer</code> object
associated with the given <span>drag data store</span>.</p></li>
<li><!--en-GB--><p id="effectAllowed-initialisation">Set the <code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> attribute to the <span>drag data
store</span>'s <span>drag data store allowed effects state</span>.</p></li>
<li>
<!--en-GB--><p id="dropEffect-initialisation">Set the <code
data-x="dom-DataTransfer-dropEffect">dropEffect</code> attribute to "<code
data-x="dom-DataTransfer-dropEffect-none">none</code>" if <var>e</var> is <code
data-x="event-dnd-dragstart">dragstart</code>, <code data-x="event-dnd-drag">drag</code>, or
<code data-x="event-dnd-dragleave">dragleave</code>; to the value corresponding to the
<span>current drag operation</span> if <var>e</var> is <code data-x="event-dnd-drop">drop</code>
or <code data-x="event-dnd-dragend">dragend</code>; and to a value based on the <code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> attribute's value and the
drag-and-drop source, as given by the following table, otherwise (i.e. if <var>e</var> is <code
data-x="event-dnd-dragenter">dragenter</code> or <code
data-x="event-dnd-dragover">dragover</code>):</p>
<table>
<thead>
<tr>
<th><code data-x="dom-DataTransfer-effectAllowed">effectAllowed</code></th>
<th><code data-x="dom-DataTransfer-dropEffect">dropEffect</code></th>
</tr>
</thead>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-none">none</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-none">none</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-copy">copy</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-copyLink">copyLink</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, "<code data-x="dom-DataTransfer-dropEffect-link">link</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-copyMove">copyMove</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-all">all</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, either "<code data-x="dom-DataTransfer-dropEffect-link">link</code>" or "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-link">link</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-link">link</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-linkMove">linkMove</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-link">link</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-move">move</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>" when what is being dragged is a selection from a text control</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-move">move</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, either "<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>" or "<code data-x="dom-DataTransfer-dropEffect-link">link</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>" when what is being dragged is a selection</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, either "<code data-x="dom-DataTransfer-dropEffect-link">link</code>" or "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>" when what is being dragged is an <code>a</code> element with an <code data-x="attr-hyperlink-href">href</code> attribute</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-link">link</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, either "<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>" or "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
<tr>
<td>Any other case</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>", or, <span data-x="concept-platform-dropEffect-override">if appropriate</span>, either "<code data-x="dom-DataTransfer-dropEffect-link">link</code>" or "<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
</tr>
</table>
<p>Where the table above provides <dfn data-x="concept-platform-dropEffect-override">possibly
appropriate alternatives</dfn>, user agents may instead use the listed alternative values if
platform conventions dictate that the user has requested those alternate effects.</p>
<p class="example">For example, Windows platform conventions are such that dragging while
holding the "alt" key indicates a preference for linking the data, rather than moving or copying
it. Therefore, on a Windows system, if "<code data-x="dom-DataTransfer-dropEffect-link">link</code>" is an option according to
the table above while the "alt" key is depressed, the user agent could select that instead of
"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>" or "<code data-x="dom-DataTransfer-dropEffect-move">move</code>".</p>
</li>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> using
<code>DragEvent</code>.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-Event-type">type</code> attribute to
<var>e</var>, its <code data-x="dom-Event-bubbles">bubbles</code> attribute to true, its <code
data-x="dom-UIEvent-view">view</code> attribute to <var>window</var>, its <code
data-x="dom-MouseEvent-relatedTarget">relatedTarget</code> attribute to <var>related
target</var>, and its <code data-x="dom-DragEvent-dataTransfer">dataTransfer</code> attribute to
<var>dataTransfer</var>.</p></li>
<li><p>If <var>e</var> is not <code data-x="event-dnd-dragleave">dragleave</code> or <code
data-x="event-dnd-dragend">dragend</code>, then initialize <var>event</var>'s <code
data-x="dom-Event-cancelable">cancelable</code> attribute to true.</p></li>
<li>
<p>Initialize <var>event</var>'s mouse and key attributes initialized according to the state of
the input devices as they would be for user interaction events.</p>
<!-- interaction event spec point -->
<p>If there is no relevant pointing device, then initialize <var>event</var>'s <code
data-x="">screenX</code>, <code data-x="">screenY</code>, <code
data-x="mouseevent-clientx">clientX</code>, <code data-x="mouseevent-clienty">clientY</code>,
and <code data-x="">button</code> attributes to 0.</p>
</li>
<li><p><span data-x="concept-event-dispatch">Dispatch</span> <var>event</var> at the specified
target element.</p></li>
<li><p>Set the <span>drag data store allowed effects state</span> to the current value of
<var>dataTransfer</var>'s <code data-x="dom-DataTransfer-effectAllowed">effectAllowed</code>
attribute. (It can only have changed value if <var>e</var> is <code
data-x="event-dnd-dragstart">dragstart</code>.)</p></li>
<li><p>If <var>dataDragStoreWasChanged</var> is true, then set the <span>drag data store
mode</span> back to the <span data-x="concept-dnd-p">protected mode</span>.</p></li>
<li><p>Break the association between <var>dataTransfer</var> and the <span>drag data
store</span>.</p></li>
</ol>
</div>
<div w-nodev>
<h4 id="drag-and-drop-processing-model">Processing model</h4>
<p>When the user attempts to begin a drag operation, the user agent must run the following steps.
User agents must act as if these steps were run even if the drag actually started in another
document or application and the user agent was not aware that the drag was occurring until it
intersected with a document under the user agent's purview.</p>
<ol>
<li>
<p>Determine what is being dragged, as follows:</p>
<p>If the drag operation was invoked on a selection, then it is the selection that is being
dragged.</p>
<p>Otherwise, if the drag operation was invoked on a <code>Document</code>, it is the first
element, going up the ancestor chain, starting at the node that the user tried to drag, that has
the IDL attribute <code data-x="dom-draggable">draggable</code> set to true. If there is no such
element, then nothing is being dragged; return, the drag-and-drop operation is never
started.</p>
<p>Otherwise, the drag operation was invoked outside the user agent's purview. What is being
dragged is defined by the document or application where the drag was started.</p>
<p class="note"><code>img</code> elements and <code>a</code> elements with an <code
data-x="attr-hyperlink-href">href</code> attribute have their <code
data-x="dom-draggable">draggable</code> attribute set to true by default.</p>
</li>
<li><p><span>Create a drag data store</span>. All the DND events fired subsequently by the steps
in this section must use this <span>drag data store</span>.</p></li>
<li>
<p>Establish which DOM node is the <dfn>source node</dfn>, as follows:</p>
<p>If it is a selection that is being dragged, then the <span>source node</span> is the
<code>Text</code> node that the user started the drag on (typically the <code>Text</code> node
that the user originally clicked). If the user did not specify a particular node, for example if
the user just told the user agent to begin a drag of "the selection", then the <span>source
node</span> is the first <code>Text</code> node containing a part of the selection.</p>
<p>Otherwise, if it is an element that is being dragged, then the <span>source node</span> is
the element that is being dragged.</p>
<p>Otherwise, the <span>source node</span> is part of another document or application. When this
specification requires that an event be dispatched at the <span>source node</span> in this case,
the user agent must instead follow the platform-specific conventions relevant to that
situation.</p>
<p class="note">Multiple events are fired on the <span>source node</span> during the course of
the drag-and-drop operation.</p>
</li>
<li>
<p>Determine the <dfn>list of dragged nodes</dfn>, as follows:</p>
<p>If it is a selection that is being dragged, then the <span>list of dragged nodes</span>
contains, in <span>tree order</span>, every node that is partially or completely included in the
selection (including all their ancestors).</p>
<p>Otherwise, the <span>list of dragged nodes</span> contains only the <span>source node</span>,
if any.</p>
</li>
<li>
<p>If it is a selection that is being dragged, then add an item to the <span>drag data store
item list</span>, with its properties set as follows:</p>
<dl>
<dt><span>The drag data item type string</span>
<dd>"<code>text/plain</code>"</dd>
<dt><span>The drag data item kind</span>
<dd><i>Text</i></dd>
<dt>The actual data</dt>
<dd>The text of the selection</dd>
</dl>
<p>Otherwise, if any files are being dragged, then add one item per file to the <span>drag data
store item list</span>, with their properties set as follows:</p>
<dl>
<dt><span>The drag data item type string</span>
<dd>The MIME type of the file, if known, or "<code>application/octet-stream</code>" otherwise.</dd>
<dt><span>The drag data item kind</span>
<dd><i>File</i></dd>
<dt>The actual data</dt>
<dd>The file's contents and name.</dd>
</dl>
<p class="note">Dragging files can currently only happen from outside a <span>navigable</span>,
for example from a file system manager application.</p>
<p>If the drag initiated outside of the application, the user agent must add items to the
<span>drag data store item list</span> as appropriate for the data being dragged, honoring
platform conventions where appropriate; however, if the platform conventions do not use <span
data-x="MIME type">MIME types</span> to label dragged data, the user agent must make a
best-effort attempt to map the types to MIME types, and, in any case, all the <span data-x="the
drag data item type string">drag data item type strings</span> must be <span>converted to ASCII
lowercase</span>.</p>
<p>User agents may also add one or more items representing the selection or dragged element(s)
in other forms, e.g. as HTML.</p>
</li>
<!-- DND-v2: text/html as an export format -->
<li>
<p>If the <span>list of dragged nodes</span> is not empty, then <span data-x="extracting
JSON">extract the microdata from those nodes into a JSON form</span>, and add one item to the
<span>drag data store item list</span>, with its properties set as follows:</p>
<dl>
<dt><span>The drag data item type string</span>
<dd><code>application/microdata+json</code></dd>
<dt><span>The drag data item kind</span>
<dd><i>Text</i></dd>
<dt>The actual data</dt>
<dd>The resulting JSON string.</dd>
</dl>
</li>
<li>
<p>Run the following substeps:</p>
<ol>
<li><p>Let <var>urls</var> be « ».</p></li>
<li>
<p>For each <var>node</var> in the <span>list of dragged nodes</span>:</p>
<dl>
<dt>If the node is an <code>a</code> element with an <code
data-x="attr-hyperlink-href">href</code> attribute</dt>
<dd>Add to <var>urls</var> the result of <span>encoding-parsing-and-serializing a URL</span>
given the element's <code data-x="attr-hyperlink-href">href</code> content attribute's value,
relative to the element's <span>node document</span>.</dd>
<dt>If the node is an <code>img</code> element with a <code data-x="attr-img-src">src</code>
attribute</dt>
<dd>Add to <var>urls</var> the result of <span>encoding-parsing-and-serializing a URL</span>
given the element's <code data-x="attr-img-src">src</code> content attribute's value, relative to
the element's <span>node document</span>.</dd>
</dl>
</li>
<li><p>If <var>urls</var> is still empty, then return.</p></li>
<li><p>Let <var>url string</var> be the result of concatenating the strings in <var>urls</var>,
in the order they were added, separated by a U+000D CARRIAGE RETURN U+000A LINE FEED character
pair (CRLF).</p></li>
<li><p>Add one item to the <span>drag data store item list</span>, with its properties set as
follows:</p>
<dl>
<dt><span>The drag data item type string</span>
<dd><code>text/uri-list</code></dd>
<dt><span>The drag data item kind</span>
<dd><i>Text</i></dd>
<dt>The actual data</dt>
<dd><var>url string</var></dd>
</dl>
</li>
</ol>
</li>
<li>
<p>Update the <span>drag data store default feedback</span> as appropriate for the user agent
(if the user is dragging the selection, then the selection would likely be the basis for this
feedback; if the user is dragging an element, then that element's rendering would be used; if
the drag began outside the user agent, then the platform conventions for determining the drag
feedback should be used).</p>
</li>
<li>
<p><span>Fire a DND event</span> named <code data-x="event-dnd-dragstart">dragstart</code> at the
<span>source node</span>.</p>
<p>If the event is canceled, then the drag-and-drop operation should not occur; return.</p>
<!-- only a "should" because the UA can always allow the user to drag without the page knowing -->
<p class="note">Since events with no event listeners registered are, almost by definition, never
canceled, drag-and-drop is always available to the user if the author does not specifically
prevent it.</p>
</li>
<li><p><span>Fire a pointer event</span> at the <span>source node</span> named <code
data-x="event-pointercancel">pointercancel</code>, and fire any other follow-up events as
required by <cite>Pointer Events</cite>. <ref>POINTEREVENTS</ref></p></li>
<li>
<p><span>Initiate the drag-and-drop operation</span> in a manner consistent with platform
conventions, and as described below.</p>
<p id="base-dnd-feedback">The drag-and-drop feedback must be generated from the first of the
following sources that is available:</p>
<ol>
<li>The <span>drag data store bitmap</span>, if any. In this case, the <span>drag data store
hot spot coordinate</span> should be used as hints for where to put the cursor relative to the
resulting image. The values are expressed as distances in <span data-x="'px'">CSS pixels</span>
from the left side and from the top side of the image respectively. <ref>CSS</ref></li>
<li>The <span>drag data store default feedback</span>.</li>
</ol>
</li>
</ol>
<p>From the moment that the user agent is to <dfn>initiate the drag-and-drop operation</dfn>,
until the end of the drag-and-drop operation, device input events (e.g. mouse and keyboard events)
must be suppressed.</p>
<p>During the drag operation, the element directly indicated by the user as the drop target is
called the <dfn>immediate user selection</dfn>. (Only elements can be selected by the user; other
nodes must not be made available as drop targets.) However, the <span>immediate user
selection</span> is not necessarily the <dfn>current target element</dfn>, which is the element
currently selected for the drop part of the drag-and-drop operation.</p>
<p>The <span>immediate user selection</span> changes as the user selects different elements
(either by pointing at them with a pointing device, or by selecting them in some other way). The
<span>current target element</span> changes when the <span>immediate user selection</span>
changes, based on the results of event listeners in the document, as described below.</p>
<p>Both the <span>current target element</span> and the <span>immediate user selection</span> can
be null, which means no target element is selected. They can also both be elements in other
(DOM-based) documents, or other (non-web) programs altogether. (For example, a user could drag
text to a word-processor.) The <span>current target element</span> is initially null.</p>
<p>In addition, there is also a <dfn>current drag operation</dfn>, which can take on the values
"<dfn><code data-x="concept-current-drag-operation-none">none</code></dfn>", "<dfn><code
data-x="concept-current-drag-operation-copy">copy</code></dfn>", "<dfn><code
data-x="concept-current-drag-operation-link">link</code></dfn>", and "<dfn><code
data-x="concept-current-drag-operation-move">move</code></dfn>". Initially, it has the value
"<code data-x="concept-current-drag-operation-none">none</code>". It is updated by the user agent
as described in the steps below.</p>
<p>User agents must, as soon as the drag operation is <span data-x="initiate the drag-and-drop
operation">initiated</span> and every 350ms (±200ms) thereafter for as long as the drag
operation is ongoing, <span>queue a task</span> to perform the following steps in sequence:</p>
<ol>
<li>
<p>If the user agent is still performing the previous iteration of the sequence (if any) when
the next iteration becomes due, return for this iteration (effectively "skipping
missed frames" of the drag-and-drop operation).</p>
</li>
<li>
<p><span>Fire a DND event</span> named <code data-x="event-dnd-drag">drag</code> at the
<span>source node</span>. If this event is canceled, the user agent must set the <span>current
drag operation</span> to "<code data-x="concept-current-drag-operation-none">none</code>" (no
drag operation).</p>
</li>
<li>
<p>If the <code data-x="event-dnd-drag">drag</code> event was not canceled and the user has not
ended the drag-and-drop operation, check the state of the drag-and-drop operation, as
follows:</p>
<ol>
<li>
<p>If the user is indicating a different <span>immediate user selection</span> than during the
last iteration (or if this is the first iteration), and if this <span>immediate user
selection</span> is not the same as the <span>current target element</span>, then update the
<span>current target element</span> as follows:</p>
<dl class="switch">
<dt>If the new <span>immediate user selection</span> is null</dt>
<dd><p>Set the <span>current target element</span> to null also.</p></dd>
<dt>If the new <span>immediate user selection</span> is in a non-DOM document or
application</dt>
<dd><p>Set the <span>current target element</span> to the <span>immediate user
selection</span>.</p></dd>
<dt>Otherwise</dt>
<dd>
<p><span>Fire a DND event</span> named <code data-x="event-dnd-dragenter">dragenter</code>
at the <span>immediate user selection</span>.</p>
<p>If the event is canceled, then set the <span>current target element</span> to the
<span>immediate user selection</span>.</p>
<p>Otherwise, run the appropriate step from the following list:</p>
<dl class="switch">
<dt>If the <span>immediate user selection</span> is a text control (e.g.,
<code>textarea</code>, or an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-text">Text</span> state) or an <span>editing host</span> or
<span>editable</span> element, and the <span>drag data store item list</span> has an item
with <span>the drag data item type string</span> "<code>text/plain</code>" and <span>the
drag data item kind</span> <i>text</i></dt>
<dd><p>Set the <span>current target element</span> to the <span>immediate user
selection</span> anyway.</p></dd>
<dt>If the <span>immediate user selection</span> is <span>the body element</span></dt>
<dd><p>Leave the <span>current target element</span> unchanged.</p></dd>
<dt>Otherwise</dt>
<dd>
<p><span>Fire a DND event</span> named <code data-x="event-dnd-dragenter">dragenter</code>
at <span>the body element</span>, if there is one, or at the <code>Document</code> object,
if not. Then, set the <span>current target element</span> to <span>the body
element</span>, regardless of whether that event was canceled or not.</p>
</dd>
</dl>
</dd>
</dl>
</li>
<li>
<p>If the previous step caused the <span>current target element</span> to change, and if the
previous target element was not null or a part of a non-DOM document, then <span>fire a DND
event</span> named <code data-x="event-dnd-dragleave">dragleave</code> at the previous target
element, with the new <span>current target element</span> as the specific <var>related
target</var>.</p>
</li>
<li>
<p>If the <span>current target element</span> is a DOM element, then <span>fire a DND
event</span> named <code data-x="event-dnd-dragover">dragover</code> at this <span>current
target element</span>.</p>
<p>If the <code data-x="event-dnd-dragover">dragover</code> event is not canceled, run the
appropriate step from the following list:</p>
<dl class="switch">
<dt>If the <span>current target element</span> is a text control (e.g.,
<code>textarea</code>, or an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-text">Text</span> state) or an <span>editing host</span> or
<span>editable</span> element, and the <span>drag data store item list</span> has an item
with <span>the drag data item type string</span> "<code>text/plain</code>" and <span>the drag
data item kind</span> <i>text</i></dt>
<dd><p>Set the <span>current drag operation</span> to either "<code
data-x="concept-current-drag-operation-copy">copy</code>" or "<code
data-x="concept-current-drag-operation-move">move</code>", as appropriate given the platform
conventions.</p></dd>
<dt>Otherwise</dt>
<dd><p>Reset the <span>current drag operation</span> to "<code
data-x="concept-current-drag-operation-none">none</code>".</p></dd>
</dl>
<p>Otherwise (if the <code data-x="event-dnd-dragover">dragover</code> event <em>is</em>
canceled), set the <span>current drag operation</span> based on the values of the <code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> and <code
data-x="dom-DataTransfer-dropEffect">dropEffect</code> attributes of the
<code>DragEvent</code> object's <code data-x="dom-DragEvent-dataTransfer">dataTransfer</code>
object as they stood after the event <span data-x="concept-event-dispatch">dispatch</span>
finished, as per the following table:</p>
<table>
<thead>
<tr>
<th><code data-x="dom-DataTransfer-effectAllowed">effectAllowed</code></th>
<th><code data-x="dom-DataTransfer-dropEffect">dropEffect</code></th>
<th>Drag operation</th>
</tr>
</thead>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>", "<code data-x="dom-DataTransfer-effectAllowed-copy">copy</code>", "<code data-x="dom-DataTransfer-effectAllowed-copyLink">copyLink</code>", "<code data-x="dom-DataTransfer-effectAllowed-copyMove">copyMove</code>", or "<code data-x="dom-DataTransfer-effectAllowed-all">all</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-copy">copy</code>"</td>
<td>"<code data-x="concept-current-drag-operation-copy">copy</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>", "<code data-x="dom-DataTransfer-effectAllowed-link">link</code>", "<code data-x="dom-DataTransfer-effectAllowed-copyLink">copyLink</code>", "<code data-x="dom-DataTransfer-effectAllowed-linkMove">linkMove</code>", or "<code data-x="dom-DataTransfer-effectAllowed-all">all</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-link">link</code>"</td>
<td>"<code data-x="concept-current-drag-operation-link">link</code>"</td>
</tr>
<tr>
<td>"<code data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>", "<code data-x="dom-DataTransfer-effectAllowed-move">move</code>", "<code data-x="dom-DataTransfer-effectAllowed-copyMove">copyMove</code>", "<code data-x="dom-DataTransfer-effectAllowed-linkMove">linkMove</code>", or "<code data-x="dom-DataTransfer-effectAllowed-all">all</code>"</td>
<td>"<code data-x="dom-DataTransfer-dropEffect-move">move</code>"</td>
<td>"<code data-x="concept-current-drag-operation-move">move</code>"</td>
</tr>
<tr>
<td colspan="2">Any other case</td>
<td>"<code data-x="concept-current-drag-operation-none">none</code>"</td>
</tr>
</table>
</li>
<li>
<p>Otherwise, if the <span>current target element</span> is not a DOM element, use
platform-specific mechanisms to determine what drag operation is being performed (none, copy,
link, or move), and set the <span>current drag operation</span> accordingly.</p>
</li>
<li>
<p>Update the drag feedback (e.g. the mouse cursor) to match the <span>current drag
operation</span>, as follows:</p>
<table>
<thead>
<tr>
<th>Drag operation</th>
<th>Feedback</th>
</tr>
</thead>
<tr>
<td>"<code data-x="concept-current-drag-operation-copy">copy</code>"</td>
<td>Data will be copied if dropped here.</td>
</tr>
<tr>
<td>"<code data-x="concept-current-drag-operation-link">link</code>"</td>
<td>Data will be linked if dropped here.</td>
</tr>
<tr>
<td>"<code data-x="concept-current-drag-operation-move">move</code>"</td>
<td>Data will be moved if dropped here.</td>
</tr>
<tr>
<td>"<code data-x="concept-current-drag-operation-none">none</code>"</td>
<td>No operation allowed, dropping here will cancel the drag-and-drop operation.</td>
</tr>
</table>
</li>
</ol>
</li>
<li>
<p>Otherwise, if the user ended the drag-and-drop operation (e.g. by releasing the mouse button
in a mouse-driven drag-and-drop interface), or if the <code data-x="event-dnd-drag">drag</code>
event was canceled, then this will be the last iteration. Run the following steps, then stop the
drag-and-drop operation:</p>
<ol>
<li>
<p>If the <span>current drag operation</span> is "<code
data-x="concept-current-drag-operation-none">none</code>" (no drag operation), or, if the user
ended the drag-and-drop operation by canceling it (e.g. by hitting the <kbd><kbd>Escape</kbd></kbd> key),
or if the <span>current target element</span> is null, then the drag operation failed. Run
these substeps:</p>
<ol>
<li><p>Let <var>dropped</var> be false.</p></li>
<li><p>If the <span>current target element</span> is a DOM element, <span>fire a DND
event</span> named <code data-x="event-dnd-dragleave">dragleave</code> at it; otherwise, if
it is not null, use platform-specific conventions for drag cancelation.</p></li>
<li><p>Set the <span>current drag operation</span> to "<code
data-x="concept-current-drag-operation-none">none</code>".</p></li>
</ol>
<p>Otherwise, the drag operation might be a success; run these substeps:</p>
<ol>
<li><p>Let <var>dropped</var> be true.</p></li>
<li><p>If the <span>current target element</span> is a DOM element, <span>fire a DND
event</span> named <code data-x="event-dnd-drop">drop</code> at it; otherwise, use
platform-specific conventions for indicating a drop.</p></li>
<li>
<p>If the event is canceled, set the <span>current drag operation</span> to the value of the
<code data-x="dom-DataTransfer-dropEffect">dropEffect</code> attribute of the
<code>DragEvent</code> object's <code data-x="dom-DragEvent-dataTransfer">dataTransfer</code>
object as it stood after the event <span data-x="concept-event-dispatch">dispatch</span>
finished.</p>
<p>Otherwise, the event is not canceled; perform the event's default action, which depends
on the exact target as follows:</p>
<dl class="switch">
<dt>If the <span>current target element</span> is a text control (e.g.,
<code>textarea</code>, or an <code>input</code> element whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-text">Text</span> state) or an <span>editing host</span> or
<span>editable</span> element, and the <span>drag data store item list</span> has an item
with <span>the drag data item type string</span> "<code>text/plain</code>" and <span>the
drag data item kind</span> <i>text</i></dt>
<dd><p>Insert the actual data of the first item in the <span>drag data store item
list</span> to have <span data-x="the drag data item type string">a drag data item type
string</span> of "<code>text/plain</code>" and <span data-x="the drag data item kind">a drag
data item kind</span> that is <i>text</i> into the text control or
<span>editing host</span> or <span>editable</span> element in a manner consistent with
platform-specific conventions (e.g. inserting it at the current mouse cursor position, or
inserting it at the end of the field).</p></dd>
<dt>Otherwise</dt>
<dd><p>Reset the <span>current drag operation</span> to "<code
data-x="concept-current-drag-operation-none">none</code>".</p></dd>
</dl>
</li>
</ol>
</li>
<li>
<p><span>Fire a DND event</span> named <code data-x="event-dnd-dragend">dragend</code> at the
<span>source node</span>.</p>
</li>
<li>
<p>Run the appropriate steps from the following list as the default action of the <code
data-x="event-dnd-dragend">dragend</code> event:</p>
<dl class="switch">
<dt>If <var>dropped</var> is true, the <span>current target element</span> is a <i>text
control</i> (see below), the <span>current drag operation</span> is "<code
data-x="concept-current-drag-operation-move">move</code>", and the source of the
drag-and-drop operation is a selection in the DOM that is entirely contained within an
<span>editing host</span></dt>
<dd><p><span>Delete the selection</span>.</p></dd>
<dt>If <var>dropped</var> is true, the <span>current target element</span> is a <i>text
control</i> (see below), the <span>current drag operation</span> is "<code
data-x="concept-current-drag-operation-move">move</code>", and the source of the
drag-and-drop operation is a selection in a text control</dt>
<dd><p>The user agent should delete the dragged selection from the relevant text
control.</p></dd>
<dt>If <var>dropped</var> is false or if the <span>current drag operation</span> is "<code
data-x="concept-current-drag-operation-none">none</code>"</dt>
<dd><p>The drag was canceled. If the platform conventions dictate that this be represented to
the user (e.g. by animating the dragged selection going back to the source of the
drag-and-drop operation), then do so.</p></dd>
<dt>Otherwise</dt>
<dd><p>The event has no default action.</p></dd>
</dl>
<p>For the purposes of this step, a <i>text control</i> is a <code>textarea</code> element or
an <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
one of the
<span data-x="attr-input-type-text">Text</span>,
<span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-tel">Tel</span>,
<span data-x="attr-input-type-url">URL</span>,
<span data-x="attr-input-type-email">Email</span>,
<span data-x="attr-input-type-password">Password</span>, or
<span data-x="attr-input-type-number">Number</span>
states.</p>
</li>
</ol>
</li>
</ol>
<p class="note">User agents are encouraged to consider how to react to drags near the edge of
scrollable regions. For example, if a user drags a link to the bottom of the <span>viewport</span>
on a long page, it might make sense to scroll the page so that the user can drop the link lower on
the page.</p>
<p class="note">This model is independent of which <code>Document</code> object the nodes involved
are from; the events are fired as described above and the rest of the processing model runs as
described above, irrespective of how many documents are involved in the operation.</p>
</div>
<h4 id="dndevents">Events summary</h4>
<!-- NON-NORMATIVE SECTION -->
<p>The following events are involved in the drag-and-drop
model.</p>
<table>
<thead>
<tr>
<th> Event name </th>
<th> Target </th>
<th> Cancelable? </th>
<th> <span>Drag data store mode</span> </th>
<th> <code data-x="dom-DataTransfer-dropEffect">dropEffect</code> </th>
<th> Default Action </th>
</tr>
</thead>
<tbody>
<tr>
<td><dfn event for="GlobalEventHandlers,Text"><code data-x="event-dnd-dragstart">dragstart</code></dfn></td>
<td><span>Source node</span></td>
<td>✓ Cancelable</td>
<td><span data-x="concept-dnd-rw">Read/write mode</span>
<td>"<code data-x="dom-DataTransfer-dropEffect-none">none</code>"</td>
<td>Initiate the drag-and-drop operation</td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers,Text"><code data-x="event-dnd-drag">drag</code></dfn></td>
<td><span>Source node</span></td>
<td>✓ Cancelable</td>
<td><span data-x="concept-dnd-p">Protected mode</span>
<td>"<code data-x="dom-DataTransfer-dropEffect-none">none</code>"</td>
<td>Continue the drag-and-drop operation</td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers"><code data-x="event-dnd-dragenter">dragenter</code></dfn></td>
<td><span>Immediate user selection</span> or <span>the body element</span></td>
<td>✓ Cancelable</td>
<td><span data-x="concept-dnd-p">Protected mode</span>
<td><!--en-GB--><a href="#dropEffect-initialisation">Based on <code>effectAllowed</code> value</a></td>
<td>Reject <span>immediate user selection</span> as potential <span data-x="current target element">target element</span></td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers"><code data-x="event-dnd-dragleave">dragleave</code></dfn></td>
<td><span data-x="current target element">Previous target element</span></td>
<td>—</td>
<td><span data-x="concept-dnd-p">Protected mode</span>
<td>"<code data-x="dom-DataTransfer-dropEffect-none">none</code>"</td>
<td>None</td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers"><code data-x="event-dnd-dragover">dragover</code></dfn></td>
<td><span>Current target element</span></td>
<td>✓ Cancelable</td>
<td><span data-x="concept-dnd-p">Protected mode</span>
<td><!--en-GB--><a href="#dropEffect-initialisation">Based on <code>effectAllowed</code> value</a></td>
<td>Reset the <span>current drag operation</span> to "none"</td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers"><code data-x="event-dnd-drop">drop</code></dfn></td>
<td><span>Current target element</span></td>
<td>✓ Cancelable</td>
<td><span data-x="concept-dnd-ro">Read-only mode</span>
<td><span>Current drag operation</span></td>
<td>Varies</td>
</tr>
<tr>
<td><dfn event for="GlobalEventHandlers,Text"><code data-x="event-dnd-dragend">dragend</code></dfn></td>
<td><span>Source node</span></td>
<td>—</td>
<td><span data-x="concept-dnd-p">Protected mode</span>
<!-- <td>Same as last event</td> -->
<td><span>Current drag operation</span></td>
<td>Varies</td>
</tr>
</tbody>
</table>
<p>All of these events bubble, are composed, and the <code
data-x="dom-DataTransfer-effectAllowed">effectAllowed</code> attribute always has the value it had
after the <code data-x="event-dnd-dragstart">dragstart</code> event, defaulting to "<code
data-x="dom-DataTransfer-effectAllowed-uninitialized">uninitialized</code>" in the <code
data-x="event-dnd-dragstart">dragstart</code> event.</p>
<h4>The <code data-x="attr-draggable">draggable</code> attribute</h4>
<p>All <span>HTML elements</span> may have the <dfn element-attr for="html-global"><code
data-x="attr-draggable">draggable</code></dfn> content attribute set. The <code
data-x="attr-draggable">draggable</code> attribute is an <span>enumerated attribute</span> with
the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/draggable"><code
data-x="attr-draggable-true">true</code></dfn>
<td><dfn data-x="attr-draggable-true-state">true</dfn>
<td>The element will be draggable.
<tr>
<td><dfn attr-value for="html-global/draggable"><code
data-x="attr-draggable-false">false</code></dfn>
<td><dfn data-x="attr-draggable-false-state">false</dfn>
<td>The element will not be draggable.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <dfn
data-x="attr-draggable-auto-state">auto</dfn> state. The auto state uses the default behavior of
the user agent.</p>
<p>An element with a <code data-x="attr-draggable">draggable</code> attribute should also have a
<code data-x="attr-title">title</code> attribute that names the element for the purpose of
non-visual interactions. <!-- "should", not "must", only because this is a relatively new
attribute and its design implications are not entirely obvious yet. For example, what happens if
you use an element with text as a drag source? Is that sufficiently clear for ATs? Indeed,
shouldn't the element generally be distinguishable anyway for it to be useful to drag? --></p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-draggable">draggable</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns true if the element is draggable; otherwise, returns false.</p>
<p>Can be set, to override the default and set the <code
data-x="attr-draggable">draggable</code> content attribute.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-draggable">draggable</code></dfn> IDL
attribute, whose value depends on the content attribute's in the way described below, controls
whether or not the element is draggable. Generally, only text selections are draggable, but
elements whose <code data-x="dom-draggable">draggable</code> IDL attribute is true become
draggable as well.</p>
<p>If an element's <code data-x="attr-draggable">draggable</code> content attribute has the state
<span data-x="attr-draggable-true-state">true</span>, the <code
data-x="dom-draggable">draggable</code> IDL attribute must return true.</p>
<p>Otherwise, if the element's <code data-x="attr-draggable">draggable</code> content attribute
has the state <span data-x="attr-draggable-false-state">false</span>, the <code
data-x="dom-draggable">draggable</code> IDL attribute must return false.</p>
<p>Otherwise, the element's <code data-x="attr-draggable">draggable</code> content attribute has
the state <span data-x="attr-draggable-auto-state">auto</span>. If the element is an
<code>img</code> element, an <code>object</code> element that <span>represents</span> an image, or
an <code>a</code> element with an <code data-x="attr-hyperlink-href">href</code> content
attribute, the <code data-x="dom-draggable">draggable</code> IDL attribute must return true;
otherwise, the <code data-x="dom-draggable">draggable</code> IDL attribute must return false.</p>
<p>If the <code data-x="dom-draggable">draggable</code> IDL attribute is set to the value false,
the <code data-x="attr-draggable">draggable</code> content attribute must be set to the literal
value "<code data-x="">false</code>". If the <code data-x="dom-draggable">draggable</code> IDL
attribute is set to the value true, the <code data-x="attr-draggable">draggable</code> content
attribute must be set to the literal value "<code data-x="">true</code>".</p>
</div>
<div w-nodev>
<h4>Security risks in the drag-and-drop model</h4>
<p>User agents must not make the data added to the <code>DataTransfer</code> object during the
<code data-x="event-dnd-dragstart">dragstart</code> event available to scripts until the <code
data-x="event-dnd-drop">drop</code> event, because otherwise, if a user were to drag sensitive
information from one document to a second document, crossing a hostile third document in the
process, the hostile document could intercept the data.</p>
<p>For the same reason, user agents must consider a drop to be successful only if the user
specifically ended the drag operation — if any scripts end the drag operation, it must be
considered unsuccessful (canceled) and the <code data-x="event-dnd-drop">drop</code> event must not be
fired.</p>
<p>User agents should take care to not start drag-and-drop operations in response to script
actions. For example, in a mouse-and-window environment, if a script moves a window while the user
has their mouse button depressed, the UA would not consider that to start a drag. This is important
because otherwise UAs could cause data to be dragged from sensitive sources and dropped into
hostile documents without the user's consent.</p>
<p>User agents should filter potentially active (scripted) content (e.g. HTML) when it is dragged
and when it is dropped, using a safelist of known-safe features. Similarly, <span data-x="relative
URL">relative URLs</span> should be turned into absolute URLs to avoid references changing in
unexpected ways. This specification does not specify how this is performed.</p>
<div class="example">
<p>Consider a hostile page providing some content and getting the user to select and drag and
drop (or indeed, copy and paste) that content to a victim page's <code
data-x="attr-contenteditable">contenteditable</code> region. If the browser does not ensure that
only safe content is dragged, potentially unsafe content such as scripts and event handlers in
the selection, once dropped (or pasted) into the victim site, get the privileges of the victim
site. This would thus enable a cross-site scripting attack.</p>
</div>
</div>
<h3 split-filename="popover">The <code data-x="attr-popover">popover</code> attribute</h3>
<p>All <span>HTML elements</span> may have the <dfn element-attr for="html-global"><code
data-x="attr-popover">popover</code></dfn> content attribute set. When specified, the element
won't be rendered until it becomes shown, at which point it will be rendered on top of other page
content.</p>
<div class="example">
<p>The <code data-x="attr-popover">popover</code> attribute is a global attribute that allows
authors flexibility to ensure popover functionality can be applied to elements with the most
relevant semantics.</p>
<p>The following demonstrates how one might create a popover sub-navigation list of
links, within the global navigation for a website.</p>
<pre><code class="html"><ul>
<li>
<a href=...>All Products</a>
<button popovertarget=sub-nav>
<img src=down-arrow.png alt="Product pages">
</button>
<ul popover id=sub-nav>
<li><a href=...>Shirts</a>
<li><a href=...>Shoes</a>
<li><a href=...>Hats etc.</a>
</ul>
</li>
<!-- other list items and links here -->
</ul></code></pre>
</div>
<p>When using <code data-x="attr-popover">popover</code> on elements without accessibility
semantics, for instance the <code>div</code> element, authors should use the appropriate ARIA
attributes to ensure the popover is accessible.</p>
<div class="example">
<p>The following shows the baseline markup to create a custom menu popover, where the first
menuitem will receive keyboard focus when the popover is invoked due to the use of the
<code data-x="">autofocus</code> attribute. Navigating the menuitems with arrow keys and
activation behaviors would still need author scripting. Additional requirements for building
custom menus widgets are defined in the <a href="https://w3c.github.io/aria/#menu">WAI-ARIA
specification</a>.</p>
<pre><code class="html"><button popovertarget=m>Actions</button>
<div role=menu id=m popover>
<button role=menuitem tabindex=-1 autofocus>Edit</button>
<button role=menuitem tabindex=-1>Hide</button>
<button role=menuitem tabindex=-1>Delete</button>
</div></code></pre>
<p>A popover can be useful for rendering a status message, confirming the action performed by
the user. The following demonstrates how one could reveal a popover in an <code>output</code>
element.</p>
<pre><code class="html"><button id=submit>Submit</button>
<p><output><span popover=manual></span></output></p>
<script>
const sBtn = document.getElementById("submit");
const outSpan = document.querySelector("output [popover=manual]");
let successMessage;
let errorMessage;
/* define logic for determining success of action
and determining the appropriate success or error
messages to use */
sBtn.addEventListener("click", ()=> {
if ( success ) {
outSpan.textContent = successMessage;
}
else {
outSpan.textContent = errorMessage;
}
outSpan.showPopover();
setTimeout(function () {
outSpan.hidePopover();
}, 10000);
});
</script></code></pre>
</div>
<p class="note">Inserting a popover element into an <code>output</code> element will generally
cause screen readers to announce the content when it becomes visible. Depending on the complexity
or frequency of the content, this could be either useful or annoying to users of these
assistive technologies. Keep this in mind when using the <code>output</code> element or other
ARIA live regions to ensure the best user experience.</p>
<p>The <code data-x="attr-popover">popover</code> attribute is an <span>enumerated
attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/popover"><code
data-x="attr-popover-auto">auto</code></dfn>
<td rowspan=2><dfn data-x="attr-popover-auto-state">auto</dfn>
<td rowspan=2>Closes other popovers when opened; has <span data-x="popover light dismiss">light
dismiss</span> and responds to <span data-x="close request">close requests</span>.
<tr>
<td>(the empty string)
<tr>
<td><dfn attr-value for="html-global/popover"><code
data-x="attr-popover-manual">manual</code></dfn>
<td><dfn data-x="attr-popover-manual-state">manual</dfn>
<td>Does not close other popovers; does not <span data-x="popover light dismiss">light
dismiss</span> or respond to <span data-x="close request">close requests</span>.
</tr>
<tr>
<td><dfn attr-value for="html-global/popover"><code
data-x="attr-popover-hint">hint</code></dfn></td>
<td><dfn data-x="attr-popover-hint-state">hint</dfn></td>
<td>Closes other hint popovers when opened, but not other auto popovers; has <span
data-x="popover light dismiss">light dismiss</span> and responds to <span data-x="close
request">close requests</span>.</td>
</tr>
</tbody>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> is the <dfn
data-x="attr-popover-none-state">no popover</dfn> state, and its <i data-x="invalid value
default">invalid value default</i> is the <span data-x="attr-popover-manual-state">manual</span>
state.</p>
<p>The <dfn attribute for="HTMLElement"><code data-x="dom-popover">popover</code></dfn> IDL
attribute must <span>reflect</span> the <span data-x="attr-popover">popover</span> attribute,
<span>limited to only known values</span>.</p>
<p>Every <span data-x="HTML elements">HTML element</span> has a <dfn export>popover visibility
state</dfn>, initially <span data-x="popover-hidden-state">hidden</span>, with these potential
values:</p>
<ul>
<li><p><dfn export for="popover visibility state"
data-x="popover-hidden-state">hidden</dfn></p></li>
<li><p><dfn export for="popover visibility state"
data-x="popover-showing-state">showing</dfn></p></li>
</ul>
<p>Every <code>Document</code> has a <dfn>popover pointerdown target</dfn>, which is an <span
data-x="HTML elements">HTML element</span> or null, initially null.</p>
<p>Every <span data-x="HTML elements">HTML element</span> has a <dfn>popover invoker</dfn>, which
is an <span data-x="HTML elements">HTML element</span> or null, initially set to null.</p>
<p>Every <span data-x="HTML elements">HTML element</span> has a <dfn>popover showing or
hiding</dfn>, which is a boolean, initially set to false.</p>
<p>Every <span data-x="HTML elements">HTML element</span> <dfn>popover toggle task tracker</dfn>,
which is a <span>toggle task tracker</span> or null, initially null.</p>
<p>Every <span data-x="HTML elements">HTML element</span> has a <dfn>popover close watcher</dfn>,
which is a <span>close watcher</span> or null, initially null.</p>
<p>Every <span data-x="HTML elements">HTML element</span> has an <dfn>opened in popover
mode</dfn>, which is a string or null, initially null.</p>
<p>The following <span data-x="concept-element-attributes-change-ext">attribute change
steps</span>, given <var>element</var>, <var>localName</var>, <var>oldValue</var>,
<var>value</var>, and <var>namespace</var>, are used for all <span>HTML elements</span>:</p>
<ol>
<li><p>If <var>namespace</var> is not null, then return.</p></li>
<li><p>If <var>localName</var> is not <code data-x="attr-popover">popover</code>, then
return.</p></li>
<li><p>If <var>element</var>'s <span>popover visibility state</span> is in the <span
data-x="popover-showing-state">showing state</span> and <var>oldValue</var> and <var>value</var>
are in different <span data-x="attr-popover">states</span>, then run the <span>hide popover
algorithm</span> given <var>element</var>, true, true, and false.</p></li>
</ol>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn
data-x="dom-showPopover">showPopover</span>()</code></dt>
<dd>Shows the popover <var>element</var> by adding it to the top layer. If <var>element</var>'s
<code data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state, then this will also close all other <span
data-x="attr-popover-auto-state">auto</span> popovers unless they are an ancestor of
<var>element</var> according to the <span>topmost popover ancestor</span> algorithm.</dd>
<dt><code data-x=""><var>element</var>.<span subdfn
data-x="dom-hidePopover">hidePopover</span>()</code></dt>
<dd>Hides the popover <var>element</var> by removing it from the top layer and applying
<code data-x="">display: none</code> to it.</dd>
<dt><code data-x=""><var>element</var>.<span subdfn
data-x="dom-togglePopover">togglePopover</span>()</code></dt>
<dd>If the popover <var>element</var> is not showing, then this method shows it. Otherwise, this
method hides it. This method returns true if the popover is open after calling it, otherwise
false.</dd>
</dl>
<p>The <dfn method for="HTMLElement"><code
data-x="dom-showPopover">showPopover(<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>invoker</var> be <var>options</var>["<code
data-x="dom-ShowPopoverOptions-source">source</code>"] if it <span data-x="map
exists">exists</span>; otherwise, null.</p></li>
<li><p>Run <span>show popover</span> given <span>this</span>, true, and
<var>invoker</var>.</p></li>
</ol>
<p>To <dfn>show popover</dfn>, given an <span data-x="HTML elements">HTML element</span>
<var>element</var>, a boolean <var>throwExceptions</var>, and an <span data-x="HTML elements">HTML
element</span> or null <var>invoker</var>:</p>
<ol>
<li><p>If the result of running <span>check popover validity</span> given <var>element</var>,
false, <var>throwExceptions</var>, and null is false, then return.</p></li>
<li><p>Let <var>document</var> be <var>element</var>'s <span>node document</span>.</p></li>
<li><p><span>Assert</span>: <var>element</var>'s <span>popover invoker</span> is null.</p></li>
<li><p><span>Assert</span>: <var>element</var> is not in <var>document</var>'s <span>top
layer</span>.</p></li>
<li><p>Let <var>nestedShow</var> be <var>element</var>'s <span>popover showing or
hiding</span>.</p></li>
<li><p>Let <var>fireEvents</var> be the boolean negation of <var>nestedShow</var>.</p></li>
<li><p>Set <var>element</var>'s <span>popover showing or hiding</span> to true.</p></li>
<li>
<p>Let <var>cleanupShowingFlag</var> be the following steps:</p>
<ol>
<li><p>If <var>nestedShow</var> is false, then set <var>element</var>'s <span>popover showing
or hiding</span> to false.</p></li>
</ol>
</li>
<li><p>If the result of <span data-x="concept-event-fire">firing an event</span> named <code
data-x="event-beforetoggle">beforetoggle</code>, using <code>ToggleEvent</code>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true, the <code
data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to "<code
data-x="">closed</code>", and the <code data-x="dom-ToggleEvent-newState">newState</code>
attribute initialized to "<code data-x="">open</code>" at <var>element</var> is false, then
run <var>cleanupShowingFlag</var> and return.</p></li>
<li>
<p>If the result of running <span>check popover validity</span> given <var>element</var>, false,
<var>throwExceptions</var>, and <var>document</var> is false, then run
<var>cleanupShowingFlag</var> and return.</p>
<p class="note"><span>Check popover validity</span> is called again because firing the <code
data-x="event-beforetoggle">beforetoggle</code> event could have disconnected this element or
changed its <code data-x="attr-popover">popover</code> attribute.</p>
</li>
<li><p>Let <var>shouldRestoreFocus</var> be false.</p></li>
<li><p>Let <var>originalType</var> be the current state of <var>element</var>'s <code
data-x="attr-popover">popover</code> attribute.</p></li>
<li><p>Let <var>stackToAppendTo</var> be null.</p></li>
<li><p>Let <var>autoAncestor</var> be the result of running the <span>topmost popover
ancestor</span> algorithm given <var>element</var>, <var>document</var>'s <span>showing auto
popover list</span>, <var>invoker</var>, and true.</p></li>
<li><p>Let <var>hintAncestor</var> be the result of running the <span>topmost popover
ancestor</span> algorithm given <var>element</var>, <var>document</var>'s <span>showing hint
popover list</span>, <var>invoker</var>, and true.</p></li>
<li>
<p>If <var>originalType</var> is the <span data-x="attr-popover-auto-state">auto</span> state,
then:</p>
<ol>
<li><p>Run <span>close entire popover list</span> given <var>document</var>'s <span>showing
hint popover list</span>, <var>shouldRestoreFocus</var>, and <var>fireEvents</var>.</p></li>
<li><p>Let <var>ancestor</var> be the result of running the <span>topmost popover
ancestor</span> algorithm given <var>element</var>, <var>document</var>'s <span>showing auto
popover list</span>, <var>invoker</var>, and true.</p></li>
<li><p>If <var>ancestor</var> is null, then set <var>ancestor</var> to
<var>document</var>.</p></li>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>ancestor</var>, <var>shouldRestoreFocus</var>, and <var>fireEvents</var>.</p></li>
<li><p>Set <var>stackToAppendTo</var> to "<code data-x="">auto</code>".</p></li>
</ol>
</li>
<li>
<p>If <var>originalType</var> is the <span data-x="attr-popover-hint-state">hint</span> state,
then:</p>
<ol>
<li>
<p>If <var>hintAncestor</var> is not null, then:</p>
<ol>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>hintAncestor</var>, <var>shouldRestoreFocus</var>, and <var>fireEvents</var>.</p></li>
<li><p>Set <var>stackToAppendTo</var> to "<code data-x="">hint</code>".</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Run <span>close entire popover list</span> given <var>document</var>'s <span>showing
hint popover list</span>, <var>shouldRestoreFocus</var>, and <var>fireEvents</var>.</p></li>
<li>
<p>If <var>autoAncestor</var> is not null, then:</p>
<ol>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>autoAncestor</var>, <var>shouldRestoreFocus</var>, and <var>fireEvents</var>.</p></li>
<li><p>Set <var>stackToAppendTo</var> to "<code data-x="">auto</code>".</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>stackToAppendTo</var> to "<code data-x="">hint</code>".</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>If <var>originalType</var> is <span data-x="attr-popover-auto-state">auto</span> or <span
data-x="attr-popover-hint-state">hint</span>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>stackToAppendTo</var> is not null.</p></li>
<li>
<p>If <var>originalType</var> is not equal to the value of <var>element</var>'s <code
data-x="attr-popover">popover</code> attribute, then:</p>
<ol>
<li><p>If <var>throwExceptions</var> is true, then throw a
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p>If the result of running <span>check popover validity</span> given <var>element</var>,
false, <var>throwExceptions</var>, and <var>document</var> is false, then run
<var>cleanupShowingFlag</var> and return.</p>
<p class="note"><span>Check popover validity</span> is called again because running <span
data-x="hide-all-popovers-until">hide all popovers until</span> above could have fired the
<code data-x="event-beforetoggle">beforetoggle</code> event, and an event handler could have
disconnected this element or changed its <code data-x="attr-popover">popover</code>
attribute.</p>
</li>
<li>
<p>If the result of running <span data-x="topmost auto popover">topmost auto or hint
popover</span> on <var>document</var> is null, then set <var>shouldRestoreFocus</var> to
true.</p>
<p class="note">This ensures that focus is returned to the previously-focused element only for
the first popover in a stack.</p>
</li>
<li>
<p>If <var>stackToAppendTo</var> is "<code data-x="">auto</code>":</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span>showing auto popover list</span> does
not contain <var>element</var>.</p></li>
<li><p>Set <var>element</var>'s <span>opened in popover mode</span> to "<code
data-x="">auto</code>".</p></li>
</ol>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>stackToAppendTo</var> is "<code
data-x="">hint</code>".</p></li>
<li><p><span>Assert</span>: <var>document</var>'s <span>showing hint popover list</span> does
not contain <var>element</var>.</p></li>
<li><p>Set <var>element</var>'s <span>opened in popover mode</span> to "<code
data-x="">hint</code>".</p></li>
</ol>
</li>
<li id="canceling-popovers">
<p>Set <var>element</var>'s <span>popover close watcher</span> to the result of <span
data-x="establish a close watcher">establishing a close watcher</span> given
<var>element</var>'s <span>relevant global object</span>, with:</p>
<ul>
<li><p><i data-x="create-close-watcher-cancelAction">cancelAction</i> being to return
true.</p></li>
<li><p><i data-x="create-close-watcher-closeAction">closeAction</i> being to <span
data-x="hide popover algorithm">hide a popover</span> given <var>element</var>, true, true,
and false.</p></li>
<li><p><i data-x="create-close-watcher-getEnabledState">getEnabledState</i> being to return
true.</p></li>
</ul>
</li>
</ol>
</li>
<li><p>Set <var>element</var>'s <span>previously focused element</span> to null.</p></li>
<li><p>Let <var>originallyFocusedElement</var> be <var>document</var>'s <span>focused area of the
document</span>'s <span>DOM anchor</span>.</p></li>
<li><p><span>Add an element to the top layer</span> given <var>element</var>.</p></li>
<li><p>Set <var>element</var>'s <span>popover visibility state</span> to <span
data-x="popover-showing-state">showing</span>.</p></li>
<li><p>Set <var>element</var>'s <span>popover invoker</span> to <var>invoker</var>.</p></li>
<li><p>Set <var>element</var>'s <span>implicit anchor element</span> to
<var>invoker</var>.</p></li>
<li><p>Run the <span>popover focusing steps</span> given <var>element</var>.</p></li>
<li><p>If <var>shouldRestoreFocus</var> is true and <var>element</var>'s <code
data-x="attr-popover">popover</code> attribute is not in the <span
data-x="attr-popover-none-state">no popover</span> state, then set <var>element</var>'s
<span>previously focused element</span> to <var>originallyFocusedElement</var>.</p></li>
<li><p><span>Queue a popover toggle event task</span> given <var>element</var>, "<code
data-x="">closed</code>", and "<code data-x="">open</code>".</p></li>
<li><p>Run <var>cleanupShowingFlag</var>.</p></li>
</ol>
<p>To <dfn>queue a popover toggle event task</dfn> given an element <var>element</var>, a string
<var>oldState</var>, and a string <var>newState</var>:
<ol>
<li>
<p>If <var>element</var>'s <span>popover toggle task tracker</span> is not null, then:</p>
<ol>
<li><p>Set <var>oldState</var> to <var>element</var>'s <span>popover toggle task
tracker</span>'s <span data-x="toggle-task-old-state">old state</span>.</p></li>
<li><p>Remove <var>element</var>'s <span>popover toggle task tracker</span>'s <span
data-x="toggle-task-task">task</span> from its <span>task queue</span>.</p></li>
<li><p>Set <var>element</var>'s <span>popover toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li>
<p><span>Queue an element task</span> given the <span>DOM manipulation task source</span> and
<var>element</var> to run the following steps:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-toggle">toggle</code> at <var>element</var>, using <code>ToggleEvent</code>, with
the <code data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to
<var>oldState</var> and the <code data-x="dom-ToggleEvent-newState">newState</code> attribute
initialized to <var>newState</var>.</p></li>
<li><p>Set <var>element</var>'s <span>popover toggle task tracker</span> to null.</p></li>
</ol>
</li>
<li><p>Set <var>element</var>'s <span>popover toggle task tracker</span> to a struct with <span
data-x="toggle-task-task">task</span> set to the just-queued <span
data-x="concept-task">task</span> and <span data-x="toggle-task-old-state">old state</span> set
to <var>oldState</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLElement"><code data-x="dom-hidePopover">hidePopover()</code></dfn>
method steps are:</p>
<ol>
<li><p>Run the <span>hide popover algorithm</span> given <span>this</span>, true, true, and
true.</p></li>
</ol>
<p>To <dfn data-x="hide popover algorithm">hide a popover</dfn> given an <span data-x="HTML
elements">HTML element</span> <var>element</var>, a boolean <var>focusPreviousElement</var>, a
boolean <var>fireEvents</var>, and a boolean <var>throwExceptions</var>:</p>
<ol>
<li><p>If the result of running <span>check popover validity</span> given <var>element</var>,
true, <var>throwExceptions</var>, and null is false, then return.</p></li>
<li><p>Let <var>document</var> be <var>element</var>'s <span>node document</span>.</p></li>
<li><p>Let <var>nestedHide</var> be <var>element</var>'s <span>popover showing or
hiding</span>.</p></li>
<li><p>Set <var>element</var>'s <span>popover showing or hiding</span> to true.</p></li>
<li><p>If <var>nestedHide</var> is true, then set <var>fireEvents</var> to false.</p></li>
<li>
<p>Let <var>cleanupSteps</var> be the following steps:</p>
<ol>
<li><p>If <var>nestedHide</var> is false, then set <var>element</var>'s <span>popover showing
or hiding</span> to false.</p></li>
<li>
<p>If <var>element</var>'s <span>popover close watcher</span> is not null, then:</p>
<ol>
<li><p><span data-x="close-watcher-destroy">Destroy</span> <var>element</var>'s <span>popover
close watcher</span>.</p></li>
<li><p>Set <var>element</var>'s <span>popover close watcher</span> to null.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>If <var>element</var>'s <code data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state or the <span
data-x="attr-popover-hint-state">hint</span> state, then:</p>
<ol>
<li><p>Run <span data-x="hide-all-popovers-until">hide all popovers until</span> given
<var>element</var>, <var>focusPreviousElement</var>, and <var>fireEvents</var>.</p></li>
<li>
<p>If the result of running <span>check popover validity</span> given <var>element</var>,
true, and <var>throwExceptions</var> is false, then run <var>cleanupSteps</var> and
return.</p>
<p class="note"><span>Check popover validity</span> is called again because running <span
data-x="hide-all-popovers-until">hide all popovers until</span> could have disconnected
<var>element</var> or changed its <code data-x="attr-popover">popover</code> attribute.</p>
</li>
</ol>
</li>
<li><p>Let <var>autoPopoverListContainsElement</var> be true if <var>document</var>'s
<span>showing auto popover list</span>'s last item is <var>element</var>, otherwise
false.</p></li>
<li><p>Set <var>element</var>'s <span>popover invoker</span> to null.</p></li>
<li>
<p>If <var>fireEvents</var> is true:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-beforetoggle">beforetoggle</code>, using <code>ToggleEvent</code>, with the <code
data-x="dom-ToggleEvent-oldState">oldState</code> attribute initialized to "<code
data-x="">open</code>" and the <code data-x="dom-ToggleEvent-newState">newState</code>
attribute initialized to "<code data-x="">closed</code>" at <var>element</var>.</p></li>
<li><p>If <var>autoPopoverListContainsElement</var> is true and <var>document</var>'s
<span>showing auto popover list</span>'s last item is not <var>element</var>, then run <span
data-x="hide-all-popovers-until">hide all popovers until</span> given <var>element</var>,
<var>focusPreviousElement</var>, and false.</p></li>
<li>
<p>If the result of running <span>check popover validity</span> given <var>element</var>,
true, <var>throwExceptions</var>, and null is false, then run <var>cleanupSteps</var> and
return.</p>
<p class="note"><span>Check popover validity</span> is called again because firing the <code
data-x="event-beforetoggle">beforetoggle</code> event could have disconnected
<var>element</var> or changed its <code data-x="attr-popover">popover</code> attribute.</p>
</li>
<li><p><span>Request an element to be removed from the top layer</span> given
<var>element</var>.</p></li>
<li><p>Set <var>element</var>'s <span>implicit anchor element</span> to null.</p></li>
</ol>
</li>
<li><p>Otherwise, <span>remove an element from the top layer immediately</span> given
<var>element</var>.</p></li>
<li><p>Set <var>element</var>'s <span>opened in popover mode</span> to null.</p></li>
<li><p>Set <var>element</var>'s <span>popover visibility state</span> to <span
data-x="popover-hidden-state">hidden</span>.</p></li>
<li><p>If <var>fireEvents</var> is true, then <span>queue a popover toggle event task</span>
given <var>element</var>, "<code data-x="">open</code>", and "<code
data-x="">closed</code>".</p></li>
<li><p>Let <var>previouslyFocusedElement</var> be <var>element</var>'s <span>previously focused
element</span>.</p></li>
<li>
<p>If <var>previouslyFocusedElement</var> is not null, then:</p>
<ol>
<li><p>Set <var>element</var>'s <span>previously focused element</span> to null.</p></li>
<li><p>If <var>focusPreviousElement</var> is true and <var>document</var>'s <span>focused area
of the document</span>'s <span>DOM anchor</span> is a <span>shadow-including inclusive
descendant</span> of <var>element</var>, then run the <span>focusing steps</span> for
<var>previouslyFocusedElement</var>; the viewport should not be scrolled by doing this
step.</p></li>
</ol>
</li>
<li><p>Run <var>cleanupSteps</var>.</p></li>
</ol>
<p>The <dfn method for="HTMLElement"><code
data-x="dom-togglePopover">togglePopover(<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>force</var> be null.</p></li>
<li><p>If <var>options</var> is a boolean, set <var>force</var> to <var>options</var>.</p></li>
<li><p>Otherwise, if <var>options</var>["<code
data-x="dom-TogglePopoverOptions-force">force</code>"] <span data-x="map exists">exists</span>,
set <var>force</var> to <var>options</var>["<code
data-x="dom-TogglePopoverOptions-force">force</code>"].</p></li>
<li><p>Let <var>invoker</var> be <var>options</var>["<code
data-x="dom-ShowPopoverOptions-source">source</code>"] if it <span data-x="map
exists">exists</span>; otherwise, null.</p></li>
<li><p>If <span>this</span>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>, and <var>force</var> is null or false, then run
the <span>hide popover algorithm</span> given <span>this</span>, true, true, and true.</p></li>
<li><p>Otherwise, if <var>force</var> is null or true, then run <span>show popover</span> given
<span>this</span>, true, and <var>invoker</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>expectedToBeShowing</var> be true if <span>this</span>'s <span>popover
visibility state</span> is <span data-x="popover-showing-state">showing</span>; otherwise
false.</p></li>
<li><p>Run <span>check popover validity</span> given <var>expectedToBeShowing</var>, true, and
null.</p></li>
</ol>
</li>
<li><p>Return true if <span>this</span>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>; otherwise false.</p></li>
</ol>
<p>To <dfn export data-x="hide-all-popovers-until">hide all popovers until</dfn>, given an <span
data-x="HTML elements">HTML element</span> or <code>Document</code> <var>endpoint</var>, a boolean
<var>focusPreviousElement</var>, and a boolean <var>fireEvents</var>:</p>
<ol>
<li><p>If <var>endpoint</var> is an <span data-x="HTML elements">HTML element</span> and
<var>endpoint</var> is not in the <span data-x="popover-showing-state">popover showing
state</span>, then return.</p></li>
<li><p>Let <var>document</var> be <var>endpoint</var>'s <span>node document</span>.</p></li>
<li><p><span>Assert</span>: <var>endpoint</var> is a <code>Document</code> or
<var>endpoint</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>.</p></li>
<li><p><span>Assert</span>: <var>endpoint</var> is a <code>Document</code> or
<var>endpoint</var>'s <code data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state or <var>endpoint</var>'s <code
data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-hint-state">hint</span> state.</p></li>
<li>
<p>If <var>endpoint</var> is a <code>Document</code>:</p>
<ol>
<li><p>Run <span>close entire popover list</span> given <var>document</var>'s <span>showing
hint popover list</span>, <var>focusPreviousElement</var>, and <var>fireEvents</var>.</p></li>
<li><p>Run <span>close entire popover list</span> given <var>document</var>'s <span>showing
auto popover list</span>, <var>focusPreviousElement</var>, and <var>fireEvents</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p>If <var>document</var>'s <span>showing hint popover list</span> contains
<var>endpoint</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>endpoint</var>'s <code data-x="attr-popover">popover</code>
attribute is in the <span data-x="attr-popover-hint-state">hint</span> state.</p></li>
<li><p>Run <span>hide popover stack until</span> given <var>endpoint</var>,
<var>document</var>'s <span>showing hint popover list</span>, <var>focusPreviousElement</var>,
and <var>fireEvents</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Run <span>close entire popover list</span> given <var>document</var>'s <span>showing hint
popover list</span>, <var>focusPreviousElement</var>, and <var>fireEvents</var>.</p></li>
<li><p>If <var>document</var>'s <span>showing auto popover list</span> does not contain
<var>endpoint</var>, then return.</p></li>
<li><p>Run <span>hide popover stack until</span> given <var>endpoint</var>, <var>document</var>'s
<span>showing auto popover list</span>, <var>focusPreviousElement</var>, and
<var>fireEvents</var>.</p></li>
</ol>
<p>To <dfn>hide popover stack until</dfn>, given an <span data-x="html elements">HTML
element</span> <var>endpoint</var>, a <span>list</span> <var>popoverList</var>, a boolean
<var>focusPreviousElement</var>, and a boolean <var>fireEvents</var>:</p>
<ol>
<li><p>Let <var>repeatingHide</var> be false.</p></li>
<li>
<p>Perform the following steps at least once:</p>
<ol>
<li><p>Let <var>lastToHide</var> be null.</p></li>
<li>
<p>For each <var>popover</var> in <var>popoverList</var>:</p>
<ol>
<li><p>If <var>popover</var> is <var>endpoint</var>, then <span>break</span>.</p></li>
<li><p>Set <var>lastToHide</var> to <var>popover</var>.</p></li>
</ol>
</li>
<li><p>If <var>lastToHide</var> is null, then return.</p></li>
<li>
<p><span>While</span> <var>lastToHide</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>:</p>
<ol>
<li><p><span>Assert</span>: <var>popoverList</var> is not empty.</p></li>
<li><p>Run the <span>hide popover algorithm</span> given the last item in
<var>popoverList</var>, <var>focusPreviousElement</var>, <var>fireEvents</var>, and
false.</p></li>
</ol>
</li>
<li><p><span>Assert</span>: <var>repeatingHide</var> is false or <var>popoverList</var>'s last
item is <var>endpoint</var>.</p></li>
<li><p>Set <var>repeatingHide</var> to true if <var>popoverList</var> contains
<var>endpoint</var> and <var>popoverList</var>'s last item is not <var>endpoint</var>,
otherwise false.</p></li>
<li><p>If <var>repeatingHide</var> is true, then set <var>fireEvents</var> to false.</p></li>
</ol>
<p>and keep performing them <span>while</span> <var>repeatingHide</var> is true.</p>
</li>
</ol>
<p class="note">The <span data-x="hide-all-popovers-until">hide all popovers until
algorithm</span> is used in several cases to hide all popovers that don't stay open when something
happens. For example, during light-dismiss of a popover, this algorithm ensures that we close only
the popovers that aren't related to the node clicked by the user.</p>
<p>To find the <dfn export>topmost popover ancestor</dfn>, given a <code>Node</code>
<var>newPopoverOrTopLayerElement</var>, a <span>list</span> <var>popoverList</var>, an <span
data-x="HTML elements">HTML element</span> or null <var>invoker</var>, and a boolean
<var>isPopover</var>, perform the following steps. They return an <span data-x="HTML
elements">HTML element</span> or null.</p>
<div class="note">
<p>The <span>topmost popover ancestor</span> algorithm will return the topmost (latest in the
<span>showing auto popover list</span>) ancestor popover for the provided popover or top layer
element. Popovers can be related to each other in several ways, creating a tree of popovers.
There are two paths through which one popover (call it the "child" popover) can have a topmost
ancestor popover (call it the "parent" popover):</p>
<ol>
<li><p>The popovers are nested within each other in the node tree. In this case, the descendant
popover is the "child" and its topmost ancestor popover is the "parent".</p></li>
<li><p>An invoking element (e.g., a <code>button</code>) has a <code
data-x="attr-popovertarget">popovertarget</code> attribute pointing to a popover. In this case,
the popover is the "child", and the popover subtree the invoking element is in is the
"parent". The invoker has to be in a popover and reference an open popover.</p></li>
</ol>
<p>In each of the relationships formed above, the parent popover has to be strictly earlier in
the <span>showing auto popover list</span> than the child popover, or it does not form a valid
ancestral relationship. This eliminates non-showing popovers and self-pointers (e.g., a popover
containing an invoking element that points back to the containing popover), and it allows for the
construction of a well-formed tree from the (possibly cyclic) graph of connections. Only <span
data-x="attr-popover-auto-state">auto</span> popovers are considered.</p>
<p>If the provided element is a top layer element such as a <code>dialog</code> which is not
showing as a popover, then <span>topmost popover ancestor</span> will only look in the node tree
to find the first popover.</p>
</div>
<ol>
<li>
<p>If <var>isPopover</var> is true:</p>
<ol>
<li><p><span>Assert</span>: <var>newPopoverOrTopLayerElement</var> is an <span data-x="HTML
elements">HTML element</span>.</p></li>
<li><p><span>Assert</span>: <var>newPopoverOrTopLayerElement</var>'s <code
data-x="attr-popover">popover</code> attribute is not in the <span
data-x="attr-popover-none-state">no popover state</span> or the <span
data-x="attr-popover-manual-state">manual</span> state.</p></li>
<li><p><span>Assert</span>: <var>newPopoverOrTopLayerElement</var>'s <span>popover visibility
state</span> is not in the <span data-x="popover-showing-state">popover showing
state</span>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>invoker</var> is null.</p></li>
</ol>
</li>
<li><p>Let <var>popoverPositions</var> be an empty <span>ordered map</span>.</p></li>
<li><p>Let <var>index</var> be 0.</p></li>
<li>
<p>For each <var>popover</var> of <var>popoverList</var>:</p>
<ol>
<li><p><span data-x="map set">Set</span> <var>popoverPositions</var>[<var>popover</var>] to
<var>index</var>.</p></li>
<li><p>Increment <var>index</var> by 1.</p></li>
</ol>
</li>
<li><p>If <var>isPopover</var> is true, then <span data-x="map set">set</span>
<var>popoverPositions</var>[<var>newPopoverOrTopLayerElement</var>] to <var>index</var>.</p></li>
<li><p>Increment <var>index</var> by 1.</p></li>
<li><p>Let <var>topmostPopoverAncestor</var> be null.</p></li>
<li>
<p>Let <var>checkAncestor</var> be an algorithm which performs the following steps given
<var>candidate</var>:</p>
<ol>
<li><p>If <var>candidate</var> is null, then return.</p></li>
<li><p>Let <var>okNesting</var> be false.</p></li>
<li><p>Let <var>candidateAncestor</var> be null.</p></li>
<li>
<p><span>While</span> <var>okNesting</var> is false:</p>
<ol>
<li><p>Set <var>candidateAncestor</var> to the result of running <span>nearest inclusive open
popover</span> given <var>candidate</var>.</p></li>
<li><p>If <var>candidateAncestor</var> is null or <var>popoverPositions</var> does not
contain <var>candidateAncestor</var>, then return.</p></li>
<li><p><span>Assert</span>: <var>candidateAncestor</var>'s <code
data-x="attr-popover">popover</code> attribute is not in the <span
data-x="attr-popover-manual-state">manual</span> or <span
data-x="attr-popover-none-state">none</span> state.</p></li>
<li><p>Set <var>okNesting</var> to true if <var>newPopoverOrTopLayerElement</var>'s <code
data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-hint-state">hint</span> state or <var>candidateAncestor</var>'s <code
data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state.</p></li>
<li><p>If <var>okNesting</var> is false, then set <var>candidate</var> to
<var>candidateAncestor</var>'s parent in the <span>flat tree</span>.</p></li>
</ol>
</li>
<li><p>Let <var>candidatePosition</var> be
<var>popoverPositions</var>[<var>candidateAncestor</var>].</p></li>
<li><p>If <var>topmostPopoverAncestor</var> is null or
<var>popoverPositions</var>[<var>topmostPopoverAncestor</var>] is less than
<var>candidatePosition</var>, then set <var>topmostPopoverAncestor</var> to
<var>candidateAncestor</var>.</p></li>
</ol>
</li>
<li><p>Run <var>checkAncestor</var> given <var>newPopoverOrTopLayerElement</var>'s parent node
within the <span>flat tree</span>.</p></li>
<li><p>Run <var>checkAncestor</var> given <var>invoker</var>.</p></li>
<li><p>Return <var>topmostPopoverAncestor</var>.</p></li>
</ol>
<p>To find the <dfn>nearest inclusive open popover</dfn> given a <code>Node</code>
<var>node</var>, perform the following steps. They return an <span data-x="html elements">HTML
element</span> or null.</p>
<ol>
<li><p>Let <var>currentNode</var> be <var>node</var>.</p></li>
<li>
<p>While <var>currentNode</var> is not null:</p>
<ol>
<li><p>If <var>currentNode</var>'s <code data-x="attr-popover">popover</code> attribute is in
the <span data-x="attr-popover-auto-state">auto</span> state and <var>currentNode</var>'s
<span>popover visibility state</span> is <span data-x="popover-showing-state">showing</span>,
then return <var>currentNode</var>.</p></li>
<li><p>Set <var>currentNode</var> to <var>currentNode</var>'s parent in the <span>flat
tree</span>.</p></li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<p>To <dfn data-x="topmost auto popover">find the topmost auto or hint popover</dfn> given a
<code>Document</code> <var>document</var>, perform the following steps. They return an <span
data-x="HTML elements">HTML element</span> or null.</p>
<ol>
<li><p>If <var>document</var>'s <span>showing hint popover list</span> is not empty, then return
<var>document</var>'s <span>showing hint popover list</span>'s last element.</p></li>
<li><p>If <var>document</var>'s <span>showing auto popover list</span> is not empty, then return
<var>document</var>'s <span>showing auto popover list</span>'s last element.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>To perform the <dfn>popover focusing steps</dfn> for an <span data-x="HTML elements">HTML
element</span> <var>subject</var>:</p>
<ol>
<li><p>If the <span>allow focus steps</span> given <var>subject</var>'s <span>node
document</span> return false, then return.</p></li>
<li><p>If <var>subject</var> is a <code>dialog</code> element, then run the <span>dialog focusing
steps</span> given <var>subject</var> and return.</p></li>
<li><p>If <var>subject</var> has the <code data-x="attr-fe-autofocus">autofocus</code>
attribute, then let <var>control</var> be <var>subject</var>.
<li><p>Otherwise, let <var>control</var> be the <span>autofocus delegate</span> for
<var>subject</var> given "<code data-x="">other</code>".</p></li>
<li><p>If <var>control</var> is null, then return.</p></li>
<li><p>Run the <span>focusing steps</span> given <var>control</var>.</p></li>
<li><p>Let <var>topDocument</var> be the <span>active document</span> of <var>control</var>'s
<span>node document</span>'s <span data-x="concept-document-bc">browsing context</span>'s
<span>top-level browsing context</span>.</p></li>
<li><p>If <var>control</var>'s <span>node document</span>'s <span
data-x="concept-document-origin">origin</span> is not the <span data-x="same origin">same</span>
as the <span data-x="concept-document-origin">origin</span> of <var>topDocument</var>, then
return.</p></li>
<li><p><span data-x="list empty">Empty</span> <var>topDocument</var>'s
<span>autofocus candidates</span>.</p></li>
<li><p>Set <var>topDocument</var>'s <span>autofocus processed flag</span> to true.</p></li>
</ol>
<p>To <dfn>check popover validity</dfn> for an <span data-x="HTML elements">HTML element</span>
<var>element</var> given a boolean <var>expectedToBeShowing</var>, a boolean
<var>throwExceptions</var>, and a <code>Document</code> or null <var>expectedDocument</var>,
perform the following steps. They throw an exception or return a boolean.</p>
<ol>
<li>
<p>If <var>element</var>'s <code data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-none-state">no popover</span> state, then:</p>
<ol>
<li><p>If <var>throwExceptions</var> is true, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return false.</p></li>
</ol>
</li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>expectedToBeShowing</var> is true and <var>element</var>'s <span>popover visibility
state</span> is not <span data-x="popover-showing-state">showing</span>; or</p></li>
<li><p><var>expectedToBeShowing</var> is false and <var>element</var>'s <span>popover
visibility state</span> is not <span data-x="popover-hidden-state">hidden</span>,</p></li>
</ul>
<p>then return false.</p>
</li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>element</var> is not <span>connected</span>;</p></li>
<li><p><var>element</var>'s <span>node document</span> is not <span>fully
active</span>;</p></li>
<li><p><var>expectedDocument</var> is not null and <var>element</var>'s <span>node
document</span> is not <var>expectedDocument</var>;</p></li>
<li><p><var>element</var> is a <code>dialog</code> element and its <span>is modal</span>
is set to true; or</li>
<li><p><var>element</var>'s <span>fullscreen flag</span> is set,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>If <var>throwExceptions</var> is true, then throw a
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return false.</p></li>
</ol>
</li>
<li><p>Return true.</p></li>
</ol>
<p>To get the <dfn id="auto-popover-list">showing auto popover list</dfn> for a
<code>Document</code> <var>document</var>:</p>
<ol>
<li><p>Let <var>popovers</var> be « ».</p></li>
<li>
<p><span data-x="list iterate">For each</span> <code>Element</code> <var>element</var> in
<var>document</var>'s <span>top layer</span>:</p>
<ol>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>element</var> is an <span data-x="HTML elements">HTML element</span>;</p></li>
<li><p><var>element</var>'s <span>opened in popover mode</span> is "<code
data-x="">auto</code>"; and</p></li>
<li><p><var>element</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>,</p></li>
</ul>
<p>then <span data-x="list append">append</span> <var>element</var> to
<var>popovers</var>.</p>
</li>
</ol>
</li>
<li><p>Return <var>popovers</var>.</p></li>
</ol>
<p>To get the <dfn>showing hint popover list</dfn> for a <code>Document</code>
<var>document</var>:</p>
<ol>
<li><p>Let <var>popovers</var> be « ».</p></li>
<li>
<p><span data-x="list iterate">For each</span> <code>Element</code> <var>element</var> in
<var>document</var>'s <span>top layer</span>:</p>
<ol>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>element</var> is an <span data-x="HTML elements">HTML element</span>;</p></li>
<li><p><var>element</var>'s <span>opened in popover mode</span> is "<code
data-x="">hint</code>"; and</p></li>
<li><p><var>element</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>,</p></li>
</ul>
<p>then <span data-x="list append">append</span> <var>element</var> to
<var>popovers</var>.</p>
</li>
</ol>
</li>
<li><p>Return <var>popovers</var>.</p></li>
</ol>
<p>To <dfn>close entire popover list</dfn> given a <span>list</span> <var>popoverList</var>, a
boolean <var>focusPreviousElement</var>, and a boolean <var>fireEvents</var>:</p>
<ol>
<li>
<p>While <var>popoverList</var> is not empty:</p>
<ol>
<li><p>Run the <span>hide popover algorithm</span> given <var>popoverList</var>'s last item,
<var>focusPreviousElement</var>, <var>fireEvents</var>, and false.</p></li>
</ol>
</li>
</ol>
<h4>The popover target attributes</h4>
<p><span data-x="concept-button">Buttons</span> may have the following content attributes:</p>
<ul>
<li><p><dfn element-attr for="html-global"><code
data-x="attr-popovertarget">popovertarget</code></dfn></p></li>
<li><p><dfn element-attr for="html-global"><code
data-x="attr-popovertargetaction">popovertargetaction</code></dfn></p></li>
</ul>
<p>If specified, the <code data-x="attr-popovertarget">popovertarget</code> attribute value must
be the <span data-x="concept-ID">ID</span> of an element with a <code
data-x="attr-popover">popover</code> attribute in the same <span>tree</span> as the <span
data-x="concept-button">button</span> with the <code
data-x="attr-popovertarget">popovertarget</code> attribute.</p>
<p>The <code data-x="attr-popovertargetaction">popovertargetaction</code> attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="html-global/popovertargetaction"
data-x="attr-popovertargetaction-toggle"><code>toggle</code></dfn>
<td><dfn data-x="attr-popovertargetaction-toggle-state">toggle</dfn>
<td>Shows or hides the targeted popover element.
<tr>
<td><dfn attr-value for="html-global/popovertargetaction"
data-x="attr-popovertargetaction-show"><code>show</code></dfn>
<td><dfn data-x="attr-popovertargetaction-show-state">show</dfn>
<td>Shows the targeted popover element.
<tr>
<td><dfn attr-value for="html-global/popovertargetaction"
data-x="attr-popovertargetaction-hide"><code>hide</code></dfn>
<td><dfn data-x="attr-popovertargetaction-hide-state">hide</dfn>
<td>Hides the targeted popover element.
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-popovertargetaction-toggle-state">toggle</span> state.</p>
<p class="note">Whenever possible ensure the popover element is placed immediately after its
triggering element in the DOM. Doing so will help ensure that the popover is exposed in a logical
programmatic reading order for users of assistive technology, such as screen readers.</p>
<div class="example">
<p>The following shows how the <code data-x="attr-popovertarget">popovertarget</code> attribute
in combination with the <code data-x="attr-popovertargetaction">popovertargetaction</code>
attribute can be used to show and close a popover:</p>
<pre><code class="html"><button popovertarget="foo" popovertargetaction="show">
Show a popover
</button>
<article popover="auto" id="foo">
This is a popover article!
<button popovertarget="foo" popovertargetaction="hide">Close</button>
</article></code></pre>
<p>If a <code data-x="attr-popovertargetaction">popovertargetaction</code> attribute is not
specified, the default action will be to toggle the associated popover. The following shows
how only specifying the <code data-x="attr-popovertarget">popovertarget</code> attribute on its
invoking button can toggle a manual popover between its opened and closed states. A manual
popover will not respond to <span data-x="popover light dismiss">light dismiss</span> or <span
data-x="close request">close requests</span>:</p>
<pre><code class="html"><input type="button" popovertarget="foo" value="Toggle the popover">
<div popover=manual id="foo">
This is a popover!
</div></code></pre>
</div>
<span data-x="concept-element-dom">DOM interface</span>:
<pre><code class="idl">interface mixin <dfn interface>PopoverInvokerElement</dfn> {
[<span>CEReactions</span>] attribute Element? <span data-x="dom-popoverTargetElement">popoverTargetElement</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-popoverTargetAction">popoverTargetAction</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-popoverTargetElement">popoverTargetElement</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-popovertarget">popovertarget</code> attribute.</p>
<p>The <dfn attribute for="HTMLElement"><code
data-x="dom-popoverTargetAction">popoverTargetAction</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-popovertargetaction">popovertargetaction</code>
attribute, <span>limited to only known values</span>.</p>
<p>To run the <dfn>popover target attribute activation behavior</dfn> given a <code>Node</code>
<var>node</var> and a <code>Node</code> <var>eventTarget</var>:</p>
<ol>
<li><p>Let <var>popover</var> be <var>node</var>'s <span>popover target element</span>.</p></li>
<li><p>If <var>popover</var> is null, then return.</p></li>
<li><p>If <var>eventTarget</var> is a <span>shadow-including inclusive descendant</span> of
<var>popover</var> and <var>popover</var> is a
<span data-x="shadow-including descendant">shadow-including descendant</span> of <var>node</var>,
then return.</p></li>
<li><p>If <var>node</var>'s <code data-x="attr-popovertargetaction">popovertargetaction</code>
attribute is in the <span data-x="attr-popovertargetaction-show">show</span> state and
<var>popover</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>, then return.</p></li>
<li><p>If <var>node</var>'s <code data-x="attr-popovertargetaction">popovertargetaction</code>
attribute is in the <span data-x="attr-popovertargetaction-hide">hide</span> state and
<var>popover</var>'s <span>popover visibility state</span> is <span
data-x="popover-hidden-state">hidden</span>, then return.</p></li>
<li><p>If <var>popover</var>'s <span>popover visibility state</span> is <span
data-x="popover-showing-state">showing</span>, then run the <span>hide popover algorithm</span>
given <var>popover</var>, true, true, and false.</p></li>
<li><p>Otherwise, if <var>popover</var>'s <span>popover visibility state</span> is <span
data-x="popover-hidden-state">hidden</span> and the result of running <span>check popover
validity</span> given <var>popover</var>, false, false, and null is true, then run <span>show
popover</span> given <var>popover</var>, false, and <var>node</var>.</p></li>
</ol>
<p>To get the <dfn>popover target element</dfn> given a <code>Node</code> <var>node</var>, perform
the following steps. They return an <span data-x="HTML elements">HTML element</span> or null.</p>
<ol>
<li><p>If <var>node</var> is not a <span data-x="concept-button">button</span>, then return
null.</p></li>
<li><p>If <var>node</var> is <span data-x="concept-fe-disabled">disabled</span>, then return
null.</p></li>
<li><p>If <var>node</var> has a <span>form owner</span> and <var>node</var> is a <span
data-x="concept-submit-button">submit button</span>, then return null.</p></li>
<li><p>Let <var>popoverElement</var> be the result of running <var>node</var>'s <span data-x="get
the attr-associated element">get the <code data-x="">popovertarget</code>-associated
element</span>.</p></li>
<li><p>If <var>popoverElement</var> is null, then return null.</p></li>
<li><p>If <var>popoverElement</var>'s <code data-x="attr-popover">popover</code> attribute is in
the <span data-x="attr-popover-none-state">no popover</span> state, then return null.</p></li>
<li><p>Return <var>popoverElement</var>.</p></li>
</ol>
<h4><dfn>Popover light dismiss</dfn></h4>
<p class="note">"Light dismiss" means that clicking outside of a popover whose <code
data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state will close the popover. This is in addition to
how such popovers respond to <span data-x="close request">close requests</span>.</p>
<p>To <dfn>light dismiss open popovers</dfn>, given a <code>PointerEvent</code>
<var>event</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <code
data-x="dom-Event-isTrusted">isTrusted</code> attribute is true.</p></li>
<li><p>Let <var>target</var> be <var>event</var>'s <span
data-x="concept-event-target">target</span>.</p></li>
<li><p>Let <var>document</var> be <var>target</var>'s <span>node document</span>.</p></li>
<li><p>Let <var>topmostPopover</var> be the result of running <span>topmost auto popover</span>
given <var>document</var>.</p></li>
<li><p>If <var>topmostPopover</var> is null, then return.</p></li>
<li><p>If <var>event</var>'s <code data-x="dom-Event-type">type</code> is "<code
data-x="event-pointerdown">pointerdown</code>", then: set <var>document</var>'s <span>popover
pointerdown target</span> to the result of running <span>topmost clicked popover</span> given
<var>target</var>.</p></li>
<li>
<p>If <var>event</var>'s <code data-x="dom-Event-type">type</code> is "<code
data-x="event-pointerup">pointerup</code>", then:</p>
<ol>
<li><p>Let <var>ancestor</var> be the result of running <span>topmost clicked popover</span>
given <var>target</var>.</p></li>
<li><p>Let <var>sameTarget</var> be true if <var>ancestor</var> is <var>document</var>'s
<span>popover pointerdown target</span>.</p></li>
<li><p>Set <var>document</var>'s <span>popover pointerdown target</span> to null.</p></li>
<li><p>If <var>ancestor</var> is null, then set <var>ancestor</var> to
<var>document</var>.</p></li>
<li><p>If <var>sameTarget</var> is true, then run <span data-x="hide-all-popovers-until">hide
all popovers until</span> given <var>ancestor</var>, false, and true.</p></li>
</ol>
</li>
</ol>
<p>To find the <dfn>topmost clicked popover</dfn>, given a <code>Node</code> <var>node</var>:</p>
<ol>
<li><p>Let <var>clickedPopover</var> be the result of running <span>nearest inclusive open
popover</span> given <var>node</var>.</p></li>
<li><p>Let <var>invokerPopover</var> be the result of running <span>nearest inclusive target
popover for invoker</span> given <var>node</var>.</p></li>
<li><p>If the result of <span data-x="get the popover stack position">getting the popover stack
position</span> given <var>clickedPopover</var> is greater than the result of <span data-x="get
the popover stack position">getting the popover stack position</span> given
<var>invokerPopover</var>, then return <var>clickedPopover</var>.</p></li>
<li><p>Return <var>invokerPopover</var>.</p></li>
</ol>
<p>To <dfn>get the popover stack position</dfn>, given an <span data-x="html elements">HTML
element</span> <var>popover</var>:</p>
<ol>
<li><p>Let <var>hintList</var> be <var>popover</var>'s <span>node document</span>'s <span>showing
hint popover list</span>.</p></li>
<li><p>Let <var>autoList</var> be <var>popover</var>'s <span>node document</span>'s <span>showing
auto popover list</span>.</p></li>
<li><p>If <var>popover</var> is in <var>hintList</var>, then return the index of
<var>popover</var> in <var>hintList</var> + the size of <var>autoList</var> + 1.</p></li>
<li><p>If <var>popover</var> is in <var>autoList</var>, then return the index of
<var>popover</var> in <var>autoList</var> + 1.</p></li>
<li><p>Return 0.</p></li>
</ol>
<p>To find the <dfn>nearest inclusive target popover for invoker</dfn> given a <code>Node</code>
<var>node</var>:</p>
<ol>
<li><p>Let <var>currentNode</var> be <var>node</var>.</p></li>
<li>
<p>While <var>currentNode</var> is not null:</p>
<ol>
<li><p>Let <var>targetPopover</var> be <var>currentNode</var>'s <span>popover target
element</span>.</p></li>
<li><p>If <var>targetPopover</var> is not null and <var>targetPopover</var>'s <code
data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state and <var>targetPopover</var>'s <span>popover
visibility state</span> is <span data-x="popover-showing-state">showing</span>, then return
<var>targetPopover</var>.</p></li>
<li><p>Set <var>currentNode</var> to <var>currentNode</var>'s ancestor in the <span>flat
tree</span>.</p></li>
</ol>
</li>
</ol>
<h2 split-filename="browsers" id="browsers">Loading web pages</h2>
<div w-nodev>
<p>This section describes features that apply most directly to web browsers. Having said that,
except where specified otherwise, the requirements defined in this section <em>do</em> apply to
all user agents, whether they are web browsers or not.</p>
</div>
<h3 id="loading-web-pages-supporting-concepts">Supporting concepts</h3>
<h4 id="origin">Origins</h4>
<!-- Hallowed are the Ori -->
<p>Origins are the fundamental currency of the web's security model. Two actors in the web
platform that share an origin are assumed to trust each other and to have the same authority.
Actors with differing origins are considered potentially hostile versus each other, and are
isolated from each other to varying degrees.</p>
<p class="example">For example, if Example Bank's web site, hosted at <code
data-x="">bank.example.com</code>, tries to examine the DOM of Example Charity's web site, hosted
at <code data-x="">charity.example.org</code>, a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code> will be raised.</p>
<hr>
<p id="origin-2">An <dfn id="concept-origin" export>origin</dfn> is one of the following:</p>
<dl>
<dt>An <dfn export data-x="concept-origin-opaque">opaque origin</dfn></dt>
<dd><p>An internal value, with no serialization it can be recreated from (it is serialized as
"<code data-x="">null</code>" per <span>serialization of an origin</span>), for which the only
meaningful operation is testing for equality.</p></dd>
<dt>A <dfn export data-x="concept-origin-tuple">tuple origin</dfn></dt>
<dd>
<p>A <span>tuple</span> consisting of:
<ul class="brief">
<li>A <dfn export for="origin" data-x="concept-origin-scheme">scheme</dfn> (an <span>ASCII
string</span>).</li>
<li>A <dfn export for="origin" data-x="concept-origin-host">host</dfn> (a <span
data-x="concept-host">host</span>).</li>
<li>A <dfn export for="origin" data-x="concept-origin-port">port</dfn> (null or a 16-bit
unsigned integer).</li>
<li>A <dfn export for="origin" data-x="concept-origin-domain">domain</dfn> (null or a <span
data-x="concept-domain">domain</span>). Null unless stated otherwise.</li>
</ul>
</dd>
</dl>
<p class="note"><span data-x="origin">Origins</span> can be shared, e.g., among multiple
<code>Document</code> objects. Furthermore, <span data-x="origin">origins</span> are generally
immutable. Only the <span data-x="concept-origin-domain">domain</span> of a <span
data-x="concept-origin-tuple">tuple origin</span> can be changed, and only through the <code
data-x="dom-document-domain">document.domain</code> API.</p>
<div w-nodev>
<p>The <dfn export data-x="concept-origin-effective-domain">effective domain</dfn> of an
<span>origin</span> <var>origin</var> is computed as follows:</p>
<ol>
<li><p>If <var>origin</var> is an <span data-x="concept-origin-opaque">opaque origin</span>,
then return null.</p></li>
<li><p>If <var>origin</var>'s <span data-x="concept-origin-domain">domain</span> is non-null,
then return <var>origin</var>'s <span data-x="concept-origin-domain">domain</span>.</p></li>
<li><p>Return <var>origin</var>'s <span data-x="concept-origin-host">host</span>.</p></li>
</ol>
<p>The <!--en-GB--><dfn id="ascii-serialisation-of-an-origin" export data-lt="serialization of an
origin|ASCII serialization of an origin">serialization of an origin</dfn> is the string obtained
by applying the following algorithm to the given <span>origin</span> <var>origin</var>:</p>
<ol>
<li><p>If <var>origin</var> is an <span data-x="concept-origin-opaque">opaque origin</span>,
then return "<code data-x="">null</code>".</p></li>
<li><p>Otherwise, let <var>result</var> be <var>origin</var>'s <span
data-x="concept-origin-scheme">scheme</span>.</p></li>
<li><p>Append "<code data-x="">://</code>" to <var>result</var>.</p></li>
<li><p>Append <var>origin</var>'s <span data-x="concept-origin-host">host</span>, <span
data-x="host serializer">serialized</span>, to <var>result</var>.</p></li>
<li><p>If <var>origin</var>'s <span data-x="concept-origin-port">port</span> is non-null, append
a U+003A COLON character (:), and <var>origin</var>'s <span
data-x="concept-origin-port">port</span>, <span data-x="serialize an integer">serialized</span>,
to <var>result</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
</div>
<p class="example">The <span data-x="serialization of an origin">serialization</span> of ("<code
data-x="">https</code>", "<code data-x="">xn--maraa-rta.example</code>", null, null) is "<code
data-x="">https://xn--maraa-rta.example</code>".</p>
<div w-nodev>
<!--en-GB--><p class="note" id="unicode-serialisation-of-an-origin">There used to also be a
<i>Unicode serialization of an origin</i>. However, it was never widely adopted.</p>
<hr>
<p>Two <span data-x="origin">origins</span>, <var>A</var> and <var>B</var>, are said to be <dfn
export>same origin</dfn> if the following algorithm returns true:</p>
<ol>
<li><p>If <var>A</var> and <var>B</var> are the same <span data-x="concept-origin-opaque">opaque
origin</span>, then return true.</p></li>
<li><p>If <var>A</var> and <var>B</var> are both <span data-x="concept-origin-tuple">tuple
origins</span> and their <span data-x="concept-origin-scheme">schemes</span>, <span
data-x="concept-origin-host">hosts</span>, and <span data-x="concept-origin-port">port</span>
are identical, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>Two <span data-x="origin">origins</span>, <var>A</var> and <var>B</var>, are said to be <dfn
export>same origin-domain</dfn> if the following algorithm returns true:</p>
<ol>
<li><p>If <var>A</var> and <var>B</var> are the same <span data-x="concept-origin-opaque">opaque
origin</span>, then return true.</p></li>
<li>
<p>If <var>A</var> and <var>B</var> are both <span data-x="concept-origin-tuple">tuple
origins</span>:</p>
<ol>
<li><p>If <var>A</var> and <var>B</var>'s <span data-x="concept-origin-scheme">schemes</span>
are identical, and their <span data-x="concept-origin-domain">domains</span> are identical and
non-null, then return true.</p></li>
<li><p>Otherwise, if <var>A</var> and <var>B</var> are <span>same origin</span> and their
<span data-x="concept-origin-domain">domains</span> are both null, return true.</p></li>
</ol>
<li><p>Return false.</p></li>
</ol>
</div>
<div class="example">
<p w-dev>The following table shows examples of when two <span data-x="concept-origin-tuple">tuple
origins</span> are <span subdfn>same origin</span> and <span subdfn>same
origin-domain</span>.</p>
<table>
<tr>
<th><var>A</var>
<th><var>B</var>
<th><span>same origin</span>
<th><span>same origin-domain</span>
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", null, null)
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", null, null)
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", 314, null)
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", 420, null)
<td>❌
<td>❌
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", 314, "<code data-x="">example.org</code>")
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", 420, "<code data-x="">example.org</code>")
<td>❌
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", null, null)
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", null, "<code data-x="">example.org</code>")
<td>✅
<td>❌
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.org</code>", null, "<code data-x="">example.org</code>")
<td>("<code data-x="">http</code>", "<code data-x="">example.org</code>", null, "<code data-x="">example.org</code>")
<td>❌
<td>❌
</table>
</div>
<h5>Sites</h5>
<p>A <dfn>scheme-and-host</dfn> is a <span>tuple</span> of a <dfn
data-x="concept-scheme-and-host-scheme">scheme</dfn> (an <span>ASCII string</span>) and a <dfn
data-x="concept-scheme-and-host-host">host</dfn> (a <span data-x="concept-host">host</span>).</p>
<p>A <dfn export>site</dfn> is an <span data-x="concept-origin-opaque">opaque origin</span> or a
<span>scheme-and-host</span>.</p>
<div w-nodev>
<p>To <dfn export>obtain a site</dfn>, given an origin <var>origin</var>, run these steps:</p>
<ol>
<li><p>If <var>origin</var> is an <span data-x="concept-origin-opaque">opaque origin</span>,
then return <var>origin</var>.</p></li>
<li><p>If <var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
domain</span> is null, then return (<var>origin</var>'s <span
data-x="concept-origin-scheme">scheme</span>, <var>origin</var>'s <span
data-x="concept-origin-host">host</span>).</p></li>
<li><p>Return (<var>origin</var>'s <span data-x="concept-origin-scheme">scheme</span>,
<var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
domain</span>).</p></li>
</ol>
<p>Two <span data-x="site">sites</span>, <var>A</var> and <var>B</var>, are said to be <dfn
export for="site" data-x="concept-site-same-site">same site</dfn> if the following algorithm
returns true:</p>
<ol>
<li><p>If <var>A</var> and <var>B</var> are the same <span data-x="concept-origin-opaque">opaque
origin</span>, then return true.</p></li>
<li><p>If <var>A</var> or <var>B</var> is an <span data-x="concept-origin-opaque">opaque
origin</span>, then return false.</p></li>
<li><p>If <var>A</var>'s and <var>B</var>'s <span
data-x="concept-scheme-and-host-scheme">scheme</span> values are different, then return
false.</p></li>
<li><p>If <var>A</var>'s and <var>B</var>'s <span
data-x="concept-scheme-and-host-host">host</span> values are not <span data-x="host
equals">equal</span>, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn export>serialization of a site</dfn> is the string obtained by applying the following
algorithm to the given <span>site</span> <var>site</var>:</p>
<ol>
<li><p>If <var>site</var> is an <span data-x="concept-origin-opaque">opaque origin</span>, then
return "<code data-x="">null</code>".</p></li>
<li><p>Let <var>result</var> be <var>site</var>[0].</p></li>
<li><p>Append "<code data-x="">://</code>" to <var>result</var>.</p></li>
<li><p>Append <var>site</var>[1], <span data-x="host serializer">serialized</span>, to
<var>result</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p class="warning">It needs to be clear from context that the serialized value is a site, not an
origin, as there is not necessarily a syntactic difference between the two. For example, the
origin ("<code data-x="">https</code>", "<code data-x="">shop.example</code>", null, null) and
the site ("<code data-x="">https</code>", "<code data-x="">shop.example</code>") have the same
serialization: "<code data-x="">https://shop.example</code>".</p>
<p>Two <span data-x="origin">origins</span>, <var>A</var> and <var>B</var>, are said to be <dfn
export>schemelessly same site</dfn> if the following algorithm returns true:</p>
<ol>
<li><p>If <var>A</var> and <var>B</var> are the same <span data-x="concept-origin-opaque">opaque
origin</span>, then return true.</p></li>
<li>
<p>If <var>A</var> and <var>B</var> are both <span data-x="concept-origin-tuple">tuple
origins</span>, then:</p>
<ol>
<li><p>Let <var>hostA</var> be <var>A</var>'s <span data-x="concept-origin-host">host</span>,
and let <var>hostB</var> be <var>B</var>'s <span
data-x="concept-origin-host">host</span>.</p></li>
<li><p>If <var>hostA</var> <span data-x="host equals">equals</span> <var>hostB</var> and
<var>hostA</var>'s <span>registrable domain</span> is null, then return true.</p></li>
<li><p>If <var>hostA</var>'s <span>registrable domain</span> <span data-x="host
equals">equals</span> <var>hostB</var>'s <span>registrable domain</span> and is non-null, then
return true.</p></li>
</ol>
</li>
<li><p>Return false.</p></li>
</ol>
<p>Two <span data-x="origin">origins</span>, <var>A</var> and <var>B</var>, are said to be <dfn
export>same site</dfn> if the following algorithm returns true:</p>
<ol>
<li><p>Let <var>siteA</var> be the result of <span data-x="obtain a site">obtaining a
site</span> given <var>A</var>.</p></li>
<li><p>Let <var>siteB</var> be the result of <span data-x="obtain a site">obtaining a
site</span> given <var>B</var>.</p></li>
<li><p>If <var>siteA</var> is <span data-x="concept-site-same-site">same site</span> with
<var>siteB</var>, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
</div>
<p class="note">Unlike the <span>same origin</span> and <span>same origin-domain</span> concepts,
for <span>schemelessly same site</span> and <span>same site</span>, the <span
data-x="concept-origin-port">port</span> and <span data-x="concept-origin-domain">domain</span>
components are ignored.</p>
<p class="warning">For the reasons <a
href="https://url.spec.whatwg.org/#warning-avoid-psl">explained in <cite>URL</cite></a>, the
<span>same site</span> and <span>schemelessly same site</span> concepts should be avoided when
possible, in favor of <span>same origin</span> checks.</p>
<div class="example" id="example-same-site">
<p w-dev>The following table shows examples of when two <span data-x="concept-origin-tuple">tuple
origins</span> are <span subdfn>schemelessly same site</span> and <span subdfn>same
site</span>.</p>
<p>Given that <code data-x="">wildlife.museum</code>, <code data-x="">museum</code>, and <code
data-x="">com</code> are <span data-x="public suffix">public suffixes</span> and that <code
data-x="">example.com</code> is not:</p>
<table>
<tr>
<th><var>A</var>
<th><var>B</var>
<th><span>schemelessly same site</span>
<th><span>same site</span>
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.com</code>")
<td>("<code data-x="">https</code>", "<code data-x="">sub.example.com</code>")
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.com</code>")
<td>("<code data-x="">https</code>", "<code data-x="">sub.other.example.com</code>")
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.com</code>")
<td>("<code data-x="">http</code>", "<code data-x="">non-secure.example.com</code>")
<td>✅
<td>❌
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">r.wildlife.museum</code>")
<td>("<code data-x="">https</code>", "<code data-x="">sub.r.wildlife.museum</code>")
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">r.wildlife.museum</code>")
<td>("<code data-x="">https</code>", "<code data-x="">sub.other.r.wildlife.museum</code>")
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">r.wildlife.museum</code>")
<td>("<code data-x="">https</code>", "<code data-x="">other.wildlife.museum</code>")
<td>❌
<td>❌
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">r.wildlife.museum</code>")
<td>("<code data-x="">https</code>", "<code data-x="">wildlife.museum</code>")
<td>❌
<td>❌
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">wildlife.museum</code>")
<td>("<code data-x="">https</code>", "<code data-x="">wildlife.museum</code>")
<td>✅
<td>✅
<tr>
<td>("<code data-x="">https</code>", "<code data-x="">example.com</code>")
<td>("<code data-x="">https</code>", "<code data-x="">example.com.</code>")
<td>❌
<td>❌
</table>
<p>(Here we have omitted the <span data-x="concept-origin-port">port</span> and <span
data-x="concept-origin-domain">domain</span> components since they are not considered.)</p>
</div>
<h5>Relaxing the same-origin restriction</h5>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-domain">domain</span> [ = <var>domain</var> ]</code></dt>
<dd>
<p>Returns the current domain used for security checks.</p>
<p>Can be set to a value that removes subdomains, to change the <span>origin</span>'s <span
data-x="concept-origin-domain">domain</span> to allow pages on other subdomains of the same
domain (if they do the same thing) to access each other. This enables pages on different hosts
of a domain to synchronously access each other's DOMs.</p>
<p>In sandboxed <code>iframe</code>s, <code>Document</code>s with <span
data-x="concept-origin-opaque">opaque origins</span>, and <code>Document</code>s without a <span
data-x="concept-document-bc">browsing context</span>, the setter will
throw a <span>"<code>SecurityError</code>"</span> exception. In cases where <code
data-x="dom-crossOriginIsolated">crossOriginIsolated</code> or <code
data-x="dom-originAgentCluster">originAgentCluster</code> return true, the setter will do
nothing.</p>
</dd>
</dl>
<div class="critical">
<p>Avoid using the <code data-x="dom-document-domain">document.domain</code> setter. It
undermines the security protections provided by the same-origin policy. This is especially acute
when using shared hosting; for example, if an untrusted third party is able to host an HTTP
server at the same IP address but on a different port, then the same-origin protection that
normally protects two different sites on the same host will fail, as the ports are ignored when
comparing origins after the <code data-x="dom-document-domain">document.domain</code> setter has
been used.</p>
<p>Because of these security pitfalls, this feature is in the process of being removed from the
web platform. (This is a long process that takes many years.)</p>
<p>Instead, use <code data-x="dom-window-postMessage">postMessage()</code> or
<code>MessageChannel</code> objects to communicate across origins in a safe manner.</p>
</div>
<div w-nodev>
<p>The <dfn attribute for="Document"><code data-x="dom-document-domain">domain</code></dfn>
getter steps are:</p>
<ol>
<li><p>Let <var>effectiveDomain</var> be <span>this</span>'s <span
data-x="concept-document-origin">origin</span>'s <span
data-x="concept-origin-effective-domain">effective domain</span>.
<li><p>If <var>effectiveDomain</var> is null, then return the empty string.</p></li>
<li><p>Return <var>effectiveDomain</var>, <span data-x="host
serializer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-document-domain">domain</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-document-bc">browsing context</span> is
null, then throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>active sandboxing flag set</span> has its <span>sandboxed
<code data-x="dom-document-domain">document.domain</code> browsing context flag</span> set, then
throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>effectiveDomain</var> be <span>this</span>'s <span
data-x="concept-document-origin">origin</span>'s <span
data-x="concept-origin-effective-domain">effective domain</span>.
<li><p>If <var>effectiveDomain</var> is null, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the given value <span data-x="is a registrable domain suffix of or is equal to">is not
a registrable domain suffix of and is not equal to</span> <var>effectiveDomain</var>, then throw
a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the <span>surrounding agent</span>'s <span>agent cluster</span>'s <span>is
origin-keyed</span> is true, then return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-document-origin">origin</span>'s <span
data-x="concept-origin-domain">domain</span> to the result of <span data-x="host
parser">parsing</span> the given value.</p></li>
</ol>
<p>To determine if a <span>scalar value string</span> <var>hostSuffixString</var> <dfn export
data-lt="is a registrable domain suffix of or is equal to|is not a registrable domain suffix of
and is not equal to">is a registrable domain suffix of or is equal to</dfn> a <span
data-x="concept-host">host</span> <var>originalHost</var>:</p>
<!-- web platform usage: document.domain, Cookies, web Authentication -->
<ol>
<li><p>If <var>hostSuffixString</var> is the empty string, then return false.</p></li>
<li><p>Let <var>hostSuffix</var> be the result of <span data-x="host parser">parsing</span>
<var>hostSuffixString</var>.</p></li>
<li><p>If <var>hostSuffix</var> is failure, then return false.</p></li>
<li>
<p>If <var>hostSuffix</var> does not <span data-x="host equals">equal</span>
<var>originalHost</var>, then:</p>
<ol>
<li>
<p>If <var>hostSuffix</var> or <var>originalHost</var> is not a <span
data-x="concept-domain">domain</span>, then return false.</p>
<p class="note">This excludes <span data-x="concept-host">hosts</span> that are <span
data-x="IP address">IP addresses</span>.</p>
</li>
<li><p>If <var>hostSuffix</var>, prefixed by U+002E (.), does not match the end of
<var>originalHost</var>, then return false.</p></li>
<!-- It would be cleaner to avoid string manipulation on domains. -->
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>hostSuffix</var> <span data-x="host equals">equals</span>
<var>hostSuffix</var>'s <span>public suffix</span>; or</p></li>
<li><p><var>hostSuffix</var>, prefixed by U+002E (.), matches the end of
<var>originalHost</var>'s <span>public suffix</span>,</p></li>
<!-- It would be cleaner to avoid string manipulation on domains. -->
</ul>
<p>then return false. <ref>URL</ref></p>
</li>
<li><p><span>Assert</span>: <var>originalHost</var>'s <span>public suffix</span>, prefixed by
U+002E (.), matches the end of <var>hostSuffix</var>.</p></li>
<!-- It would be cleaner to avoid string manipulation on domains. -->
</ol>
</li>
<li><p>Return true.</p></li>
</ol>
<div class="example" id="example-registrable-domain-suffix">
<table>
<tr>
<th><var>hostSuffixString</var></th>
<th><var>originalHost</var></th>
<th>Outcome of <span>is a registrable domain suffix of or is equal to</span></th>
<th>Notes</th>
</tr>
<tr>
<td>"<code data-x="">0.0.0.0</code>"</td>
<td><code data-x="">0.0.0.0</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">0x10203</code>"</td>
<td><code data-x="">0.1.2.3</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">[0::1]</code>"</td>
<td><code data-x="">::1</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">example.com</code>"</td>
<td><code data-x="">example.com</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">example.com</code>"</td>
<td><code data-x="">example.com.</code></td>
<td>❌</td>
<td rowspan="2">Trailing dot is significant.</td>
</tr>
<tr>
<td>"<code data-x="">example.com.</code>"</td>
<td><code data-x="">example.com</code></td>
<td>❌</td>
</tr>
<tr>
<td>"<code data-x="">example.com</code>"</td>
<td><code data-x="">www.example.com</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">com</code>"</td>
<td><code data-x="">example.com</code></td>
<td>❌</td>
<td>At the time of writing, <code data-x="">com</code> is a public suffix.</td>
</tr>
<tr>
<td>"<code data-x="">example</code>"</td>
<td><code data-x="">example</code></td>
<td>✅</td>
<td></td>
</tr>
<tr>
<td>"<code data-x="">compute.amazonaws.com</code>"</td>
<td><code data-x="">example.compute.amazonaws.com</code></td>
<td>❌</td>
<td rowspan="3">At the time of writing, <code data-x=""><var>*</var>.compute.amazonaws.com</code> is a public suffix.</td>
</tr>
<tr>
<td>"<code data-x="">example.compute.amazonaws.com</code>"</td>
<td><code data-x="">www.example.compute.amazonaws.com</code></td>
<td>❌</td>
</tr>
<tr>
<td>"<code data-x="">amazonaws.com</code>"</td>
<td><code data-x="">www.example.compute.amazonaws.com</code></td>
<td>❌</td>
</tr>
<tr>
<td>"<code data-x="">amazonaws.com</code>"</td>
<td><code data-x="">test.amazonaws.com</code></td>
<td>✅</td>
<td>At the time of writing, <code data-x="">amazonaws.com</code> is a registrable domain.</td>
</tr>
</table>
</div>
</div>
<h4><span id="origin-isolation"></span>Origin-keyed agent clusters</h4>
<dl class="domintro">
<dt><code data-x="">window.<span subdfn data-x="dom-originAgentCluster">originAgentCluster</span></code></dt>
<dd>
<p>Returns true if this <code>Window</code> belongs to an <span>agent cluster</span> which is
<span>origin</span>-<span data-x="agent cluster key">keyed</span>, in the manner described in
this section.</p>
</dd>
</dl>
<p>A <code>Document</code> delivered over a <span>secure context</span> can request that it be
placed in an <span>origin</span>-<span data-x="agent cluster key">keyed</span> <span>agent
cluster</span>, by using the `<dfn http-header><code>Origin-Agent-Cluster</code></dfn>` HTTP
response header. This header is a <span data-x="http-structured-header">structured header</span>
whose value must be a <span data-x="http-structured-header-boolean">boolean</span>.
<ref>STRUCTURED-FIELDS</ref></p>
<p><span w-nodev>Per the processing model in the <span data-x="create-the-document-object">create
and initialize a new <code>Document</code> object</span>, values</span><span w-dev>Values</span>
that are not the <span data-x="http-structured-header-boolean">structured header boolean</span>
true value (i.e., `<code data-x="">?1</code>`) will be ignored.</p>
<p>The consequences of using this header are that <span w-nodev>the resulting
<code>Document</code>'s <span>agent cluster key</span> is its <span
data-x="concept-document-origin">origin</span>, instead of the <span data-x="obtain a
site">corresponding site</span>. In terms of observable effects, this means that
</span>attempting to <a href="#relaxing-the-same-origin-restriction">relax the same-origin
restriction</a> using <code data-x="dom-document-domain">document.domain</code> will instead do
nothing, and it will not be possible to send <code>WebAssembly.Module</code> objects to
cross-origin <code>Document</code>s (even if they are <span>same site</span>). Behind the scenes,
this isolation can allow user agents to allocate implementation-specific resources corresponding
to <span data-x="agent cluster">agent clusters</span>, such as processes or threads, more
efficiently.</p>
<p>Note that within a <span>browsing context group</span>, the
`<code>Origin-Agent-Cluster</code>` header can never cause same-origin <code>Document</code>
objects to end up in different <span data-x="agent cluster">agent clusters</span>, even if one
sends the header and the other doesn't.<span w-nodev> This is prevented by means of the
<span>historical agent cluster key map</span>.</span></p>
<p class="note">This means that the <code
data-x="dom-originAgentCluster">originAgentCluster</code> getter can return false, even if the
header is set, if the header was omitted on a previously-loaded same-origin page in the same
<span>browsing context group</span>. Similarly, it can return true even when the header is not
set.</p>
<p w-nodev>The <dfn attribute for="Window"><code
data-x="dom-originAgentCluster">originAgentCluster</code></dfn> getter steps are to return the
<span>surrounding agent</span>'s <span>agent cluster</span>'s <span>is origin-keyed</span>.</p>
<p class="note"><code>Document</code>s with an <span data-x="concept-origin-opaque">opaque
origin</span> can be considered unconditionally origin-keyed; for them the header has no effect,
and the <code data-x="dom-originAgentCluster">originAgentCluster</code> getter will always return
true.</p>
<p class="note">Similarly, <code>Document</code>s whose <span>agent cluster</span>'s <span
data-x="agent-cluster-cross-origin-isolation">cross-origin isolation mode</span> is not "<code
data-x="cross-origin-isolation-none">none</code>" are automatically origin-keyed. The
`<code>Origin-Agent-Cluster</code>` header might be useful as an additional hint to
implementations about resource allocation, since the `<code>Cross-Origin-Opener-Policy</code>`
and `<code>Cross-Origin-Embedder-Policy</code>` headers used to achieve cross-origin isolation
are more about ensuring that everything in the same address space opts in to being there. But
adding it would have no additional observable effects on author code.</p>
<h4>Cross-origin opener policies</h4>
<p>An <dfn id="cross-origin-opener-policy-value">opener policy value</dfn> allows a document which
is navigated to in a <span>top-level browsing context</span> to force the creation of a new
<span>top-level browsing context</span>, and a corresponding <span data-x="tlbc
group">group</span>. The possible values are:</p>
<dl>
<dt>"<dfn><code data-x="coop-unsafe-none">unsafe-none</code></dfn>"</dt>
<dd><p>This is the (current) default and means that the document will occupy the same
<span>top-level browsing context</span> as its predecessor, unless that document specified a
different <span>opener policy</span>.</p></dd>
<dt>"<dfn><code data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code></dfn>"</dt>
<dd><p>This forces the creation of a new <span>top-level browsing context</span> for the
document, unless its predecessor specified the same <span>opener policy</span> and they are
<span>same origin</span>.</p></dd>
<dt>"<dfn><code data-x="coop-same-origin">same-origin</code></dfn>"</dt>
<dd><p>This behaves the same as "<code
data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>", with the addition that
any <span>auxiliary browsing context</span> created needs to contain <span>same origin</span>
documents that also have the same <span>opener policy</span> or it will appear closed to the
opener.</p></dd>
<dt>"<dfn><code data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code></dfn>"</dt>
<dd>
<p>This behaves the same as "<code data-x="coop-same-origin">same-origin</code>", with the
addition that it sets the (new) <span>top-level browsing context</span>'s <span data-x="tlbc
group">group</span>'s <span data-x="bcg-cross-origin-isolation">cross-origin isolation
mode</span> to one of "<code data-x="cross-origin-isolation-logical">logical</code>" or "<code
data-x="cross-origin-isolation-concrete">concrete</code>".</p>
<p class="note">"<code data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code>" cannot
be directly set via the `<code>Cross-Origin-Opener-Policy</code>` header, but results from a
combination of setting both `<code data-x=""><span>Cross-Origin-Opener-Policy</span>: <span
data-x="coop-same-origin">same-origin</span></code>` and a
`<code>Cross-Origin-Embedder-Policy</code>` header whose value is <span>compatible with
cross-origin isolation</span> together.</p>
</dd>
<dt>"<dfn><code data-x="coop-noopener-allow-popups">noopener-allow-popups</code></dfn>"</dt>
<dd>
<p>This forces the creation of a new <span>top-level browsing context</span> for the document,
regardless of its predecessor.</p>
<div class="note">
<p>While including a <code
data-x="coop-noopener-allow-popups">noopener-allow-popups</code> value severs the opener
relationship between the document on which it is applied and its opener, it does not create a
robust security boundary between those same-origin documents.</p>
<p>Other risks from same-origin applications include:</p>
<ul>
<li><p>Same-origin requests fetching the document's content — could be mitigated through
Fetch Metadata filtering. <ref>FETCHMETADATA</ref></p></li>
<li><p>Same-origin framing - could be mitigated through <code>X-Frame-Options</code> or CSP
<code data-x="frame-ancestors directive">frame-ancestors</code>.</p></li>
<li><p>JavaScript accessible cookies - can be mitigated by ensuring all cookies are <code
data-x="">httponly</code>.</p></li>
<li><p><code data-x="dom-localStorage">localStorage</code> access to sensitive data.</p></li>
<li><p>Service worker installation.</p></li>
<li><p><a href="https://w3c.github.io/ServiceWorker/#cache">Cache API</a> manipulation or
access to sensitive data. <ref>SW</ref></p></li>
<li><p><code data-x="">postMessage</code> or <code>BroadcastChannel</code> messaging that
exposes sensitive information.</p></li>
<li><p>Autofill which may not require user interaction for same-origin documents.</p></li>
</ul>
<p>Developers using <code data-x="coop-noopener-allow-popups">noopener-allow-popups</code>
need to make sure that their sensitive applications don't rely on client-side features
accessible to other same-origin documents, e.g., <code
data-x="dom-localStorage">localStorage</code> and other client-side storage APIs,
<code>BroadcastChannel</code> and related same-origin communication mechanisms. They also need
to make sure that their server-side endpoints don't return sensitive data to non-navigation
requests, whose response content is accessible to same-origin
documents.</p>
</div>
</dd>
</dl>
<div w-nodev>
<p>An <dfn id="cross-origin-opener-policy">opener policy</dfn> consists of:</p>
<ul>
<li><p>A <dfn data-x="coop-struct-value">value</dfn>, which is an <span data-x="opener policy
value">opener policy value</span>, initially "<code
data-x="coop-unsafe-none">unsafe-none</code>".</p></li>
<li><p>A <dfn data-x="coop-struct-report-endpoint">reporting endpoint</dfn>, which is string or
null, initially null.</p></li>
<li><p>A <dfn data-x="coop-struct-report-only-value">report-only value</dfn>, which is an <span
data-x="opener policy value">opener policy value</span>, initially "<code
data-x="coop-unsafe-none">unsafe-none</code>".</p></li>
<li><p>A <dfn data-x="coop-struct-report-only-endpoint">report-only reporting endpoint</dfn>,
which is a string or null, initially null.</p></li>
</ul>
<p>To <dfn data-x="matching-coop">match opener policy values</dfn>, given an <span>opener policy
value</span> <var>documentCOOP</var>, an <span>origin</span> <var>documentOrigin</var>, an
<span>opener policy value</span> <var>responseCOOP</var>, and an <span>origin</span>
<var>responseOrigin</var>:</p>
<ol>
<li><p>If <var>documentCOOP</var> is "<code data-x="coop-unsafe-none">unsafe-none</code>" and
<var>responseCOOP</var> is "<code data-x="coop-unsafe-none">unsafe-none</code>", then return
true.</p></li>
<li><p>If <var>documentCOOP</var> is "<code data-x="coop-unsafe-none">unsafe-none</code>" or
<var>responseCOOP</var> is "<code data-x="coop-unsafe-none">unsafe-none</code>", then return
false.</p></li>
<li><p>If <var>documentCOOP</var> is <var>responseCOOP</var> and <var>documentOrigin</var> is
<span>same origin</span> with <var>responseOrigin</var>, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
</div>
<h5 id="the-coop-headers">The headers</h5>
<p>A <code>Document</code>'s <span data-x="concept-document-coop">cross-origin opener
policy</span> is derived from the `<dfn http-header
id="cross-origin-opener-policy-2"><code>Cross-Origin-Opener-Policy</code></dfn>` and `<dfn
http-header><code>Cross-Origin-Opener-Policy-Report-Only</code></dfn>` HTTP response headers.
These headers are <span data-x="http-structured-header">structured headers</span> whose value must
be a <span data-x="http-structured-header-token">token</span>. <ref>STRUCTURED-FIELDS</ref></p>
<p>The valid <span data-x="http-structured-header-token">token</span> values are the <span
data-x="opener policy value">opener policy values</span>. The token may also have
attached <span data-x="http-structured-header-parameters">parameters</span>; of these, the "<dfn
data-x="coop-report-to"><code>report-to</code></dfn>" parameter can have a <span>valid URL
string</span> identifying an appropriate reporting endpoint. <ref>REPORTING</ref></p>
<p class="note"><span w-nodev>Per the processing model described below, user</span><span
w-dev>User</span> agents will ignore this header if it contains an invalid value. Likewise, user
agents will ignore this header if the value cannot be parsed as a <span
data-x="http-structured-header-token">token</span>.</p>
<div w-nodev>
<hr>
<p>To <dfn data-x="obtain-coop">obtain an opener policy</dfn> given a <span
data-x="concept-response">response</span> <var>response</var> and an <span>environment</span>
<var>reservedEnvironment</var>:</p>
<ol>
<li><p>Let <var>policy</var> be a new <span>opener policy</span>.</p></li>
<li><p>If <var>reservedEnvironment</var> is a <span>non-secure context</span>, then return
<var>policy</var>.</p></li>
<li><p>Let <var>parsedItem</var> be the result of <span>getting a structured field value</span>
given `<code>Cross-Origin-Opener-Policy</code>` and "<code data-x="">item</code>" from
<var>response</var>'s <span data-x="concept-response-header-list">header list</span>.</p></li>
<li>
<p>If <var>parsedItem</var> is not null, then:</p>
<ol>
<li>
<p>If <var>parsedItem</var>[0] is "<code data-x="coop-same-origin">same-origin</code>",
then:</p>
<ol>
<li><p>Let <var>coep</var> be the result of <span data-x="obtain an embedder
policy">obtaining a cross-origin embedder policy</span> from <var>response</var> and
<var>reservedEnvironment</var>.</p></li>
<li><p>If <var>coep</var>'s <span data-x="embedder-policy-value">value</span> is
<span>compatible with cross-origin isolation</span>, then set <var>policy</var>'s <span
data-x="coop-struct-value">value</span> to "<code
data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code>".</p></li>
<li><p>Otherwise, set <var>policy</var>'s <span data-x="coop-struct-value">value</span> to
"<code data-x="coop-same-origin">same-origin</code>".</p></li>
</ol>
</li>
<li><p>If <var>parsedItem</var>[0] is "<code
data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>", then set
<var>policy</var>'s <span data-x="coop-struct-value">value</span> to "<code
data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>".</p></li>
<li><p>If <var>parsedItem</var>[0] is "<code
data-x="coop-noopener-allow-popups">noopener-allow-popups</code>", then set
<var>policy</var>'s <span data-x="coop-struct-value">value</span> to "<code
data-x="coop-noopener-allow-popups">noopener-allow-popups</code>".</p></li>
<li><p>If <var>parsedItem</var>[1]["<code data-x="coop-report-to">report-to</code>"] <span
data-x="map exists">exists</span> and it is a string, then set <var>policy</var>'s <span
data-x="coop-struct-report-endpoint">reporting endpoint</span> to
<var>parsedItem</var>[1]["<code data-x="coop-report-to">report-to</code>"].</p></li>
</ol>
</li>
<li><p>Set <var>parsedItem</var> to the result of <span>getting a structured field value</span>
given `<code>Cross-Origin-Opener-Policy-Report-Only</code>` and "<code data-x="">item</code>"
from <var>response</var>'s <span data-x="concept-response-header-list">header
list</span>.</p></li>
<li>
<p>If <var>parsedItem</var> is not null, then:</p>
<ol>
<li>
<p>If <var>parsedItem</var>[0] is "<code data-x="coop-same-origin">same-origin</code>",
then:</p>
<ol>
<li><p>Let <var>coep</var> be the result of <span data-x="obtain an embedder
policy">obtaining a cross-origin embedder policy</span> from <var>response</var> and
<var>reservedEnvironment</var>.</p></li>
<li>
<p>If <var>coep</var>'s <span data-x="embedder-policy-value">value</span> is
<span>compatible with cross-origin isolation</span> or <var>coep</var>'s <span
data-x="embedder-policy-report-only-value">report-only value</span> is <span>compatible
with cross-origin isolation</span>, then set <var>policy</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> to "<code
data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code>".</p>
<p class="note">Report only COOP also considers report-only COEP to assign the special
"<code data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code>" value. This allows
developers more freedom in the order of deployment of COOP and COEP.</p>
</li>
<li><p>Otherwise, set <var>policy</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> to "<code
data-x="coop-same-origin">same-origin</code>".</p></li>
</ol>
</li>
<li><p>If <var>parsedItem</var>[0] is "<code
data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>", then set
<var>policy</var>'s <span data-x="coop-struct-report-only-value">report-only value</span> to
"<code data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>".</p></li>
<li><p>If <var>parsedItem</var>[1]["<code data-x="coop-report-to">report-to</code>"] <span
data-x="map exists">exists</span> and it is a string, then set <var>policy</var>'s <span
data-x="coop-struct-report-only-endpoint">report-only reporting endpoint</span> to
<var>parsedItem</var>[1]["<code data-x="coop-report-to">report-to</code>"].</p></li>
</ol>
</li>
<li><p>Return <var>policy</var>.</p></li>
</ol>
<h5 id="browsing-context-group-switches-due-to-cross-origin-opener-policy">Browsing context group
switches due to opener policy</h5>
<p>To <dfn data-x="check-browsing-context-group-switch-coop-value-popup">check if popup COOP
values require a browsing context group switch</dfn>, given two <span
data-x="origin">origins</span> <var>responseOrigin</var> and
<var>activeDocumentNavigationOrigin</var>, and two <span data-x="coop-struct-value">opener policy
values</span> <var>responseCOOPValue</var> and <var>activeDocumentCOOPValue</var>:</p>
<ol>
<li><p><var>responseCOOPValue</var> is "<code
data-x="coop-noopener-allow-popups">noopener-allow-popups</code>", then return true.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>activeDocumentCOOPValue</var>'s <span data-x="coop-struct-value">value</span> is
"<code data-x="coop-same-origin-allow-popups">same-origin-allow-popups</code>" or
"<code data-x="coop-noopener-allow-popups">noopener-allow-popups</code>"; and</p></li>
<li><p><var>responseCOOPValue</var> is "<code
data-x="coop-unsafe-none">unsafe-none</code>",</p></li>
</ul>
<p>then return false.</p>
</li>
<li><p>If the result of <span data-x="matching-coop">matching</span>
<var>activeDocumentCOOPValue</var>, <var>activeDocumentNavigationOrigin</var>,
<var>responseCOOPValue</var>, and <var>responseOrigin</var> is true, then return false.</p></li>
<li><p>Return true.</p>
</ol>
<p>To <dfn data-x="check-browsing-context-group-switch-coop-value">check if COOP values require a
browsing context group switch</dfn>, given a boolean <var>isInitialAboutBlank</var>, two <span
data-x="origin">origins</span> <var>responseOrigin</var> and
<var>activeDocumentNavigationOrigin</var>, and two <span data-x="coop-struct-value">opener policy
values</span> <var>responseCOOPValue</var> and <var>activeDocumentCOOPValue</var>:</p>
<ol>
<li><p>If <var>isInitialAboutBlank</var> is true, then return the result of <span
data-x="check-browsing-context-group-switch-coop-value-popup">checking if popup COOP values
requires a browsing context group switch</span> with <var>responseOrigin</var>,
<var>activeDocumentNavigationOrigin</var>, <var>responseCOOPValue</var>, and
<var>activeDocumentCOOPValue</var>.</p></li>
<li>
<p class="note">Here we are dealing with a non-popup navigation.</p>
<p>If the result of <span data-x="matching-coop">matching</span>
<var>activeDocumentCOOPValue</var>, <var>activeDocumentNavigationOrigin</var>,
<var>responseCOOPValue</var>, and <var>responseOrigin</var> is true, then return false.</p>
</li>
<li><p>Return true.</p>
</ol>
<p>To <dfn data-x="check-bcg-switch-navigation-report-only">check if enforcing report-only COOP
would require a browsing context group switch</dfn>, given a boolean
<var>isInitialAboutBlank</var>, two <span data-x="origin">origins</span>
<var>responseOrigin</var>, <var>activeDocumentNavigationOrigin</var>, and two <span data-x="opener
policy">opener policies</span> <var>responseCOOP</var> and <var>activeDocumentCOOP</var>:</p>
<ol>
<li>
<p>If the result of <span data-x="check-browsing-context-group-switch-coop-value">checking if
COOP values require a browsing context group switch</span> given
<var>isInitialAboutBlank</var>, <var>responseOrigin</var>,
<var>activeDocumentNavigationOrigin</var>, <var>responseCOOP</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> and
<var>activeDocumentCOOPReportOnly</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> is false, then return
false.</p>
<p class="note">Matching report-only policies allows a website to specify the same report-only
opener policy on all its pages and not receive violation reports for navigations between these
pages.</p>
</li>
<li><p>If the result of <span data-x="check-browsing-context-group-switch-coop-value">checking
if COOP values require a browsing context group switch</span> given
<var>isInitialAboutBlank</var>, <var>responseOrigin</var>,
<var>activeDocumentNavigationOrigin</var>, <var>responseCOOP</var>'s <span
data-x="coop-struct-value">value</span> and <var>activeDocumentCOOPReportOnly</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> is true, then return
true.</p></li>
<li><p>If the result of <span data-x="check-browsing-context-group-switch-coop-value">checking
if COOP values require a browsing context group switch</span> given
<var>isInitialAboutBlank</var>, <var>responseOrigin</var>,
<var>activeDocumentNavigationOrigin</var>, <var>responseCOOP</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span> and
<var>activeDocumentCOOPReportOnly</var>'s <span data-x="coop-struct-value">value</span> is true,
then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>An <dfn data-x="coop-enforcement-result">opener policy enforcement result</dfn> is a
<span>struct</span> with the following <span data-x="struct item">items</span>:</p>
<ul>
<li><p>A boolean <dfn data-x="coop-enforcement-bcg-switch">needs a browsing context group
switch</dfn>, initially false.</p></li>
<li><p>A boolean <dfn data-x="coop-enforcement-bcg-switch-report-only">would need a browsing
context group switch due to report-only</dfn>, initially false.</p></li>
<li><p>A <span>URL</span> <dfn data-x="coop-enforcement-url">url</dfn>.</p></li>
<li><p>An <span>origin</span> <dfn data-x="coop-enforcement-origin">origin</dfn>.</p></li>
<li><p>An <span>opener policy</span> <dfn data-x="coop-enforcement-coop">opener
policy</dfn>.</p></li>
<li><p>A boolean <dfn data-x="coop-enforcement-source">current context is navigation
source</dfn>, initially false.</p></li>
</ul>
<p>To <dfn data-x="coop-enforce">enforce a response's opener policy</dfn>, given a <span>browsing
context</span> <var>browsingContext</var>, a <span>URL</span> <var>responseURL</var>, an
<span>origin</span> <var>responseOrigin</var>, an <span>opener policy</span>
<var>responseCOOP</var>, an <span data-x="coop-enforcement-result">opener policy enforcement
result</span> <var>currentCOOPEnforcementResult</var>, and a <span
data-x="concept-request-referrer">referrer</span> <var>referrer</var>:</p>
<ol>
<li>
<p>Let <var>newCOOPEnforcementResult</var> be a new <span
data-x="coop-enforcement-result">opener policy enforcement result</span> with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-bcg-switch">needs a browsing context group switch</span></dt>
<dd><var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-bcg-switch">needs
a browsing context group switch</span></dd>
<dt><span data-x="coop-enforcement-bcg-switch-report-only">would need a browsing context group switch due to report-only</span></dt>
<dd><var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-bcg-switch-report-only">would need a browsing context group switch
due to report-only</span></dd>
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>responseURL</var></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>responseCOOP</var></dd>
<dt><span data-x="coop-enforcement-source">current context is navigation source</span></dt>
<dd>true</dd>
</dl>
</li>
<li><p>Let <var>isInitialAboutBlank</var> be <var>browsingContext</var>'s <span>active
document</span>'s <span>is initial <code>about:blank</code></span>.</p></li>
<li><p>If <var>isInitialAboutBlank</var> is true and <var>browsingContext</var>'s <span
data-x="browsing-context-initial-url">initial URL</span> is null, set
<var>browsingContext</var>'s <span data-x="browsing-context-initial-url">initial URL</span> to
<var>responseURL</var>.</p></li>
<li>
<p>If the result of <span data-x="check-browsing-context-group-switch-coop-value">checking if
COOP values require a browsing context group switch</span> given
<var>isInitialAboutBlank</var>, <var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-coop">opener policy</span>'s <span
data-x="coop-struct-value">value</span>, <var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-origin">origin</span>, <var>responseCOOP</var>'s <span
data-x="coop-struct-value">value</span>, and <var>responseOrigin</var> is true, then:</p>
<ol>
<li><p>Set <var>newCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-bcg-switch">needs a browsing context group switch</span> to
true.</p></li>
<li>
<p>If <var>browsingContext</var>'s <span data-x="tlbc group">group</span>'s <span>browsing
context set</span>'s <span data-x="list size">size</span> is greater than 1, then:</p>
<ol>
<li><p><span data-x="coop-violation-navigation-to">Queue a violation report for browsing
context group switch when navigating to a COOP response</span> with <var>responseCOOP</var>,
"<code data-x="">enforce</code>", <var>responseURL</var>,
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-url">url</span>,
<var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-origin">origin</span>, <var>responseOrigin</var>, and
<var>referrer</var>.</p></li>
<li><p><span data-x="coop-violation-navigation-from">Queue a violation report for browsing
context group switch when navigating away from a COOP response</span> with
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-coop">opener
policy</span>, "<code data-x="">enforce</code>", <var>currentCOOPEnforcementResult</var>'s
<span data-x="coop-enforcement-url">url</span>, <var>responseURL</var>,
<var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-origin">origin</span>, <var>responseOrigin</var>, and
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-source">current
context is navigation source</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>If the result of <span data-x="check-bcg-switch-navigation-report-only">checking if
enforcing report-only COOP would require a browsing context group switch</span> given
<var>isInitialAboutBlank</var>, <var>responseOrigin</var>,
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-origin">origin</span>,
<var>responseCOOP</var>, and <var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-coop">opener policy</span>, is true, then:</p>
<ol>
<li><p>Set <var>newCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-bcg-switch-report-only">would
need a browsing context group switch due to report-only</span> to true.</p></li>
<li>
<p>If <var>browsingContext</var>'s <span data-x="tlbc group">group</span>'s <span>browsing
context set</span>'s <span data-x="list size">size</span> is greater than 1, then:</p>
<ol>
<li><p><span data-x="coop-violation-navigation-to">Queue a violation report for browsing
context group switch when navigating to a COOP response</span> with <var>responseCOOP</var>,
"<code data-x="">reporting</code>", <var>responseURL</var>,
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-url">url</span>,
<var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-origin">origin</span>, <var>responseOrigin</var>, and
<var>referrer</var>.</p></li>
<li><p><span data-x="coop-violation-navigation-from">Queue a violation report for browsing
context group switch when navigating away from a COOP response</span> with
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-coop">opener
policy</span>, "<code data-x="">reporting</code>",
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-url">url</span>,
<var>responseURL</var>, <var>currentCOOPEnforcementResult</var>'s <span
data-x="coop-enforcement-origin">origin</span>, <var>responseOrigin</var>, and
<var>currentCOOPEnforcementResult</var>'s <span data-x="coop-enforcement-source">current
context is navigation source</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>newCOOPEnforcementResult</var>.</p></li>
</ol>
<p>To <dfn data-x="obtain-browsing-context-navigation">obtain a browsing context to use for a
navigation response</dfn>, given <span>navigation params</span> <var>navigationParams</var>:</p>
<ol>
<li><p>Let <var>browsingContext</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>'s <span data-x="nav-bc">active browsing
context</span>.</p></li>
<li><p>If <var>browsingContext</var> is not a <span>top-level browsing context</span>, then
return <var>browsingContext</var>.</p></li>
<li><p>Let <var>coopEnforcementResult</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span>.</p></li>
<li><p>Let <var>swapGroup</var> be <var>coopEnforcementResult</var>'s <span
data-x="coop-enforcement-bcg-switch">needs a browsing context group switch</span>.</p></li>
<li><p>Let <var>sourceOrigin</var> be <var>browsingContext</var>'s
<span>active document</span>'s <span data-x="concept-document-origin">origin</span>.</p></li>
<li><p>Let <var>destinationOrigin</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-origin">origin</span>.</p></li>
<li>
<p>If <var>sourceOrigin</var> is not <span>same site</span> with
<var>destinationOrigin</var>:</p>
<ol>
<li>
<p>If either of <var>sourceOrigin</var> or <var>destinationOrigin</var> have a <span
data-x="concept-origin-scheme">scheme</span> that is not an <span>HTTP(S) scheme</span> and
the user agent considers it necessary for <var>sourceOrigin</var> and
<var>destinationOrigin</var> to be isolated from each other (for
<span>implementation-defined</span> reasons), optionally set <var>swapGroup</var> to true.</p>
<p class="note">For example, if a user navigates from <code data-x="">about:settings</code> to
<code data-x="">https://example.com</code>, the user agent could force a swap.</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/10842">Issue #10842</a> tracks
settling on an interoperable behavior here, instead of letting this be optional.</p>
</li>
<li>
<p>If <var>navigationParams</var>'s <span data-x="navigation-params-user-involvement"> user
involvement</span> is "<code data-x="uni-browser-ui">browser UI</code>", optionally set
<var>swapGroup</var> to true.</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/6356">Issue #6356</a> tracks
settling on an interoperable behavior here, instead of letting this be optional.</p>
</li>
</ol>
</li>
<li>
<p>If <var>browsingContext</var>'s <span data-x="tlbc group">group</span>'s <span>browsing
context set</span>'s <span data-x="list size">size</span> is 1, optionally set
<var>swapGroup</var> to true.</p>
<p class="note">Some implementations swap browsing context groups here for performance
reasons.</p>
<p class="note">The check for other contexts that could script this one is not sufficient to
prevent differences in behavior that could affect a web page. Even if there are currently no
other contexts, the destination page could open a window, then if the user navigates back, the
previous page could expect to be able to script the opened window. Doing a swap here would break
that use case.</p>
</li>
<li>
<p>If <var>swapGroup</var> is false, then:</p>
<ol>
<li><p>If <var>coopEnforcementResult</var>'s <span
data-x="coop-enforcement-bcg-switch-report-only">would need a browsing context group switch
due to report-only</span> is true, set <var>browsingContext</var>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span> to a new
unique identifier.</p></li>
<li><p>Return <var>browsingContext</var>.</p></li>
</ol>
</li>
<li>
<p>Let <var>newBrowsingContext</var> be the first return value of <span>creating a new
top-level browsing context and document</span>.</p>
<p class="note">In this case we are going to perform a browsing context group swap.
<var>browsingContext</var> will not be used by the new <code>Document</code> that we are about
to <span data-x="create-the-document-object">create</span>. If it is not used by other
<code>Document</code>s either (such as ones in the back/forward cache), then the user agent
might <a href="#a-browsing-context-is-discarded">destroy it</a> at this point.</p>
</li>
<li><p>Let <var>navigationCOOP</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-coop">cross-origin opener policy</span>.</p></li>
<li>
<p>If <var>navigationCOOP</var>'s <span data-x="coop-struct-value">value</span> is "<code
data-x="coop-same-origin-plus-COEP">same-origin-plus-COEP</code>", then set
<var>newBrowsingContext</var>'s <span data-x="tlbc group">group</span>'s <span
data-x="bcg-cross-origin-isolation">cross-origin isolation mode</span> to either "<code
data-x="cross-origin-isolation-logical">logical</code>" or "<code
data-x="cross-origin-isolation-concrete">concrete</code>". The choice of which is
<span>implementation-defined</span>.</p>
<p class="note">It is difficult on some platforms to provide the security properties required
by the <span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin
isolated capability</span>. "<code data-x="cross-origin-isolation-concrete">concrete</code>"
grants access to it and "<code data-x="cross-origin-isolation-logical">logical</code>" does
not.</p>
</li>
<li><p>Let <var>sandboxFlags</var> be a <span data-x="list clone">clone</span> of
<var>navigationParams</var>'s <span
data-x="navigation-params-sandboxing">final sandboxing flag set</span>.</p></li>
<li>
<p>If <var>sandboxFlags</var> is not empty, then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigationCOOP</var>'s <span data-x="coop-struct-value">value</span> is
"<code data-x="coop-unsafe-none">unsafe-none</code>".</p></li>
<li><p><span>Assert</span>: <var>newBrowsingContext</var>'s <span>popup sandboxing flag
set</span> <span data-x="list is empty">is empty</span>.</p></li>
<li><p>Set <var>newBrowsingContext</var>'s <span>popup sandboxing flag set</span> to
<var>sandboxFlags</var>.</p></li>
</ol>
</li>
<li><p>Return <var>newBrowsingContext</var>.</p></li>
</ol>
<h5 id="coop-reporting"><span id="reporting"></span>Reporting</h5>
<p>An <dfn>accessor-accessed relationship</dfn> is an enum that describes the relationship
between two <span data-x="browsing context">browsing contexts</span> between which an access
happened. It can take the following values:</p>
<dl>
<dt><dfn data-x="accessor-accessed-opener">accessor is opener</dfn></dt>
<dd><p>The accessor <span>browsing context</span> or one of its <span data-x="ancestor browsing
context">ancestors</span> is the <span>opener browsing context</span> of the accessed
<span>browsing context</span>'s <span data-x="bc-tlbc">top-level browsing
context</span>.</p></dd>
<dt><dfn data-x="accessor-accessed-openee">accessor is openee</dfn></dt>
<dd><p>The accessed <span>browsing context</span> or one of its <span data-x="ancestor browsing
context">ancestors</span> is the <span>opener browsing context</span> of the accessor
<span>browsing context</span>'s <span data-x="bc-tlbc">top-level browsing
context</span>.</p></dd>
<dt><dfn data-x="accessor-accessed-none">none</dfn></dt>
<dd><p>There is no opener relationship between the accessor <span>browsing context</span>, the
accessor <span>browsing context</span>, or any of their <span data-x="ancestor browsing
context">ancestors</span>.</p></dd>
</dl>
<p>To <dfn data-x="coop-check-access-report">check if an access between two browsing contexts
should be reported</dfn>, given two <span data-x="browsing context">browsing contexts</span>
<var>accessor</var> and <var>accessed</var>, a JavaScript property name <var>P</var>, and an
<span>environment settings object</span> <var>environment</var>:</p>
<ol>
<li><p>If <var>P</var> is not a <span>cross-origin accessible window property name</span>, then
return.</p></li>
<li><p><span>Assert</span>: <var>accessor</var>'s <span>active document</span> and
<var>accessed</var>'s <span>active document</span> are both <span>fully active</span>.</p></li>
<li><p>Let <var>accessorTopDocument</var> be <var>accessor</var>'s <span
data-x="bc-tlbc">top-level browsing context</span>'s <span>active document</span>.</p></li>
<li><p>Let <var>accessorInclusiveAncestorOrigins</var> be the list obtained by taking the <span
data-x="concept-document-origin">origin</span> of the <span data-x="nav-document">active
document</span> of each of <var>accessor</var>'s <span>active document</span>'s <span>inclusive
ancestor navigables</span>.</p></li>
<li><p>Let <var>accessedTopDocument</var> be <var>accessed</var>'s <span
data-x="bc-tlbc">top-level browsing context</span>'s <span>active document</span>.</p></li>
<li><p>Let <var>accessedInclusiveAncestorOrigins</var> be the list obtained by taking the <span
data-x="concept-document-origin">origin</span> of the <span data-x="nav-document">active
document</span> of each of <var>accessed</var>'s <span>active document</span>'s <span>inclusive
ancestor navigables</span>.</p></li>
<li>
<p>If any of <var>accessorInclusiveAncestorOrigins</var> are not <span>same origin</span> with
<var>accessorTopDocument</var>'s <span data-x="concept-document-origin">origin</span>, or if
any of <var>accessedInclusiveAncestorOrigins</var> are not <span>same origin</span> with
<var>accessedTopDocument</var>'s <span data-x="concept-document-origin">origin</span>, then
return.</p>
<p class="note">This avoids leaking information about cross-origin iframes to a top level frame
with opener policy reporting.</p>
</li>
<li><p>If <var>accessor</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span> is
<var>accessed</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span>, then
return.</p></li>
<li><p>Let <var>accessorAccessedRelationship</var> be a new <span>accessor-accessed
relationship</span> with value <span data-x="accessor-accessed-none">none</span>.</p></li>
<li><p>If <var>accessed</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s
<span>opener browsing context</span> is <var>accessor</var> or is an <span data-x="ancestor
browsing context">ancestor</span> of <var>accessor</var>, then set
<var>accessorAccessedRelationship</var> to <span data-x="accessor-accessed-opener">accessor is
opener</span>.</p></li>
<li><p>If <var>accessor</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s
<span>opener browsing context</span> is <var>accessed</var> or is an <span data-x="ancestor
browsing context">ancestor</span> of <var>accessed</var>, then set
<var>accessorAccessedRelationship</var> to <span data-x="accessor-accessed-openee">accessor is
openee</span>.</p></li>
<li><p><span data-x="coop-violation-access">Queue violation reports for accesses</span>, given
<var>accessorAccessedRelationship</var>, <var>accessorTopDocument</var>'s <span
data-x="concept-document-coop">opener policy</span>, <var>accessedTopDocument</var>'s <span
data-x="concept-document-coop">opener policy</span>, <var>accessor</var>'s <span>active
document</span>'s <span data-x="concept-document-url">URL</span>, <var>accessed</var>'s
<span>active document</span>'s <span data-x="concept-document-url">URL</span>,
<var>accessor</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="browsing-context-initial-url">initial URL</span>, <var>accessed</var>'s <span
data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="browsing-context-initial-url">initial URL</span>, <var>accessor</var>'s <span>active
document</span>'s <span data-x="concept-document-origin">origin</span>, <var>accessed</var>'s
<span>active document</span>'s <span data-x="concept-document-origin">origin</span>,
<var>accessor</var>'s <span data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="opener-origin-at-creation">opener origin at creation</span>, <var>accessed</var>'s <span
data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="opener-origin-at-creation">opener origin at creation</span>,
<var>accessorTopDocument</var>'s <span data-x="dom-document-referrer">referrer</span>,
<var>accessedTopDocument</var>'s <span data-x="dom-document-referrer">referrer</span>,
<var>P</var>, and <var>environment</var>.</p></li>
</ol>
<p>To <dfn data-x="sanitize-url-report">sanitize a URL to send in a report</dfn> given a
<span>URL</span> <var>url</var>:</p>
<ol>
<li><p>Let <var>sanitizedURL</var> be a copy of <var>url</var>.</p></li>
<li><p><span data-x="set the username">Set the username</span> given <var>sanitizedURL</var> and
the empty string.
<li><p><span data-x="set the password">Set the password</span> given <var>sanitizedURL</var> and
the empty string.
<li><p>Return the <span data-x="concept-url-serializer">serialization</span> of
<var>sanitizedURL</var> with <span data-x="url serializer exclude fragment"><i>exclude
fragment</i></span> set to true.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-navigation-to">queue a violation report for browsing context
group switch when navigating to a COOP response</dfn> given an <span data-x="opener policy">opener
policy</span> <var>coop</var>, a string <var>disposition</var>, a <span>URL</span>
<var>coopURL</var>, a <span>URL</span> <var>previousResponseURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>previousResponseOrigin</var>, and a
<span data-x="concept-request-referrer">referrer</span> <var>referrer</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li><p>Let <var>coopValue</var> be <var>coop</var>'s <span
data-x="coop-struct-value">value</span>.</p></li>
<li><p>If <var>disposition</var> is "<code data-x="">reporting</code>", then set
<var>coopValue</var> to <var>coop</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span>.</p></li>
<li><p>Let <var>serializedReferrer</var> be an empty string.</p></li>
<li><p>If <var>referrer</var> is a <span>URL</span>, set <var>serializedReferrer</var> to the
<span data-x="concept-url-serializer">serialization</span> of <var>referrer</var>.
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td><var>disposition</var></td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coopValue</var></td>
</tr>
<tr>
<td>previousResponseURL</td>
<td>If <var>coopOrigin</var> and <var>previousResponseOrigin</var> are <span>same origin</span> this is the <span data-x="sanitize-url-report">sanitization</span> of <var>previousResponseURL</var>, null otherwise.</td>
</tr>
<tr>
<td>referrer</td>
<td><var>serializedReferrer</var></td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">navigation-to-response</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code
data-x="">coop</code>" for <var>coop</var>'s <span
data-x="coop-struct-report-endpoint">reporting endpoint</span> with <var>coopURL</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-navigation-from">queue a violation report for browsing context
group switch when navigating away from a COOP response</dfn> given an <span data-x="opener
policy">opener policy</span> <var>coop</var>, a string <var>disposition</var>, a <span>URL</span>
<var>coopURL</var>, a <span>URL</span> <var>nextResponseURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>nextResponseOrigin</var>, and a
boolean <var>isCOOPResponseNavigationSource</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li><p>Let <var>coopValue</var> be <var>coop</var>'s <span
data-x="coop-struct-value">value</span>.</p></li>
<li><p>If <var>disposition</var> is "<code data-x="">reporting</code>", then set
<var>coopValue</var> to <var>coop</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span>.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td><var>disposition</var></td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coopValue</var></td>
</tr>
<tr>
<td>nextResponseURL</td>
<td>If <var>coopOrigin</var> and <var>nextResponseOrigin</var> are <span>same origin</span>
or <var>isCOOPResponseNavigationSource</var> is true, this is the <span
data-x="sanitize-url-report">sanitization</span> of <var>nextResponseURL</var>, null otherwise.</td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">navigation-from-response</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code
data-x="">coop</code>" for <var>coop</var>'s <span
data-x="coop-struct-report-endpoint">reporting endpoint</span> with <var>coopURL</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access">queue violation reports for accesses</dfn>, given an
<span>accessor-accessed relationship</span> <var>accessorAccessedRelationship</var>, two <span
data-x="opener policy">opener policies</span> <var>accessorCOOP</var> and <var>accessedCOOP</var>,
four <span data-x="url">URLs</span> <var>accessorURL</var>, <var>accessedURL</var>,
<var>accessorInitialURL</var>, <var>accessedInitialURL</var>, four <span
data-x="origin">origins</span> <var>accessorOrigin</var>, <var>accessedOrigin</var>,
<var>accessorCreatorOrigin</var> and <var>accessedCreatorOrigin</var>, two <span
data-x="dom-document-referrer">referrers</span> <var>accessorReferrer</var> and
<var>accessedReferrer</var>, a string <var>propertyName</var>, and an <span>environment settings
object</span> <var>environment</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li><p>Let <var>coopValue</var> be <var>coop</var>'s <span
data-x="coop-struct-value">value</span>.</p></li>
<li><p>If <var>disposition</var> is "<code data-x="">reporting</code>", then set
<var>coopValue</var> to <var>coop</var>'s <span
data-x="coop-struct-report-only-value">report-only value</span>.</p></li>
<li>
<p>If <var>accessorAccessedRelationship</var> is <span
data-x="accessor-accessed-opener">accessor is opener</span>:</p>
<ol>
<li><p><span data-x="coop-violation-access-to-opened">Queue a violation report
for access to an opened window</span>, given <var>accessorCOOP</var>, <var>accessorURL</var>,
<var>accessedURL</var>, <var>accessedInitialURL</var>, <var>accessorOrigin</var>,
<var>accessedOrigin</var>, <var>accessedCreatorOrigin</var>, <var>propertyName</var>,
and <var>environment</var>.</p></li>
<li><p><span data-x="coop-violation-access-from-opener">Queue a violation report for access
from the opener</span>, given <var>accessedCOOP</var>, <var>accessedURL</var>,
<var>accessorURL</var>, <var>accessedOrigin</var>, <var>accessorOrigin</var>,
<var>propertyName</var>, and <var>accessedReferrer</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>accessorAccessedRelationship</var> is <span
data-x="accessor-accessed-openee">accessor is openee</span>:</p>
<ol>
<li><p><span data-x="coop-violation-access-to-opener">Queue a violation report for access to
the opener</span>, given <var>accessorCOOP</var>, <var>accessorURL</var>,
<var>accessedURL</var>, <var>accessorOrigin</var>, <var>accessedOrigin</var>,
<var>propertyName</var>, <var>accessorReferrer</var>, and <var>environment</var>.</p></li>
<li><p><span data-x="coop-violation-access-from-opened">Queue a violation report for access
from an opened window</span>, given <var>accessedCOOP</var>, <var>accessedURL</var>,
<var>accessorURL</var>, <var>accessorInitialURL</var>, <var>accessedOrigin</var>,
<var>accessorOrigin</var>, <var>accessorCreatorOrigin</var>, and
<var>propertyName</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span data-x="coop-violation-access-to-opened">Queue a violation report for
access to another window</span>, given <var>accessorCOOP</var>, <var>accessorURL</var>,
<var>accessedURL</var>, <var>accessorOrigin</var>, <var>accessedOrigin</var>,
<var>propertyName</var>, and <var>environment</var></p></li>
<li><p><span data-x="coop-violation-access-from-other">Queue a violation report for
access from another window</span>, given <var>accessedCOOP</var>, <var>accessedURL</var>,
<var>accessorURL</var>, <var>accessedOrigin</var>, <var>accessorOrigin</var>, and
<var>propertyName</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn data-x="coop-violation-access-to-opener">queue a violation report for access to the
opener</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>, two
<span data-x="URL">URLs</span> <var>coopURL</var> and <var>openerURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>openerOrigin</var>, a string
<var>propertyName</var>, a <span data-x="concept-request-referrer">referrer</span>
<var>referrer</var>, and an <span>environment settings object</span> <var>environment</var>:</p>
<ol>
<li><p>Let <var>sourceFile</var>, <var>lineNumber</var> and <var>columnNumber</var> be the
relevant script URL and problematic position which triggered this report.</p></li>
<li><p>Let <var>serializedReferrer</var> be an empty string.</p></li>
<li><p>If <var>referrer</var> is a <span>URL</span>, set <var>serializedReferrer</var> to the
<span data-x="concept-url-serializer">serialization</span> of <var>referrer</var>.
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>property</td>
<td><var>propertyName</var></td>
</tr>
<tr>
<td>openerURL</td>
<td>If <var>coopOrigin</var> and <var>openerOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>openerURL</var>, null
otherwise.</td>
</tr>
<tr>
<td>referrer</td>
<td><var>serializedReferrer</var></td>
</tr>
<tr>
<td>sourceFile</td>
<td><var>sourceFile</var></td>
</tr>
<tr>
<td>lineNumber</td>
<td><var>lineNumber</var></td>
</tr>
<tr>
<td>columnNumber</td>
<td><var>columnNumber</var></td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">access-to-opener</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code
data-x="">coop</code>" for <var>coop</var>'s <span
data-x="coop-struct-report-endpoint">reporting endpoint</span> with <var>coopURL</var> and
<var>environment</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access-to-opened">queue a violation report for access to an
opened window</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>,
three <span data-x="URL">URLs</span> <var>coopURL</var>, <var>openedWindowURL</var> and
<var>initialWindowURL</var>, three <span data-x="origin">origins</span> <var>coopOrigin</var>,
<var>openedWindowOrigin</var>, and <var>openerInitialOrigin</var>, a string
<var>propertyName</var>, and an <span>environment settings object</span>
<var>environment</var>:</p>
<ol>
<li><p>Let <var>sourceFile</var>, <var>lineNumber</var> and <var>columnNumber</var> be the
relevant script URL and problematic position which triggered this report.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>property</td>
<td><var>propertyName</var></td>
</tr>
<tr>
<td>openedWindowURL</td>
<td>If <var>coopOrigin</var> and <var>openedWindowOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>openedWindowURL</var>,
null otherwise.</td>
</tr>
<tr>
<td>openedWindowInitialURL</td>
<td>If <var>coopOrigin</var> and <var>openerInitialOrigin</var> are <span>same origin</span>,
this is the <span data-x="sanitize-url-report">sanitization</span> of
<var>initialWindowURL</var>, null otherwise.</td>
</tr>
<tr>
<td>sourceFile</td>
<td><var>sourceFile</var></td>
</tr>
<tr>
<td>lineNumber</td>
<td><var>lineNumber</var></td>
</tr>
<tr>
<td>columnNumber</td>
<td><var>columnNumber</var></td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">access-to-opener</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code data-x="">coop</code>"
for <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span> with
<var>coopURL</var> and <var>environment</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access-to-other">queue a violation report for access to another
window</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>, two
<span data-x="URL">URLs</span> <var>coopURL</var> and <var>otherURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>otherOrigin</var>, a string
<var>propertyName</var>, and an <span>environment settings object</span>
<var>environment</var>:</p>
<ol>
<li><p>Let <var>sourceFile</var>, <var>lineNumber</var> and <var>columnNumber</var> be the
relevant script URL and problematic position which triggered this report.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>property</td>
<td><var>propertyName</var></td>
</tr>
<tr>
<td>otherURL</td>
<td>If <var>coopOrigin</var> and <var>otherOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>otherURL</var>, null
otherwise.</td>
</tr>
<tr>
<td>sourceFile</td>
<td><var>sourceFile</var></td>
</tr>
<tr>
<td>lineNumber</td>
<td><var>lineNumber</var></td>
</tr>
<tr>
<td>columnNumber</td>
<td><var>columnNumber</var></td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">access-to-opener</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code data-x="">coop</code>"
for <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span> with
<var>coopURL</var> and <var>environment</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access-from-opener">queue a violation report for access from the
opener</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>, two
<span data-x="URL">URLs</span> <var>coopURL</var> and <var>openerURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>openerOrigin</var>, a string
<var>propertyName</var>, and a <span data-x="concept-request-referrer">referrer</span>
<var>referrer</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li><p>Let <var>serializedReferrer</var> be an empty string.</p></li>
<li><p>If <var>referrer</var> is a <span>URL</span>, set <var>serializedReferrer</var> to the
<span data-x="concept-url-serializer">serialization</span> of <var>referrer</var>.
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>property</td>
<td><var>propertyName</var></td>
</tr>
<tr>
<td>openerURL</td>
<td>If <var>coopOrigin</var> and <var>openerOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>openerURL</var>, null
otherwise.</td>
</tr>
<tr>
<td>referrer</td>
<td><var>serializedReferrer</var></td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">access-to-opener</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code data-x="">coop</code>"
for <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span> with
<var>coopURL</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access-from-opened">queue a violation report for access from an
opened window</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>,
three <span data-x="URL">URLs</span> <var>coopURL</var>, <var>openedWindowURL</var> and
<var>initialWindowURL</var>, three <span data-x="origin">origins</span> <var>coopOrigin</var>,
<var>openedWindowOrigin</var>, and <var>openerInitialOrigin</var>, and a string
<var>propertyName</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coopValue</var></td>
</tr>
<tr>
<td>property</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>openedWindowURL</td>
<td>If <var>coopOrigin</var> and <var>openedWindowOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>openedWindowURL</var>,
null otherwise.</td>
</tr>
<tr>
<td>openedWindowInitialURL</td>
<td>If <var>coopOrigin</var> and <var>openerInitialOrigin</var> are <span>same origin</span>,
this is the <span data-x="sanitize-url-report">sanitization</span> of
<var>initialWindowURL</var>, null otherwise.</td>
</tr>
<tr>
<td>type</td>
<td>"<code data-x="">access-to-opener</code>"</td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code data-x="">coop</code>"
for <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span> with
<var>coopURL</var>.</p></li>
</ol>
<p>To <dfn data-x="coop-violation-access-from-other">queue a violation report for access from
another window</dfn>, given an <span data-x="opener policy">opener policy</span> <var>coop</var>,
two <span data-x="URL">URLs</span> <var>coopURL</var> and <var>otherURL</var>, two <span
data-x="origin">origins</span> <var>coopOrigin</var> and <var>otherOrigin</var>, and a string
<var>propertyName</var>:</p>
<ol>
<li><p>If <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span>
is null, return.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>disposition</td>
<td>"<code data-x="">reporting</code>"</td>
</tr>
<tr>
<td>effectivePolicy</td>
<td><var>coop</var>'s <span data-x="coop-struct-report-only-value">report-only
value</span></td>
</tr>
<tr>
<td>property</td>
<td><var>propertyName</var></td>
</tr>
<tr>
<td>otherURL</td>
<td>If <var>coopOrigin</var> and <var>otherOrigin</var> are <span>same origin</span>, this
is the <span data-x="sanitize-url-report">sanitization</span> of <var>otherURL</var>, null
otherwise.</td>
</tr>
<tr>
<td>type</td>
<td><code data-x="">access-to-opener</code></td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as "<code data-x="">coop</code>"
for <var>coop</var>'s <span data-x="coop-struct-report-endpoint">reporting endpoint</span> with
<var>coopURL</var>.</p></li>
</ol>
</div>
<h4 id="coep">Cross-origin embedder policies</h4>
<p>An <dfn export>embedder policy value</dfn> is one of three strings that controls the fetching
of cross-origin resources without explicit permission from resource owners.</p>
<dl>
<dt>"<dfn data-x="coep-unsafe-none" export for="embedder policy value"><code
data-x="">unsafe-none</code></dfn>"</dt>
<dd><p>This is the default value. When this value is used, cross-origin resources can be fetched
without giving explicit permission through the <span>CORS protocol</span> or the
`<code>Cross-Origin-Resource-Policy</code>` header.</p></dd>
<dt>"<dfn data-x="coep-require-corp" export for="embedder policy value"><code
data-x="">require-corp</code></dfn>"</dt>
<dd><p>When this value is used, fetching cross-origin resources requires the server's
explicit permission through the <span>CORS protocol</span> or the
`<code>Cross-Origin-Resource-Policy</code>` header.</p></dd>
<dt>"<dfn data-x="coep-credentialless" export for="embedder policy value"><code
data-x="">credentialless</code></dfn>"</dt>
<dd><p>When this value is used, fetching cross-origin no-CORS resources omits credentials. In
exchange, an explicit `<code>Cross-Origin-Resource-Policy</code>` header is not required. Other
requests sent with credentials require the server's explicit permission through the <span>CORS
protocol</span> or the `<code>Cross-Origin-Resource-Policy</code>` header.</p></dd>
</dl>
<div class="warning">
<p>Before supporting "<code data-x="coep-credentialless">credentialless</code>", implementers are
strongly encouraged to support both:
<ul class="brief">
<li><a href="https://wicg.github.io/private-network-access/">Private Network Access</a></li>
<li><a href="https://github.com/annevk/orb">Opaque Response Blocking</a></li>
</ul>
<p>Otherwise, it would allow attackers to leverage the client's network position to read non
public resources, using the <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p>
</div>
<p>An <span>embedder policy value</span> is <dfn>compatible with cross-origin isolation</dfn> if
it is "<code data-x="coep-credentialless">credentialless</code>" or "<code
data-x="coep-require-corp">require-corp</code>".</p>
<div w-nodev>
<p>An <dfn export>embedder policy</dfn> consists of:</p>
<ul>
<li><p>A <dfn data-x="embedder-policy-value" for="embedder policy"
export>value</dfn>, which is an <span>embedder policy value</span>, initially "<code
data-x="coep-unsafe-none">unsafe-none</code>".</p></li>
<li><p>A <dfn data-x="embedder-policy-reporting-endpoint" for="embedder policy"
export>reporting endpoint</dfn> string, initially the empty string.</p></li>
<li><p>A <dfn data-x="embedder-policy-report-only-value" for="embedder policy"
export>report only value</dfn>, which is an <span>embedder policy value</span>, initially
"<code data-x="coep-unsafe-none">unsafe-none</code>".</p></li>
<li><p>A <dfn data-x="embedder-policy-report-only-reporting-endpoint" for="embedder
policy" export>report only reporting endpoint</dfn> string, initially the empty
string.</p></li>
</ul>
<p>The <dfn export>"<code>coep</code>" report type</dfn> is a <span>report type</span> whose value
is "<code data-x="">coep</code>". It is <span>visible to
<code>ReportingObserver</code>s</span>.</p>
</div>
<h5 id="the-coep-headers">The headers</h5>
<p>The `<dfn http-header><code>Cross-Origin-Embedder-Policy</code></dfn>` and
`<dfn http-header><code>Cross-Origin-Embedder-Policy-Report-Only</code></dfn>` HTTP response
headers allow a server to declare an <span>embedder policy</span> for an <span>environment
settings object</span>. These headers are <span data-x="http-structured-header">structured
headers</span> whose values must be <span data-x="http-structured-header-token">token</span>.
<ref>STRUCTURED-FIELDS</ref>
<p>The valid <span
data-x="http-structured-header-token">token</span> values are the <span data-x="embedder policy
value">embedder policy values</span>. The token may also have attached <span
data-x="http-structured-header-parameters">parameters</span>; of these, the "<dfn
data-x="coep-report-to"><code>report-to</code></dfn>" parameter can have a <span>valid URL
string</span> identifying an appropriate reporting endpoint. <ref>REPORTING</ref></p>
<div class="note">
<p>The <span data-x="obtain an embedder policy">processing model</span> fails open (by defaulting
to "<code data-x="coep-unsafe-none">unsafe-none</code>") in the presence of a header that cannot
be parsed as a token. This includes inadvertent lists created by combining multiple instances of
the `<code>Cross-Origin-Embedder-Policy</code>` header present in a given response:</p>
<table class="data">
<thead>
<tr>
<th>`<code>Cross-Origin-Embedder-Policy</code>`</th>
<th>Final <span>embedder policy value</span></th>
</tr>
</thead>
<tbody>
<tr>
<td><em>No header delivered</em></td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
<tr>
<td>`<code data-x="">require-corp</code>`</td>
<td>"<code data-x="coep-require-corp">require-corp</code>"</td>
</tr>
<tr>
<td>`<code data-x="">unknown-value</code>`</td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
<tr>
<td>`<code data-x="">require-corp, unknown-value</code>`</td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
<tr>
<td>`<code data-x="">unknown-value, unknown-value</code>`</td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
<tr>
<td>`<code data-x="">unknown-value, require-corp</code>`</td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
<tr>
<td>`<code data-x="">require-corp, require-corp</code>`</td>
<td>"<code data-x="coep-unsafe-none">unsafe-none</code>"</td>
</tr>
</tbody>
</table>
<p>(The same applies to `<code>Cross-Origin-Embedder-Policy-Report-Only</code>`.)</p>
</div>
<div w-nodev>
<hr>
<p>To <dfn export>obtain an embedder policy</dfn> from a <span
data-x="concept-response">response</span> <var>response</var> and an <span>environment</span>
<var>environment</var>:</p>
<ol>
<li><p>Let <var>policy</var> be a new <span>embedder policy</span>.</p></li>
<li><p>If <var>environment</var> is a <span>non-secure context</span>, then return
<var>policy</var>.</p></li>
<li><p>Let <var>parsedItem</var> be the result of <span>getting a structured field value</span>
with `<code>Cross-Origin-Embedder-Policy</code>` and "<code data-x="">item</code>" from
<var>response</var>'s <span data-x="concept-response-header-list">header list</span>.</p></li>
<li>
<p>If <var>parsedItem</var> is non-null and <var>parsedItem</var>[0] is <span>compatible with
cross-origin isolation</span>:</p>
<ol>
<li><p>Set <var>policy</var>'s <span data-x="embedder-policy-value">value</span> to
<var>parsedItem</var>[0].</p></li>
<li><p>If <var>parsedItem</var>[1]["<code data-x="coep-report-to">report-to</code>"] <span
data-x="map exists">exists</span>, then set <var>policy</var>'s <span
data-x="embedder-policy-reporting-endpoint">endpoint</span> to
<var>parsedItem</var>[1]["<code data-x="coep-report-to">report-to</code>"].</p></li>
</ol>
</li>
<li><p>Set <var>parsedItem</var> to the result of <span>getting a structured field value</span>
with `<code>Cross-Origin-Embedder-Policy-Report-Only</code>` and "<code data-x="">item</code>"
from <var>response</var>'s <span data-x="concept-response-header-list">header
list</span>.</p></li>
<li>
<p>If <var>parsedItem</var> is non-null and <var>parsedItem</var>[0] is <span>compatible with
cross-origin isolation</span>:</p>
<ol>
<li><p>Set <var>policy</var>'s <span
data-x="embedder-policy-report-only-value">report only value</span> to
<var>parsedItem</var>[0].</p></li>
<li><p>If <var>parsedItem</var>[1]["<code data-x="coep-report-to">report-to</code>"] <span
data-x="map exists">exists</span>, then set <var>policy</var>'s <span
data-x="embedder-policy-report-only-reporting-endpoint">endpoint</span> to
<var>parsedItem</var>[1]["<code data-x="coep-report-to">report-to</code>"].</p></li>
</ol>
</li>
<li><p>Return <var>policy</var>.</p></li>
</ol>
<h5>Embedder policy checks</h5>
<p>To <dfn>check a navigation response's adherence to its embedder policy</dfn> given a <span
data-x="concept-response">response</span> <var>response</var>, a <span>navigable</span>
<var>navigable</var>, and an <span>embedder policy</span> <var>responsePolicy</var>:</p>
<ol>
<li><p>If <var>navigable</var> is not a <span>child navigable</span>, then return
true.</p></li>
<li><p>Let <var>parentPolicy</var> be <var>navigable</var>'s <span
data-x="nav-container-document">container document</span>'s <span
data-x="concept-document-policy-container">policy container</span>'s <span
data-x="policy-container-embedder-policy">embedder policy</span>.</p></li>
<li><p>If <var>parentPolicy</var>'s <span data-x="embedder-policy-report-only-value">report-only
value</span> is <span>compatible with cross-origin isolation</span> and
<var>responsePolicy</var>'s <span data-x="embedder-policy-value">value</span> is not, then
<span>queue a cross-origin embedder policy inheritance violation</span> with <var>response</var>,
"<code data-x="">navigation</code>", <var>parentPolicy</var>'s <span
data-x="embedder-policy-report-only-reporting-endpoint">report only reporting endpoint</span>,
"<code data-x="">reporting</code>", and <var>navigable</var>'s <span
data-x="nav-container-document">container document</span>'s <span>relevant settings
object</span>.</p></li>
<li><p>If <var>parentPolicy</var>'s <span data-x="embedder-policy-value">value</span> is not
<span>compatible with cross-origin isolation</span> or <var>responsePolicy</var>'s <span
data-x="embedder-policy-value">value</span> is <span>compatible with cross-origin
isolation</span>, then return true.</p></li>
<li><p><span>Queue a cross-origin embedder policy inheritance violation</span> with
<var>response</var>, "<code data-x="">navigation</code>", <var>parentPolicy</var>'s <span
data-x="embedder-policy-reporting-endpoint">reporting endpoint</span>,
"<code data-x="">enforce</code>", and <var>navigable</var>'s
<span data-x="nav-container-document">container document</span>'s <span>relevant settings
object</span>.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn>check a global object's embedder policy</dfn> given a <code>WorkerGlobalScope</code>
<var>workerGlobalScope</var>, an <span>environment settings object</span> <var>owner</var>, and
a <span data-x="concept-response">response</span> <var>response</var>:</p>
<ol>
<li><p>If <var>workerGlobalScope</var> is not a <code>DedicatedWorkerGlobalScope</code> object,
then return true.</p></li>
<li><p>Let <var>policy</var> be <var>workerGlobalScope</var>'s <span
data-x="concept-WorkerGlobalScope-embedder-policy">embedder policy</span>.
<li><p>Let <var>ownerPolicy</var> be <var>owner</var>'s <span
data-x="concept-settings-object-policy-container">policy container</span>'s <span
data-x="policy-container-embedder-policy">embedder policy</span>.
<li><p>If <var>ownerPolicy</var>'s <span data-x="embedder-policy-report-only-value">report-only
value</span> is <span>compatible with cross-origin isolation</span> and <var>policy</var>'s
<span data-x="embedder-policy-value">value</span> is not, then <span>queue a cross-origin
embedder policy inheritance violation</span> with <var>response</var>, "<code data-x="">worker
initialization</code>", <var>ownerPolicy</var>'s <span
data-x="embedder-policy-report-only-reporting-endpoint">report only reporting endpoint</span>,
"<code data-x="">reporting</code>", and <var>owner</var>.</p></li>
<li><p>If <var>ownerPolicy</var>'s <span data-x="embedder-policy-value">value</span> is not
<span>compatible with cross-origin isolation</span> or <var>policy</var>'s <span
data-x="embedder-policy-value">value</span> is <span>compatible with cross-origin
isolation</span>, then return true.</p></li>
<li><p><span>Queue a cross-origin embedder policy inheritance violation</span> with
<var>response</var>, "<code data-x="">worker initialization</code>", <var>ownerPolicy</var>'s
<span data-x="embedder-policy-reporting-endpoint">reporting endpoint</span>,
"<code data-x="">enforce</code>", and <var>owner</var>.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn>queue a cross-origin embedder policy inheritance violation</dfn> given a <span
data-x="concept-response">response</span> <var>response</var>, a string <var>type</var>, a string
<var>endpoint</var>, a string <var>disposition</var>, and an <span>environment settings
object</span> <var>settings</var>:</p>
<ol>
<li><p>Let <var>serialized</var> be the result of <span
data-x="serialize-a-response-url-for-reporting">serializing a response URL for
reporting</span> with <var>response</var>.</p></li>
<li>
<p>Let <var>body</var> be a new object containing the following properties:</p>
<table class="data">
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td><var>type</var></td>
</tr>
<tr>
<td>blockedURL</td>
<td><var>serialized</var></td>
</tr>
<tr>
<td>disposition</td>
<td><var>disposition</var></td>
</tr>
</tbody>
</table>
</li>
<li><p><span data-x="queue a report">Queue</span> <var>body</var> as the
<span>"<code>coep</code>" report type</span> for <var>endpoint</var> on <var>settings</var>.
</ol>
</div>
<h4>Sandboxing</h4>
<p>A <dfn export>sandboxing flag set</dfn> is a set of zero or more of the following flags, which
are used to restrict the abilities that potentially untrusted resources have:</p>
<dl>
<dt>The <dfn export>sandboxed navigation browsing context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxLinks">prevents content from navigating browsing contexts other
than the sandboxed browsing context itself</a> (or browsing contexts further nested inside it),
<span data-x="auxiliary browsing context">auxiliary browsing contexts</span> (which are protected
by the <span>sandboxed auxiliary navigation browsing context flag</span> defined next), and the
<span>top-level browsing context</span> (which is protected by the <span>sandboxed top-level
navigation without user activation browsing context flag</span> and <span>sandboxed top-level
navigation with user activation browsing context flag</span> defined below).</p>
<p>If the <span>sandboxed auxiliary navigation browsing context flag</span> is not set, then in
certain cases the restrictions nonetheless allow popups (new <span data-x="top-level browsing
context">top-level browsing contexts</span>) to be opened. These <span data-x="browsing
context">browsing contexts</span> always have <dfn>one permitted sandboxed navigator</dfn>, set
when the browsing context is created, which allows the <span>browsing context</span> that
created them to actually navigate them. (Otherwise, the <span>sandboxed navigation browsing
context flag</span> would prevent them from being navigated even if they were opened.)</p>
</dd>
<dt>The <dfn export>sandboxed auxiliary navigation browsing context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxWindowOpen">prevents content from creating new auxiliary browsing
contexts</a>, e.g. using the <code data-x="attr-hyperlink-target">target</code> attribute or
the <code data-x="dom-open">window.open()</code> method.</p>
</dd>
<dt>The <dfn export>sandboxed top-level navigation without user activation browsing
context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxLinks">prevents content from navigating their <span>top-level
browsing context</span></a> and <a href="#sandboxClose">prevents content from closing their
<span>top-level browsing context</span></a>. It is consulted only when the sandboxed browsing
context's <span>active window</span> does not have <span>transient activation</span>.</p>
<p>When the <span>sandboxed top-level navigation without user activation browsing context
flag</span> is <em>not</em> set, content can navigate its <span>top-level browsing
context</span>, but other <span data-x="browsing context">browsing contexts</span> are still
protected by the <span>sandboxed navigation browsing context flag</span> and possibly
the <span>sandboxed auxiliary navigation browsing context flag</span>.</p>
</dd>
<dt>The <dfn export>sandboxed top-level navigation with user activation browsing context
flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxLinks">prevents content from navigating their <span>top-level
browsing context</span></a> and <a href="#sandboxClose">prevents content from closing their
<span>top-level browsing context</span></a>. It is consulted only when the sandboxed browsing
context's <span>active window</span> has <span>transient activation</span>.</p>
<p>As with the <span>sandboxed top-level navigation without user activation browsing context
flag</span>, this flag only affects the <span>top-level browsing context</span>; if it is not
set, other <span data-x="browsing context">browsing contexts</span> might still be protected by
other flags.</p>
</dd>
<dt>The <dfn export>sandboxed origin browsing context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxOrigin">forces content into an opaque origin</a>, thus preventing
it from accessing other content from the same <span>origin</span>.</p>
<p>This flag also <a href="#sandboxCookies">prevents script from reading from or writing to the
<code data-x="dom-document-cookie">document.cookie</code> IDL attribute</a>, and blocks access
to <code data-x="dom-localStorage">localStorage</code>.</p>
</dd>
<dt>The <dfn export>sandboxed forms browsing context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxSubmitBlocked">blocks form submission</a>.</p>
</dd>
<dt>The <dfn export>sandboxed pointer lock browsing context flag</dfn></dt>
<dd>
<p>This flag disables the Pointer Lock API. <ref>POINTERLOCK</ref></p>
</dd>
<dt>The <dfn export>sandboxed scripts browsing context flag</dfn></dt>
<dd>
<p>This flag <a href="#sandboxScriptBlocked">blocks script execution</a>.</p>
</dd>
<dt>The <dfn export>sandboxed automatic features browsing context flag</dfn></dt>
<dd>
<p>This flag blocks features that trigger automatically, such as <span
data-x="attr-media-autoplay">automatically playing a video</span> or <span
data-x="attr-fe-autofocus">automatically focusing a form control</span>.</p>
</dd>
<dt>The <dfn export>sandboxed <code data-x="dom-document-domain">document.domain</code>
browsing context flag</dfn></dt>
<dd>
<p>This flag prevents content from using the
<code data-x="dom-document-domain">document.domain</code> setter.</p>
</dd>
<dt>The <dfn export>sandbox propagates to auxiliary browsing contexts flag</dfn></dt>
<dd>
<p>This flag prevents content from escaping the sandbox by ensuring that any
<span>auxiliary browsing context</span> it creates inherits the content's
<span>active sandboxing flag set</span>.</p>
</dd>
<dt>The <dfn export>sandboxed modals flag</dfn></dt>
<dd>
<p>This flag prevents content from using any of the following features to produce modal
dialogs:</p>
<ul>
<li><code data-x="dom-alert">window.alert()</code></li>
<li><code data-x="dom-confirm">window.confirm()</code></li>
<li><code data-x="dom-print">window.print()</code></li>
<li><code data-x="dom-prompt">window.prompt()</code></li>
<li>the <code data-x="event-beforeunload">beforeunload</code> event</li>
</ul>
</dd>
<dt>The <dfn export>sandboxed orientation lock browsing context flag</dfn></dt>
<dd>
<p>This flag disables the ability to lock the screen orientation.
<ref>SCREENORIENTATION</ref></p>
</dd>
<dt>The <dfn export>sandboxed presentation browsing context flag</dfn></dt>
<dd>
<p>This flag disables the Presentation API. <ref>PRESENTATION</ref></p>
</dd>
<dt>The <dfn export>sandboxed downloads browsing context flag</dfn></dt>
<dd>
<p>This flag prevents content from initiating or instantiating downloads, whether through <span
data-x="downloading hyperlinks">downloading hyperlinks</span> or through <a
href="#navigation-as-a-download">navigation</a> that gets <span data-x="handle as a
download">handled as a download</span>.</p>
</dd>
<dt>The <dfn export>sandboxed custom protocols navigation browsing context flag</dfn></dt>
<dd>
<p>This flag prevents navigations toward non <span data-x="fetch scheme">fetch schemes</span>
from being <span data-x="hand-off to external software">handed off to external
software</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>When the user agent is to <dfn export>parse a sandboxing directive</dfn>, given a string
<var>input</var> and a <span>sandboxing flag set</span> <var>output</var>, it must run the following
steps:</p>
<ol>
<li><p><span data-x="split a string on ASCII whitespace">Split <var>input</var> on ASCII
whitespace</span>, to obtain <var>tokens</var>.</p></li>
<li><p>Let <var>output</var> be empty.</p></li>
<li>
<p>Add the following flags to <var>output</var>:</p>
<ul>
<li><p>The <span>sandboxed navigation browsing context flag</span>.</p></li>
<li><p>The <span>sandboxed auxiliary navigation browsing context flag</span>, unless
<var>tokens</var> contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code></dfn> keyword.</p></li>
<li><p>The <span>sandboxed top-level navigation without user activation browsing context
flag</span>, unless <var>tokens</var> contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code></dfn>
keyword.</p></li>
<li>
<p>The <span>sandboxed top-level navigation with user activation browsing context flag</span>,
unless <var>tokens</var> contains either the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code></dfn>
keyword or the <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> keyword.</p>
<p class="note">This means that if the <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code> is present, the <code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>
keyword will have no effect. For this reason, specifying both is a document conformance error.</p>
</li>
<li>
<p>The <span>sandboxed origin browsing context flag</span>, unless the <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code></dfn> keyword.</p>
<div class="note">
<p>The <code data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code> keyword
is intended for two cases.</p>
<p>First, it can be used to allow content from the same site to be sandboxed to disable
scripting, while still allowing access to the DOM of the sandboxed content.</p>
<p>Second, it can be used to embed content from a third-party site, sandboxed to prevent that
site from opening popups, etc, without preventing the embedded page from communicating back
to its originating site, using the database APIs to store data, etc.</p>
</div>
</li>
<li><p>The <span>sandboxed forms browsing context flag</span>, unless <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-forms">allow-forms</code></dfn> keyword.</p></li>
<li><p>The <span>sandboxed pointer lock browsing context flag</span>, unless <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-pointer-lock">allow-pointer-lock</code></dfn>
keyword.</p></li>
<li><p>The <span>sandboxed scripts browsing context flag</span>, unless <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code></dfn> keyword.</p></li>
<li>
<p>The <span>sandboxed automatic features browsing context flag</span>, unless
<var>tokens</var> contains the <code
data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code> keyword (defined above).</p>
<p class="note">This flag is relaxed by the same keyword as scripts, because when scripts are
enabled these features are trivially possible anyway, and it would be unfortunate to force
authors to use script to do them when sandboxed rather than allowing them to use the
declarative features.</p>
</li>
<li><p>The <span>sandboxed <code data-x="dom-document-domain">document.domain</code> browsing
context flag</span>.</p></li>
<li><p>The <span>sandbox propagates to auxiliary browsing contexts flag</span>, unless
<var>tokens</var> contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-popups-to-escape-sandbox">allow-popups-to-escape-sandbox</code></dfn>
keyword.</p></li>
<li><p>The <span>sandboxed modals flag</span>, unless <var>tokens</var> contains the <dfn
attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-modals">allow-modals</code></dfn> keyword.</p></li>
<li><p>The <span>sandboxed orientation lock browsing context flag</span>, unless
<var>tokens</var> contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-orientation-lock">allow-orientation-lock</code></dfn>
keyword.</p></li>
<li><p>The <span>sandboxed presentation browsing context flag</span>, unless <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-presentation">allow-presentation</code></dfn>
keyword.</p></li>
<li><p>The <span>sandboxed downloads browsing context flag</span>, unless <var>tokens</var>
contains the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-downloads">allow-downloads</code></dfn> keyword.</p></li>
<li><p>The <span>sandboxed custom protocols navigation browsing context flag</span>, unless
<var>tokens</var> contains either the <dfn attr-value for="iframe/sandbox"><code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code></dfn>
keyword, the <code data-x="attr-iframe-sandbox-allow-popups">allow-popups</code> keyword, or
the <code data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code>
keyword.</p></li>
</ul>
</li>
</ol>
<hr>
<p>Every <span>top-level browsing context</span> has a <dfn>popup sandboxing flag set</dfn>, which
is a <span>sandboxing flag set</span>. When a <span>browsing context</span> is created, its
<span>popup sandboxing flag set</span> must be empty. It is populated by <span>the rules for
choosing a navigable</span> and the <span data-x="obtain-browsing-context-navigation">obtain
a browsing context to use for a navigation response</span> algorithm.</p>
<p>Every <code>iframe</code> element has an <dfn><code>iframe</code> sandboxing flag set</dfn>,
which is a <span>sandboxing flag set</span>. Which flags in an <span><code>iframe</code>
sandboxing flag set</span> are set at any particular time is determined by the <code>iframe</code>
element's <code data-x="attr-iframe-sandbox">sandbox</code> attribute.</p>
<p>Every <code>Document</code> has an <dfn for="Document" export>active sandboxing flag set</dfn>,
which is a <span>sandboxing flag set</span>. When the <code>Document</code> is created, its
<span>active sandboxing flag set</span> must be empty. It is populated by the <span
data-x="navigate">navigation algorithm</span>.</p>
<p id="forced-sandboxing-flag-set">Every <span data-x="concept-csp-list">CSP list</span>
<var>cspList</var> has <dfn>CSP-derived sandboxing flags</dfn>, which is a <span>sandboxing flag
set</span>. It is the return value of the following algorithm:</p>
<ol>
<li><p>Let <var>directives</var> be an empty <span data-x="set">ordered set</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> policy in <var>cspList</var>:</p>
<ol>
<li><p>If <var>policy</var>'s <span data-x="csp-disposition">disposition</span> is not "<code
data-x="">enforce</code>", then <span>continue</span>.</p></li>
<li><p>If <var>policy</var>'s <span data-x="csp-directive-set">directive set</span> <span
data-x="list contains">contains</span> a <span data-x="Content Security Policy
directive">directive</span> whose name is "<code data-x="sandbox directive">sandbox</code>",
then <span data-x="list append">append</span> that directive to
<var>directives</var>.</p></li>
</ol>
</li>
<li><p>If <var>directives</var> is empty, then return an empty <span>sandboxing flag
set</span>.</p></li>
<li><p>Let <var>directive</var> be <var>directives</var>[<var>directives</var>'s <span
data-x="list size">size</span> − 1].</p></li>
<li><p>Return the result of <span data-x="parse a sandboxing directive">parsing the sandboxing
directive</span> <var>directive</var>.</p></li>
</ol>
<hr>
<p>To <dfn data-x="determining the creation sandboxing flags">determine the creation sandboxing
flags</dfn> for a <span data-x="concept-document-bc">browsing context</span> <var>browsing
context</var>, given null or an element <var>embedder</var>, return the <span data-x="set
union">union</span> of the flags that are present in the following <span data-x="sandboxing flag
set">sandboxing flag sets</span>:</p>
<ul>
<li><p>If <var>embedder</var> is null, then: the flags set on <var>browsing context</var>'s
<span>popup sandboxing flag set</span>.</p></li>
<li><p>If <var>embedder</var> is an element, then: the flags set on <var>embedder</var>'s
<span><code>iframe</code> sandboxing flag set</span>.</p></li>
<li><p>If <var>embedder</var> is an element, then: the flags set on <var>embedder</var>'s
<span>node document</span>'s <span>active sandboxing flag set</span>.</p></li>
</ul>
<h4 id="policy-containers">Policy containers</h4>
<p>A <dfn export>policy container</dfn> is a <span>struct</span> containing policies that apply to
a <code>Document</code>, a <code>WorkerGlobalScope</code>, or a <code>WorkletGlobalScope</code>.
It has the following <span data-x="struct item">items</span>:</p>
<!-- Note: each item has to define a default value for creating a new policy container. -->
<ul>
<li><p>A <dfn export for="policy container" data-x="policy-container-csp-list">CSP list</dfn>,
which is a <span data-x="concept-csp-list">CSP list</span>. It is initially empty.</p></li>
<li><p>An <dfn export for="policy container" data-x="policy-container-embedder-policy">embedder
policy</dfn>, which is an <span>embedder policy</span>. It is initially a new <span>embedder
policy</span>.</p></li>
<li><p>A <dfn export for="policy container" data-x="policy-container-referrer-policy">referrer
policy</dfn>, which is a <span>referrer policy</span>. It is initially the <span>default referrer
policy</span>.</p></li>
</ul>
<p class="XXX">Move other policies into the policy container.</p>
<p>To <dfn export>clone a policy container</dfn> given a <span>policy container</span>
<var>policyContainer</var>:</p>
<ol>
<li><p>Let <var>clone</var> be a new <span>policy container</span>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>policy</var> in
<var>policyContainer</var>'s <span data-x="policy-container-csp-list">CSP list</span>, <span
data-x="list append">append</span> a copy of <var>policy</var> into <var>clone</var>'s <span
data-x="policy-container-csp-list">CSP list</span>.</p></li>
<li><p>Set <var>clone</var>'s <span data-x="policy-container-embedder-policy">embedder
policy</span> to a copy of <var>policyContainer</var>'s <span
data-x="policy-container-embedder-policy">embedder policy</span>.</p></li>
<li><p>Set <var>clone</var>'s <span data-x="policy-container-referrer-policy">referrer
policy</span> to <var>policyContainer</var>'s <span
data-x="policy-container-referrer-policy">referrer policy</span>.</p></li>
<li><p>Return <var>clone</var>.</p></li>
</ol>
<p>To determine whether a <span>URL</span> <var>url</var> <dfn>requires storing the policy
container in history</dfn>:</p>
<ol>
<li><p>If <var>url</var>'s <span data-x="concept-url-scheme">scheme</span> is "<code
data-x="">blob</code>", then return false.</p></li>
<!-- Note that we are not storing the policy container in history for blob URLs since we can
always retrieve again a blob URL entry's environment's policy container during a history
navigation. Indeed, as per https://www.w3.org/TR/FileAPI/#lifeTime, if the environment that
created the blob URL is dead at the point of the history navigation, then the blob URL itself
must have been deleted, too. We might want to store the policy container alongside the blob URL
entry directly (https://github.com/w3c/FileAPI/issues/142), and then reconsider this. -->
<!-- See about:srcdoc discussion:
https://github.com/whatwg/html/issues/6809#issuecomment-1170924595 -->
<li><p>If <var>url</var> <span data-x="is-local">is local</span>, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn export data-lt="creating a policy container from a fetch response" data-x="creating a
policy container from a fetch response">create a policy container from a fetch response</dfn>
given a <span data-x="concept-response">response</span> <var>response</var> and an
<span>environment</span>-or-null <var>environment</var>:</p>
<ol>
<li><p>If <var>response</var>'s <span data-x="concept-response-url">URL</span>'s <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">blob</code>", then return a <span
data-x="clone a policy container">clone</span> of <var>response</var>'s <span
data-x="concept-response-url">URL</span>'s <span data-x="concept-url-blob-entry">blob URL
entry</span>'s <span data-x="blob-url-entry-environment">environment</span>'s <span>policy
container</span>.</p></li>
<li><p>Let <var>result</var> be a new <span>policy container</span>.</p></li>
<li><p>Set <var>result</var>'s <span data-x="policy-container-csp-list">CSP list</span> to the
result of <span data-x="parse-response-csp">parsing a response's Content Security Policies</span>
given <var>response</var>.</p></li>
<li><p>If <var>environment</var> is non-null, then set <var>result</var>'s <span
data-x="policy-container-embedder-policy">embedder policy</span> to the result of <span
data-x="obtain an embedder policy">obtaining an embedder policy</span> given <var>response</var>
and <var>environment</var>. Otherwise, set it to "<code
data-x="coep-unsafe-none">unsafe-none</code>".</p></li>
<li><p>Set <var>result</var>'s <span data-x="policy-container-referrer-policy">referrer
policy</span> to the result of <span data-x="parse-referrer-policy-header">parsing the
`<code>Referrer-Policy</code>` header</span> given <var>response</var>.
<ref>REFERRERPOLICY</ref></p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p>To <dfn data-x="determining navigation params policy container">determine navigation params
policy container</dfn> given a <span>URL</span> <var>responseURL</var> and four <span
data-x="policy container">policy container</span>-or-nulls <var>historyPolicyContainer</var>,
<var>initiatorPolicyContainer</var>, <var>parentPolicyContainer</var>, and
<var>responsePolicyContainer</var>:</p>
<ol>
<li>
<p>If <var>historyPolicyContainer</var> is not null, then:</p>
<ol>
<li><p><span>Assert</span>: <var>responseURL</var> <span>requires storing the policy container
in history</span>.</p></li>
<li><p>Return a <span data-x="clone a policy container">clone</span> of
<var>historyPolicyContainer</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>responseURL</var> is <code>about:srcdoc</code>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>parentPolicyContainer</var> is not null.</p></li>
<li><p>Return a <span data-x="clone a policy container">clone</span> of
<var>parentPolicyContainer</var>.</p></li>
</ol>
</li>
<li><p>If <var>responseURL</var> <span data-x="is-local">is local</span> and
<var>initiatorPolicyContainer</var> is not null, then return a <span data-x="clone a policy
container">clone</span> of <var>initiatorPolicyContainer</var>.</p></li>
<li><p>If <var>responsePolicyContainer</var> is not null, then return
<var>responsePolicyContainer</var>.</p></li>
<li><p>Return a new <span>policy container</span>.</p></li>
</ol>
<p>To <dfn data-x="initialize worker policy container">initialize a worker global scope's policy
container</dfn> given a <code>WorkerGlobalScope</code> <var>workerGlobalScope</var>, a <span
data-x="concept-response">response</span> <var>response</var>, and an <span>environment</span>
<var>environment</var>:</p>
<ol>
<li>
<p>If <var>workerGlobalScope</var>'s <span data-x="concept-WorkerGlobalScope-url">url</span>
<span data-x="is-local">is local</span> but its <span data-x="concept-url-scheme">scheme</span>
is not "<code data-x="">blob</code>":</p>
<ol>
<li><p><span>Assert</span>: <var>workerGlobalScope</var>'s <span>owner set</span>'s <span
data-x="list size">size</span> is 1.</p></li>
<li><p>Set <var>workerGlobalScope</var>'s <span
data-x="concept-WorkerGlobalScope-policy-container">policy container</span> to a <span
data-x="clone a policy container">clone</span> of <var>workerGlobalScope</var>'s <span>owner
set</span>[0]'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-policy-container">policy container</span>.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>workerGlobalScope</var>'s <span
data-x="concept-WorkerGlobalScope-policy-container">policy container</span> to the result of
<span>creating a policy container from a fetch response</span> given
<var>response</var> and <var>environment</var>.</p></li>
</ol>
</div>
<h3 id="nav-traversal-apis" split-filename="nav-history-apis">APIs related to navigation and
session history</h3>
<div w-nodev>
<h4 id="cross-origin-objects">Security infrastructure for <code>Window</code>,
<code>WindowProxy</code>, and <code>Location</code> objects</h4>
<p>Although typically objects cannot be accessed across <span data-x="origin">origins</span>, the
web platform would not be true to itself if it did not have some legacy exceptions to that rule
that the web depends upon.</p>
<p>This section uses the terminology and typographic conventions from the JavaScript
specification. <ref>JAVASCRIPT</ref></p>
<h5>Integration with IDL</h5>
<p>When <span>perform a security check</span> is invoked, with a <var>platformObject</var>,
<var>identifier</var>, and <var>type</var>, run these steps:</p>
<ol>
<li><p>If <var>platformObject</var> is not a <code>Window</code> or <code>Location</code> object,
then return.</p></li>
<li>
<p>For each <var>e</var> of <span>CrossOriginProperties</span>(<var>platformObject</var>):</p>
<ol>
<li>
<p>If <span>SameValue</span>(<var>e</var>.[[Property]], <var>identifier</var>) is true,
then:</p>
<ol>
<li><p>If <var>type</var> is "<code data-x="">method</code>" and <var>e</var> has neither
[[NeedsGet]] nor [[NeedsSet]], then return.</p></li>
<li><p>Otherwise, if <var>type</var> is "<code data-x="">getter</code>" and
<var>e</var>.[[NeedsGet]] is true, then return.</p></li>
<li><p>Otherwise, if <var>type</var> is "<code data-x="">setter</code>" and
<var>e</var>.[[NeedsSet]] is true, then return.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<var>platformObject</var>) is false, then
throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h5>Shared internal slot: [[CrossOriginPropertyDescriptorMap]]</h5>
<p><code>Window</code> and <code>Location</code> objects both have a
<dfn>[[CrossOriginPropertyDescriptorMap]]</dfn> internal slot, whose value is initially an empty
map.</p>
<p>The <span>[[CrossOriginPropertyDescriptorMap]]</span> internal slot contains a map
with entries whose keys are (<var>currentGlobal</var>, <var>objectGlobal</var>,
<var>propertyKey</var>)-tuples and values are property descriptors, as a memoization of what is
visible to scripts when <var>currentGlobal</var> inspects a <code>Window</code> or
<code>Location</code> object from <var>objectGlobal</var>. It is filled lazily by
<span>CrossOriginGetOwnPropertyHelper</span>, which consults it on future lookups.</p>
<p>User agents should allow a value held in the map to be garbage collected along with its
corresponding key when nothing holds a reference to any part of the value. That is, as long as
garbage collection is not observable.</p>
<p class="example">For example, with <code data-x="">const href =
Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set</code> the value and its
corresponding key in the map cannot be garbage collected as that would be observable.</p>
<p>User agents may have an optimization whereby they remove key-value pairs from the map when
<code data-x="dom-document-domain">document.domain</code> is set. This is not observable as <code
data-x="dom-document-domain">document.domain</code> cannot revisit an earlier value.</p>
<p class="example">For example, setting <code data-x="dom-document-domain">document.domain</code>
to "<code data-x="">example.com</code>" on www.example.com means user agents can remove all
key-value pairs from the map where part of the key is www.example.com, as that can never be part
of the <span>origin</span> again and therefore the corresponding value could never be retrieved
from the map.</p>
<h5>Shared abstract operations</h5>
<h6><dfn>CrossOriginProperties</dfn> ( <var>O</var> )</h6>
<ol>
<li><p><span>Assert</span>: <var>O</var> is a <code>Location</code> or <code>Window</code>
object.</p></li>
<li><p>If <var>O</var> is a <code>Location</code> object, then return «
{ [[Property]]: "<code data-x="">href</code>", [[NeedsGet]]: false, [[NeedsSet]]: true },
{ [[Property]]: "<code data-x="">replace</code>" } ».</p></li>
<li><p>Return «
{ [[Property]]: "<code data-x="">window</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">self</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">location</code>", [[NeedsGet]]: true, [[NeedsSet]]: true },
{ [[Property]]: "<code data-x="">close</code>" },
{ [[Property]]: "<code data-x="">closed</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">focus</code>" },
{ [[Property]]: "<code data-x="">blur</code>" },
{ [[Property]]: "<code data-x="">frames</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">length</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">top</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">opener</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">parent</code>", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "<code data-x="">postMessage</code>" } ».</p></li>
</ol>
<p class="note">This abstract operation does not return a <span>Completion Record</span>.</p>
<p class="note">Indexed properties do not need to be safelisted in this algorithm, as they are
handled directly by the <code>WindowProxy</code> object.</p>
<p>A JavaScript property name <var>P</var> is a <dfn>cross-origin accessible window property
name</dfn> if it is "<code data-x="">window</code>", "<code data-x="">self</code>", "<code
data-x="">location</code>", "<code data-x="">close</code>", "<code data-x="">closed</code>",
"<code data-x="">focus</code>", "<code data-x="">blur</code>", "<code data-x="">frames</code>",
"<code data-x="">length</code>", "<code data-x="">top</code>", "<code data-x="">opener</code>",
"<code data-x="">parent</code>", "<code data-x="">postMessage</code>", or an <span>array index
property name</span>.</p>
<h6><dfn>CrossOriginPropertyFallback</dfn> ( <var>P</var> )</h6>
<ol>
<li><p>If <var>P</var> is "<code data-x="">then</code>", <span>%Symbol.toStringTag%</span>,
<span>%Symbol.hasInstance%</span>, or <span>%Symbol.isConcatSpreadable%</span>, then return
<span>PropertyDescriptor</span>{
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: true }.</p></li>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h6><dfn>IsPlatformObjectSameOrigin</dfn> ( <var>O</var> )</h6>
<ol>
<li><p>Return true if the <span>current settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span> is <span>same origin-domain</span> with
<var>O</var>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, and false otherwise.</p></li>
</ol>
<p class="note">This abstract operation does not return a <span>Completion Record</span>.</p>
<p class="note">Here the <span>current settings object</span> roughly corresponds to the "caller",
because this check occurs before the <span data-x="JavaScript execution context">execution
context</span> for the getter/setter/method in question makes its way onto the <span>JavaScript
execution context stack</span>. For example, in the code <code data-x="">w.document</code>, this
step is invoked before the <code data-x="dom-document">document</code> getter is reached as part
of the <a href="#windowproxy-get">[[Get]]</a> algorithm for the <code>WindowProxy</code>
<var>w</var>.</p>
<h6><dfn>CrossOriginGetOwnPropertyHelper</dfn> ( <var>O</var>, <var>P</var> )</h6>
<p class="note">If this abstract operation returns undefined and there is no custom behavior, the
caller needs to throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>. In
practice this is handled by the caller calling <span>CrossOriginPropertyFallback</span>.</p>
<ol>
<li><p>Let <var>crossOriginKey</var> be a tuple consisting of the <span>current settings
object</span>, <var>O</var>'s <span>relevant settings object</span>, and <var>P</var>.</p></li>
<li>
<p>For each <var>e</var> of <span>CrossOriginProperties</span>(<var>O</var>):</p>
<ol>
<li>
<p>If <span>SameValue</span>(<var>e</var>.[[Property]], <var>P</var>) is true, then:</p>
<ol>
<li><p>If the value of the <span>[[CrossOriginPropertyDescriptorMap]]</span> internal slot of
<var>O</var> contains an entry whose key is <var>crossOriginKey</var>, then return that
entry's value.</p></li>
<li><p>Let <var>originalDesc</var> be <span>OrdinaryGetOwnProperty</span>(<var>O</var>,
<var>P</var>).</p></li>
<li><p>Let <var>crossOriginDesc</var> be undefined.</p></li>
<li>
<p>If <var>e</var>.[[NeedsGet]] and <var>e</var>.[[NeedsSet]] are absent, then:</p>
<ol>
<li><p>Let <var>value</var> be <var>originalDesc</var>.[[Value]].</p></li>
<li><p>If <span>IsCallable</span>(<var>value</var>) is true, then set <var>value</var> to
an anonymous built-in function, created in the <span>current realm</span>, that performs
the same steps as the IDL operation <var>P</var> on object <var>O</var>.</p></li>
<li><p>Set <var>crossOriginDesc</var> to <span>PropertyDescriptor</span>{
[[Value]]: <var>value</var>,
[[Enumerable]]: false,
[[Writable]]: false,
[[Configurable]]: true }.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>crossOriginGet</var> be undefined.</p></li>
<li><p>If <var>e</var>.[[NeedsGet]] is true, then set <var>crossOriginGet</var> to an
anonymous built-in function, created in the <span>current realm</span>, that performs the
same steps as the getter of the IDL attribute <var>P</var> on object
<var>O</var>.</p></li>
<li><p>Let <var>crossOriginSet</var> be undefined.</p></li>
<li><p>If <var>e</var>.[[NeedsSet]] is true, then set <var>crossOriginSet</var> to an
anonymous built-in function, created in the <span>current realm</span>, that performs the
same steps as the setter of the IDL attribute <var>P</var> on object
<var>O</var>.</p></li>
<li><p>Set <var>crossOriginDesc</var> to <span>PropertyDescriptor</span>{
[[Get]]: <var>crossOriginGet</var>,
[[Set]]: <var>crossOriginSet</var>,
[[Enumerable]]: false,
[[Configurable]]: true }.</p></li>
</ol>
</li>
<li><p>Create an entry in the value of the <span>[[CrossOriginPropertyDescriptorMap]]</span>
internal slot of <var>O</var> with key <var>crossOriginKey</var> and value
<var>crossOriginDesc</var>.</p></li>
<li><p>Return <var>crossOriginDesc</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return undefined.</p></li>
</ol>
<p class="note">This abstract operation does not return a <span>Completion Record</span>.</p>
<p class="note">The reason that the property descriptors produced here are configurable is to
preserve the <span>invariants of the essential internal methods</span> required by the JavaScript
specification. In particular, since the value of the property can change as a consequence of
navigation, it is required that the property be configurable. (However, see <a
href="https://github.com/tc39/ecma262/issues/672">tc39/ecma262 issue #672</a> and references to it
elsewhere in this specification for cases where we are not able to preserve these invariants, for
compatibility with existing web content.) <ref>JAVASCRIPT</ref></p>
<p class="note">The reason the property descriptors are non-enumerable, despite this mismatching
the same-origin behavior, is for compatibility with existing web content. See <a
href="https://github.com/whatwg/html/issues/3183">issue #3183</a> for details.</p>
<h6><dfn>CrossOriginGet</dfn> ( <var>O</var>, <var>P</var>, <var>Receiver</var> )</h6>
<ol>
<li><p>Let <var>desc</var> be ? <var>O</var>.[[GetOwnProperty]](<var>P</var>).</p></li>
<li><p><span>Assert</span>: <var>desc</var> is not undefined.</p></li>
<li><p>If <span>IsDataDescriptor</span>(<var>desc</var>) is true, then return
<var>desc</var>.[[Value]].</p></li>
<li><p><span>Assert</span>: <span>IsAccessorDescriptor</span>(<var>desc</var>) is true.</p></li>
<li><p>Let <var>getter</var> be <var>desc</var>.[[Get]].</p></li>
<li><p>If <var>getter</var> is undefined, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Return ? <span>Call</span>(<var>getter</var>, <var>Receiver</var>).</p></li>
</ol>
<h6><dfn>CrossOriginSet</dfn> ( <var>O</var>, <var>P</var>, <var>V</var>,
<var>Receiver</var> )</h6>
<ol>
<li><p>Let <var>desc</var> be ? <var>O</var>.[[GetOwnProperty]](<var>P</var>).</p></li>
<li><p><span>Assert</span>: <var>desc</var> is not undefined.</p></li>
<li>
<p>If <var>desc</var>.[[Set]] is present and its value is not undefined, then:
<ol>
<li><p>Perform ? <span>Call</span>(<var>desc</var>.[[Set]], <var>Receiver</var>,
« <var>V</var> »).</p></li>
<li><p>Return true.</p></li>
</ol>
</li>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h6><dfn>CrossOriginOwnPropertyKeys</dfn> ( <var>O</var> )</h6>
<ol>
<li><p>Let <var>keys</var> be a new empty <span data-x="js-List">List</span>.</p></li>
<li><p>For each <var>e</var> of <span>CrossOriginProperties</span>(<var>O</var>), <span
data-x="list append">append</span> <var>e</var>.[[Property]] to <var>keys</var>.</p></li>
<li><p>Return the concatenation of <var>keys</var> and « "<code data-x="">then</code>",
<span>%Symbol.toStringTag%</span>, <span>%Symbol.hasInstance%</span>, <span>%Symbol.isConcatSpreadable%</span>
».</p></li>
</ol>
<p class="note">This abstract operation does not return a <span>Completion Record</span>.</p>
</div>
<h4>The <code>Window</code> object</h4>
<pre><code class="idl">[Global=Window,
Exposed=Window,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface>Window</dfn> : <span>EventTarget</span> {
// the current browsing context
[<span>LegacyUnforgeable</span>] readonly attribute <span>WindowProxy</span> <span data-x="dom-window">window</span>;
[Replaceable] readonly attribute <span>WindowProxy</span> <span data-x="dom-self">self</span>;
[<span>LegacyUnforgeable</span>] readonly attribute <span>Document</span> <span data-x="dom-document">document</span>;
attribute DOMString <span data-x="dom-name">name</span>; <!-- not [Replaceable] per WebKit and IE8 -->
[PutForwards=<span data-x="dom-location-href">href</span>, <span>LegacyUnforgeable</span>] readonly attribute <span>Location</span> <span data-x="dom-location">location</span>;
readonly attribute <span>History</span> <span data-x="dom-history">history</span>;
readonly attribute <span>Navigation</span> <span data-x="dom-navigation">navigation</span>;
readonly attribute <span>CustomElementRegistry</span> <span data-x="dom-window-customElements">customElements</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-locationbar">locationbar</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-menubar">menubar</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-personalbar">personalbar</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-scrollbars">scrollbars</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-statusbar">statusbar</span>;
[Replaceable] readonly attribute <span>BarProp</span> <span data-x="dom-window-toolbar">toolbar</span>;
attribute DOMString <span data-x="dom-window-status">status</span>;
undefined <span data-x="dom-window-close">close</span>();
readonly attribute boolean <span data-x="dom-window-closed">closed</span>;
undefined <span data-x="dom-window-stop">stop</span>();
undefined <span data-x="dom-window-focus">focus</span>();
undefined <span data-x="dom-window-blur">blur</span>();
// other browsing contexts
[Replaceable] readonly attribute <span>WindowProxy</span> <span data-x="dom-frames">frames</span>;
[Replaceable] readonly attribute unsigned long <span data-x="dom-length">length</span>;
[<span>LegacyUnforgeable</span>] readonly attribute <span>WindowProxy</span>? <span data-x="dom-top">top</span>;
attribute any <span data-x="dom-opener">opener</span>;
[Replaceable] readonly attribute <span>WindowProxy</span>? <span data-x="dom-parent">parent</span>;
readonly attribute <span>Element</span>? <span data-x="dom-frameElement">frameElement</span>;
<span>WindowProxy</span>? <span data-x="dom-open">open</span>(optional USVString url = "", optional DOMString target = "_blank", optional [<span>LegacyNullToEmptyString</span>] DOMString features = "");
// Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
// object on the prototype chain. Indeed, this does not make the global object an exotic object.
// Indexed access is taken care of by the <span>WindowProxy</span> exotic object.
<a href="#dom-window-nameditem">getter</a> <span data-x="idl-object">object</span> (DOMString name);
// the user agent
readonly attribute <span>Navigator</span> <span data-x="dom-navigator">navigator</span>;
[Replaceable] readonly attribute <span>Navigator</span> <span data-x="dom-clientInformation">clientInformation</span>; // legacy alias of .navigator
readonly attribute boolean <span data-x="dom-originAgentCluster">originAgentCluster</span>;
// user prompts
undefined <span data-x="dom-alert-noargs">alert</span>();
undefined <span data-x="dom-alert">alert</span>(DOMString message);
boolean <span data-x="dom-confirm">confirm</span>(optional DOMString message = "");
DOMString? <span data-x="dom-prompt">prompt</span>(optional DOMString message = "", optional DOMString default = "");
undefined <span data-x="dom-print">print</span>();
undefined <span data-x="dom-window-postMessage">postMessage</span>(any message, USVString targetOrigin, optional sequence<<span data-x="idl-object">object</span>> transfer = []);
undefined <span data-x="dom-window-postMessage-options">postMessage</span>(any message, optional <span>WindowPostMessageOptions</span> options = {});
// <a href="#Window-partial">also has obsolete members</a>
};
<span>Window</span> includes <span>GlobalEventHandlers</span>;
<span>Window</span> includes <span>WindowEventHandlers</span>;
dictionary <dfn dictionary>WindowPostMessageOptions</dfn> : <span>StructuredSerializeOptions</span> {
USVString <dfn dict-member for="WindowPostMessageOptions" data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</dfn> = "/";
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window">window</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-frames">frames</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-self">self</span></code></dt>
<dd><p>These attributes all return <var>window</var>.</p></dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-document">document</span></code></dt>
<dd><p>Returns the <code>Document</code> associated with <var>window</var>.</p></dd>
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-defaultView">defaultView</span></code></dt>
<dd><p>Returns the <code>Window</code> associated with <var>document</var>, if there is one, or null otherwise.</p></dd>
</dl>
<div w-nodev>
<p>The <code>Window</code> object has an <dfn export data-x="concept-document-window">associated
<code>Document</code></dfn>, which is a <code>Document</code> object. It is set when the
<code>Window</code> object is created, and only ever changed during <span
data-x="navigate">navigation</span> from the <span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code>.</p>
<p>A <code>Window</code>'s <dfn export for="Window" data-x="window bc">browsing context</dfn> is
its <span data-x="concept-document-window">associated <code>Document</code></span>'s <span
data-x="concept-document-bc">browsing context</span>. <span class="note">It is either null or a
<span>browsing context</span>.</span></p>
<p>A <code>Window</code>'s <dfn export for="Window" data-x="window navigable">navigable</dfn> is
the <span>navigable</span> whose <span data-x="nav-document">active document</span> is the
<code>Window</code>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s, or null if there is no such <span>navigable</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window">window</code></dfn>, <dfn attribute
for="Window"><code data-x="dom-frames">frames</code></dfn>, and <dfn attribute for="Window"><code
data-x="dom-self">self</code></dfn> getter steps are to return <span>this</span>'s <span
data-x="concept-relevant-realm">relevant realm</span>.[[GlobalEnv]].[[GlobalThisValue]].</p>
<p>The <dfn attribute for="Window"><code data-x="dom-document">document</code></dfn> getter steps
are to return <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p>
<p class="note">The <code>Document</code> object associated with a <code>Window</code> object can
change in exactly one case: when the <span>navigate</span> algorithm <span
data-x="create-the-document-object">creates a new <code>Document</code> object</span> for the
first page loaded in a <span>browsing context</span>. In that specific case, the
<code>Window</code> object of the <span data-x="is initial about:blank">initial
<code>about:blank</code></span> page is reused and gets a new <code>Document</code> object.</p>
<p>The <dfn attribute for="Document"><code
data-x="dom-document-defaultView">defaultView</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-document-bc">browsing context</span> is null,
then return null.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-document-bc">browsing context</span>'s
<code>WindowProxy</code> object.</p></li>
</ol>
<hr>
<p>For historical reasons, <code>Window</code> objects must also have a writable, configurable,
non-enumerable property named <dfn><code>HTMLDocument</code></dfn> whose value is the
<code>Document</code> <span>interface object</span>.</p>
</div>
<h5 id="apis-for-creating-and-navigating-browsing-contexts-by-name">Opening and closing windows</h5>
<dl class="domintro">
<dt><code data-x=""><var>window</var> = <var>window</var>.<span subdfn data-x="dom-open">open</span>([ <var>url</var> [, <var>target</var> [, <var>features</var> ] ] ])</code></dt>
<dd>
<p>Opens a window to show <var>url</var> (defaults to "<code>about:blank</code>"), and returns
it. <var>target</var> (defaults to "<code data-x="">_blank</code>") gives the name of the new
window. If a window already exists with that name, it is reused. The <var>features</var>
argument can contain a <span>set of comma-separated tokens</span>:</p>
<dl>
<dt>"<code data-x="">noopener</code>"</dt>
<dt>"<code data-x="">noreferrer</code>"</dt>
<dd><p>These behave equivalently to the <code data-x="rel-noopener">noopener</code> and <code
data-x="rel-noreferrer">noreferrer</code> link types on <span
data-x="hyperlink">hyperlinks</span>.</p></dd>
<dt>"<code data-x="">popup</code>"</dt>
<dd><p>Encourages user agents to provide a minimal web browser user interface for the new
window. (Impacts the <code data-x="dom-BarProp-visible">visible</code> getter on all
<code>BarProp</code> objects as well.)</p></dd>
</dl>
<pre class="example"><code class="js">globalThis.open("https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg", undefined, "noopener,popup");</code></pre>
</dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-name">name</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the name of the window.</p>
<p>Can be set, to change the name.</p>
</dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-close">close</span>()</code></dt>
<dd><p>Closes the window.</p></dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-closed">closed</span></code></dt>
<dd><p>Returns true if the window has been closed, false otherwise.</p></dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-stop">stop</span>()</code></dt>
<dd><p>Cancels the document load.</p></dd>
</dl>
<div w-nodev>
<p>To <dfn>get noopener for window open</dfn>, given a <code>Document</code>
<var>sourceDocument</var>, an <span>ordered map</span> <var>tokenizedFeatures</var>, and a
<span>URL record</span>-or-null <var>url</var>, perform the following steps. They return a
boolean.</p>
<ol>
<li>
<p>If <var>url</var> is not null and <var>url</var>'s <span
data-x="concept-url-blob-entry">blob URL entry</span> is not null:</p>
<ol>
<li><p>Let <var>blobOrigin</var> be <var>url</var>'s <span
data-x="concept-url-blob-entry">blob URL entry</span>'s <span
data-x="blob-url-entry-environment">environment</span>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Let <var>topLevelOrigin</var> be <var>sourceDocument</var>'s <span>relevant settings
object</span>'s <span>top-level origin</span>.</p></li>
<li><p>If <var>blobOrigin</var> is not <span>same site</span> with <var>topLevelOrigin</var>,
then return true.</p></li>
</ol>
</li>
<li><p>Let <var>noopener</var> be false.</p></li>
<li><p>If <var>tokenizedFeatures</var>["<code data-x="">noopener</code>"] <span data-x="map
exists">exists</span>, then set <var>noopener</var> to the result of <span
data-x="concept-window-open-features-parse-boolean">parsing <var>tokenizedFeatures</var>["<code
data-x="">noopener</code>"] as a boolean feature</span>.</p></li>
<li><p>Return <var>noopener</var>.</p></li>
</ol>
<p>The <dfn>window open steps</dfn>, given a string <var>url</var>, a string <var>target</var>,
and a string <var>features</var>, are as follows:</p>
<ol>
<li><p>If the <span>event loop</span>'s <span>termination nesting level</span> is nonzero,
then return null.</p></li>
<li><p>Let <var>sourceDocument</var> be the <span>entry global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>urlRecord</var> be null.</p></li>
<li>
<p>If <var>url</var> is not the empty string, then:</p>
<ol>
<li><p>Set <var>urlRecord</var> to the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to <var>sourceDocument</var>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>If <var>target</var> is the empty string, then set <var>target</var> to "<code
data-x="">_blank</code>".</p></li>
<li><p>Let <var>tokenizedFeatures</var> be the result of <span
data-x="concept-window-open-features-tokenize">tokenizing</span> <var>features</var>.</p></li>
<li><p>Let <var>noreferrer</var> be false.</p></li>
<li><p>If <var>tokenizedFeatures</var>["<code data-x="">noreferrer</code>"] <span data-x="map
exists">exists</span>, then set <var>noreferrer</var> to the result of <span
data-x="concept-window-open-features-parse-boolean">parsing <var>tokenizedFeatures</var>["<code
data-x="">noreferrer</code>"] as a boolean feature</span>.</p></li>
<li><p>Let <var>noopener</var> be the result of <span
data-x="get noopener for window open">getting noopener for window open</span> with
<var>sourceDocument</var>, <var>tokenizedFeatures</var>, and <var>urlRecord</var>.</p></li>
<li><p><span data-x="map remove">Remove</span> <var>tokenizedFeatures</var>["<code
data-x="">noopener</code>"] and <var>tokenizedFeatures</var>["<code
data-x="">noreferrer</code>"].</p></li>
<li><p>Let <var>referrerPolicy</var> be the empty string.</p></li>
<li><p>If <var>noreferrer</var> is true, then set <var>noopener</var> to true and set
<var>referrerPolicy</var> to "<code data-x="">no-referrer</code>".</p></li>
<li>
<p>Let <var>targetNavigable</var> and <var>windowType</var> be the result of applying <span>the
rules for choosing a navigable</span> given <var>target</var>, <var>sourceDocument</var>'s
<span>node navigable</span>, and <var>noopener</var>.</p>
<p class="example">If there is a user agent that supports control-clicking a link to open it in
a new tab, and the user control-clicks on an element whose <code
data-x="handler-onclick">onclick</code> handler uses the <code
data-x="dom-open">window.open()</code> API to open a page in an <code>iframe</code> element,
the user agent could override the selection of the target browsing context to instead target a
new tab.</p>
</li>
<li><p>If <var>targetNavigable</var> is null, then return null.</p></li>
<li>
<p>If <var>windowType</var> is either "<code data-x="">new and unrestricted</code>" or "<code
data-x="">new with no opener</code>", then:</p>
<ol>
<li><p>Set <var>targetNavigable</var>'s <span data-x="nav-bc">active browsing context</span>'s
<span>is popup</span> to the result of <span data-x="popup-window-is-requested">checking if a
popup window is requested</span>, given <var>tokenizedFeatures</var>.</p></li>
<li><p><span>Set up browsing context features</span> for <var>targetNavigable</var>'s <span
data-x="nav-bc">active browsing context</span> given
<var>tokenizedFeatures</var>. <ref>CSSOMVIEW</ref></p></li>
<li><p>If <var>urlRecord</var> is null, then set <var>urlRecord</var> to a <span>URL
record</span> representing <code>about:blank</code>.</p></li>
<li>
<p>If <var>urlRecord</var> <span>matches <code>about:blank</code></span>, then perform the
<span>URL and history update steps</span> given <var>targetNavigable</var>'s <span
data-x="nav-document">active document</span> and <var>urlRecord</var>.</p>
<p class="note">This is necessary in case <var>url</var> is something like <code
data-x="">about:blank?foo</code>. If <var>url</var> is just plain <code
data-x="">about:blank</code>, this will do nothing.</p>
</li>
<li><p>Otherwise, <span>navigate</span><!--DONAV window.open()--> <var>targetNavigable</var>
to <var>urlRecord</var> using <var>sourceDocument</var>, with <i
data-x="navigation-referrer-policy">referrerPolicy</i> set to <var>referrerPolicy</var> and
<i><span>exceptionsEnabled</span></i> set to true.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><!--DONAV window.open()--><p>If <var>urlRecord</var> is not null, then
<span>navigate</span> <var>targetNavigable</var> to <var>urlRecord</var> using
<var>sourceDocument</var>, with <i data-x="navigation-referrer-policy">referrerPolicy</i> set
to <var>referrerPolicy</var> and <i><span>exceptionsEnabled</span></i> set to true.</p></li>
<li><p>If <var>noopener</var> is false, then set <var>targetNavigable</var>'s <span
data-x="nav-bc">active browsing context</span>'s <span>opener browsing context</span> to
<var>sourceDocument</var>'s <span data-x="concept-document-bc">browsing
context</span>.</p></li>
</ol>
</li>
<li><p>If <var>noopener</var> is true or <var>windowType</var> is "<code data-x="">new with no
opener</code>", then return null.</p></li>
<li><p>Return <var>targetNavigable</var>'s <span data-x="nav-wp">active
<code>WindowProxy</code></span>.</p></li>
</ol>
<p>The <dfn for="Window" method><code data-x="dom-open">open(<var>url</var>, <var>target</var>,
<var>features</var>)</code></dfn> method steps are to run the <span>window open steps</span> with
<var>url</var>, <var>target</var>, and <var>features</var>.</p>
<p class="note">The method provides a mechanism for <span data-x="navigate">navigating</span> an
existing <span>browsing context</span> or opening and navigating an <span>auxiliary browsing
context</span>.</p>
<hr>
<p>To <dfn data-x="concept-window-open-features-tokenize">tokenize the <var>features</var>
argument</dfn>:</p>
<ol>
<li><p>Let <var>tokenizedFeatures</var> be a new <span>ordered map</span>.</p></li>
<li><p>Let <var>position</var> point at the first code point of <var>features</var>.</p></li>
<li>
<p><span>While</span> <var>position</var> is not past the end of <var>features</var>:</p>
<ol>
<li><p>Let <var>name</var> be the empty string.</p></li>
<li><p>Let <var>value</var> be the empty string.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span data-x="feature
separator">feature separators</span> from <var>features</var> given <var>position</var>. This
skips past leading separators before the name.</p></li>
<li><p><span>Collect a sequence of code points</span> that are not <span data-x="feature
separator">feature separators</span> from <var>features</var> given <var>position</var>. Set
<var>name</var> to the collected characters, <span>converted to ASCII lowercase</span>.</p></li>
<li><p>Set <var>name</var> to the result of <span>normalizing the feature name</span>
<var>name</var>.</p></li>
<li>
<p><span>While</span> <var>position</var> is not past the end of <var>features</var> and the
code point at <var>position</var> in <var>features</var> is not U+003D (=):</p>
<ol>
<li><p>If the code point at <var>position</var> in <var>features</var> is U+002C (,), or if
it is not a <span>feature separator</span>, then <span>break</span>.</p></li>
<li><p>Advance <var>position</var> by 1.</p></li>
</ol>
<p class="note">This skips to the first U+003D (=) but does not skip past a U+002C (,) or a
non-separator.</p>
</li>
<li>
<p>If the code point at <var>position</var> in <var>features</var> is a <span>feature
separator</span>:</p>
<ol>
<li>
<p>While <var>position</var> is not past the end of <var>features</var> and the code point
at <var>position</var> in <var>features</var> is a <span>feature separator</span>:</p>
<ol>
<li><p>If the code point at <var>position</var> in <var>features</var> is U+002C (,), then
<span>break</span>.</p></li>
<li><p>Advance <var>position</var> by 1.</p></li>
</ol>
<p class="note">This skips to the first non-separator but does not skip past a U+002C
(,).</p>
</li>
<li><p><span>Collect a sequence of code points</span> that are not <span data-x="feature
separator">feature separators</span> code points from <var>features</var> given
<var>position</var>. Set <var>value</var> to the collected code points, <span>converted to
ASCII lowercase</span>.</p></li>
</ol>
</li>
<li><p>If <var>name</var> is not the empty string, then set
<var>tokenizedFeatures</var>[<var>name</var>] to <var>value</var>.</p></li>
</ol>
</li>
<li><p>Return <var>tokenizedFeatures</var>.</p></li>
</ol>
<p>To <dfn data-x="window-feature-is-set">check if a window feature is set</dfn>, given
<var>tokenizedFeatures</var>, <var>featureName</var>, and <var>defaultValue</var>:</p>
<ol>
<li><p>If <var>tokenizedFeatures</var>[<var>featureName</var>] <span data-x="map
exists">exists</span>, then return the result of <span
data-x="concept-window-open-features-parse-boolean">parsing
<var>tokenizedFeatures</var>[<var>featureName</var>] as a boolean feature</span>.</p></li>
<li><p>Return <var>defaultValue</var>.</p></li>
</ol>
<p>To <dfn data-x="popup-window-is-requested">check if a popup window is requested</dfn>, given
<var>tokenizedFeatures</var>:</p>
<ol>
<li><p>If <var>tokenizedFeatures</var> is <span data-x="map empty">empty</span>, then return
false.</p></li>
<li><p>If <var>tokenizedFeatures</var>["<code data-x="">popup</code>"] <span data-x="map
exists">exists</span>, then return the result of <span
data-x="concept-window-open-features-parse-boolean">parsing
<var>tokenizedFeatures</var>["<code data-x="">popup</code>"] as a boolean
feature</span>.</p></li>
<li><p>Let <var>location</var> be the result of <span data-x="window-feature-is-set">checking if
a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">location</code>", and false.</p></li>
<li><p>Let <var>toolbar</var> be the result of <span data-x="window-feature-is-set">checking if
a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">toolbar</code>", and false.</p></li>
<li><p>If <var>location</var> and <var>toolbar</var> are both false, then return true.</p></li>
<li><p>Let <var>menubar</var> be the result of <span data-x="window-feature-is-set">checking if
a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">menubar</code>", and false.</p></li>
<li><p>If <var>menubar</var> is false, then return true.</p></li>
<li><p>Let <var>resizable</var> be the result of <span data-x="window-feature-is-set">checking if
a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">resizable</code>", and true.</p></li>
<li><p>If <var>resizable</var> is false, then return true.</p></li>
<li><p>Let <var>scrollbars</var> be the result of <span data-x="window-feature-is-set">checking
if a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">scrollbars</code>", and false.</p></li>
<li><p>If <var>scrollbars</var> is false, then return true.</p></li>
<li><p>Let <var>status</var> be the result of <span data-x="window-feature-is-set">checking if
a window feature is set</span>, given <var>tokenizedFeatures</var>, "<code
data-x="">status</code>", and false.</p></li>
<li><p>If <var>status</var> is false, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>A code point is a <dfn>feature separator</dfn> if it is <span>ASCII whitespace</span>, U+003D
(=), or U+002C (,).</p>
<p>For legacy reasons, there are some aliases of some feature names. To <dfn data-x="normalizing
the feature name">normalize a feature name</dfn> <var>name</var>, switch on <var>name</var>:</p>
<dl class="switch">
<dt>"<code data-x="">screenx</code>"
<dd>Return "<code data-x="">left</code>".
<dt>"<code data-x="">screeny</code>"
<dd>Return "<code data-x="">top</code>".
<dt>"<code data-x="">innerwidth</code>"
<dd>Return "<code data-x="">width</code>".
<dt>"<code data-x="">innerheight</code>"
<dd>Return "<code data-x="">height</code>".
<dt>Anything else
<dd>Return <var>name</var>.
</dl>
<p>To <dfn data-x="concept-window-open-features-parse-boolean">parse a boolean feature</dfn> given
a string <var>value</var>:</p>
<ol>
<li><p>If <var>value</var> is the empty string, then return true.</p></li>
<li><p>If <var>value</var> <span>is</span> "<code data-x="">yes</code>", then return
true.</p></li>
<li><p>If <var>value</var> <span>is</span> "<code data-x="">true</code>", then return
true.</p></li>
<li><p>Let <var>parsed</var> be the result of <span data-x="rules for parsing integers">parsing
<var>value</var> as an integer</span>.</p></li>
<li><p>If <var>parsed</var> is an error, then set it to 0.</p></li>
<li><p>Return false if <var>parsed</var> is 0, and true otherwise.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="Window"><code data-x="dom-name">name</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="window navigable">navigable</span> is null, then
return the empty string.</p></li>
<li><p>Return <span>this</span>'s <span data-x="window navigable">navigable</span>'s <span
data-x="nav-target">target name</span>.</p></li>
</ol>
<p>The <code data-x="dom-name">name</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="window navigable">navigable</span> is null, then
return.</p></li>
<li><p>Set <span>this</span>'s <span data-x="window navigable">navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-nav-target-name">navigable target name</span> to the given value.</p></li>
</ol>
<p class="note">The name <a href="#resetBCName">gets reset</a> when the navigable is <span
data-x="navigate">navigated</span> to another <span>origin</span>.</p>
<hr>
<p>The <dfn method for="Window"><code data-x="dom-window-close">close()</code></dfn> method steps
are:</p>
<ol>
<li><p>Let <var>thisTraversable</var> be <span>this</span>'s <span data-x="window
navigable">navigable</span>.</p></li>
<li><p>If <var>thisTraversable</var> is not a <span>top-level traversable</span>, then
return.</p></li>
<li><p>If <var>thisTraversable</var>'s <span>is closing</span> is true, then return.</p></li>
<li><p>Let <var>browsingContext</var> be <var>thisTraversable</var>'s <span
data-x="nav-bc">active browsing context</span>.</p></li>
<li><p>Let <var>sourceSnapshotParams</var> be the result of <span>snapshotting source snapshot
params</span> given <var>thisTraversable</var>'s <span data-x="nav-document">active
document</span>.</p></li>
<li>
<p>If all the following are true:</p>
<ul>
<li><p><var>thisTraversable</var> is <span>script-closable</span>;</p></li>
<li><p>the <span data-x="concept-incumbent-global">incumbent global object</span>'s <span
data-x="window bc">browsing context</span> is <span>familiar with</span>
<var>browsingContext</var>; and</p></li>
<li id="sandboxClose"><p>the <span data-x="concept-incumbent-global">incumbent global
object</span>'s <span data-x="window navigable">navigable</span> is <span>allowed by
sandboxing to navigate</span> <var>thisTraversable</var>, given
<var>sourceSnapshotParams</var>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Set <var>thisTraversable</var>'s <span>is closing</span> to true.</p></li>
<li><p><span>Queue a task</span> on the <span>DOM manipulation task source</span> to <span
data-x="definitely close a top-level traversable">definitely close</span>
<var>thisTraversable</var>.</p></li>
</ol>
</li>
</ol>
<p>A <span>navigable</span> is <dfn>script-closable</dfn> if its <span data-x="nav-bc">active
browsing context</span> is an <span>auxiliary browsing context</span> that was created by a
script (as opposed to by an action of the user), or if it is a <span>top-level traversable</span>
whose <span data-x="tn-session-history-entries">session history entries</span>'s <span
data-x="list size">size</span> is 1.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-closed">closed</code></dfn> getter
steps are to return true if <span>this</span>'s <span data-x="window bc">browsing context</span>
is null or its <span>is closing</span> is true; otherwise false.</p>
<p>The <dfn method for="Window"><code data-x="dom-window-stop">stop()</code></dfn> method steps
are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="window navigable">navigable</span> is null, then
return.</p></li>
<li><p><span data-x="nav-stop">Stop loading</span> <span>this</span>'s <span data-x="window
navigable">navigable</span>.</p></li>
</ol>
</div>
<h5 id="accessing-other-browsing-contexts">Indexed access on the <code>Window</code> object</h5>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-length">length</span></code></dt>
<dd><p>Returns the number of <span>document-tree child navigables</span>.</p></dd>
<dt><code data-x=""><var>window</var>[<var>index</var>]</code></dt>
<dd><p>Returns the <code>WindowProxy</code> corresponding to the indicated <span
data-x="document-tree child navigables">document-tree child navigables</span>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Window"><code data-x="dom-length">length</code></dfn> getter steps are
to return <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>document-tree child navigables</span>'s <span data-x="list
size">size</span>.</p>
<p class="note">Indexed access to <span>document-tree child navigables</span> is defined through
the <a href="#windowproxy-getownproperty">[[GetOwnProperty]]</a> internal method of the
<code>WindowProxy</code> object.</p>
</div>
<h5>Named access on the <code>Window</code> object</h5>
<dl class="domintro">
<dt><code data-x=""><var>window</var>[<var>name</var>]</code></dt>
<dd>
<p>Returns the indicated element or collection of elements.</p>
<p>As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to
this API can vary over time, as new features are added to the web platform, for example. Instead
of this, use <code data-x="">document.getElementById()</code> or <code
data-x="">document.querySelector()</code>.</p>
</dd>
</dl>
<div w-nodev>
<p id="child-browsing-context-name-property-set"><span
id="document-tree-child-browsing-context-name-property-set"></span>The <dfn>document-tree child
navigable target name property set</dfn> of a <code>Window</code> object <var>window</var> is the
return value of running these steps:</p>
<ol>
<li><p>Let <var>children</var> be the <span>document-tree child navigables</span> of
<var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p></li>
<li><p>Let <var>firstNamedChildren</var> be an empty <span data-x="set">ordered
set</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of <var>children</var>:</p>
<ol>
<li><p>Let <var>name</var> be <var>navigable</var>'s <span
data-x="nav-target">target name</span>.</p></li>
<li><p>If <var>name</var> is the empty string, then <span>continue</span>.</p></li>
<li><p>If <var>firstNamedChildren</var> <span data-x="list contains">contains</span> a
<span>navigable</span> whose <span data-x="nav-target">target name</span> is <var>name</var>,
then <span>continue</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>navigable</var> to
<var>firstNamedChildren</var>.</p></li>
</ol>
</li>
<li><p>Let <var>names</var> be an empty <span data-x="set">ordered set</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>firstNamedChildren</var>:</p>
<ol>
<li><p>Let <var>name</var> be <var>navigable</var>'s <span
data-x="nav-target">target name</span>.</p></li>
<li><p>If <var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin</span> with
<var>window</var>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then <span data-x="list
append">append</span> <var>name</var> to <var>names</var>.</p></li>
</ol>
</li>
<li><p>Return <var>names</var>.</p></li>
</ol>
<div class="example">
<p>The two seperate iterations mean that in the following example, hosted on <code
data-x="">https://example.org/</code>, assuming <code data-x="">https://elsewhere.example/</code>
sets <code data-x="dom-name">window.name</code> to "<code data-x="">spices</code>", evaluating
<code data-x="">window.spices</code> after everything has loaded will yield undefined:</p>
<pre><code class="html"><iframe src=https://elsewhere.example.com/></iframe>
<iframe name=spices></iframe></code></pre>
</div>
<p>The <code>Window</code> object <span data-x="support named properties">supports named
properties</span>. The <span>supported property names</span> of a <code>Window</code> object
<var>window</var> at any moment consist of the following, in <span>tree order</span> according to
the element that contributed them, ignoring later duplicates:</p>
<!-- KEEP THIS LIST IN SYNC WITH "NAMED OBJECTS" BELOW -->
<ul>
<li><p><var>window</var>'s <span>document-tree child navigable target name property
set</span>;</p></li>
<li><p>the value of the <code data-x="">name</code> content attribute for all <code>embed</code>,
<code>form</code>, <code>img</code>, and <code>object</code> elements that
have a non-empty <code data-x="">name</code> content attribute and are <span>in a document
tree</span> with <var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span> as their <span>root</span>; and</p></li>
<li><p>the value of the <code data-x="attr-id">id</code> content attribute for all <span>HTML
elements</span> that have a non-empty <code data-x="attr-id">id</code> content attribute and are
<span>in a document tree</span> with <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> as their
<span>root</span>.</p></li>
</ul>
<p id="dom-window-nameditem">To <span>determine the value of a named property</span>
<var>name</var> in a <code>Window</code> object <var>window</var>, the user agent must return the
value obtained using the following steps:</p>
<ol>
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1716 -->
<li>
<p>Let <var>objects</var> be the list of <span data-x="dom-window-namedItem-filter">named
objects</span> of <var>window</var> with the name <var>name</var>.</p>
<p class="note">There will be at least one such object, since the algorithm would otherwise not
have been <span data-x="named-properties-object-getownproperty">invoked by Web IDL</span>.</p>
</li>
<li>
<p>If <var>objects</var> contains a <span>navigable</span>, then:</p>
<ol>
<li><p>Let <var>container</var> be the first <span>navigable container</span> in
<var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="descendant">descendants</span> whose
<span>content navigable</span> is in <var>objects</var>.</p></li>
<li><p>Return <var>container</var>'s <span>content navigable</span>'s <span
data-x="nav-wp">active <code>WindowProxy</code></span>.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>objects</var> has only one element, return that element.</p></li>
<li><p>Otherwise, return an <code>HTMLCollection</code> rooted at <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span>, whose filter matches
only <span data-x="dom-window-namedItem-filter">named objects</span> of <var>window</var> with
the name <var>name</var>. (By definition, these will all be elements.)</p></li>
<!-- the same one each time is returned, because of the rule under collections -->
</ol>
<p><dfn data-x="dom-window-nameditem-filter">Named objects</dfn> of <code>Window</code> object
<var>window</var> with the name <var>name</var>, for the purposes of the above algorithm, consist
of the following:</p>
<!-- KEEP THIS LIST IN SYNC WITH SUPPORTED PROPERTY NAMES ABOVE -->
<ul>
<li><p><span>document-tree child navigables</span> of <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> whose <span
data-x="nav-target">target name</span> is <var>name</var>;</p></li>
<li><p><code>embed</code>, <code>form</code>, <code>img</code>, or
<code>object</code> elements that have a <code data-x="">name</code> content attribute whose
value is <var>name</var> and are <span>in a document tree</span> with <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> as their
<span>root</span>; and</p></li>
<li><p><span>HTML elements</span> that have an <code data-x="attr-id">id</code> content attribute
whose value is <var>name</var> and are <span>in a document tree</span> with <var>window</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span> as their
<span>root</span>.</p></li>
</ul>
<p class="note">Since the <code>Window</code> interface has the <code
data-x="Global">[Global]</code> extended attribute, its named properties follow the rules for
<span data-x="named properties object">named properties objects</span> rather than <span
data-x="legacy platform object">legacy platform objects</span>.</p>
</div>
<h5 id="navigating-nested-browsing-contexts-in-the-dom">Accessing related windows</h5>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-top">top</span></code></dt>
<dd><p>Returns the <code>WindowProxy</code> for the <span>top-level traversable</span>.</p></dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-opener">opener</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the <code>WindowProxy</code> for the <span>opener browsing context</span>.</p>
<p>Returns null if there isn't one or if it has been set to null.</p>
<p>Can be set to null.</p>
</dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-parent">parent</span></code></dt>
<dd><p>Returns the <code>WindowProxy</code> for the <span data-x="nav-parent">parent
navigable</span>.</p></dd>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-frameElement">frameElement</span></code></dt>
<dd>
<p>Returns the <span>navigable container</span> element.</p>
<p>Returns null if there isn't one, and in cross-origin situations.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="Window"><code data-x="dom-top">top</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="window navigable">navigable</span> is null, then
return null.</p></li>
<li><p>Return <span>this</span>'s <span data-x="window navigable">navigable</span>'s <span
data-x="nav-top">top-level traversable</span>'s <span data-x="nav-wp">active
<code>WindowProxy</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="Window"><code data-x="dom-opener">opener</code></dfn> getter steps
are:</p>
<ol>
<li><p>Let <var>current</var> be <span>this</span>'s <span data-x="window bc">browsing
context</span>.</p></li>
<li><p>If <var>current</var> is null, then return null.</p></li>
<li><p>If <var>current</var>'s <span>opener browsing context</span> is null, then return
null.</p></li>
<li><p>Return <var>current</var>'s <span>opener browsing context</span>'s
<code>WindowProxy</code> object.</p></li>
</ol>
<p>The <code data-x="dom-opener">opener</code> setter steps are:</p>
<ol>
<li><p>If the given value is null and <span>this</span>'s <span data-x="window bc">browsing
context</span> is non-null, then set <span>this</span>'s <span data-x="window bc">browsing
context</span>'s <span>opener browsing context</span> to null.</p></li>
<li><p>If the given value is non-null, then perform ?
<span>DefinePropertyOrThrow</span>(<span>this</span>, "<code data-x="">opener</code>", {
[[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
}).</p></li>
</ol>
<div class="note">
<p>Setting <code data-x="dom-opener">window.opener</code> to null clears the <span>opener
browsing context</span> reference. In practice, this prevents future scripts from accessing their
<span>opener browsing context</span>'s <code>Window</code> object.</p>
<p>By default, scripts can access their <span>opener browsing context</span>'s
<code>Window</code> object through the <code data-x="dom-opener">window.opener</code> getter.
E.g., a script can set <code data-x="">window.opener.location</code>, causing the <span>opener
browsing context</span> to navigate.</p>
</div>
<p>The <dfn attribute for="Window"><code data-x="dom-parent">parent</code></dfn> getter steps
are:</p>
<ol>
<li><p>Let <var>navigable</var> be <span>this</span>'s <span data-x="window
navigable">navigable</span>.</p></li>
<li><p>If <var>navigable</var> is null, then return null.</p></li>
<li><p>If <var>navigable</var>'s <span data-x="nav-parent">parent</span> is not null, then set
<var>navigable</var> to <var>navigable</var>'s <span data-x="nav-parent">parent</span>.</p></li>
<li><p>Return <var>navigable</var>'s <span data-x="nav-wp">active
<code>WindowProxy</code></span>.</p></li>
</ol>
<p>The <dfn attribute for="Window"><code data-x="dom-frameElement">frameElement</code></dfn>
getter steps are:</p>
<ol>
<li><p>Let <var>current</var> be <span>this</span>'s <span>node navigable</span>.</p></li>
<li><p>If <var>current</var> is null, then return null.</p></li>
<li><p>Let <var>container</var> be <var>current</var>'s <span
data-x="nav-container">container</span>.</p></li>
<li><p>If <var>container</var> is null, then return null.</p></li>
<li><p>If <var>container</var>'s <span>node document</span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>current settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then return null.</p></li>
<li><p>Return <var>container</var>.</p></li>
</ol>
<div class="example">
<p>An example of when these properties can return null is as follows:</p>
<pre><code class="html"><!DOCTYPE html>
<iframe></iframe>
<script>
"use strict";
const element = document.querySelector("iframe");
const iframeWindow = element.contentWindow;
element.remove();
console.assert(iframeWindow.top === null);
console.assert(iframeWindow.parent === null);
console.assert(iframeWindow.frameElement === null);
</script></code></pre>
<p>Here the <span>browsing context</span> corresponding to <code data-x="">iframeWindow</code>
was <span data-x="destroy a document">nulled out</span> when <code data-x="">element</code> was
removed from the document.</p>
</div>
</div>
<h5 id="browser-interface-elements">Historical browser interface element APIs</h5>
<p>For historical reasons, the <code>Window</code> interface had some properties that represented
the visibility of certain web browser interface elements.</p>
<p w-nodev>For privacy and interoperability reasons, those properties now return values that
represent whether the <code>Window</code>'s <span data-x="window bc">browsing context</span>'s
<span>is popup</span> property is true or false.</p>
<p w-dev>For privacy and interoperability reasons, those properties now return all return the same value:
whether or not the window represents a popup window.</p>
<p w-nodev>Each interface element is represented by a <code>BarProp</code> object:</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>BarProp</dfn> {
readonly attribute boolean <span data-x="dom-BarProp-visible">visible</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-locationbar">locationbar</span>.<span subdfn data-x="dom-BarProp-visible">visible</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-menubar">menubar</span>.<span data-x="dom-BarProp-visible">visible</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-personalbar">personalbar</span>.<span data-x="dom-BarProp-visible">visible</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-scrollbars">scrollbars</span>.<span data-x="dom-BarProp-visible">visible</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-statusbar">statusbar</span>.<span data-x="dom-BarProp-visible">visible</span></code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-toolbar">toolbar</span>.<span data-x="dom-BarProp-visible">visible</span></code></dt>
<dd><p>Returns true if the <code>Window</code> is not a popup; otherwise, returns false.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="BarProp"><code data-x="dom-BarProp-visible">visible</code></dfn> getter
steps are:</p>
<ol>
<li><p>Let <var>browsingContext</var> be <span>this</span>'s <span>relevant global
object</span>'s <span data-x="window bc">browsing context</span>.</p></li>
<li><p>If <var>browsingContext</var> is null, then return true.</p></li>
<li><p>Return the negation of <var>browsingContext</var>'s <span data-x="bc-tlbc">top-level
browsing context</span>'s <span>is popup</span>.</p></li>
</ol>
<p>The following <code>BarProp</code> objects must exist for each <code>Window</code> object:</p>
<dl>
<dt><dfn>The location bar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented the user interface element that contains a control that displays the
browser's location bar.</dd>
<dt><dfn>The menu bar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented the user interface element that contains a list of commands in menu
form, or some similar interface concept.</dd>
<dt><dfn>The personal bar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented the user interface element that contains links to the user's
favorite pages, or some similar interface concept.</dd>
<dt><dfn>The scrollbar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented the user interface element that contains a scrolling mechanism, or
some similar interface concept.</dd>
<dt><dfn>The status bar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented a user interface element found immediately below or after the
document, as appropriate for the user's media, which typically provides information about ongoing
network activity or information about elements that the user's pointing device is currently
indicating.</dd>
<dt><dfn>The toolbar <code>BarProp</code> object</dfn></dt>
<dd>Historically represented the user interface element found immediately above or before the
document, as appropriate for the user's media, which typically provides <span data-x="apply the
traverse history step">session history traversal</span> controls (back and forward buttons,
reload buttons, etc.).</dd>
</dl>
<p>The <dfn attribute for="Window"><code data-x="dom-window-locationbar">locationbar</code></dfn>
attribute must return <span>the location bar <code>BarProp</code> object</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-menubar">menubar</code></dfn>
attribute must return <span>the menu bar <code>BarProp</code> object</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-personalbar">personalbar</code></dfn>
attribute must return <span>the personal bar <code>BarProp</code> object</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-scrollbars">scrollbars</code></dfn>
attribute must return <span>the scrollbar <code>BarProp</code> object</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-statusbar">statusbar</code></dfn>
attribute must return <span>the status bar <code>BarProp</code> object</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-window-toolbar">toolbar</code></dfn>
attribute must return <span>the toolbar <code>BarProp</code> object</span>.</p>
<hr>
<p>For historical reasons, the <dfn attribute for="Window"><code
data-x="dom-window-status">status</code></dfn> attribute on the <code>Window</code> object must,
on getting, return the last string it was set to, and on setting, must set itself to the new
value. When the <code>Window</code> object is created, the attribute must be set to the empty
string. It does not do anything else.</p>
<h5>Script settings for <code>Window</code> objects</h5>
<p>To <dfn>set up a window environment settings object</dfn>, given a <span>URL</span>
<var>creationURL</var>, a <span>JavaScript execution context</span> <var>execution context</var>,
null or an <span>environment</span> <var>reservedEnvironment</var>, a <span>URL</span>
<var>topLevelCreationURL</var>, and an <span>origin</span> <var>topLevelOrigin</var>, run these
steps:</p>
<ol>
<li><p>Let <var>realm</var> be the value of <var>execution context</var>'s Realm
component.</p></li>
<li><p>Let <var>window</var> be <var>realm</var>'s <span data-x="concept-realm-global">global
object</span>.</p></li>
<li>
<p>Let <var>settings object</var> be a new <span>environment settings object</span> whose
algorithms are defined as follows:</p>
<dl>
<dt>The <span>realm execution context</span></dt>
<dd>
<p>Return <var>execution context</var>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-module-map">module map</span></dt>
<dd>
<p>Return the <span data-x="concept-document-module-map">module map</span> of
<var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p>
</dd>
<dt>The <span>API base URL</span></dt>
<dd>
<p>Return the current <span data-x="document base URL">base URL</span> of <var>window</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-origin">origin</span></dt>
<dd>
<p>Return the <span data-x="concept-document-origin">origin</span> of <var>window</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-policy-container">policy container</span></dt>
<dd>
<p>Return the <span data-x="concept-document-policy-container">policy container</span> of
<var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin
isolated capability</span></dt>
<dd>
<p>Return true if both of the following hold, and false otherwise:</p>
<ul>
<li><p><var>realm</var>'s <span>agent cluster</span>'s <span
data-x="agent-cluster-cross-origin-isolation">cross-origin-isolation mode</span> is "<code
data-x="cross-origin-isolation-concrete">concrete</code>", and</p></li>
<li><p><var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span> is <span>allowed to use</span> the "<code
data-x="cross-origin-isolated-feature">cross-origin-isolated</code>" feature.</p></li>
</ul>
</dd>
<dt>The <span data-x="concept-settings-object-time-origin">time origin</span></dt>
<dd>
<p>Return <var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>load timing info</span>'s <span>navigation start
time</span>.</p>
</dd>
</dl>
</li>
<li>
<p>If <var>reservedEnvironment</var> is non-null, then:</p>
<ol>
<li><p>Set <var>settings object</var>'s <span data-x="concept-environment-id">id</span> to
<var>reservedEnvironment</var>'s <span data-x="concept-environment-id">id</span>, <span
data-x="concept-environment-target-browsing-context">target browsing context</span> to
<var>reservedEnvironment</var>'s <span
data-x="concept-environment-target-browsing-context">target browsing context</span>, and <span
data-x="concept-environment-active-service-worker">active service worker</span> to
<var>reservedEnvironment</var>'s <span
data-x="concept-environment-active-service-worker">active service worker</span>.</p></li>
<li>
<p>Set <var>reservedEnvironment</var>'s <span data-x="concept-environment-id">id</span> to
the empty string.</p>
<p class="note">The identity of the reserved environment is considered to be fully
transferred to the created <span>environment settings object</span>. The reserved environment
is not searchable by the <span>environment</span>’s <span
data-x="concept-environment-id">id</span> from this point on.</p>
</li>
</ol>
</li>
<li><p>Otherwise, set <var>settings object</var>'s <span
data-x="concept-environment-id">id</span> to a new unique opaque string, <var>settings
object</var>'s <span data-x="concept-environment-target-browsing-context">target browsing
context</span> to null, and <var>settings object</var>'s <span
data-x="concept-environment-active-service-worker">active service worker</span> to null.</p></li>
<li><p>Set <var>settings object</var>'s <span data-x="concept-environment-creation-url">creation
URL</span> to <var>creationURL</var>, <var>settings object</var>'s <span>top-level creation
URL</span> to <var>topLevelCreationURL</var>, and <var>settings object</var>'s <span>top-level
origin</span> to <var>topLevelOrigin</var>.</p></li>
<li><p>Set <var>realm</var>'s [[HostDefined]] field to <var>settings object</var>.</p></li>
</ol>
</div>
<h4>The <code>WindowProxy</code> exotic object</h4>
<p>A <dfn interface><code>WindowProxy</code></dfn> is an exotic object that wraps a
<code>Window</code> ordinary object, indirecting most operations through to the wrapped object.
Each <span>browsing context</span> has an associated <code>WindowProxy</code> object. When the
<span>browsing context</span> is <span data-x="navigate">navigated</span>, the <code>Window</code>
object wrapped by the <span>browsing context</span>'s associated <code>WindowProxy</code> object
is changed.</p>
<div w-nodev>
<p>The <code>WindowProxy</code> exotic object must use the ordinary internal methods except where
it is explicitly specified otherwise below.</p>
<p>There is no <code>WindowProxy</code> <span>interface object</span>.</p>
<p>Every <code>WindowProxy</code> object has a <dfn data-x="concept-windowproxy-window"
export>[[Window]]</dfn> internal slot representing the wrapped <code>Window</code> object.</p>
<p class="note">Although <code>WindowProxy</code> is named as a "proxy", it does not do
polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to
reuse machinery between <code>WindowProxy</code> and <code>Location</code> objects. As long as the
<code>Window</code> object remains an ordinary object this is unobservable and can be implemented
either way.</p>
<h5 id="windowproxy-getprototypeof">[[GetPrototypeOf]] ( )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then return !
<span>OrdinaryGetPrototypeOf</span>(<var>W</var>).</p></li>
<li><p>Return null.</p></li>
</ol>
<h5 id="windowproxy-setprototypeof">[[SetPrototypeOf]] ( <var>V</var> )</h5>
<ol>
<li><p>Return ! <span>SetImmutablePrototype</span>(<b>this</b>, <var>V</var>).</p></li>
</ol>
<h5 id="windowproxy-isextensible">[[IsExtensible]] ( )</h5>
<ol>
<li><p>Return true.</p></li>
</ol>
<h5 id="windowproxy-preventextensions">[[PreventExtensions]] ( )</h5>
<ol>
<li><p>Return false.</p></li>
</ol>
<h5 id="windowproxy-getownproperty">[[GetOwnProperty]] ( <var>P</var> )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li>
<p>If <var>P</var> is an <span>array index property name</span>, then:</p>
<ol>
<li><p>Let <var>index</var> be ! <span>ToUint32</span>(<var>P</var>).</p></li>
<li><p>Let <var>children</var> be the <span>document-tree child navigables</span> of
<var>W</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p></li>
<li><p>Let <var>value</var> be undefined.</p></li>
<li>
<p>If <var>index</var> is less than <var>children</var>'s <span data-x="list
size">size</span>, then:</p>
<ol>
<li><p><span data-x="list sort">Sort</span> <var>children</var> in ascending order, with
<var>navigableA</var> being less than <var>navigableB</var> if <var>navigableA</var>'s <span
data-x="nav-container">container</span> was inserted into <var>W</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> earlier than
<var>navigableB</var>'s <span data-x="nav-container">container</span> was.</p></li>
<li><p>Set <var>value</var> to <var>children</var>[<var>index</var>]'s <span
data-x="nav-wp">active <code>WindowProxy</code></span>.</p></li>
</ol>
</li>
<!-- sort order: https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2860 -->
<li>
<p>If <var>value</var> is undefined, then:</p>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then return
undefined.</p></li>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>Return <span>PropertyDescriptor</span>{
[[Value]]: <var>value</var>,
[[Writable]]: false,
[[Enumerable]]: true,
[[Configurable]]: true }.</p></li>
</ol>
</li>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then return !
<span>OrdinaryGetOwnProperty</span>(<var>W</var>, <var>P</var>).</p>
<p class="note">This is a <span>willful violation</span> of the JavaScript specification's
<span>invariants of the essential internal methods</span> to maintain compatibility with
existing web content. See <a href="https://github.com/tc39/ecma262/issues/672">tc39/ecma262
issue #672</a> for more information. <ref>JAVASCRIPT</ref></p>
</li>
<li><p>Let <var>property</var> be <span>CrossOriginGetOwnPropertyHelper</span>(<var>W</var>,
<var>P</var>).</p></li>
<li><p>If <var>property</var> is not undefined, then return <var>property</var>.</p></li>
<li>
<p>If <var>property</var> is undefined and <var>P</var> is in <var>W</var>'s <span>document-tree
child navigable target name property set</span>, then:</p>
<ol>
<li><p>Let <var>value</var> be the <span data-x="nav-wp">active
<code>WindowProxy</code></span> of the <span data-x="dom-window-nameditem-filter">named
object</span> of <var>W</var> with the name <var>P</var>.</p></li>
<li>
<p>Return <span>PropertyDescriptor</span>{
[[Value]]: <var>value</var>,
[[Enumerable]]: false,
[[Writable]]: false,
[[Configurable]]: true }.</p>
<p class="note">The reason the property descriptors are non-enumerable, despite this
mismatching the same-origin behavior, is for compatibility with existing web content. See <a
href="https://github.com/whatwg/html/issues/3183">issue #3183</a> for details.</p>
</li>
</ol>
<li><p>Return ? <span>CrossOriginPropertyFallback</span>(<var>P</var>).</p></li>
</ol>
<h5 id="windowproxy-defineownproperty">[[DefineOwnProperty]] ( <var>P</var>, <var>Desc</var>
)</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then:
<ol>
<li><p>If <var>P</var> is an <span>array index property name</span>, return false.</p></li>
<li>
<p>Return ? <span>OrdinaryDefineOwnProperty</span>(<var>W</var>, <var>P</var>,
<var>Desc</var>).</p>
<p class="note">This is a <span>willful violation</span> of the JavaScript specification's
<span>invariants of the essential internal methods</span> to maintain compatibility with
existing web content. See <a href="https://github.com/tc39/ecma262/issues/672">tc39/ecma262
issue #672</a> for more information. <ref>JAVASCRIPT</ref></p>
</li>
</ol>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h5 id="windowproxy-get">[[Get]] ( <var>P</var>, <var>Receiver</var> )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li><p><span data-x="coop-check-access-report">Check if an access between two browsing contexts
should be reported</span>, given the <span>current global object</span>'s
<span data-x="window bc">browsing context</span>, <var>W</var>'s <span
data-x="window bc">browsing context</span>, <var>P</var>, and the <span>current settings
object</span>.</p></li>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then return ?
<span>OrdinaryGet</span>(<b>this</b>, <var>P</var>, <var>Receiver</var>).</p></li>
<li><p>Return ? <span>CrossOriginGet</span>(<b>this</b>, <var>P</var>,
<var>Receiver</var>).</p></li>
</ol>
<p class="note"><b>this</b> is passed rather than <var>W</var> as <span>OrdinaryGet</span> and
<span>CrossOriginGet</span> will invoke the <a
href="#windowproxy-getownproperty">[[GetOwnProperty]]</a> internal method.</p>
<h5 id="windowproxy-set">[[Set]] ( <var>P</var>, <var>V</var>, <var>Receiver</var> )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li><p><span data-x="coop-check-access-report">Check if an access between two browsing contexts
should be reported</span>, given the <span>current global object</span>'s <span>browsing
context</span>, <var>W</var>'s <span>browsing context</span>, <var>P</var>,
and the <span>current settings object</span>.</p></li>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then:</p>
<ol>
<li><p>If <var>P</var> is an <span>array index property name</span>,
then return false.</p></li>
<li><p>Return ? <span>OrdinarySet</span>(<var>W</var>, <var>P</var>, <var>V</var>,
<var>Receiver</var>).</p></li>
</ol>
</li>
<li>
<p>Return ? <span>CrossOriginSet</span>(<b>this</b>, <var>P</var>, <var>V</var>,
<var>Receiver</var>).</p>
<p class="note"><b>this</b> is passed rather than <var>W</var> as <span>CrossOriginSet</span>
will invoke the <a href="#windowproxy-getownproperty">[[GetOwnProperty]]</a>
internal method.</p>
</li>
</ol>
<h5 id="windowproxy-delete">[[Delete]] ( <var>P</var> )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the
<span data-x="concept-windowproxy-window">[[Window]]</span> internal slot of
<b>this</b>.</p></li>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then:
<ol>
<li>
<p>If <var>P</var> is an <span>array index property name</span>, then:</p>
<ol>
<li><p>Let <var>desc</var> be ! <b>this</b>.[[GetOwnProperty]](<var>P</var>).</p></li>
<li><p>If <var>desc</var> is undefined, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
</li>
<li><p>Return ? <span>OrdinaryDelete</span>(<var>W</var>, <var>P</var>).</p></li>
</ol>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h5 id="windowproxy-ownpropertykeys">[[OwnPropertyKeys]] ( )</h5>
<ol>
<li><p>Let <var>W</var> be the value of the <span
data-x="concept-windowproxy-window">[[Window]]</span> internal slot of <b>this</b>.</p></li>
<li><p>Let <var>maxProperties</var> be <var>W</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span>'s <span>document-tree
child navigables</span>'s <span data-x="list size">size</span>.</p></li>
<li><p>Let <var>keys</var> be <span data-x="exclusive range">the range</span> 0 to
<var>maxProperties</var>, exclusive.</p></li>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<var>W</var>) is true, then return the
concatenation of <var>keys</var> and
<span>OrdinaryOwnPropertyKeys</span>(<var>W</var>).</p></li>
<li><p>Return the concatenation of <var>keys</var> and !
<span>CrossOriginOwnPropertyKeys</span>(<var>W</var>).</p></li>
</ol>
</div>
<h4>The <code>Location</code> interface</h4>
<p>Each <code>Window</code> object is associated with a unique instance of a <code>Location</code>
object, allocated when the <code>Window</code> object is created.</p>
<div w-nodev>
<p class="warning">The <code>Location</code> exotic object is defined through a mishmash of IDL,
invocation of JavaScript internal methods post-creation, and overridden JavaScript internal
methods. Coupled with its scary security policy, please take extra care while implementing
this excrescence.</p>
<p>To create a <code>Location</code> object, run these steps:</p>
<ol>
<li><p>Let <var>location</var> be a new <code>Location</code> <span>platform
object</span>.</p></li>
<li><p>Let <var>valueOf</var> be <var>location</var>'s <span
data-x="concept-relevant-realm">relevant
realm</span>.[[Intrinsics]].[[<span>%Object.prototype.valueOf%</span>]].</p></li>
<li><p>Perform ! <var>location</var>.[[DefineOwnProperty]]("<code data-x="">valueOf</code>", {
[[Value]]: <var>valueOf</var>,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }).</p></li>
<li><p>Perform ! <var>location</var>.[[DefineOwnProperty]](<span>%Symbol.toPrimitive%</span>, {
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }).</p></li>
<li><p>Set the value of the <span>[[DefaultProperties]]</span> internal slot of
<var>location</var> to <var>location</var>.[[OwnPropertyKeys]]().</p></li>
<li><p>Return <var>location</var>.</p></li>
</ol>
<p class="note">The addition of <code data-x="">valueOf</code> and <span>%Symbol.toPrimitive%</span> own
data properties, as well as the fact that all of <code>Location</code>'s IDL attributes are marked
<code data-x="">[<span>LegacyUnforgeable</span>]</code>, is required by legacy code that consulted
the <code>Location</code> interface, or stringified it, to determine the <span
data-x="concept-document-url">document URL</span>, and then used it in a security-sensitive way.
In particular, the <code data-x="">valueOf</code>, <span>%Symbol.toPrimitive%</span>, and <code
data-x="">[<span>LegacyUnforgeable</span>]</code> stringifier mitigations ensure that code such as
<code data-x="">foo[location] = bar</code> or <code data-x="">location + ""</code> cannot be
misdirected.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-location">location</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-location">location</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns a <code>Location</code> object with the current page's location.</p>
<p>Can be set, to navigate to another page.</p>
</dd>
</dl>
<div w-nodev>
<p>The <code>Document</code> object's <dfn attribute for="Document"><code
data-x="dom-document-location">location</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant global object</span>'s <code>Location</code> object, if
<span>this</span> is <span>fully active</span>, and null otherwise.</p>
<p>The <code>Window</code> object's <dfn attribute for="Window"><code
data-x="dom-location">location</code></dfn> getter steps are to return <span>this</span>'s
<code>Location</code> object.</p>
</div>
<p><code>Location</code> objects provide a representation of the <span
data-x="concept-document-url">URL</span> of their associated <code>Document</code>, as well as
methods for <span data-x="navigate">navigating</span> and <span data-x="reload">reloading</span>
the associated <span>navigable</span>.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>Location</dfn> { // but see also <a href="#the-location-interface">additional creation steps</a> and <a href="#location-internal-methods">overridden internal methods</a>
[<span>LegacyUnforgeable</span>] stringifier attribute USVString <span data-x="dom-location-href">href</span>;
[<span>LegacyUnforgeable</span>] readonly attribute USVString <span data-x="dom-location-origin">origin</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-protocol">protocol</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-host">host</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-hostname">hostname</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-port">port</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-pathname">pathname</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-search">search</span>;
[<span>LegacyUnforgeable</span>] attribute USVString <span data-x="dom-location-hash">hash</span>;
[<span>LegacyUnforgeable</span>] undefined <span data-x="dom-location-assign">assign</span>(USVString url);
[<span>LegacyUnforgeable</span>] undefined <span data-x="dom-location-replace">replace</span>(USVString url);
[<span>LegacyUnforgeable</span>] undefined <span data-x="dom-location-reload">reload</span>();
[<span>LegacyUnforgeable</span>, SameObject] readonly attribute <span>DOMStringList</span> <span data-x="dom-location-ancestorOrigins">ancestorOrigins</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>location</var>.<span data-x="">toString()</span></code></dt>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-href">href</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL.</p>
<p>Can be set, to navigate to the given URL.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-origin">origin</span></code></dt>
<dd><p>Returns the <code>Location</code> object's URL's origin.</p></dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-protocol">protocol</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's scheme.</p>
<p>Can be set, to navigate to the same URL with a changed scheme.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-host">host</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's host and port (if different from the default
port for the scheme).</p>
<p>Can be set, to navigate to the same URL with a changed host and port.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-hostname">hostname</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's host.</p>
<p>Can be set, to navigate to the same URL with a changed host.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-port">port</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's port.</p>
<p>Can be set, to navigate to the same URL with a changed port.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-pathname">pathname</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's path.</p>
<p>Can be set, to navigate to the same URL with a changed path.</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-search">search</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's query (includes leading "<code
data-x="">?</code>" if non-empty).</p>
<p>Can be set, to navigate to the same URL with a changed query (ignores leading "<code
data-x="">?</code>").</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-hash">hash</span></code></dt>
<dd>
<p>Returns the <code>Location</code> object's URL's fragment (includes leading "<code
data-x="">#</code>" if non-empty).</p>
<p>Can be set, to navigate to the same URL with a changed fragment (ignores leading "<code
data-x="">#</code>").</p>
</dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-assign">assign</span>(<var>url</var>)</code></dt>
<dd><p>Navigates to the given URL.</p></dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-replace">replace</span>(<var>url</var>)</code></dt>
<dd><p>Removes the current page from the session history and navigates to the given URL.</p></dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-reload">reload</span>()</code></dt>
<dd><p>Reloads the current page.</p></dd>
<dt><code data-x=""><var>location</var>.<span subdfn data-x="dom-location-ancestorOrigins">ancestorOrigins</span></code></dt>
<dd>
<p>Returns a <code>DOMStringList</code> object listing the origins of the <span>ancestor navigables</span>' <span
data-x="nav-document">active documents</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Location</code> object has an associated <dfn>relevant <code>Document</code></dfn>,
which is its <span>relevant global object</span>'s <span
data-x="window bc">browsing context</span>'s <span>active document</span>, if this
<code>Location</code> object's <span>relevant global object</span>'s <span data-x="window
bc">browsing context</span> is non-null, and null otherwise.</p>
<p>A <code>Location</code> object has an associated <dfn data-x="concept-location-url">url</dfn>,
which is this <code>Location</code> object's <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-url">URL</span>, if this <code>Location</code> object's <span>relevant
<code>Document</code></span> is non-null, and <code>about:blank</code> otherwise.</p>
<p>A <code>Location</code> object has an associated <dfn
data-x="concept-location-ancestor-origins-list">ancestor origins list</dfn>. When a
<code>Location</code> object is created, its <span
data-x="concept-location-ancestor-origins-list">ancestor origins list</span> must be set to a
<code>DOMStringList</code> object whose associated list is the <span>list</span> of strings that
the following steps would produce:</p>
<ol>
<li><p>Let <var>output</var> be a new <span>list</span> of strings.</p></li>
<li><p>Let <var>current</var> be the <code>Location</code> object's <span>relevant
<code>Document</code></span>.</p></li>
<li>
<p>While <var>current</var>'s <span data-x="doc-container-document">container document</span>
is non-null:</p>
<ol>
<li><p>Set <var>current</var> to <var>current</var>'s <span
data-x="doc-container-document">container document</span>.</p></li>
<li><p><span data-x="list append">Append</span> the <span data-x="serialization of an
origin">serialization</span> of <var>current</var>'s <span
data-x="concept-document-origin">origin</span> to <var>output</var>.</p></li>
</ol>
</li>
<li><p>Return <var>output</var>.</p></li>
</ol>
<p>To <dfn><code>Location</code>-object navigate</dfn> a <code>Location</code> object
<var>location</var> to a <span>URL</span> <var>url</var>, optionally given a <code
data-x="NavigationHistoryBehavior">NavigationHistoryBehavior</code> <var>historyHandling</var>
(default "<code data-x="NavigationHistoryBehavior-auto">auto</code>"):</p>
<ol>
<li><p>Let <var>navigable</var> be <var>location</var>'s <span>relevant global object</span>'s
<span data-x="window navigable">navigable</span>.</p></li>
<li><p>Let <var>sourceDocument</var> be the <span data-x="concept-incumbent-global">incumbent
global object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p></li>
<li><p>If <var>location</var>'s <span>relevant <code>Document</code></span> is not yet
<span>completely loaded</span>, and the <span data-x="concept-incumbent-global">incumbent global
object</span> does not have <span>transient activation</span>, then set
<var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li><p><span>Navigate</span><!--DONAV location--> <var>navigable</var> to <var>url</var> using
<var>sourceDocument</var>, with <i><span>exceptionsEnabled</span></i> set to true and <i
data-x="navigation-hh">historyHandling</i> set to <var>historyHandling</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-href">href</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-location-url">url</span>, <span
data-x="concept-url-serializer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-href">href</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>Let <var>url</var> be the result of <span>encoding-parsing a URL</span> given the given
value, relative to the <span>entry settings object</span>.</p></li>
<li><p>If <var>url</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>url</var>.</p></li>
</ol>
<p class="note">The <code data-x="dom-location-href">href</code> setter intentionally has no
security check.</p>
<p>The <dfn attribute for="Location"><code data-x="dom-location-origin">origin</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return the <span data-x="serialization of an origin">serialization</span> of
<span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-origin">origin</span>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-protocol">protocol</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-scheme">scheme</span>, followed by "<code data-x="">:</code>".</p></li>
</ol>
<p>The <code data-x="dom-location-protocol">protocol</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li>
<p>Let <var>possibleFailure</var> be the result of <span data-x="basic url parser">basic URL
parsing</span> the given value, followed by "<code data-x="">:</code>", with <var>copyURL</var>
as <span data-x="basic url parser url"><i>url</i></span> and <span>scheme start state</span> as
<span data-x="basic url parser state override"><i>state override</i></span>.</p>
<p class="note">Because the URL parser ignores multiple consecutive colons, providing a value
of "<code data-x="">https:</code>" (or even "<code data-x="">https::::</code>") is the same as
providing a value of "<code data-x="">https</code>".</p>
</li>
<li><p>If <var>possibleFailure</var> is failure, then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>copyURL</var>'s <span data-x="concept-url-scheme">scheme</span> is not an
<span>HTTP(S) scheme</span>, then terminate these steps.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-host">host</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-host">host</span> is null, return the empty
string.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-port">port</span> is null, return
<var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>, followed by "<code data-x="">:</code>" and <var>url</var>'s <span
data-x="concept-url-port">port</span>, <span data-x="serialize an
integer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-host">host</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If <var>copyURL</var> has an <span>opaque path</span>, then return.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>host
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-hostname">hostname</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-host">host</span> is null, return the empty string.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-hostname">hostname</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If <var>copyURL</var> has an <span>opaque path</span>, then return.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>hostname
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-port">port</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-port">port</span> is null, return the empty string.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-port">port</span>, <span data-x="serialize an
integer">serialized</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-port">port</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If <var>copyURL</var> <span>cannot have a username/password/port</span>, then
return.</p></li>
<li><p>If the given value is the empty string, then set <var>copyURL</var>'s <span
data-x="concept-url-port">port</span> to null.</p></li>
<li><p>Otherwise, <span data-x="basic url parser">basic URL parse</span> the given value, with
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>port
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-pathname">pathname</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return the result of <span data-x="URL path serializer">URL path serializing</span> this
<code>Location</code> object's <span data-x="concept-location-url">url</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-pathname">pathname</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If <var>copyURL</var> has an <span>opaque path</span>, then return.</p></li>
<li><p>Set <var>copyURL</var>'s <span data-x="concept-url-path">path</span> to the empty
list.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> the given value, with
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>path start
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-search">search</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-query">query</span> is either null or the empty string, return the empty
string.</p></li>
<li><p>Return "<code data-x="">?</code>", followed by <span>this</span>'s <span
data-x="concept-location-url">url</span>'s <span
data-x="concept-url-query">query</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-search">search</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>If the given value is the empty string, set <var>copyURL</var>'s <span
data-x="concept-url-query">query</span> to null.
<li>
<p>Otherwise, run these substeps:</p>
<ol>
<li><p>Let <var>input</var> be the given value with a single leading "<code
data-x="">?</code>" removed, if any.</p></li>
<li><p>Set <var>copyURL</var>'s <span data-x="concept-url-query">query</span> to the empty
string.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> <var>input</var>, with null, the
<span>relevant <code>Document</code></span>'s <span>document's character encoding</span>,
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span>, and <span>query
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
</ol>
</li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p>The <dfn attribute for="Location"><code data-x="dom-location-hash">hash</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is non-null and its
<span data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with
the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-fragment">fragment</span> is either null or the empty string, return the
empty string.</p></li>
<li><p>Return "<code data-x="">#</code>", followed by <span>this</span>'s <span
data-x="concept-location-url">url</span>'s <span
data-x="concept-url-fragment">fragment</span>.</p></li>
</ol>
<p>The <code data-x="dom-location-hash">hash</code> setter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>copyURL</var> be a copy of <span>this</span>'s <span
data-x="concept-location-url">url</span>.</p></li>
<li><p>Let <var>input</var> be the given value with a single leading "<code data-x="">#</code>"
removed, if any.</p></li>
<li><p>Set <var>copyURL</var>'s <span data-x="concept-url-fragment">fragment</span> to the empty
string.</p></li>
<li><p><span data-x="basic url parser">Basic URL parse</span> <var>input</var>, with
<var>copyURL</var> as <span data-x="basic url parser url"><i>url</i></span> and <span>fragment
state</span> as <span data-x="basic url parser state override"><i>state
override</i></span>.</p></li>
<li>
<p>If <var>copyURL</var>'s <span data-x="concept-url-fragment">fragment</span> is
<span>this</span>'s <span data-x="concept-location-url">url</span>'s <span
data-x="concept-url-fragment">fragment</span>, then return.</p>
<p class="note">This bailout is necessary for compatibility with deployed content, which <a
href="https://bugzilla.mozilla.org/show_bug.cgi?id=1733797#c2">redundantly sets <code
data-x="dom-location-hash">location.hash</code> on scroll</a>. It does not apply to other
mechanisms of fragment navigation, such as the <code
data-x="dom-location-href">location.href</code> setter or <code
data-x="dom-location-assign">location.assign()</code>.</p>
</li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>copyURL</var>.</p></li>
</ol>
<p class="note">Unlike the equivalent API for the <code>a</code> and <code>area</code> elements,
the <code data-x="dom-location-hash">hash</code> setter does not special case the empty string, to
remain compatible with deployed scripts.</p>
<hr>
<p>The <dfn method for="Location"><code
data-x="dom-location-assign">assign(<var>url</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to the <span>entry settings object</span>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>urlRecord</var>.</p></li>
</ol>
<p>The <dfn method for="Location"><code
data-x="dom-location-replace">replace(<var>url</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then
return.</p></li>
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to the <span>entry settings object</span>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span><code>Location</code>-object navigate</span> <span>this</span> to
<var>urlRecord</var> given "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
</ol>
<p class="note">The <code data-x="dom-location-replace">replace()</code> method intentionally has
no security check.</p>
<p>The <dfn method for="Location"><code data-x="dom-location-reload">reload()</code></dfn> method
steps are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant
<code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is null, then return.</p></li>
<li><p>If <var>document</var>'s <span data-x="concept-document-origin">origin</span> is not
<span>same origin-domain</span> with the <span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span>Reload</span> <var>document</var>'s <span>node navigable</span>.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="Location"><code
data-x="dom-location-ancestorOrigins">ancestorOrigins</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span> is null, then return
an empty <span>list</span>.</p></li>
<li><p>If <span>this</span>'s <span>relevant <code>Document</code></span>'s <span
data-x="concept-document-origin">origin</span> is not <span>same origin-domain</span> with the
<span>entry settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Otherwise, return <span>this</span>'s <span
data-x="concept-location-ancestor-origins-list">ancestor origins list</span>.</p></li>
</ol>
<p class="warning">The details of how the <code
data-x="dom-location-ancestorOrigins">ancestorOrigins</code> attribute works are still
controversial and might change. See <a href="https://github.com/whatwg/html/issues/1918">issue
#1918</a> for more information.</p>
<hr>
<p id="location-internal-methods">As explained earlier, the <code>Location</code> exotic object
requires additional logic beyond IDL for security purposes. The <code>Location</code> object must
use the ordinary internal methods except where it is explicitly specified otherwise below.</p>
<p>Also, every <code>Location</code> object has a <dfn>[[DefaultProperties]]</dfn> internal slot
representing its own properties at time of its creation.</p>
<h5 id="location-getprototypeof">[[GetPrototypeOf]] ( )</h5>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then return !
<span>OrdinaryGetPrototypeOf</span>(<b>this</b>).</p></li>
<li><p>Return null.</p></li>
</ol>
<h5 id="location-setprototypeof">[[SetPrototypeOf]] ( <var>V</var> )</h5>
<ol>
<li><p>Return ! <span>SetImmutablePrototype</span>(<b>this</b>, <var>V</var>).</p></li>
</ol>
<h5 id="location-isextensible">[[IsExtensible]] ( )</h5>
<ol>
<li><p>Return true.</p></li>
</ol>
<h5 id="location-preventextensions">[[PreventExtensions]] ( )</h5>
<ol>
<li><p>Return false.</p></li>
</ol>
<h5 id="location-getownproperty">[[GetOwnProperty]] ( <var>P</var> )</h5>
<ol>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then:</p>
<ol>
<li><p>Let <var>desc</var> be <span>OrdinaryGetOwnProperty</span>(<b>this</b>,
<var>P</var>).</p></li>
<li><p>If the value of the <span>[[DefaultProperties]]</span> internal slot of <b>this</b>
contains <var>P</var>, then set <var>desc</var>.[[Configurable]] to true.</p></li>
<li><p>Return <var>desc</var>.</p></li>
</ol>
</li>
<li><p>Let <var>property</var> be <span>CrossOriginGetOwnPropertyHelper</span>(<b>this</b>,
<var>P</var>).</p></li>
<li><p>If <var>property</var> is not undefined, then return <var>property</var>.</p></li>
<li><p>Return ? <span>CrossOriginPropertyFallback</span>(<var>P</var>).</p></li>
</ol>
<h5 id="location-defineownproperty">[[DefineOwnProperty]] ( <var>P</var>, <var>Desc</var> )</h5>
<ol>
<li>
<p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then:</p>
<ol>
<li><p>If the value of the <span>[[DefaultProperties]]</span> internal slot of <b>this</b>
contains <var>P</var>, then return false.</p></li>
<li><p>Return ? <span>OrdinaryDefineOwnProperty</span>(<b>this</b>, <var>P</var>,
<var>Desc</var>).</p></li>
</ol>
</li>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h5 id="location-get">[[Get]] ( <var>P</var>, <var>Receiver</var> )</h5>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then return ?
<span>OrdinaryGet</span>(<b>this</b>, <var>P</var>, <var>Receiver</var>).</p></li>
<li><p>Return ? <span>CrossOriginGet</span>(<b>this</b>, <var>P</var>,
<var>Receiver</var>).</p></li>
</ol>
<h5 id="location-set">[[Set]] ( <var>P</var>, <var>V</var>, <var>Receiver</var> )</h5>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then return ?
<span>OrdinarySet</span>(<b>this</b>, <var>P</var>, <var>V</var>, <var>Receiver</var>).</p></li>
<li><p>Return ? <span>CrossOriginSet</span>(<b>this</b>, <var>P</var>, <var>V</var>,
<var>Receiver</var>).</p></li>
</ol>
<h5 id="location-delete">[[Delete]] ( <var>P</var> )</h5>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then return ?
<span>OrdinaryDelete</span>(<b>this</b>, <var>P</var>).</p></li>
<li><p>Throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
<h5 id="location-ownpropertykeys">[[OwnPropertyKeys]] ( )</h5>
<ol>
<li><p>If <span>IsPlatformObjectSameOrigin</span>(<b>this</b>) is true, then return
<span>OrdinaryOwnPropertyKeys</span>(<b>this</b>).</p></li>
<li><p>Return <span>CrossOriginOwnPropertyKeys</span>(<b>this</b>).</p></li>
</ol>
</div>
<h4>The <code>History</code> interface</h4>
<pre><code class="idl">enum <dfn enum>ScrollRestoration</dfn> { "<span data-x="dom-ScrollRestoration-auto">auto</span>", "<span data-x="dom-ScrollRestoration-manual">manual</span>" };
[Exposed=Window]
interface <dfn interface>History</dfn> {
readonly attribute unsigned long <span data-x="dom-history-length">length</span>;
attribute <span>ScrollRestoration</span> <span data-x="dom-history-scroll-restoration">scrollRestoration</span>;
readonly attribute any <span data-x="dom-history-state">state</span>;
undefined <span data-x="dom-history-go">go</span>(optional long delta = 0);
undefined <span data-x="dom-history-back">back</span>();
undefined <span data-x="dom-history-forward">forward</span>();
undefined <span data-x="dom-history-pushState">pushState</span>(any data, DOMString unused, optional USVString? url = null);
undefined <span data-x="dom-history-replaceState">replaceState</span>(any data, DOMString unused, optional USVString? url = null);
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><span subdfn data-x="dom-history">history</span>.<span subdfn data-x="dom-history-length">length</span></code></dt>
<dd><p>Returns the number of overall <span data-x="tn-session-history-entries">session history
entries</span> for the current <span>traversable navigable</span>.</p></dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-scroll-restoration">scrollRestoration</span></code></dt>
<dd><p>Returns the <span data-x="she-scroll-restoration-mode">scroll restoration mode</span> of
the <span data-x="nav-active-history-entry">active session history entry</span>.</p></dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span data-x="dom-history-scroll-restoration">scrollRestoration</span> = <var>value</var></code></dt>
<dd><p>Set the <span data-x="she-scroll-restoration-mode">scroll restoration mode</span> of the
<span data-x="nav-active-history-entry">active session history entry</span> to
<var>value</var>.</p></dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-state">state</span></code></dt>
<dd><p>Returns the <span data-x="she-classic-history-api-state">classic history API state</span>
of the <span data-x="nav-active-history-entry">active session history entry</span>, deserialized
into a JavaScript value.</p></dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span data-x="dom-history-go">go</span>()</code></dt>
<dd><p>Reloads the current page.</p></dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-go">go</span>(<var>delta</var>)</code></dt>
<dd>
<p>Goes back or forward the specified number of steps in the overall <span
data-x="tn-session-history-entries">session history entries</span> list for the current
<span>traversable navigable</span>.</p>
<p>A zero delta will reload the current page.</p>
<p>If the delta is out of range, does nothing.</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-back">back</span>()</code></dt>
<dd>
<p>Goes back one step in the overall <span data-x="tn-session-history-entries">session history
entries</span> list for the current <span>traversable navigable</span>.</p>
<p>If there is no previous page, does nothing.</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-forward">forward</span>()</code></dt>
<dd>
<p>Goes forward one step in the overall <span data-x="tn-session-history-entries">session
history entries</span> list for the current <span>traversable navigable</span>.</p>
<p>If there is no next page, does nothing.</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-pushState">pushState</span>(<var>data</var>, "")</code></dt>
<dd>
<p>Adds a new entry into session history with its <span
data-x="she-classic-history-api-state">classic history API state</span> set to a serialization
of <var>data</var>. The <span data-x="nav-active-history-entry">active history entry</span>'s
<span data-x="she-url">URL</span> will be copied over and used for the new entry's URL.</p>
<p>(The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.)</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span data-x="dom-history-pushState">pushState</span>(<var>data</var>, "", <var>url</var>)</code></dt>
<dd>
<p>Adds a new entry into session history with its <span
data-x="she-classic-history-api-state">classic history API state</span> set to a serialization
of <var>data</var>, and with its <span data-x="she-url">URL</span> set to <var>url</var>.</p>
<p>If the current <code>Document</code> <span data-x="can have its URL rewritten">cannot have
its URL rewritten</span> to <var>url</var>, a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code> will be thrown.</p>
<p>(The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.)</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span subdfn data-x="dom-history-replaceState">replaceState</span>(<var>data</var>, "")</code></dt>
<dd>
<p>Updates the <span data-x="she-classic-history-api-state">classic history API state</span> of
the <span data-x="nav-active-history-entry">active session history entry</span> to a structured
clone of <var>data</var>.</p>
<p>(The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.)</p>
</dd>
<dt><code data-x=""><span data-x="dom-history">history</span>.<span data-x="dom-history-replaceState">replaceState</span>(<var>data</var>, "", <var>url</var>)</code></dt>
<dd>
<p>Updates the <span data-x="she-classic-history-api-state">classic history API state</span> of
the <span data-x="nav-active-history-entry">active session history entry</span> to a structured
clone of <var>data</var>, and its <span data-x="she-url">URL</span> to <var>url</var>.</p>
<p>If the current <code>Document</code> <span data-x="can have its URL rewritten">cannot have
its URL rewritten</span> to <var>url</var>, a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code> will be thrown.</p>
<p>(The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.)</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Document</code> has a <dfn data-x="doc-history">history object</dfn>, a
<code>History</code> object.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-history">history</code></dfn> getter steps
are to return <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="doc-history">history object</span>.</p>
<hr>
<p>Each <code>History</code> object has <dfn data-x="concept-history-state">state</dfn>,
initially null.</p>
<p>Each <code>History</code> object has a <dfn data-x="concept-history-length">length</dfn>, a
non-negative integer, initially 0.</p>
<p>Each <code>History</code> object has an <dfn data-x="concept-history-index">index</dfn>, a
non-negative integer, initially 0.</p>
<p class="note">Although the <span data-x="concept-history-index">index</span> is not directly
exposed, it can be inferred from changes to the <span
data-x="concept-history-length">length</span> during synchronous navigations. In fact, that is
what it's used for.</p>
<p>The <dfn attribute for="History"><code data-x="dom-history-length">length</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-history-length">length</span>.</p></li>
</ol>
<p>The <dfn attribute for="History"><code
data-x="dom-history-scroll-restoration">scrollRestoration</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Return <span>this</span>'s <span>node navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-scroll-restoration-mode">scroll restoration mode</span>.</p></li>
</ol>
<p>The <code data-x="dom-history-scroll-restoration">scrollRestoration</code> setter steps
are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <span>this</span>'s <span>node navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-scroll-restoration-mode">scroll restoration mode</span> to the given value.</p></li>
</ol>
<p>The <dfn attribute for="History"><code data-x="dom-history-state">state</code></dfn> getter
steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Return <span>this</span>'s <span data-x="concept-history-state">state</span>.</p></li>
</ol>
<p>The <dfn method for="History"><code data-x="dom-history-go">go(<var>delta</var>)</code></dfn>
method steps are to <span>delta traverse</span> <span>this</span> given <var>delta</var>.</p>
<p>The <dfn method for="History"><code data-x="dom-history-back">back()</code></dfn> method steps
are to <span>delta traverse</span> <span>this</span> given −1.</p>
<p>The <dfn method for="History"><code data-x="dom-history-forward">forward()</code></dfn> method
steps are to <span>delta traverse</span> <span>this</span> given +1.</p>
<p>To <dfn>delta traverse</dfn> a <code>History</code> object <var>history</var> given an integer
<var>delta</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>history</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>delta</var> is 0, then <span>reload</span> <var>document</var>'s <span>node
navigable</span>, and return.</p></li>
<li><p><span>Traverse the history by a delta</span> given <var>document</var>'s <span>node
navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>, <var>delta</var>,
and with <i data-x="traverse-sourceDocument">sourceDocument</i> set to
<var>document</var>.</p></li>
</ol>
<p>The <dfn method for="History"><code data-x="dom-history-pushState">pushState(<var>data</var>,
<var>unused</var>, <var>url</var>)</code></dfn> method steps are to run the <span>shared history
push/replace state steps</span> given <span>this</span>, <var>data</var>, <var>url</var>, and
"<code data-x="NavigationHistoryBehavior-push">push</code>".</p>
<p>The <dfn method for="History"><code
data-x="dom-history-replaceState">replaceState(<var>data</var>, <var>unused</var>,
<var>url</var>)</code></dfn> method steps are to run the <span>shared history push/replace state
steps</span> given <span>this</span>, <var>data</var>, <var>url</var>, and "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
<p>The <dfn>shared history push/replace state steps</dfn>, given a <code>History</code>
<var>history</var>, a value <var>data</var>, a <span>scalar value string</span>-or-null
<var>url</var>, and a <span>history handling behavior</span> <var>historyHandling</var>, are:</p>
<ol>
<li><p>Let <var>document</var> be <var>history</var>'s associated <code>Document</code>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Optionally, throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.
(For example, the user agent might disallow calls to these methods that are invoked on a timer,
or from event listeners that are not triggered in response to a clear user action, or that are
invoked in rapid succession.)</p></li>
<li><p>Let <var>serializedData</var> be
<span>StructuredSerializeForStorage</span>(<var>data</var>). Rethrow any exceptions.</p></li>
<li><p>Let <var>newURL</var> be <var>document</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li>
<p>If <var>url</var> is not null or the empty string, then:</p>
<ol>
<li><p>Set <var>newURL</var> to the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to the <span>relevant settings object</span> of
<var>history</var>.</p></li>
<li><p>If <var>newURL</var> is failure, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <var>document</var> <span data-x="can have its URL rewritten">cannot have its URL
rewritten</span> to <var>newURL</var>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
</ol>
<p class="note">The special case for the empty string here is historical, and leads to
different resulting URLs when comparing code such as <code data-x="">location.href = ""</code>
(which performs URL parsing on the empty string) versus <code
data-x="">history.pushState(null, "", "")</code> (which bypasses it).</p>
</li>
<li><p>Let <var>navigation</var> be <var>history</var>'s <span>relevant global object</span>'s
<span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>continue</var> be the result of <span data-x="fire a push/replace/reload navigate
event">firing a push/replace/reload <code data-x="event-navigate">navigate</code> event</span> at
<var>navigation</var> with <i data-x="fire-navigate-prr-navigationType">navigationType</i> set to
<var>historyHandling</var>, <i data-x="fire-navigate-prr-isSameDocument">isSameDocument</i> set
to true, <i data-x="fire-navigate-prr-destinationURL">destinationURL</i> set to
<var>newURL</var>, and <i
data-x="fire-navigate-prr-classicHistoryAPIState">classicHistoryAPIState</i> set to
<var>serializedData</var>.</p></li>
<li><p>If <var>continue</var> is false, then return.</p>
<li><p>Run the <span>URL and history update steps</span> given <var>document</var> and
<var>newURL</var>, with <i data-x="uhus-serializedData">serializedData</i> set to
<var>serializedData</var> and <i data-x="uhus-historyHandling">historyHandling</i> set to
<var>historyHandling</var>.</p></li>
</ol>
<p>User agents may limit the number of state objects added to the session history per page. If a
page hits the <span>implementation-defined</span> limit, user agents must remove the entry
immediately after the first entry for that <code>Document</code> object in the session history
after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
as a LIFO buffer for navigation.)</p>
<p>A <code>Document</code> <var>document</var> <dfn>can have its URL rewritten</dfn> to a
<span>URL</span> <var>targetURL</var> if the following algorithm returns true:</p>
<ol>
<li><p>Let <var>documentURL</var> be <var>document</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>If <var>targetURL</var> and <var>documentURL</var> differ in their <span
data-x="concept-url-scheme">scheme</span>, <span data-x="concept-url-username">username</span>,
<span data-x="concept-url-password">password</span>, <span
data-x="concept-url-host">host</span>, or <span data-x="concept-url-port">port</span>
components, then return false.</p></li>
<li>
<p>If <var>targetURL</var>'s <span data-x="concept-url-scheme">scheme</span> is an
<span>HTTP(S) scheme</span>, then return true.</p>
<p class="note">Differences in <span data-x="concept-url-path">path</span>, <span
data-x="concept-url-query">query</span>, and <span
data-x="concept-url-fragment">fragment</span> are allowed for <code data-x="http
protocol">http:</code> and <code data-x="https protocol">https:</code> URLs.</p>
</li>
<li>
<p>If <var>targetURL</var>'s <span data-x="concept-url-scheme">scheme</span> is "<code
data-x="">file</code>", then:</p>
<ol>
<li><p>If <var>targetURL</var> and <var>documentURL</var> differ in their <span
data-x="concept-url-path">path</span> component, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p class="note">Differences in <span data-x="concept-url-query">query</span> and <span
data-x="concept-url-fragment">fragment</span> are allowed for <code data-x="">file:</code>
URLs.</p>
</li>
<li>
<p>If <var>targetURL</var> and <var>documentURL</var> differ in their <span
data-x="concept-url-path">path</span> component or <span
data-x="concept-url-query">query</span> components, then return false.</p>
<p class="note">Only differences in <span data-x="concept-url-fragment">fragment</span> are
allowed for other types of URLs.</p>
</li>
<li><p>Return true.</p></li>
</ol>
</div>
<div class="example">
<table>
<thead>
<tr>
<th><var>document</var>'s <span data-x="concept-document-url">URL</span>
<th><var>targetURL</var>
<th><span subdfn>can have its URL rewritten</span>
<tbody>
<tr>
<td><code data-x="">https://example.com/home</code>
<td><code data-x="">https://example.com/home#about</code>
<td>✅
<tr>
<td><code data-x="">https://example.com/home</code>
<td><code data-x="">https://example.com/home?page=shop</code>
<td>✅
<tr>
<td><code data-x="">https://example.com/home</code>
<td><code data-x="">https://example.com/shop</code>
<td>✅
<tr>
<td><code data-x="">https://example.com/home</code>
<td><code data-x="">https://user:pass@example.com/home</code>
<td>❌
<tr>
<td><code data-x="">https://example.com/home</code>
<td><code data-x="">http://example.com/home</code>
<td>❌
<tr>
<td><code data-x="">file:///path/to/x</code>
<td><code data-x="">file:///path/to/x#hash</code>
<td>✅
<tr>
<td><code data-x="">file:///path/to/x</code>
<td><code data-x="">file:///path/to/x?search</code>
<td>✅
<tr>
<td><code data-x="">file:///path/to/x</code>
<td><code data-x="">file:///path/to/y</code>
<td>❌
<tr>
<td><code data-x="">about:blank</code>
<td><code data-x="">about:blank#hash</code>
<td>✅
<tr>
<td><code data-x="">about:blank</code>
<td><code data-x="">about:blank?search</code>
<td>❌
<tr>
<td><code data-x="">about:blank</code>
<td><code data-x="">about:srcdoc</code>
<td>❌
<tr>
<td><code data-x="">data:text/html,foo</code>
<td><code data-x="">data:text/html,foo#hash</code>
<td>✅
<tr>
<td><code data-x="">data:text/html,foo</code>
<td><code data-x="">data:text/html,foo?search</code>
<td>❌
<tr>
<td><code data-x="">data:text/html,foo</code>
<td><code data-x="">data:text/html,bar</code>
<td>❌
<tr>
<td><code data-x="">data:text/html,foo</code>
<td><code data-x="">data:bar</code>
<td>❌
<tr>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43</code>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash</code>
<td>✅
<tr>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43</code>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search</code>
<td>❌
<tr>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43</code>
<td><code data-x="">blob:https://example.com/anything</code>
<td>❌
<tr>
<td><code data-x="">blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43</code>
<td><code data-x="">blob:path</code>
<td>❌
</table>
<p>Note how only the <span data-x="concept-document-url">URL</span> of the <code>Document</code>
matters, and not its <span data-x="concept-document-origin">origin</span>. They can mismatch in
cases like <code>about:blank</code> <code>Document</code>s with inherited origins, in sandboxed
<code>iframe</code>s, or when the <code data-x="dom-document-domain">document.domain</code>
setter has been used.</p>
</div>
<div class="example">
<p>Consider a game where the user can navigate along a line, such that the user is always at some
coordinate, and such that the user can bookmark the page corresponding to a particular
coordinate, to return to it later.</p>
<p>A static page implementing the x=5 position in such a game could look like the following:</p>
<pre><code class="html"><!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate 5 on the line.</p>
<p>
<a href="?x=6">Advance to 6</a> or
<a href="?x=4">retreat to 4</a>?
</p></code></pre>
<p>The problem with such a system is that each time the user clicks, the whole page has to be
reloaded. Here instead is another way of doing it, using script:</p>
<pre><code class="html"><!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
<p>
<a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
<a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
</p>
<script>
var currentPage = 5; // prefilled by server
function go(d) {
setupPage(currentPage + d);
history.pushState(currentPage, "", '?x=' + currentPage);
}
onpopstate = function(event) {
setupPage(event.state);
}
function setupPage(page) {
currentPage = page;
document.title = 'Line Game - ' + currentPage;
document.getElementById('coord').textContent = currentPage;
document.links[0].href = '?x=' + (currentPage+1);
document.links[0].textContent = 'Advance to ' + (currentPage+1);
document.links[1].href = '?x=' + (currentPage-1);
document.links[1].textContent = 'retreat to ' + (currentPage-1);
}
</script></code></pre>
<p>In systems without script, this still works like the previous example. However, users that
<em>do</em> have script support can now navigate much faster, since there is no network access
for the same experience. Furthermore, contrary to the experience the user would have with just a
naïve script-based approach, bookmarking and navigating the session history still work.</p>
<p>In the example above, the <var>data</var> argument to the <code
data-x="dom-history-pushState">pushState()</code> method is the same information as would be sent
to the server, but in a more convenient form, so that the script doesn't have to parse the URL
each time the user navigates.</p>
</div>
<div class="example">
<p>Most applications want to use the same <span>scroll restoration mode</span> value for all of
their history entries. To achieve this they can set the <code
data-x="dom-history-scroll-restoration">scrollRestoration</code> attribute as soon as possible
(e.g., in the first <code>script</code> element in the document's <code>head</code> element) to
ensure that any entry added to the history session gets the desired scroll restoration mode.</p>
<pre><code class="html"><head>
<script>
if ('scrollRestoration' in history)
history.scrollRestoration = 'manual';
</script>
</head>
</code></pre>
</div>
<h4 id="navigation-api">The navigation API</h4>
<h5 id="navigation-api-intro">Introduction</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The navigation API, provided by the global <code data-x="dom-navigation">navigation</code>
property, provides a modern and web application-focused way of managing navigations and history entries. It is a successor to the classic <code data-x="dom-location">location</code> and <code data-x="dom-history">history</code> APIs.</p>
<p>One ability the API provides is inspecting <span data-x="session history entry">session history entries</span>. For example, the following will display the entries' URLs in an ordered list:</p>
<pre><code class="js">const ol = document.createElement("ol");
ol.start = 0; // so that the list items' ordinal values match up with the entry indices
for (const entry of navigation.entries()) {
const li = document.createElement("li");
if (entry.index < navigation.currentEntry.index) {
li.className = "backward";
} else if (entry.index > navigation.currentEntry.index) {
li.className = "forward";
} else {
li.className = "current";
}
li.textContent = entry.url;
ol.append(li);
}</code></pre>
<p>The <code data-x="dom-Navigation-entries">navigation.entries()</code> array contains <code>NavigationHistoryEntry</code> instances, which have other useful properties in addition to the <code data-x="dom-NavigationHistoryEntry-url">url</code> and <code data-x="dom-NavigationHistoryEntry-index">index</code> properties shown here. Note that the array only contains <code>NavigationHistoryEntry</code> objects that represent the current <span>navigable</span>, and thus its contents are not impacted by navigations inside <span data-x="navigable container">navigable containers</span> such as <code>iframe</code>s, or by navigations of the <span data-x="nav-parent">parent navigable</span> in cases where the navigation API is itself being used inside an <code>iframe</code>. Additionally, it only contains <code>NavigationHistoryEntry</code> objects representing same-<span>origin</span> <span data-x="session history entry">session history entries</span>, meaning that if the user has visited other origins before or after the current one, there will not be corresponding <code>NavigationHistoryEntry</code>s.</p>
<hr>
<p>The navigation API can also be used to navigate, reload, or traverse through the history:</p>
<pre><code class="html"><button onclick="navigation.reload()">Reload</button>
<input type="url" id="navigationURL">
<button onclick="navigation.navigate(navigationURL.value)">Navigate</button>
<button id="backButton" onclick="navigation.back()">Back</button>
<button id="forwardButton" onclick="navigation.forward()">Forward</button>
<select id="traversalDestinations"></select>
<button id="goButton" onclick="navigation.traverseTo(traversalDestinations.value)">Traverse To</button>
<script>
backButton.disabled = !navigation.canGoBack;
forwardButton.disabled = !navigation.canGoForward;
for (const entry of navigation.entries()) {
traversalDestinations.append(new Option(entry.url, entry.key));
}
</script></code></pre>
<p>Note that traversals are again limited to same-<span>origin</span> destinations, meaning that, for example, <code data-x="dom-Navigation-canGoBack">navigation.canGoBack</code> will be false if the previous <span>session history entry</span> is for a page from another origin.</p>
<hr>
<p>The most powerful part of the navigation API is the <code data-x="event-navigate">navigate</code> event, which fires whenever almost any navigation or traversal occurs in the current <span>navigable</span>:</p>
<pre><code class="js">navigation.onnavigate = event => {
console.log(event.navigationType); // "push", "replace", "reload", or "traverse"
console.log(event.destination.url);
console.log(event.userInitiated);
// ... and <a href="#the-navigateevent-interface">other useful properties</a>
};</code></pre>
<p>(The event will not fire for <a href="#nav-traversal-ui">location bar-initiated navigations</a>, or navigations initiated from other windows, when the destination of the navigation is a new document.)</p>
<p>Much of the time, the event's <code data-x="dom-Event-cancelable">cancelable</code> property will be true, meaning this event can be canceled using <code data-x="dom-Event-preventDefault">preventDefault()</code>:</p>
<pre><code class="js">navigation.onnavigate = event => {
if (event.cancelable && isDisallowedURL(event.destination.url)) {
alert(`Please don't go to ${event.destination.url}!`);
event.preventDefault();
}
};
</code></pre>
<p>The <code data-x="dom-Event-cancelable">cancelable</code> property will be false for some "<code data-x="dom-NavigationType-traverse">traverse</code>" navigations, such as those taking place inside <span data-x="child navigable">child navigables</span>, those crossing to new origins, or when the user attempts to traverse again shortly after a previous call to <code data-x="dom-Event-preventDefault">preventDefault()</code> prevented them from doing so.</p>
<p>The <code>NavigateEvent</code>'s <code data-x="dom-NavigateEvent-intercept">intercept()</code> method allows intercepting a navigation and converting it into a same-document navigation:</p>
<pre><code class="js">navigation.addEventListener("navigate", e => {
// Some navigations, e.g. cross-origin navigations, we cannot intercept.
// Let the browser handle those normally.
if (!e.canIntercept) {
return;
}
// Similarly, don't intercept fragment navigations or downloads.
if (e.hashChange || e.downloadRequest !== null) {
return;
}
const url = new URL(event.destination.url);
if (url.pathname.startsWith("/articles/")) {
e.intercept({
async handler() {
// The URL has already changed, so show a placeholder while
// fetching the new content, such as a spinner or loading page.
renderArticlePagePlaceholder();
// Fetch the new content and display when ready.
const articleContent = await getArticleContent(url.pathname, { signal: e.signal });
renderArticlePage(articleContent);
}
});
}
});</code></pre>
<p>Note that the <code data-x="dom-NavigationInterceptOptions-handler">handler</code> function can return a promise to represent the asynchronous progress, and success or failure, of the navigation. While the promise is still pending, browser UI can treat the navigation as ongoing (e.g., by presenting a loading spinner). Other parts of the navigation API are also sensitive to these promises, such as the return value of <code data-x="dom-Navigation-navigate">navigation.navigate()</code>:
<pre><code class="js">const { committed, finished } = await navigation.navigate("/articles/the-navigation-api-is-cool");
// The committed promise will fulfill once the URL has changed, which happens
// immediately (as long as the NavigateEvent wasn't canceled).
await committed;
// The finished promise will fulfill once the Promise returned by handler() has
// fulfilled, which happens once the article is downloaded and rendered. (Or,
// it will reject, if handler() fails along the way).
await finished;</code></pre>
<h5 id="navigation-interface">The <code>Navigation</code> interface</h5>
<div w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>Navigation</dfn> : <span>EventTarget</span> {
sequence<<span>NavigationHistoryEntry</span>> <span data-x="dom-Navigation-entries">entries</span>();
readonly attribute <span>NavigationHistoryEntry</span>? <span data-x="dom-Navigation-currentEntry">currentEntry</span>;
undefined <span data-x="dom-Navigation-updateCurrentEntry">updateCurrentEntry</span>(<span>NavigationUpdateCurrentEntryOptions</span> options);
readonly attribute <span>NavigationTransition</span>? <span data-x="dom-Navigation-transition">transition</span>;
readonly attribute <span>NavigationActivation</span>? <span data-x="dom-Navigation-activation">activation</span>;
readonly attribute boolean <span data-x="dom-Navigation-canGoBack">canGoBack</span>;
readonly attribute boolean <span data-x="dom-Navigation-canGoForward">canGoForward</span>;
<span>NavigationResult</span> <span data-x="dom-Navigation-navigate">navigate</span>(USVString url, optional <span>NavigationNavigateOptions</span> options = {});
<span>NavigationResult</span> <span data-x="dom-Navigation-reload">reload</span>(optional <span>NavigationReloadOptions</span> options = {});
<span>NavigationResult</span> <span data-x="dom-Navigation-traverseTo">traverseTo</span>(DOMString key, optional <span>NavigationOptions</span> options = {});
<span>NavigationResult</span> <span data-x="dom-Navigation-back">back</span>(optional <span>NavigationOptions</span> options = {});
<span>NavigationResult</span> <span data-x="dom-Navigation-forward">forward</span>(optional <span>NavigationOptions</span> options = {});
attribute <span>EventHandler</span> <span data-x="handler-Navigation-onnavigate">onnavigate</span>;
attribute <span>EventHandler</span> <span data-x="handler-Navigation-onnavigatesuccess">onnavigatesuccess</span>;
attribute <span>EventHandler</span> <span data-x="handler-Navigation-onnavigateerror">onnavigateerror</span>;
attribute <span>EventHandler</span> <span data-x="handler-Navigation-oncurrententrychange">oncurrententrychange</span>;
};
dictionary <dfn dictionary>NavigationUpdateCurrentEntryOptions</dfn> {
required any <dfn dict-member for="NavigationUpdateCurrentEntryOptions" data-x="dom-NavigationUpdateCurrentEntryOptions-state">state</dfn>;
};
dictionary <dfn dictionary>NavigationOptions</dfn> {
any <dfn dict-member for="NavigationOptions" data-x="dom-NavigationOptions-info">info</dfn>;
};
dictionary <dfn dictionary>NavigationNavigateOptions</dfn> : <span>NavigationOptions</span> {
any <dfn dict-member for="NavigationNavigateOptions" data-x="dom-NavigationNavigateOptions-state">state</dfn>;
<span>NavigationHistoryBehavior</span> <dfn dict-member for="NavigationNavigateOptions" data-x="dom-NavigationNavigateOptions-history">history</dfn> = "<span data-x="NavigationHistoryBehavior-auto">auto</span>";
};
dictionary <dfn dictionary>NavigationReloadOptions</dfn> : <span>NavigationOptions</span> {
any <dfn dict-member for="NavigationNavigateOptions" data-x="dom-NavigationReloadOptions-state">state</dfn>;
};
dictionary <dfn dictionary>NavigationResult</dfn> {
<span data-x="idl-Promise">Promise</span><<span>NavigationHistoryEntry</span>> <dfn dict-member for="NavigationResult" data-x="dom-NavigationResult-committed">committed</dfn>;
<span data-x="idl-Promise">Promise</span><<span>NavigationHistoryEntry</span>> <dfn dict-member for="NavigationResult" data-x="dom-NavigationResult-finished">finished</dfn>;
};
enum <dfn enum>NavigationHistoryBehavior</dfn> {
"<span data-x="NavigationHistoryBehavior-auto">auto</span>",
"<span data-x="NavigationHistoryBehavior-push">push</span>",
"<span data-x="NavigationHistoryBehavior-replace">replace</span>"
};</code></pre>
<p>Each <code>Window</code> has an associated <dfn data-x="window-navigation-api">navigation
API</dfn>, which is a <code>Navigation</code> object. Upon creation of the <code>Window</code>
object, its <span data-x="window-navigation-api">navigation API</span> must be set to a
<span>new</span> <code>Navigation</code> object created in the <code>Window</code> object's <span
data-x="concept-relevant-realm">relevant realm</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-navigation">navigation</code></dfn> getter
steps are to return <span>this</span>'s <span data-x="window-navigation-api">navigation
API</span>.</p>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>Navigation</code> interface:</p>
<table>
<thead>
<tr>
<th><span data-x="event handlers">Event handler</span>
<th><span>Event handler event type</span>
<tbody>
<tr>
<td><dfn attribute for="Navigation"><code data-x="handler-Navigation-onnavigate">onnavigate</code></dfn>
<td><code data-x="event-navigate">navigate</code>
<tr>
<td><dfn attribute for="Navigation"><code data-x="handler-Navigation-onnavigatesuccess">onnavigatesuccess</code></dfn>
<td><code data-x="event-navigatesuccess">navigatesuccess</code>
<tr>
<td><dfn attribute for="Navigation"><code data-x="handler-Navigation-onnavigateerror">onnavigateerror</code></dfn>
<td><code data-x="event-navigateerror">navigateerror</code>
<tr>
<td><dfn attribute for="Navigation"><code data-x="handler-Navigation-oncurrententrychange">oncurrententrychange</code></dfn>
<td><code data-x="event-currententrychange">currententrychange</code>
</table>
<h5 id="navigation-api-core">Core infrastructure</h5>
<div w-nodev>
<p>Each <code>Navigation</code> has an associated <dfn data-x="navigation-entry-list">entry
list</dfn>, a <span>list</span> of <code>NavigationHistoryEntry</code> objects, initially
empty.</p>
<p>Each <code>Navigation</code> has an associated <dfn
data-x="navigation-current-entry-index">current entry index</dfn>, an integer, initially
−1.</p>
<p>The <dfn data-x="navigation-current-entry">current entry</dfn> of a <code>Navigation</code>
<var>navigation</var> is the result of running the following steps:</p>
<ol>
<li><p>If <var>navigation</var> <span>has entries and events disabled</span>, then return
null.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span
data-x="navigation-current-entry-index">current entry index</span> is not −1.</p></li>
<li><p>Return <var>navigation</var>'s <span data-x="navigation-entry-list">entry
list</span>[<var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span>].</p></li>
</ol>
<p>A <code>Navigation</code> <var>navigation</var> <dfn>has entries and events disabled</dfn> if
the following steps return true:</p>
<ol>
<li><p>Let <var>document</var> be <var>navigation</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return true.</p></li>
<li><p>If <var>document</var>'s <span>is initial <code>about:blank</code></span> is true, then
return true.</p></li>
<li><p>If <var>document</var>'s <span data-x="concept-document-origin">origin</span> is <span
data-x="concept-origin-opaque">opaque</span>, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>To <dfn data-x="getting the navigation API entry index">get the navigation API entry
index</dfn> of a <span>session history entry</span> <var>she</var> within a
<code>Navigation</code> <var>navigation</var>:</p>
<ol>
<li><p>Let <var>index</var> be 0.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>nhe</var> of <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span>:</p>
<ol>
<li><p>If <var>nhe</var>'s <span data-x="nhe-she">session history entry</span> is equal to
<var>she</var>, then return <var>index</var>.</p></li>
<li><p>Increment <var>index</var> by 1.</p></li>
</ol>
</li>
<li><p>Return −1.</p></li>
</ol>
<hr>
</div>
<p>A key type used throughout the navigation API is the <code>NavigationType</code>
enumeration:</p>
<pre><code class="idl">enum <dfn enum>NavigationType</dfn> {
"<span data-x="dom-NavigationType-push">push</span>",
"<span data-x="dom-NavigationType-replace">replace</span>",
"<span data-x="dom-NavigationType-reload">reload</span>",
"<span data-x="dom-NavigationType-traverse">traverse</span>"
};</code></pre>
<p>This captures the main web developer-visible types of "navigations", which (as <a
href="#note-meaning-of-navigate">noted elsewhere</a>) do not exactly correspond to this standard's
singular <span>navigate</span> algorithm. The meaning of each value is the following:</p>
<dl>
<dt>"<dfn enum-value for="NavigationType"><code data-x="dom-NavigationType-push">push</code></dfn>"</dt>
<dd>Corresponds to calls to <span>navigate</span> where the <span>history handling
behavior</span> ends up as "<code data-x="NavigationHistoryBehavior-push">push</code>", or to
<code data-x="dom-History-pushState">history.pushState()</code>.</dd>
<dt>"<dfn enum-value for="NavigationType"><code data-x="dom-NavigationType-replace">replace</code></dfn>"</dt>
<dd>Corresponds to calls to <span>navigate</span> where the <span>history handling
behavior</span> ends up as "<code data-x="NavigationHistoryBehavior-replace">replace</code>", or
to <code data-x="dom-History-pushState">history.replaceState()</code>.</dd>
<dt>"<dfn enum-value for="NavigationType"><code data-x="dom-NavigationType-reload">reload</code></dfn>"</dt>
<dd>Corresponds to calls to <span>reload</span>.</dd>
<dt>"<dfn enum-value for="NavigationType"><code data-x="dom-NavigationType-traverse">traverse</code></dfn>"</dt>
<dd>Corresponds to calls to <span>traverse the history by a delta</span>.</dd>
</dl>
<div w-nodev>
<p class="note">The value space of the <code>NavigationType</code> enumeration is a superset of
the value space of the specification-internal <span>history handling behavior</span> type. Several
parts of this standard make use of this overlap, by passing in a <span>history handling
behavior</span> to an algorithm that expects a <code>NavigationType</code>.</p>
<h5 id="navigation-api-entry-updates">Initializing and updating the entry list</h5>
<p>To <dfn>initialize the navigation API entries for a new document</dfn> given a
<code>Navigation</code> <var>navigation</var>, a <span>list</span> of <span data-x="session
history entry">session history entries</span> <var>newSHEs</var>, and a <span>session history
entry</span> <var>initialSHE</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>navigation</var>'s <span data-x="navigation-entry-list">entry
list</span> <span data-x="list is empty">is empty</span>.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span
data-x="navigation-current-entry-index">current entry index</span> is −1.</p></li>
<li><p>If <var>navigation</var> <span>has entries and events disabled</span>, then
return.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>newSHE</var> of <var>newSHEs</var>:</p>
<ol>
<li><p>Let <var>newNHE</var> be a <span>new</span> <code>NavigationHistoryEntry</code> created
in the <span data-x="concept-relevant-realm">relevant realm</span> of
<var>navigation</var>.</p></li>
<li><p>Set <var>newNHE</var>'s <span data-x="nhe-she">session history entry</span> to
<var>newSHE</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>newNHE</var> to <var>navigation</var>'s
<span data-x="navigation-entry-list">entry list</span>.</p></li>
</ol>
<p class="note"><var>newSHEs</var> will have originally come from <span>getting session history
entries for the navigation API</span>, and thus each <var>newSHE</var> will be contiguous <span
data-x="same origin">same</span> <span data-x="document-state-origin">origin</span> with
<var>initialSHE</var>.</p>
</li>
<li><p>Set <var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span> to the result of <span>getting the navigation API entry index</span> of
<var>initialSHE</var> within <var>navigation</var>.</p></li>
</ol>
<p>To <dfn>update the navigation API entries for reactivation</dfn> given a
<code>Navigation</code> <var>navigation</var>, a <span>list</span> of <span data-x="session
history entry">session history entries</span> <var>newSHEs</var>, and a <span>session history
entry</span> <var>reactivatedSHE</var>:</p>
<ol>
<li><p>If <var>navigation</var> <span>has entries and events disabled</span>, then
return.</p></li>
<li><p>Let <var>newNHEs</var> be a new empty <span>list</span>.</p></li>
<li><p>Let <var>oldNHEs</var> be a <span data-x="list clone">clone</span> of
<var>navigation</var>'s <span data-x="navigation-entry-list">entry list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>newSHE</var> of <var>newSHEs</var>:</p>
<ol>
<li><p>Let <var>newNHE</var> be null.</p></li>
<li>
<p>If <var>oldNHEs</var> <span data-x="list contains">contains</span> a
<code>NavigationHistoryEntry</code> <var>matchingOldNHE</var> whose <span
data-x="nhe-she">session history entry</span> is <var>newSHE</var>, then:</p>
<ol>
<li><p>Set <var>newNHE</var> to <var>matchingOldNHE</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>matchingOldNHE</var> from
<var>oldNHEs</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Set <var>newNHE</var> to a <span>new</span> <code>NavigationHistoryEntry</code>
created in the <span data-x="concept-relevant-realm">relevant realm</span> of
<var>navigation</var>.</p></li>
<li><p>Set <var>newNHE</var>'s <span data-x="nhe-she">session history entry</span> to
<var>newSHE</var>.</p></li>
</ol>
</li>
<li><p><span data-x="list append">Append</span> <var>newNHE</var> to
<var>newNHEs</var>.</p></li>
</ol>
<p class="note"><var>newSHEs</var> will have originally come from <span>getting session history
entries for the navigation API</span>, and thus each <var>newSHE</var> will be contiguous <span
data-x="same origin">same</span> <span data-x="document-state-origin">origin</span> with
<var>reactivatedSHE</var>.</p>
<p class="note">By the end of this loop, all <code>NavigationHistoryEntry</code>s that remain in
<var>oldNHEs</var> represent <span data-x="session history entry">session history entries</span>
which have been disposed while the <code>Document</code> was in <a
href="#note-bfcache">bfcache</a>.</p>
</li>
<li><p>Set <var>navigation</var>'s <span>entry list</span> to <var>newNHEs</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span> to the result of <span>getting the navigation API entry index</span> of
<var>reactivatedSHE</var> within <var>navigation</var>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>navigation</var>'s <span>relevant global object</span> to run the following
steps:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>disposedNHE</var> of
<var>oldNHEs</var>:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-dispose">dispose</code> at <var>disposedNHE</var>.</p></li>
</ol>
</li>
</ol>
<div class="note">
<p>We delay these steps by a task to ensure that <code data-x="event-dispose">dispose</code>
events will fire after the <code data-x="event-pageshow">pageshow</code> event. This ensures
that <code data-x="event-pageshow">pageshow</code> is the first event a page receives upon
<span data-x="reactivate a document">reactivation</span>.</p>
<p>(However, the rest of this algorithm runs before the <code
data-x="event-pageshow">pageshow</code> event fires. This ensures that <code
data-x="dom-Navigation-entries">navigation.entries()</code> and <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> will have correctly-updated
values during any <code data-x="event-pageshow">pageshow</code> event handlers.)</p>
</div>
</li>
</ol>
<p>To <dfn>update the navigation API entries for a same-document navigation</dfn> given a
<code>Navigation</code> <var>navigation</var>, a <span>session history entry</span>
<var>destinationSHE</var>, and a <code>NavigationType</code> <var>navigationType</var>:</p>
<ol>
<li><p>If <var>navigation</var> <span>has entries and events disabled</span>, then
return.</p></li>
<li><p>Let <var>oldCurrentNHE</var> be the <span data-x="navigation-current-entry">current
entry</span> of <var>navigation</var>.</p></li>
<li><p>Let <var>disposedNHEs</var> be a new empty <span>list</span>.</p></li>
<li>
<p>If <var>navigationType</var> is "<code data-x="dom-NavigationType-traverse">traverse</code>",
then:</p>
<ol>
<li><p>Set <var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span> to the result of <span>getting the navigation API entry index</span> of
<var>destinationSHE</var> within <var>navigation</var>.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span
data-x="navigation-current-entry-index">current entry index</span> is not −1.</p></li>
</ol>
<p class="note">This algorithm is only called for same-document traversals. Cross-document
traversals will instead call either <span>initialize the navigation API entries for a new
document</span> or <span>update the navigation API entries for reactivation</span>.</p>
</li>
<li>
<p>Otherwise, if <var>navigationType</var> is "<code
data-x="dom-NavigationType-push">push</code>", then:</p>
<ol>
<li><p>Set <var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span> to <var>navigation</var>'s <span data-x="navigation-current-entry-index">current
entry index</span> + 1.</p></li>
<li><p>Let <var>i</var> be <var>navigation</var>'s <span
data-x="navigation-current-entry-index">current entry index</span>.</p></li>
<li>
<p><span>While</span> <var>i</var> < <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span>'s <span data-x="list size">size</span>:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span>[<var>i</var>] to
<var>disposedNHEs</var>.</p></li>
<li><p>Set <var>i</var> to <var>i</var> + 1.</p></li>
</ol>
</li>
<li><p><span data-x="list remove">Remove</span> all items in <var>disposedNHEs</var> from
<var>navigation</var>'s <span data-x="navigation-entry-list">entry list</span>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>navigationType</var> is "<code
data-x="dom-NavigationType-replace">replace</code>", then:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>oldCurrentNHE</var> to
<var>disposedNHEs</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>navigationType</var> is "<code data-x="dom-NavigationType-push">push</code>" or
"<code data-x="dom-NavigationType-replace">replace</code>", then:</p>
<ol>
<li><p>Let <var>newNHE</var> be a <span>new</span> <code>NavigationHistoryEntry</code> created
in the <span data-x="concept-relevant-realm">relevant realm</span> of
<var>navigation</var>.</p></li>
<li><p>Set <var>newNHE</var>'s <span data-x="nhe-she">session history entry</span> to
<var>destinationSHE</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span data-x="navigation-entry-list">entry
list</span>[<var>navigation</var>'s <span data-x="navigation-current-entry-index">current entry
index</span>] to <var>newNHE</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>navigation</var>'s <span>ongoing API method tracker</span> is non-null, then
<span>notify about the committed-to entry</span> given <var>navigation</var>'s <span>ongoing API
method tracker</span> and the <span data-x="navigation-current-entry">current entry</span> of
<var>navigation</var>.</p>
<p class="note">It is important to do this before firing the <code
data-x="event-dispose">dispose</code> or <code
data-x="event-currententrychange">currententrychange</code> events, since event handlers could
start another navigation, or otherwise change the value of <var>navigation</var>'s <span>ongoing
API method tracker</span>.</p>
</li>
<li>
<p><span>Prepare to run script</span> given <var>navigation</var>'s <span>relevant settings
object</span>.</p>
<p class="note">See <a href="#note-suppress-microtasks-during-navigation-events">the discussion
for other navigation API events</a> to understand why we do this.</p>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-currententrychange">currententrychange</code> at <var>navigation</var> using
<code>NavigationCurrentEntryChangeEvent</code>, with its <code
data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</code> attribute
initialized to <var>navigationType</var> and its <code
data-x="dom-NavigationCurrentEntryChangeEvent-from">from</code> initialized to
<var>oldCurrentNHE</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>disposedNHE</var> of
<var>disposedNHEs</var>:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-dispose">dispose</code> at <var>disposedNHE</var>.</p></li>
</ol>
</li>
<li><p><span>Clean up after running script</span> given <var>navigation</var>'s <span>relevant
settings object</span>.</p></li>
</ol>
<p class="XXX">In implementations, same-document navigations can cause <span data-x="session
history entry">session history entries</span> to be disposed by falling off the back of the
session history entry list. This is not yet handled by the above algorithm (or by any other part
of this standard). See <a href="https://github.com/whatwg/html/issues/8620">issue #8620</a> to
track progress on defining the correct behavior in such cases.</p>
</div>
<h5>The <code>NavigationHistoryEntry</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigationHistoryEntry</dfn> : <span>EventTarget</span> {
readonly attribute USVString? <span data-x="dom-NavigationHistoryEntry-url">url</span>;
readonly attribute DOMString <span data-x="dom-NavigationHistoryEntry-key">key</span>;
readonly attribute DOMString <span data-x="dom-NavigationHistoryEntry-id">id</span>;
readonly attribute long long <span data-x="dom-NavigationHistoryEntry-index">index</span>;
readonly attribute boolean <span data-x="dom-NavigationHistoryEntry-sameDocument">sameDocument</span>;
any <span data-x="dom-NavigationHistoryEntry-getState">getState</span>();
attribute <span>EventHandler</span> <span data-x="handler-NavigationHistoryEntry-ondispose">ondispose</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-url">url</span></code></dt>
<dd>
<p>The URL of this navigation history entry.</p>
<p>This can return null if the entry corresponds to a different <code>Document</code> than the
current one (i.e., if <code data-x="dom-NavigationHistoryEntry-sameDocument">sameDocument</code>
is false), and that <code>Document</code> was fetched with a <span>referrer policy</span> of
"<code data-x="">no-referrer</code>" or "<code data-x="">origin</code>", since that indicates
the <code>Document</code> in question is hiding its URL even from other same-origin pages.</p>
</dd>
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-key">key</span></code></dt>
<dd>
<p>A user agent-generated random UUID string representing this navigation history entry's place
in the navigation history list. This value will be reused by other
<code>NavigationHistoryEntry</code> instances that replace this one due to "<code
data-x="dom-NavigationType-replace">replace</code>" navigations, and will survive reloads and
session restores.</p>
<p>This is useful for navigating back to this entry in the navigation history list, using <code
data-x="dom-Navigation-traverseTo">navigation.traverseTo(key)</code>.</p>
</dd>
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-id">id</span></code></dt>
<dd>
<p>A user agent-generated random UUID string representing this specific navigation history
entry. This value will <em>not</em> be reused by other <code>NavigationHistoryEntry</code>
instances. This value will survive reloads and session restores.</p>
<p>This is useful for associating data with this navigation history entry using other storage
APIs.</p>
</dd>
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-index">index</span></code></dt>
<dd><p>The index of this <code>NavigationHistoryEntry</code> within <code
data-x="dom-Navigation-entries">navigation.entries()</code>, or −1 if the entry is not in
the navigation history entry list.</p></dd>
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-sameDocument">sameDocument</span></code></dt>
<dd><p>Indicates whether or not this navigation history entry is for the same
<code>Document</code> as the current one, or not. This will be true, for example, when the entry
represents a fragment navigation or single-page app navigation.</p></dd>
<dt><code data-x=""><var>entry</var>.<span subdfn data-x="dom-NavigationHistoryEntry-getState">getState</span>()</code></dt>
<dd>
<p>Returns the <span data-x="StructuredDeserialize">deserialization</span> of the state stored
in this entry, which was added to the entry using <code
data-x="dom-Navigation-navigate">navigation.navigate()</code> or <code
data-x="dom-Navigation-updateCurrentEntry">navigation.updateCurrentEntry()</code>. This state
survives reloads and session restores.</p>
<p>Note that in general, unless the state value is a primitive, <code class="js"
data-x="">entry.getState() !== entry.getState()</code>, since a fresh deserialization is
returned each time.</p>
<p>This state is unrelated to the classic history API's <code
data-x="dom-history-state">history.state</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <code>NavigationHistoryEntry</code> has an associated <dfn data-x="nhe-she">session
history entry</dfn>, which is a <span>session history entry</span>.</p>
<p>The <dfn data-x="concept-NavigationHistoryEntry-key">key</dfn> of a
<code>NavigationHistoryEntry</code> <var>nhe</var> is given by the return value of the following
algorithm:</p>
<ol>
<li><p>If <var>nhe</var>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then return the empty string.</p></li>
<li><p>Return <var>nhe</var>'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-key">navigation API key</span>.</p></li>
</ol>
<p>The <dfn data-x="concept-NavigationHistoryEntry-id">ID</dfn> of a
<code>NavigationHistoryEntry</code> <var>nhe</var> is given by the return value of the following
algorithm:</p>
<ol>
<li><p>If <var>nhe</var>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then return the empty string.</p></li>
<li><p>Return <var>nhe</var>'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-id">navigation API ID</span>.</p></li>
</ol>
<p>The <dfn data-x="concept-NavigationHistoryEntry-index">index</dfn> of a
<code>NavigationHistoryEntry</code> <var>nhe</var> is given by the return value of the following
algorithm:</p>
<ol>
<li><p>If <var>nhe</var>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then return −1.</p></li>
<li><p>Return the result of <span>getting the navigation API entry index</span> of
<span>this</span>'s <span data-x="nhe-she">session history entry</span> within
<span>this</span>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>.</p></li>
</ol>
<p>The <dfn attribute for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-url">url</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return the empty
string.</p></li>
<li><p>Let <var>she</var> be <span>this</span>'s <span data-x="nhe-she">session history
entry</span>.</p></li>
<li><p>If <var>she</var>'s <span data-x="she-document">document</span> does not equal
<var>document</var>, and <var>she</var>'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-request-referrer-policy">request referrer
policy</span> is "<code data-x="">no-referrer</code>" or "<code data-x="">origin</code>", then
return null.</p></li>
<li><p>Return <var>she</var>'s <span data-x="she-url">URL</span>, <span
data-x="concept-url-serializer">serialized</span>.</p></li>
</ol>
<p>The <dfn attribute for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-key">key</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationHistoryEntry-key">key</span>.</p>
<p>The <dfn attribute for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-id">id</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationHistoryEntry-id">ID</span>.</p>
<p>The <dfn attribute for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-index">index</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationHistoryEntry-index">index</span>.</p>
<p>The <dfn attribute for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-sameDocument">sameDocument</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return false.</p></li>
<li><p>Return true if <span>this</span>'s <span data-x="nhe-she">session history entry</span>'s
<span data-x="she-document">document</span> equals <var>document</var>, and false
otherwise.</p></li>
</ol>
<p>The <dfn method for="NavigationHistoryEntry"><code
data-x="dom-NavigationHistoryEntry-getState">getState()</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then return undefined.</p></li>
<li>
<p>Return <span>StructuredDeserialize</span>(<span>this</span>'s <span data-x="nhe-she">session
history entry</span>'s <span data-x="she-navigation-api-state">navigation API state</span>).
Rethrow any exceptions.</p>
<p class="note">This can in theory throw an exception, if attempting to deserialize a large
<code data-x="idl-ArrayBuffer">ArrayBuffer</code> when not enough memory is available.</p>
</li>
</ol>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>NavigationHistoryEntry</code> interface:</p>
<table>
<thead>
<tr>
<th><span data-x="event handlers">Event handler</span>
<th><span>Event handler event type</span>
<tbody>
<tr>
<td><dfn attribute for="NavigationHistoryEntry"><code data-x="handler-NavigationHistoryEntry-ondispose">ondispose</code></dfn>
<td><code data-x="event-dispose">dispose</code>
</table>
<h5>The history entry list</h5>
<dl class="domintro">
<dt><code data-x=""><var>entries</var> = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-entries">entries()</span></code></dt>
<dd><p>Returns an array of <code>NavigationHistoryEntry</code> instances represent the current
navigation history entry list, i.e., all <span data-x="session history entry">session history
entries</span> for this <span>navigable</span> that are <span>same origin</span> and contiguous
to the <span data-x="nav-current-history-entry">current session history entry</span>.</p>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-currentEntry">currentEntry</span></code></dt>
<dd><p>Returns the <code>NavigationHistoryEntry</code> corresponding to the <span
data-x="nav-current-history-entry">current session history entry</span>.</p>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-updateCurrentEntry">updateCurrentEntry</span>({ <span data-x="dom-NavigationUpdateCurrentEntryOptions-state">state</span> })</code></dt>
<dd>
<p>Updates the <span data-x="she-navigation-api-state">navigation API state</span> of the <span
data-x="nav-current-history-entry">current session history entry</span>, without performing a
navigation like <code data-x="dom-navigation-reload">navigation.reload()</code> would do.</p>
<p>This method is best used to capture updates to the page that have already happened, and need
to be reflected into the navigation API state. For cases where the state update is meant to
drive a page update, instead use <code
data-x="dom-Navigation-navigate">navigation.navigate()</code> or <code
data-x="dom-Navigation-reload">navigation.reload()</code>, which will trigger a <code
data-x="event-navigate">navigate</code> event.</p>
</dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-canGoBack">canGoBack</span></code></dt>
<dd><p>Returns true if the current <span data-x="nav-current-history-entry">current session
history entry</span> (i.e., <code data-x="dom-Navigation-currentEntry">currentEntry</code>) is
not the first one in the navigation history entry list (i.e., in <code
data-x="dom-Navigation-entries">entries()</code>). This means that there is a previous
<span>session history entry</span> for this <span>navigable</span>, and its <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span> is <span>same origin</span> with the current
<code>Document</code>'s <span data-x="concept-document-origin">origin</span>.</p>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-canGoForward">canGoForward</span></code></dt>
<dd><p>Returns true if the current <span data-x="nav-current-history-entry">current session
history entry</span> (i.e., <code data-x="dom-Navigation-currentEntry">currentEntry</code>) is
not the last one in the navigation history entry list (i.e., in <code
data-x="dom-Navigation-entries">entries()</code>). This means that there is a next <span>session
history entry</span> for this <span>navigable</span>, and its <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span> is <span>same origin</span> with the current
<code>Document</code>'s <span data-x="concept-document-origin">origin</span>.</p>
</dl>
<div w-nodev>
<p>The <dfn method for="Navigation"><code data-x="dom-Navigation-entries">entries()</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span> <span>has entries and events disabled</span>, then return the empty
list.</p></li>
<li>
<p>Return <span>this</span>'s <span data-x="navigation-entry-list">entry list</span>.</p>
<p class="note">Recall that because of Web IDL's sequence type conversion rules, this will
create a new JavaScript array object on each call. That is, <code data-x=""><span
data-x="dom-Navigation-entries">navigation.entries()</span> !== <span
data-x="dom-Navigation-entries">navigation.entries()</span></code>.</p>
</li>
</ol>
<p>The <dfn attribute for="Navigation"><code
data-x="dom-Navigation-currentEntry">currentEntry</code></dfn> getter steps are to return the
<span data-x="navigation-current-entry">current entry</span> of <span>this</span>.</p>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-updateCurrentEntry">updateCurrentEntry(<var>options</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>Let <var>current</var> be the <span data-x="navigation-current-entry">current entry</span>
of <span>this</span>.</p></li>
<li><p>If <var>current</var> is null, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>serializedState</var> be
<span>StructuredSerializeForStorage</span>(<var>options</var>["<code
data-x="dom-NavigationUpdateCurrentEntryOptions-state">state</code>"]), rethrowing any
exceptions.</p></li>
<li><p>Set <var>current</var>'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-state">navigation API state</span> to
<var>serializedState</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-currententrychange">currententrychange</code> at <span>this</span> using
<code>NavigationCurrentEntryChangeEvent</code>, with its <code
data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</code> attribute
initialized to null and its <code data-x="dom-NavigationCurrentEntryChangeEvent-from">from</code>
initialized to <var>current</var>.</p></li>
</ol>
<p>The <dfn attribute for="Navigation"><code
data-x="dom-Navigation-canGoBack">canGoBack</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span> <span>has entries and events disabled</span>, then return
false.</p></li>
<li><p><span>Assert</span>: <span>this</span>'s <span
data-x="navigation-current-entry-index">current entry index</span> is not −1.</p></li>
<li><p>If <span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> is 0, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn attribute for="Navigation"><code
data-x="dom-Navigation-canGoForward">canGoForward</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span> <span>has entries and events disabled</span>, then return
false.</p></li>
<li><p><span>Assert</span>: <span>this</span>'s <span
data-x="navigation-current-entry-index">current entry index</span> is not −1.</p></li>
<li><p>If <span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> is equal to <span>this</span>'s <span data-x="navigation-entry-list">entry
list</span>'s <span data-x="list size">size</span> − 1, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
</div>
<h5 id="navigation-api-initiating-navigations">Initiating navigations</h5>
<dl class="domintro">
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-navigate">navigate</span>(<var>url</var>)</code></dt>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-navigate">navigate</span>(<var>url</var>, <var>options</var>)</code></dt>
<dd>
<p><span data-x="navigate">Navigates</span> the current page to the given <var>url</var>.
<var>options</var> can contain the following values:</p>
<ul>
<li><p><code subdfn data-x="dom-NavigationNavigateOptions-history">history</code> can be set to
"<code subdfn data-x="NavigationHistoryBehavior-replace">replace</code>" to replace the current
session history entry, instead of pushing a new one.</p></li>
<li><p><code subdfn data-x="dom-NavigationOptions-info">info</code> can be set to any value; it
will populate the <code data-x="dom-NavigateEvent-info">info</code> property of the
corresponding <code>NavigateEvent</code>.</p></li>
<li><p><code subdfn data-x="dom-NavigationNavigateOptions-state">state</code> can be set to any
<span data-x="serializable objects">serializable</span> value; it will populate the state
retrieved by <code
data-x="dom-NavigationHistoryEntry-getState">navigation.currentEntry.getState()</code> once the
navigation completes, for same-document navigations. (It will be ignored for navigations that
end up cross-document.)</p></li>
</ul>
<p>By default this will perform a full navigation (i.e., a cross-document navigation, unless the
given URL differs only in a <span data-x="concept-url-fragment">fragment</span> from the current
one). The <code data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code> method can
be used to convert it into a same-document navigation.</p>
<p>The returned promises will behave as follows:</p>
<ul>
<li><p>For navigations that get aborted, both promises will reject with an
<span>"<code>AbortError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>For same-document navigations created by using the <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code> method, <code
data-x="dom-NavigationResult-committed">committed</code> will fulfill immediately, and <code
data-x="dom-NavigationResult-finished">finished</code> will fulfill or reject according to any
promsies returned by handlers passed to <code
data-x="dom-NavigateEvent-intercept">intercept()</code>.</p></li>
<li><p>For other same-document navigations (e.g., non-intercepted <span
data-x="navigate-fragid">fragment navigations</span>), both promises will fulfill
immediately.</p></li>
<li><p>For cross-document navigations, or navigations that result in 204 or 205 <span
data-x="concept-response-status">statuses</span> or `<code
data-x="http-content-disposition">Content-Disposition: attachment</code>` header fields from
the server (and thus do not actually navigate), both promises will never settle.</p></li>
</ul>
<p>In all cases, when the returned promises fulfill, it will be with the
<code>NavigationHistoryEntry</code> that was navigated to.</p>
</dd>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-reload">reload</span>(<var>options</var>)</code></dt>
<dd>
<p><span data-x="reload">Reloads</span> the current page. <var>options</var> can contain <code
data-x="dom-NavigationOptions-info">info</code> and <code subdfn
data-x="dom-NavigationReloadOptions-state">state</code>, which behave as described above.</p>
<p>The default behavior of performing a from-network-or-cache reload of the current page can be
overriden by the using the <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code> method. Doing so will mean
this call only updates state or passes along the appropriate <code
data-x="dom-NavigationOptions-info">info</code>, plus performing whater actions the <code
data-x="event-navigate">navigate</code> event handlers see fit to carry out.</p>
<p>The returned promises will behave as follows:</p>
<ul>
<li><p>If the reload is intercepted by using the <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code> method, <code
data-x="dom-NavigationResult-committed">committed</code> will fulfill immediately, and <code
data-x="dom-NavigationResult-finished">finished</code> will fulfill or reject according to any
promsies returned by handlers passed to <code
data-x="dom-NavigateEvent-intercept">intercept()</code>.</p></li>
<li><p>Otherwise, both promises will never settle.</p></li>
</ul>
</dd>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-traverseTo">traverseTo</span>(<var>key</var>)</code></dt>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-traverseTo">traverseTo</span>(<var>key</var>, { <span data-x="dom-NavigationOptions-info">info</span> })</code></dt>
<dd>
<p><span data-x="apply the traverse history step">Traverses</span> to the closest <span>session
history entry</span> that matches the <code>NavigationHistoryEntry</code> with the given
<var>key</var>. <code data-x="dom-NavigationOptions-info">info</code> can be set to any value;
it will populate the <code data-x="dom-NavigateEvent-info">info</code> property of the
corresponding <code>NavigateEvent</code>.</p>
<p>If a traversal to that <span>session history entry</span> is already in progress, then this
will return the promises for that original traversal, and <code
data-x="dom-NavigateEvent-info">info</code> will be ignored.</p>
<p>The returned promises will behave as follows:</p>
<ul>
<li><p>If there is no <code>NavigationHistoryEntry</code> in <code
data-x="dom-Navigation-entries">navigation.entries()</code> whose <code
data-x="dom-NavigationHistoryEntry-key">key</code> matches <var>key</var>, both promises will
reject with an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>For same-document traversals intercepted by the <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code> method, <code
data-x="dom-NavigationResult-committed">committed</code> will fulfill as soon as the traversal
is processed and <code data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> is
updated, and <code data-x="dom-NavigationResult-finished">finished</code> will fulfill or
reject according to any promsies returned by the handlers passed to <code
data-x="dom-NavigateEvent-intercept">intercept()</code>.</p></li>
<li><p>For non-intercepted same-document travesals, both promises will fulfill as soon as the
traversal is processed and <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> is updated.</p></li>
<li><p>For cross-document traversals, including attempted cross-document traversals that end up
resulting in a 204 or 205 <span data-x="concept-response-status">statuses</span> or `<code
data-x="http-content-disposition">Content-Disposition: attachment</code>` header fields from
the server (and thus do not actually traverse), both promises will never settle.</p></li>
</ul>
</dd>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-back">back</span>(<var>key</var>)</code></dt>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-back">back</span>(<var>key</var>, { <span data-x="dom-NavigationOptions-info">info</span> })</code></dt>
<dd>
<p>Traverses to the closest previous <span>session history entry</span> which results in this
<span>navigable</span> traversing, i.e., which corresponds to a different
<code>NavigationHistoryEntry</code> and thus will cause <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> to change. <code
data-x="dom-NavigationOptions-info">info</code> can be set to any value; it will populate the
<code data-x="dom-NavigateEvent-info">info</code> property of the corresponding
<code>NavigateEvent</code>.</p>
<p>If a traversal to that <span>session history entry</span> is already in progress, then this
will return the promises for that original traversal, and <code
data-x="dom-NavigateEvent-info">info</code> will be ignored.</p>
<p>The returned promises behave equivalently to those returned by <code
data-x="dom-Navigation-traverseTo">traverseTo()</code>.</p>
</dd>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-forward">forward</span>(<var>key</var>)</code></dt>
<dt><code data-x="">{ <span data-x="dom-NavigationResult-committed">committed</span>, <span data-x="dom-NavigationResult-finished">finished</span> } = <span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-forward">forward</span>(<var>key</var>, { <span data-x="dom-NavigationOptions-info">info</span> })</code></dt>
<dd>
<p>Traverses to the closest forward <span>session history entry</span> which results in this
<span>navigable</span> traversing, i.e., which corresponds to a different
<code>NavigationHistoryEntry</code> and thus will cause <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> to change. <code
data-x="dom-NavigationOptions-info">info</code> can be set to any value; it will populate the
<code data-x="dom-NavigateEvent-info">info</code> property of the corresponding
<code>NavigateEvent</code>.</p>
<p>If a traversal to that <span>session history entry</span> is already in progress, then this
will return the promises for that original traversal, and <code
data-x="dom-NavigateEvent-info">info</code> will be ignored.</p>
<p>The returned promises behave equivalently to those returned by <code
data-x="dom-Navigation-traverseTo">traverseTo()</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-navigate">navigate(<var>url</var>, <var>options</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>Let <var>urlRecord</var> be the result of <span data-x="parse a URL">parsing a URL</span>
given <var>url</var>, relative to <span>this</span>'s <span>relevant settings
object</span>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>options</var>["<code
data-x="dom-NavigationNavigateOptions-history">history</code>"] is "<code
data-x="NavigationHistoryBehavior-push">push</code>", and <span>the navigation must be a
replace</span> given <var>urlRecord</var> and <var>document</var>, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p>
<li><p>Let <var>state</var> be <var>options</var>["<code
data-x="dom-NavigationNavigateOptions-state">state</code>"], if it <span data-x="map
exists">exists</span>; otherwise, undefined.</p></li>
<li>
<p>Let <var>serializedState</var> be
<span>StructuredSerializeForStorage</span>(<var>state</var>). If this throws an exception, then
return an <span data-x="navigation-api-early-error-result">early error result</span> for that
exception.</p>
<p class="note">It is important to perform this step early, since serialization can invoke web
developer code, which in turn might change various things we check in later steps.</p>
</li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
<li><p>If <var>document</var>'s <span>unload counter</span> is greater than 0, then return an
<span data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>info</var> be <var>options</var>["<code
data-x="dom-NavigationOptions-info">info</code>"], if it <span data-x="map exists">exists</span>;
otherwise, undefined.</p></li>
<li><p>Let <var>apiMethodTracker</var> be the result of <span data-x="maybe set the upcoming
non-traverse API method tracker">maybe setting the upcoming non-traverse API method
tracker</span> for <span>this</span> given <var>info</var> and
<var>serializedState</var>.</p></li>
<li>
<p><!-- DONAV navigation API --><span>Navigate</span> <var>document</var>'s <span>node
navigable</span> to <var>urlRecord</var> using <var>document</var>, with <i
data-x="navigation-hh">historyHandling</i> set to <var>options</var>["<code
data-x="dom-NavigationNavigateOptions-history">history</code>"] and <i
data-x="navigation-navigation-api-state">navigationAPIState</i> set to
<var>serializedState</var>.</p>
<p class="note">Unlike <code data-x="dom-location-assign">location.assign()</code> and friends,
which are exposed across <span data-x="same origin-domain">origin-domain</span> boundaries,
<code data-x="dom-Navigation-navigate">navigation.navigate()</code> can only be accessed by code
with direct synchronous access to the <code data-x="dom-navigation">window.navigation</code>
property. Thus, we avoid the complications about attributing the source document of the
navigation, and we don't need to deal with the <span>allowed by sandboxing to navigate</span>
check and its acccompanying <i data-x="exceptionsEnabled">exceptionsEnabled</i> flag. We just
treat all navigations as if they come from the <code>Document</code> corresponding to this
<code>Navigation</code> object itself (i.e., <var>document</var>).</p>
</li>
<li>
<p>If <span>this</span>'s <span>upcoming non-traverse API method tracker</span> is
<var>apiMethodTracker</var>, then:</p>
<p class="note">If the <span>upcoming non-traverse API method tracker</span> is still
<var>apiMethodTracker</var>, this means that the <span>navigate</span> algorithm bailed out
before ever getting to the <span>inner <code data-x="event-navigate">navigate</code> event
firing algorithm</span> which would <span data-x="promote an upcoming API method tracker to
ongoing">promote that upcoming API method tracker to ongoing</span>.</p>
<ol>
<li><p>Set <span>this</span>'s <span>upcoming non-traverse API method tracker</span> to
null.</p></li>
<li><p>Return an <span data-x="navigation-api-early-error-result">early error result</span> for
an <span>"<code>AbortError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li><p>Return a <span>navigation API method tracker-derived result</span> for
<var>apiMethodTracker</var>.</p></li>
</ol>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-reload">reload(<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>serializedState</var> be
<span>StructuredSerializeForStorage</span>(undefined).</p></li>
<li>
<p>If <var>options</var>["<code data-x="dom-NavigationReloadOptions-state">state</code>"] <span
data-x="map exists">exists</span>, then set <var>serializedState</var> to
<span>StructuredSerializeForStorage</span>(<var>options</var>["<code
data-x="dom-NavigationReloadOptions-state">state</code>"]). If this throws an exception, then
return an <span data-x="navigation-api-early-error-result">early error result</span> for that
exception.</p>
<p class="note">It is important to perform this step early, since serialization can invoke web
developer code, which in turn might change various things we check in later steps.</p>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>current</var> be the <span data-x="navigation-current-entry">current
entry</span> of <span>this</span>.</p></li>
<li><p>If <var>current</var> is not null, then set <var>serializedState</var> to
<var>current</var>'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-state">navigation API state</span>.</p></li>
</ol>
</li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
<li><p>If <var>document</var>'s <span>unload counter</span> is greater than 0, then return an
<span data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>info</var> be <var>options</var>["<code
data-x="dom-NavigationOptions-info">info</code>"], if it <span data-x="map exists">exists</span>;
otherwise, undefined.</p></li>
<li><p>Let <var>apiMethodTracker</var> be the result of <span data-x="maybe set the upcoming
non-traverse API method tracker">maybe setting the upcoming non-traverse API method
tracker</span> for <span>this</span> given <var>info</var> and
<var>serializedState</var>.</p></li>
<li><p><span>Reload</span> <var>document</var>'s <span>node navigable</span> with <i
data-x="reload-navigation-api-state">navigationAPIState</i> set to
<var>serializedState</var>.</p></li>
<li><p>Return a <span>navigation API method tracker-derived result</span> for
<var>apiMethodTracker</var>.</p></li>
</ol>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-traverseTo">traverseTo(<var>key</var>, <var>options</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> is −1, then return an <span data-x="navigation-api-early-error-result">early
error result</span> for an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span data-x="navigation-entry-list">entry list</span> does not
<span data-x="list contains">contain</span> a <code>NavigationHistoryEntry</code> whose <span
data-x="nhe-she">session history entry</span>'s <span data-x="she-navigation-api-key">navigation
API key</span> equals <var>key</var>, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return the result of <span>performing a navigation API traversal</span> given
<span>this</span>, <var>key</var>, and <var>options</var>.</p></li>
</ol>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-back">back(<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> is −1 or 0, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>key</var> be <span>this</span>'s <span data-x="navigation-entry-list">entry
list</span>[<span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> − 1]'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-key">navigation API key</span>.</p></li>
<li><p>Return the result of <span>performing a navigation API traversal</span> given
<span>this</span>, <var>key</var>, and <var>options</var>.</p></li>
</ol>
<p>The <dfn method for="Navigation"><code
data-x="dom-Navigation-forward">forward(<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> is −1 or is equal to <span>this</span>'s <span
data-x="navigation-entry-list">entry list</span>'s <span data-x="list size">size</span> −
1, then return an <span data-x="navigation-api-early-error-result">early error result</span> for
an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>key</var> be <span>this</span>'s <span data-x="navigation-entry-list">entry
list</span>[<span>this</span>'s <span data-x="navigation-current-entry-index">current entry
index</span> + 1]'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-key">navigation API key</span>.</p></li>
<li><p>Return the result of <span>performing a navigation API traversal</span> given
<span>this</span>, <var>key</var>, and <var>options</var>.</p></li>
</ol>
<p>To <dfn data-x="performing a navigation API traversal">perform a navigation API traversal</dfn>
given a <code>Navigation</code> <var>navigation</var>, a string <var>key</var>, and a
<code>NavigationOptions</code> <var>options</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>navigation</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return an <span
data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
<li><p>If <var>document</var>'s <span>unload counter</span> is greater than 0, then return an
<span data-x="navigation-api-early-error-result">early error result</span> for an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>current</var> be the <span data-x="navigation-current-entry">current entry</span>
of <var>navigation</var>.</p></li>
<li><p>If <var>key</var> equals <var>current</var>'s <span data-x="nhe-she">session history
entry</span>'s <span data-x="she-navigation-api-key">navigation API key</span>, then return «[
"<code data-x="dom-NavigationResult-committed">committed</code>" → <span>a promise resolved
with</span> <var>current</var>, "<code data-x="dom-NavigationResult-finished">finished</code>"
→ <span>a promise resolved with</span> <var>current</var> ]».</p></li>
<li><p>If <var>navigation</var>'s <span>upcoming traverse API method
trackers</span>[<var>key</var>] <span data-x="map exists">exists</span>, then return a
<span>navigation API method tracker-derived result</span> for <var>navigation</var>'s
<span>upcoming traverse API method trackers</span>[<var>key</var>].</p></li>
<li><p>Let <var>info</var> be <var>options</var>["<code
data-x="dom-NavigationOptions-info">info</code>"], if it <span data-x="map exists">exists</span>;
otherwise, undefined.</p></li>
<li><p>Let <var>apiMethodTracker</var> be the result of <span data-x="add an upcoming traverse
API method tracker">adding an upcoming traverse API method tracker</span> for
<var>navigation</var> given <var>key</var> and <var>info</var>.</p></li>
<li><p>Let <var>navigable</var> be <var>document</var>'s <span>node navigable</span>.</p></li>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li><p>Let <var>sourceSnapshotParams</var> be the result of <span>snapshotting source snapshot
params</span> given <var>document</var>.</p></li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session history
traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p>Let <var>navigableSHEs</var> be the result of <span>getting session history
entries</span> given <var>navigable</var>.</p></li>
<li>
<p>Let <var>targetSHE</var> be the <span>session history entry</span> in
<var>navigableSHEs</var> whose <span data-x="she-navigation-api-key">navigation API key</span>
is <var>key</var>. If no such entry exists, then:</p>
<ol>
<li><p><span>Queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>navigation</var>'s <span>relevant global object</span> to
<span>reject the finished promise</span> for <var>apiMethodTracker</var> with an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Abort these steps.</p></li>
</ol>
<p class="note">This path is taken if <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span> was outdated compared to
<var>navigableSHEs</var>, which can occur for brief periods while all the relevant threads and
processes are being synchronized in reaction to a history change.</p>
</li>
<li>
<p>If <var>targetSHE</var> is <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>, then abort these
steps.</p>
<p class="note">This can occur if a previously <span
data-x="tn-append-session-history-traversal-steps">queued</span> traversal already took us to
this <span>session history entry</span>. In that case the previous traversal will have dealt
with <var>apiMethodTracker</var> already.</p>
</li>
<li><p>Let <var>result</var> be the result of <span data-x="apply the traverse history
step">applying the traverse history step</span> given by <var>targetSHE</var>'s <span
data-x="she-step">step</span> to <var>traversable</var>, given <var>sourceSnapshotParams</var>,
<var>navigable</var>, and "<code data-x="uni-none">none</code>".</p></li>
<li><p>If <var>result</var> is "<code data-x="">canceled-by-beforeunload</code>", then
<span>queue a global task</span> on the <span>navigation and traversal task source</span> given
<var>navigation</var>'s <span>relevant global object</span> to <span>reject the finished
promise</span> for <var>apiMethodTracker</var> with a new
<span>"<code>AbortError</code>"</span> <code>DOMException</code> created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p>If <var>result</var> is "<code data-x="">initiator-disallowed</code>", then <span>queue a
global task</span> on the <span>navigation and traversal task source</span> given
<var>navigation</var>'s <span>relevant global object</span> to <span>reject the finished
promise</span> for <var>apiMethodTracker</var> with a new
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p>
<div class="note">
<p>When <var>result</var> is "<code data-x="">canceled-by-beforeunload</code>" or "<code
data-x="">initiator-disallowed</code>", the <code data-x="event-navigate">navigate</code>
event was never fired, <span data-x="abort the ongoing navigation">aborting the ongoing
navigation</span> would not be correct; it would result in a <code
data-x="event-navigateerror">navigateerror</code> event without a preceding <code
data-x="event-navigate">navigate</code> event.</p>
<p>In the "<code data-x="">canceled-by-navigate</code>" case, <code
data-x="event-navigate">navigate</code> <em>is</em> fired, but the <span>inner <code
data-x="event-navigate">navigate</code> event firing algorithm</span> will take care of
<span data-x="abort the ongoing navigation">aborting the ongoing navigation</span>.</p>
</div>
</li>
</ol>
</li>
<li><p>Return a <span>navigation API method tracker-derived result</span> for
<var>apiMethodTracker</var>.</p></li>
</ol>
<p>An <dfn data-x="navigation-api-early-error-result">early error result</dfn> for an exception
<var>e</var> is a <code>NavigationResult</code> dictionary instance given by «[ "<code
data-x="dom-NavigationResult-committed">committed</code>" → <span>a promise rejected with</span>
<var>e</var>, "<code data-x="dom-NavigationResult-finished">finished</code>" → <span>a promise
rejected with</span> <var>e</var> ]».</p>
<p>A <dfn>navigation API method tracker-derived result</dfn> for a <span>navigation API method
tracker</span> is a <code>NavigationResult</code> dictionary instance given by «[ "<code
data-x="dom-NavigationResult-committed">committed</code>" → <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed">committed promise</span>, "<code
data-x="dom-NavigationResult-finished">finished</code>" → <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-finished">finished promise</span> ]».</p>
</div>
<h5>Ongoing navigation tracking</h5>
<div w-nodev>
<p>During any given navigation (in the <span data-x="NavigationType">broad sense of the
word</span>), the <code>Navigation</code> object needs to keep track of the following:</p>
<table>
<caption>For all navigations</caption>
<thead>
<tr>
<th>State
<th>Duration
<th>Explanation
<tbody>
<tr>
<td>The <code>NavigateEvent</code>
<td>For the duration of event firing
<td>So that if the navigation is canceled while the event is firing, we can <span data-x="canceled flag">cancel</span> the event
<tr>
<td>The event's <span data-x="concept-NavigateEvent-abort-controller">abort controller</span>
<td>Until all promises returned from handlers passed to <code data-x="dom-NavigateEvent-intercept">intercept()</code> have settled
<td>So that if the navigation is canceled, we can <span>signal abort</span>
<tr>
<td>Whether a new element was <span data-x="focusing steps">focused</span>
<td>Until all promises returned from handlers passed to <code data-x="dom-NavigateEvent-intercept">intercept()</code> have settled
<td>So that if one was, focus is not <span data-x="potentially reset the focus">reset</span>
<tr>
<td>The <code>NavigationHistoryEntry</code> being navigated to
<td>From when it is determined, until all promises returned from handlers passed to <code data-x="dom-NavigateEvent-intercept">intercept()</code> have settled
<td>So that we know what to resolve any <code data-x="dom-NavigationResult-committed">committed</code> and <code data-x="dom-NavigationResult-finished">finished</code> promises with
<tr>
<td>Any <code data-x="dom-NavigationResult-finished">finished</code> promise that was returned
<td>Until all promises returned from handlers passed to <code data-x="dom-NavigateEvent-intercept">intercept()</code> have settled
<td>So that we can resolve or reject it appropriately
</table>
<table>
<caption>For non-"<code data-x="dom-NavigationType-traverse">traverse</code>" navigations</caption>
<thead>
<tr>
<th>State
<th>Duration
<th>Explanation
<tbody>
<tr>
<td>Any <code data-x="dom-NavigationNavigateOptions-state">state</code>
<td>For the duration of event firing
<td>So that we can update the current entry's <span data-x="she-navigation-api-state">navigation API state</span> if the event finishes firing without being <span data-x="canceled flag">canceled</span>
</table>
<table>
<caption>For "<code data-x="dom-NavigationType-traverse">traverse</code>" navigations</caption>
<thead>
<tr>
<th>State
<th>Duration
<th>Explanation
<tbody>
<tr>
<td>Any <code data-x="dom-NavigationOptions-info">info</code>
<td>Until the task is queued to fire the <code data-x="event-navigate">navigate</code> event
<td>So that we can use it to fire the <code data-x="event-navigate">navigate</code> after the trip through the <span data-x="tn-session-history-traversal-queue">session history traversal queue</span>.
<tr>
<td>Any <code data-x="dom-NavigationResult-committed">committed</code> promise that was returned
<td>Until the session history is updated (inside that same task)
<td>So that we can resolve or reject it appropriately
<tr>
<td>Whether <code data-x="dom-NavigateEvent-intercept">intercept()</code> was called
<td>Until the session history is updated (inside that same task)
<td>So that we can suppress the normal scroll restoration logic in favor of the behavior given by the <code data-x="dom-NavigationInterceptOptions-scroll">scroll</code> option
</table>
<p>We also cannot assume there is only a single navigation requested at any given time, due to web
developer code such as:</p>
<pre><code class="js">const p1 = navigation.navigate(url1).finished;
const p2 = navigation.navigate(url2).finished;</code></pre>
<p>That is, in this scenario, we need to ensure that while navigating to <code
data-x="">url2</code>, we still have the promise <code data-x="">p1</code> around so that we can
reject it. We can't just get rid of any ongoing navigation promises the moment the second call to
<code data-x="dom-Navigation-navigate">navigate()</code> happens.</p>
<p>We end up accomplishing all this by associating the following with each
<code>Navigation</code>:</p>
<ul>
<li><p><dfn>Ongoing <code data-x="event-navigate">navigate</code> event</dfn>, a
<code>NavigateEvent</code> or null, initially null.</p></li>
<li><p><dfn>Focus changed during ongoing navigation</dfn>, a boolean, initially false.</p></li>
<li><p><dfn>Suppress normal scroll restoration during ongoing navigation</dfn>, a boolean,
initially false.</p></li>
<li><p><dfn>Ongoing API method tracker</dfn>, a <span>navigation API method tracker</span> or
null, initially null.</p></li>
<li><p><dfn>Upcoming non-traverse API method tracker</dfn>, a <span>navigation API method
tracker</span> or null, initially null.</p></li>
<li><p><dfn>Upcoming traverse API method trackers</dfn>, an <span>ordered map</span> from strings
to <span data-x="navigation API method tracker">navigation API method trackers</span>, initially
empty.</p></li>
</ul>
<p class="note">The state here that is not stored in <span data-x="navigation API method
tracker">navigation API method trackers</span> is state which needs to be tracked even for
navigations that are not initiated via navigation API methods.</p>
<p>A <dfn>navigation API method tracker</dfn> is a <span>struct</span> with the following <span
data-x="struct item">items</span>:</p>
<ul>
<li><p>A <dfn data-x="navigation-api-method-tracker-navigation">navigation object</dfn>, a
<code>Navigation</code></p></li>
<li><p>A <dfn data-x="navigation-api-method-tracker-key">key</dfn>, a string or null</p></li>
<li><p>An <dfn data-x="navigation-api-method-tracker-info">info</dfn>, a JavaScript
value</p></li>
<li><p>A <dfn data-x="navigation-api-method-tracker-state">serialized state</dfn>, a
<span>serialized state</span> or null</p></li>
<li><p>A <dfn data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</dfn>,
a <code>NavigationHistoryEntry</code> or null</p></li>
<li><p>A <dfn data-x="navigation-api-method-tracker-committed">committed promise</dfn>, a
promise</p></li>
<li><p>A <dfn data-x="navigation-api-method-tracker-finished">finished promise</dfn>, a
promise</p></li>
</ul>
<p>All this state is then managed via the following algorithms.</p>
<p>To <dfn>maybe set the upcoming non-traverse API method tracker</dfn> given a
<code>Navigation</code> <var>navigation</var>, a JavaScript value <var>info</var>, and a
<span>serialized state</span>-or-null <var>serializedState</var>:</p>
<ol>
<li><p>Let <var>committedPromise</var> and <var>finishedPromise</var> be new promises created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p><span>Mark as handled</span> <var>finishedPromise</var>.</p>
<div class="note" id="note-mark-as-handled-navigation-api-finished">
<p>The web developer doesn’t necessarily care about <var>finishedPromise</var> being
rejected:</p>
<ul>
<li><p>They might only care about <var>committedPromise</var>.</p></li>
<li><p>They could be doing multiple synchronous navigations within the same task, in which
case all but the last will be aborted (causing their <var>finishedPromise</var> to reject).
This could be an application bug, but also could just be an emergent feature of disparate
parts of the application overriding each others' actions.</p></li>
<li><p>They might prefer to listen to other transition-failure signals instead of
<var>finishedPromise</var>, e.g., the <code data-x="event-navigateerror">navigateerror</code>
event, or the <code
data-x="dom-NavigationTransition-finished">navigation.transition.finished</code>
promise.</p></li>
</ul>
<p>As such, we mark it as handled to ensure that it never triggers <code
data-x="event-unhandledrejection">unhandledrejection</code> events.</p>
</div>
</li>
<li>
<p>Let <var>apiMethodTracker</var> be a new <span>navigation API method tracker</span> with:</p>
<dl class="props">
<dt><span data-x="navigation-api-method-tracker-navigation">navigation object</span></dt>
<dd><var>navigation</var></dd>
<dt><span data-x="navigation-api-method-tracker-key">key</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-api-method-tracker-info">info</span></dt>
<dd><var>info</var></dd>
<dt><span data-x="navigation-api-method-tracker-state">serialized state</span></dt>
<dd><var>serializedState</var></dd>
<dt><span data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-api-method-tracker-committed">committed promise</span></dt>
<dd><var>committedPromise</var></dd>
<dt><span data-x="navigation-api-method-tracker-finished">finished promise</span></dt>
<dd><var>finishedPromise</var></dd>
</dl>
</li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>upcoming non-traverse API method
tracker</span> is null.</p></li>
<li id="dont-always-set-upcoming-non-traverse-api-method-tracker">
<p>If <var>navigation</var> does not <span data-x="has entries and events disabled">have
entries and events disabled</span>, then set <var>navigation</var>'s <span>upcoming
non-traverse API method tracker</span> to <var>apiMethodTracker</var>.</p>
<p class="note">If <var>navigation</var> <span>has entries and events disabled</span>, then
<var>committedPromise</var> and <var>finishedPromise</var> will never fulfill (since we never
create a <code>NavigationHistoryEntry</code> object for such <code>Document</code>s, and so we
have nothing to resolve them with); there is no <code>NavigationHistoryEntry</code> to apply
<var>serializedState</var> to; and there is no <code data-x="event-navigate">navigate</code>
event to include <var>info</var> with. So, we don't need to track this API method call after
all.</p>
</li>
<li><p>Return <var>apiMethodTracker</var>.</p></li>
</ol>
<p>To <dfn>add an upcoming traverse API method tracker</dfn> given a <code>Navigation</code>
<var>navigation</var>, a string <var>destinationKey</var>, and a JavaScript value
<var>info</var>:</p>
<ol>
<li><p>Let <var>committedPromise</var> and <var>finishedPromise</var> be new promises created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p><span>Mark as handled</span> <var>finishedPromise</var>.</p>
<p class="note">See the <a href="#note-mark-as-handled-navigation-api-finished">previous
discussion</a> about why this is done.</p>
</li>
<li>
<p>Let <var>apiMethodTracker</var> be a new <span>navigation API method tracker</span> with:</p>
<dl class="props">
<dt><span data-x="navigation-api-method-tracker-navigation">navigation object</span></dt>
<dd><var>navigation</var></dd>
<dt><span data-x="navigation-api-method-tracker-key">key</span></dt>
<dd><var>destinationKey</var></dd>
<dt><span data-x="navigation-api-method-tracker-info">info</span></dt>
<dd><var>info</var></dd>
<dt><span data-x="navigation-api-method-tracker-state">serialized state</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-api-method-tracker-committed">committed promise</span></dt>
<dd><var>committedPromise</var></dd>
<dt><span data-x="navigation-api-method-tracker-finished">finished promise</span></dt>
<dd><var>finishedPromise</var></dd>
</dl>
</li>
<li><p>Set <var>navigation</var>'s <span>upcoming traverse API method
trackers</span>[<var>destinationKey</var>] to <var>apiMethodTracker</var>.</p></li>
<li><p>Return <var>apiMethodTracker</var>.</p></li>
</ol>
<p>To <dfn>promote an upcoming API method tracker to ongoing</dfn> given a <code>Navigation</code>
<var>navigation</var> and a string-or-null <var>destinationKey</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>ongoing API method tracker</span> is
null.</p></li>
<li>
<p>If <var>destinationKey</var> is not null, then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>upcoming non-traverse API method
tracker</span> is null.</p></li>
<li>
<p>If <var>navigation</var>'s <span>upcoming traverse API method
trackers</span>[<var>destinationKey</var>] <span data-x="map exists">exists</span>, then:</p>
<ol>
<li><p>Set <var>navigation</var>'s <span>ongoing API method tracker</span> to
<var>navigation</var>'s <span>upcoming traverse API method
trackers</span>[<var>destinationKey</var>].</p></li>
<li><p><span data-x="map remove">Remove</span> <var>navigation</var>'s <span>upcoming
traverse API method trackers</span>[<var>destinationKey</var>].</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Set <var>navigation</var>'s <span>ongoing API method tracker</span> to
<var>navigation</var>'s <span>upcoming non-traverse API method tracker</span>.</p></li>
<li><p>Set <var>navigation</var>'s <span>upcoming non-traverse API method tracker</span> to
null.</p></li>
</ol>
</li>
</ol>
<p>To <dfn data-x="navigation-api-method-tracker-clean-up">clean up</dfn> a <span>navigation API
method tracker</span> <var>apiMethodTracker</var>:</p>
<ol>
<li><p>Let <var>navigation</var> be <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-navigation">navigation object</span>.</p></li>
<li><p>If <var>navigation</var>'s <span>ongoing API method tracker</span> is
<var>apiMethodTracker</var>, then set <var>navigation</var>'s <span>ongoing API method
tracker</span> to null.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>key</var> be <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-key">key</span>.</p></li>
<li><p><span>Assert</span>: <var>key</var> is not null.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>upcoming traverse API method
trackers</span>[<var>key</var>] <span data-x="map exists">exists</span>.</p></li>
<li><p><span data-x="map remove">Remove</span> <var>navigation</var>'s <span>upcoming traverse
API method trackers</span>[<var>key</var>].</p></li>
</ol>
</li>
</ol>
<p>To <dfn>notify about the committed-to entry</dfn> given a <span>navigation API method
tracker</span> <var>apiMethodTracker</var> and a <code>NavigationHistoryEntry</code>
<var>nhe</var>:</p>
<ol>
<li><p>Set <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</span> to
<var>nhe</var>.</p></li>
<li>
<p>If <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-state">serialized state</span> is not null, then set
<var>nhe</var>'s <span data-x="nhe-she">session history entry</span>'s <span
data-x="she-navigation-api-state">navigation API state</span> to <var>apiMethodTracker</var>'s
<span data-x="navigation-api-method-tracker-state">serialized state</span>.</p>
<p class="note">If it's null, then we're traversing to <var>nhe</var> via <code
data-x="dom-Navigation-traverseTo">navigation.traverseTo()</code>, which does not allow changing
the state.</p>
<p class="note">At this point, <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-state">serialized state</span> is no longer needed.
Implementations might want to clear it out to avoid keeping it alive for the lifetime of the
<span>navigation API method tracker</span>.</p>
</li>
<li>
<p>Resolve <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed">committed promise</span> with
<var>nhe</var>.</p>
<p class="note">At this point, <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed">committed promise</span> is only needed in
cases where it has not yet been returned to author code. Implementations might want to clear it
out to avoid keeping it alive for the lifetime of the <span>navigation API method
tracker</span>.</p>
</li>
</ol>
<p>To <dfn>resolve the finished promise</dfn> for a <span>navigation API method tracker</span>
<var>apiMethodTracker</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</span> is not
null.</p></li>
<li><p>Resolve <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-finished">finished promise</span> with its <span
data-x="navigation-api-method-tracker-committed-to-entry">committed-to entry</span>.</p></li>
<li><p><span data-x="navigation-api-method-tracker-clean-up">Clean up</span>
<var>apiMethodTracker</var>.</p></li>
</ol>
<p>To <dfn>reject the finished promise</dfn> for a <span>navigation API method tracker</span>
<var>apiMethodTracker</var> with a JavaScript value <var>exception</var>:</p>
<ol>
<li>
<p>Reject <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed">committed promise</span> with
<var>exception</var>.</p>
<p class="note">This will do nothing if <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-committed">committed promise</span> was previously
resolved via <span>notify about the committed-to entry</span>.</p>
</li>
<li><p>Reject <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-finished">finished promise</span> with
<var>exception</var>.</p></li>
<li><p><span data-x="navigation-api-method-tracker-clean-up">Clean up</span>
<var>apiMethodTracker</var>.</p></li>
</ol>
<p>To <dfn>abort the ongoing navigation</dfn> given a <code>Navigation</code>
<var>navigation</var> and an optional <code>DOMException</code> <var>error</var>:</p>
<ol>
<li><p>Let <var>event</var> be <var>navigation</var>'s <span>ongoing <code
data-x="event-navigate">navigate</code> event</span>.</p></li>
<li><p><span>Assert</span>: <var>event</var> is not null.</p></li>
<li><p>Set <var>navigation</var>'s <span>focus changed during ongoing navigation</span> to
false.</p></li>
<li><p>Set <var>navigation</var>'s <span>suppress normal scroll restoration during ongoing
navigation</span> to false.</p></li>
<li><p>If <var>error</var> was not given, then let <var>error</var> be a new
<span>"<code>AbortError</code>"</span> <code>DOMException</code> created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>If <var>event</var>'s <span>dispatch flag</span> is set, then set <var>event</var>'s
<span>canceled flag</span> to true.</p></li>
<li><p><span>Signal abort</span> on <var>event</var>'s <span
data-x="concept-NavigateEvent-abort-controller">abort controller</span> given
<var>error</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span>ongoing <code data-x="event-navigate">navigate</code>
event</span> to null.</p></li>
<li>
<p>Let <var>errorInfo</var> be the result of <span data-x="extract-error">extracting error
information</span> from <var>error</var>.</p>
<p class="note">For example, if this algorithm is reached because of a call to <code
data-x="dom-window-stop">window.stop()</code>, these properties would probably end up
initialized based on the line of script that called <code
data-x="dom-window-stop">window.stop()</code>. But if it's because the user clicked the stop
button, these properties would probably end up with default values like the empty string or
0.</p>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-navigateerror">navigateerror</code> at <var>navigation</var> using
<code>ErrorEvent</code>, with additional attributes initialized according to
<var>errorInfo</var>.</p></li>
<li><p>If <var>navigation</var>'s <span>ongoing API method tracker</span> is non-null, then
<span>reject the finished promise</span> for <var>apiMethodTracker</var> with
<var>error</var>.</p></li>
<li>
<p>If <var>navigation</var>'s <span data-x="concept-Navigation-transition">transition</span> is
not null, then:</p>
<ol>
<li><p>Reject <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span>'s <span
data-x="concept-NavigationTransition-finished">finished promise</span> with
<var>error</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> to null.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>inform the navigation API about aborting navigation</dfn> in a <span>navigable</span>
<var>navigable</var>:</p>
<ol>
<li><p>If this algorithm is running on <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span>relevant agent</span>'s <span data-x="concept-agent-event-loop">event
loop</span>, then continue on to the following steps. Otherwise, <span>queue a global task</span>
on the <span>navigation and traversal task source</span> given <var>navigable</var>'s <span
data-x="nav-window">active window</span> to run the following steps.</p></li>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>If <var>navigation</var>'s <span>ongoing <code data-x="event-navigate">navigate</code>
event</span> is null, then return.</p></li>
<li><p><span>Abort the ongoing navigation</span> given <var>navigation</var>.</p></li>
</ol>
<p>To <dfn>inform the navigation API about child navigable destruction</dfn> given a
<span>navigable</span> <var>navigable</var>:</p>
<ol>
<li><p><span>Inform the navigation API about aborting navigation</span> in
<var>navigable</var>.</p></li>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>traversalAPIMethodTrackers</var> be a <span data-x="list clone">clone</span> of
<var>navigation</var>'s <span>upcoming traverse API method trackers</span>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>apiMethodTracker</var> of
<var>traversalAPIMethodTrackers</var>: <span>reject the finished promise</span> for
<var>apiMethodTracker</var> with a new <span>"<code>AbortError</code>"</span>
<code>DOMException</code> created in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
</ol>
<hr>
<p>The ongoing navigation concept is most-directly exposed to web developers through the <code
data-x="dom-Navigation-transition">navigation.transition</code> property, which is an instance of
the <code>NavigationTransition</code> interface:</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigationTransition</dfn> {
readonly attribute <span>NavigationType</span> <span data-x="dom-NavigationTransition-navigationType">navigationType</span>;
readonly attribute <span>NavigationHistoryEntry</span> <span data-x="dom-NavigationTransition-from">from</span>;
readonly attribute <span data-x="idl-Promise">Promise</span><undefined> <span data-x="dom-NavigationTransition-finished">finished</span>;
};</code></pre>
</div>
<dl class="domintro">
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-transition">transition</span></code></dt>
<dd>
<p>A <code>NavigationTransition</code> representing any ongoing navigation that hasn't yet
reached the <code data-x="event-navigatesuccess">navigatesuccess</code> or <code
data-x="event-navigateerror">navigateerror</code> stage, if one exists; or null, if there is no
such transition ongoing.</p>
<p>Since <code data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> (and other
properties like <code data-x="dom-location-href">location.href</code>) are updated immediately
upon navigation, this <code data-x="dom-Navigation-transition">navigation.transition</code>
property is useful for determining when such navigations are not yet fully settled, according to
any handlers passed to <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code>.</p>
</dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-transition">transition</span>.<span subdfn data-x="dom-NavigationTransition-navigationType">navigationType</span></code></dt>
<dd><p>One of "<code data-x="dom-NavigationType-push">push</code>", "<code
data-x="dom-NavigationType-replace">replace</code>", "<code
data-x="dom-NavigationType-reload">reload</code>", or "<code
data-x="dom-NavigationType-traverse">traverse</code>", indicating what type of navigation this
transition is for.</p></dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-transition">transition</span>.<span subdfn data-x="dom-NavigationTransition-from">from</span></code></dt>
<dd><p>The <code>NavigationHistoryEntry</code> from which the transition is coming. This can be
useful to compare against <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code>.</p></dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-transition">transition</span>.<span subdfn data-x="dom-NavigationTransition-finished">finished</span></code></dt>
<dd><p>A promise which fulfills at the same time as the <code
data-x="event-navigatesuccess">navigatesuccess</code> fires, or rejects at the same time the
<code data-x="event-navigateerror">navigateerror</code> event fires.</p></dd>
</dl>
<div w-nodev>
<p>Each <code>Navigation</code> has a <dfn
data-x="concept-Navigation-transition">transition</dfn>, which is a
<code>NavigationTransition</code> or null, initially null.</p>
<p>The <dfn attribute for="Navigation"><code
data-x="dom-Navigation-transition">transition</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-Navigation-transition">transition</span>.</p>
<p>Each <code>NavigationTransition</code> has an associated <dfn
data-x="concept-NavigationTransition-navigationType">navigation type</dfn>, which is a
<code>NavigationType</code>.</p>
<p>Each <code>NavigationTransition</code> has an associated <dfn
data-x="concept-NavigationTransition-from">from entry</dfn>, which is a
<code>NavigationHistoryEntry</code>.</p>
<p>Each <code>NavigationTransition</code> has an associated <dfn
data-x="concept-NavigationTransition-finished">finished promise</dfn>, which is a promise.</p>
<p>The <dfn attribute for="NavigationTransition"><code
data-x="dom-NavigationTransition-navigationType">navigationType</code></dfn> getter steps are to
return <span>this</span>'s <span data-x="concept-NavigationTransition-navigationType">navigation
type</span>.</p>
<p>The <dfn attribute for="NavigationTransition"><code
data-x="dom-NavigationTransition-from">from</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationTransition-from">from entry</span>.</p>
<p>The <dfn attribute for="NavigationTransition"><code
data-x="dom-NavigationTransition-finished">finished</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationTransition-finished">finished
promise</span>.</p>
</div>
<h5 id="navigation-activation-interface">The <code>NavigationActivation</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigationActivation</dfn> {
readonly attribute <span>NavigationHistoryEntry</span>? <span data-x="dom-NavigationActivation-from">from</span>;
readonly attribute <span>NavigationHistoryEntry</span> <span data-x="dom-NavigationActivation-entry">entry</span>;
readonly attribute <span>NavigationType</span> <span data-x="dom-NavigationActivation-navigationType">navigationType</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span subdfn data-x="dom-Navigation-activation">activation</span></code></dt>
<dd>
<p>A <code>NavigationActivation</code> containing information about the most recent
cross-document navigation, the navigation that "activated" this <code>Document</code>.</p>
<p>While <code data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> and the
<code>Document</code>'s <span data-x="concept-document-url">URL</span> can be updated regularly
due to same-document navigations, <code
data-x="dom-Navigation-activation">navigation.activation</code> stays constant, and its properties
are only updated if the <code>Document</code> is <span
data-x="reactivate a document">reactivated</span> from history.</p>
</dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-activation">activation</span>.<span subdfn data-x="dom-NavigationActivation-entry">entry</span></code></dt>
<dd><p>A <code>NavigationHistoryEntry</code>, equivalent to the value of the <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> property at the moment the
<code>Document</code> was activated.</p></dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-activation">activation</span>.<span subdfn data-x="dom-NavigationActivation-from">from</span></code></dt>
<dd>
<p>A <code>NavigationHistoryEntry</code>, representing the <code>Document</code> that was active
right before the current <code>Document</code>. This will have a value null in case the
previous <code>Document</code> was not <span>same origin</span> with this one or if it was the
<span data-x="is initial about:blank">initial <code>about:blank</code></span>
<code>Document</code>.</p>
<p>There are some cases in which either the <code
data-x="dom-NavigationActivation-from">from</code> or <code
data-x="dom-NavigationActivation-entry">entry</code> <code>NavigationHistoryEntry</code> objects
would not be viable targets for the <code data-x="dom-Navigation-traverseTo">traverseTo()</code>
method, as they might not be retained in history. For example, the <code>Document</code> can be
activated using <code data-x="dom-location-replace">location.replace()</code> or its initial
entry could be replaced by <code
data-x="dom-history-replaceState">history.replaceState()</code>. However, those entries' <code
data-x="dom-NavigationHistoryEntry-url">url</code> property and <code
data-x="dom-NavigationHistoryEntry-getState">getState()</code> method are still accessible.</p>
</dd>
<dt><code data-x=""><span data-x="dom-navigation">navigation</span>.<span data-x="dom-Navigation-activation">activation</span>.<span subdfn data-x="dom-NavigationActivation-navigationType">navigationType</span></code></dt>
<dd><p>One of "<code data-x="dom-NavigationType-push">push</code>", "<code
data-x="dom-NavigationType-replace">replace</code>", "<code
data-x="dom-NavigationType-reload">reload</code>", or "<code
data-x="dom-NavigationType-traverse">traverse</code>", indicating what type of navigation
activated this <code>Document</code>.</p></dd>
</dl>
<p>Each <code>Navigation</code> has an associated <dfn
data-x="navigation-activation">activation</dfn>, which is null or a
<code>NavigationActivation</code> object, initially null.</p>
<p>Each <code>NavigationActivation</code> has:</p>
<ul>
<li><p><dfn data-x="nav-activation-old-entry">old entry</dfn>, null or a
<code>NavigationHistoryEntry</code>.</p></li>
<li><p><dfn data-x="nav-activation-new-entry">new entry</dfn>, null or a
<code>NavigationHistoryEntry</code>.</p></li>
<li><p><dfn data-x="nav-activation-navigation-type">navigation type</dfn>, a
<code>NavigationType</code>.</p></li>
</ul>
<p>The <dfn attribute for="Navigation"><code
data-x="dom-Navigation-activation">activation</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="navigation-activation">activation</span>.</p>
<p>The <dfn attribute for="NavigationActivation"><code
data-x="dom-NavigationActivation-from">from</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="nav-activation-old-entry">old entry</span>.</p>
<p>The <dfn attribute for="NavigationActivation"><code
data-x="dom-NavigationActivation-entry">entry</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="nav-activation-new-entry">new entry</span>.</p>
<p>The <dfn attribute for="NavigationActivation"><code
data-x="dom-NavigationActivation-navigationType">navigationType</code></dfn> getter steps are to
return <span>this</span>'s <span
data-x="nav-activation-navigation-type">navigation type</span>.</p>
<h5>The <code data-x="event-navigate">navigate</code> event</h5>
<p>A major feature of the navigation API is the <code data-x="event-navigate">navigate</code>
event. This event is fired on any navigation (in the <span data-x="NavigationType">broad sense of
the word</span>), allowing web developers to monitor such outgoing navigations. In many cases, the
event is <code data-x="dom-Event-cancelable">cancelable</code>, which allows preventing the
navigation from happening. And in others, the navigation can be intercepted and replaced with a
same-document navigation by using the <code
data-x="dom-NavigateEvent-intercept">intercept()</code> method of the <code>NavigateEvent</code>
class.</p>
<h6>The <code>NavigateEvent</code> interface</h6>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigateEvent</dfn> : <span>Event</span> {
constructor(DOMString type, <span>NavigateEventInit</span> eventInitDict);
readonly attribute <span>NavigationType</span> <span data-x="dom-NavigateEvent-navigationType">navigationType</span>;
readonly attribute <span>NavigationDestination</span> <span data-x="dom-NavigateEvent-destination">destination</span>;
readonly attribute boolean <span data-x="dom-NavigateEvent-canIntercept">canIntercept</span>;
readonly attribute boolean <span data-x="dom-NavigateEvent-userInitiated">userInitiated</span>;
readonly attribute boolean <span data-x="dom-NavigateEvent-hashChange">hashChange</span>;
readonly attribute <span>AbortSignal</span> <span data-x="dom-NavigateEvent-signal">signal</span>;
readonly attribute <code>FormData</code>? <span data-x="dom-NavigateEvent-formData">formData</span>;
readonly attribute DOMString? <span data-x="dom-NavigateEvent-downloadRequest">downloadRequest</span>;
readonly attribute any <span data-x="dom-NavigateEvent-info">info</span>;
readonly attribute boolean <span data-x="dom-NavigateEvent-hasUAVisualTransition">hasUAVisualTransition</span>;
readonly attribute Element? <span data-x="dom-NavigateEvent-sourceElement">sourceElement</span>;
undefined <span data-x="dom-NavigateEvent-intercept">intercept</span>(optional <span>NavigationInterceptOptions</span> options = {});
undefined <span data-x="dom-NavigateEvent-scroll">scroll</span>();
};
dictionary <dfn dictionary>NavigateEventInit</dfn> : <span>EventInit</span> {
<span>NavigationType</span> <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-navigationType">navigationType</dfn> = "<span data-x="dom-NavigationType-push">push</span>";
required <span>NavigationDestination</span> <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-destination">destination</dfn>;
boolean <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-canIntercept">canIntercept</dfn> = false;
boolean <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-userInitiated">userInitiated</dfn> = false;
boolean <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-hashChange">hashChange</dfn> = false;
required <span>AbortSignal</span> <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-signal">signal</dfn>;
<span>FormData</span>? <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-formData">formData</dfn> = null;
DOMString? <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-downloadRequest">downloadRequest</dfn> = null;
any <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-info">info</dfn>;
boolean <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-hasUAVisualTransition">hasUAVisualTransition</dfn> = false;
Element? <dfn dict-member for="NavigateEventInit" data-x="dom-NavigateEventInit-sourceElement">sourceElement</dfn> = null;
};
dictionary <dfn dictionary>NavigationInterceptOptions</dfn> {
<span>NavigationInterceptHandler</span> <dfn dict-member for="NavigationInterceptOptions" data-x="dom-NavigationInterceptOptions-handler">handler</dfn>;
<span>NavigationFocusReset</span> <dfn dict-member for="NavigationInterceptOptions" data-x="dom-NavigationInterceptOptions-focusReset">focusReset</dfn>;
<span>NavigationScrollBehavior</span> <dfn dict-member for="NavigationInterceptOptions" data-x="dom-NavigationInterceptOptions-scroll">scroll</dfn>;
};
enum <dfn enum>NavigationFocusReset</dfn> {
"<dfn enum-value for="NavigationFocusReset" data-x="dom-NavigationFocusReset-after-transition">after-transition</dfn>",
"<dfn enum-value for="NavigationFocusReset" data-x="dom-NavigationFocusReset-manual">manual</dfn>"
};
enum <dfn enum>NavigationScrollBehavior</dfn> {
"<dfn enum-value for="NavigationScrollBehavior" data-x="dom-NavigationScrollBehavior-after-transition">after-transition</dfn>",
"<dfn enum-value for="NavigationScrollBehavior" data-x="dom-NavigationScrollBehavior-manual">manual</dfn>"
};
callback <dfn callback>NavigationInterceptHandler</dfn> = <span data-x="idl-Promise">Promise</span><undefined> ();</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-navigationType">navigationType</span></code></dt>
<dd><p>One of "<code data-x="dom-NavigationType-push">push</code>", "<code
data-x="dom-NavigationType-replace">replace</code>", "<code
data-x="dom-NavigationType-reload">reload</code>", or "<code
data-x="dom-NavigationType-traverse">traverse</code>", indicating what type of navigation this
is.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-destination">destination</span></code></dt>
<dd><p>A <code>NavigationDestination</code> representing the destination of the
navigation.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-canIntercept">canIntercept</span></code></dt>
<dd>
<p>True if <code data-x="dom-NavigateEvent-intercept">intercept()</code> can be called to
intercept this navigation and convert it into a same-document navigation, replacing its usual
behavior; false otherwise.</p>
<p>Generally speaking, this will be true whenever the current <code>Document</code> <span>can
have its URL rewritten</span> to the destination URL, except for in the case of cross-document
"<code data-x="dom-NavigationType-traverse">traverse</code>" navigations, where it will always
be false.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-userInitiated">userInitiated</span></code></dt>
<dd><p>True if this navigation was due to a user clicking on an <code>a</code> element,
submitting a <code>form</code> element, or using the <a href="#nav-traversal-ui">browser UI</a>
to navigate; false otherwise.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-hashChange">hashChange</span></code></dt>
<dd><p>True for a <span data-x="navigate-fragid">fragment navigation</span>; false
otherwise.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-signal">signal</span></code></dt>
<dd>
<p>An <code>AbortSignal</code> which will become aborted if the navigation gets canceled, e.g.,
by the user pressing their browser's "Stop" button, or by another navigation interrupting this
one.</p>
<p>The expected pattern is for developers to pass this along to any async operations, such as
<code>fetch()</code>, which they perform as part of handling this navigation.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-formData">formData</span></code></dt>
<dd>
<p>The <code>FormData</code> representing the submitted form entries for this navigation, if
this navigation is a "<code data-x="dom-NavigationType-push">push</code>" or "<code
data-x="dom-NavigationType-replace">replace</code>" navigation representing a POST <span
data-x="concept-form-submit">form submission</span>; null otherwise.</p>
<p>(Notably, this will be null even for "<code data-x="dom-NavigationType-reload">reload</code>"
or "<code data-x="dom-NavigationType-traverse">traverse</code>" navigations that are revisiting
a <span>session history entry</span> that was originally created from a form submission.)</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-downloadRequest">downloadRequest</span></code></dt>
<dd>
<p>Represents whether or not this navigation was requested to be a download, by using an
<code>a</code> or <code>area</code> element's <code
data-x="attr-hyperlink-download">download</code> attribute:</p>
<ul>
<li><p>If a download was not requested, then this property is null.</p></li>
<li><p>If a download was requested, returns the filename that was supplied as the <code
data-x="attr-hyperlink-download">download</code> attribute's value. (This could be the empty
string.)</p></li>
</ul>
<p>Note that a download being requested does not always mean that a download will happen: for
example, a download might be blocked by browser security policies, or end up being treated as a
"<code data-x="NavigationHistoryBehavior-push">push</code>" navigation for <a
href="https://github.com/whatwg/html/issues/7718" class="XXX">unspecified reasons</a>.</p>
<p>Similarly, a navigation might end up being a download even if it was not requested to be one,
due to the destination server responding with a `<code
data-x="http-content-disposition">Content-Disposition: attachment</code>` header.</p>
<p>Finally, note that the <code data-x="event-navigate">navigate</code> event will not fire at
all for downloads initiated using browser UI affordances, e.g., those created by right-clicking
and choosing to save the target of a link.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-info">info</span></code></dt>
<dd><p>An arbitrary JavaScript value passed via one of the <a
href="#navigation-api-initiating-navigations">navigation API methods</a> which initiated this
navigation, or undefined if the navigation was initiated by the user or by a different
API.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-hasUAVisualTransition">hasUAVisualTransition</span></code></dt>
<dd><p>Returns true if the user agent performed a visual transition for this navigation before
dispatching this event. If true, the best user experience will be given if the author
synchronously updates the DOM to the post-navigation state.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-sourceElement">sourceElement</span></code></dt>
<dd><p>Returns the <code>Element</code> responsible for this navigation. This can be an
<code>a</code>or <code>area</code> element, a <span
data-x="concept-submit-button">submit button</span>, or a submitted <code>form</code>
element.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-intercept">intercept</span>({ <span subdfn data-x="dom-NavigationInterceptOptions-handler">handler</span>, <span subdfn data-x="dom-NavigationInterceptOptions-focusReset">focusReset</span>, <span subdfn data-x="dom-NavigationInterceptOptions-scroll">scroll</span> })</code></dt>
<dd>
<p>Intercepts this navigation, preventing its normal handling and instead converting it into a
same-document navigation of the same type to the destination URL.</p>
<p>The <code data-x="dom-NavigationInterceptOptions-handler">handler</code> option can be a
function that returns a promise. The handler function will run after the <code
data-x="event-navigate">navigate</code> event has finished firing, and the <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> property has been
synchronously updated. This returned promise is used to signal the duration, and success or
failure, of the navigation. After it settles, the browser signals to the user (e.g., via a
loading spinner UI, or assistive technology) that the navigation is finished. Additionally, it
fires <code data-x="event-navigatesuccess">navigatesuccess</code> or <code
data-x="event-navigateerror">navigateerror</code> events as appropriate, which other parts of
the web application can respond to.</p>
<p>By default, using this method will cause focus to reset when any handlers' returned promises
settle. Focus will be reset to the first element with the <code
data-x="attr-fe-autofocus">autofocus</code> attribute set, or <span>the body element</span> if
the attribute isn't present. The <code
data-x="dom-NavigationInterceptOptions-focusReset">focusReset</code> option can be set to "<code
data-x="dom-NavigationFocusReset-manual">manual</code>" to avoid this behavior.</p>
<p>By default, using this method will delay the browser's scroll restoration logic for "<code
data-x="dom-NavigationType-traverse">traverse</code>" or "<code
data-x="dom-NavigationType-reload">reload</code>" navigations, or its
scroll-reset/scroll-to-a-fragment logic for "<code data-x="dom-NavigationType-push">push</code>"
or "<code data-x="dom-NavigationType-replace">replace</code>" navigations, until any handlers'
returned promises settle. The <code data-x="dom-NavigationInterceptOptions-scroll">scroll</code>
option can be set to "<code data-x="dom-NavigationScrollBehavior-manual">manual</code>" to turn
off any browser-driven scroll behavior entirely for this navigation, or <code
data-x="dom-NavigateEvent-scroll">scroll()</code> can be called before the promise settles to
trigger this behavior early.</p>
<p>This method will throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>
if <code data-x="dom-NavigateEvent-canIntercept">canIntercept</code> is false, or if <code
data-x="dom-Event-isTrusted">isTrusted</code> is false. It will throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if not called
synchronously, during event dispatch.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigateEvent-scroll">scroll</span>()</code></dt>
<dd>
<p>For "<code data-x="dom-NavigationType-traverse">traverse</code>" or "<code
data-x="dom-NavigationType-reload">reload</code>" navigations, restores the scroll position
using the browser's usual scroll restoration logic.</p>
<p>For "<code data-x="dom-NavigationType-push">push</code>" or "<code
data-x="dom-NavigationType-replace">replace</code>" navigations, either resets the scroll
position to the top of the document or scrolls to the <span
data-x="concept-url-fragment">fragment</span> specified by <code
data-x="dom-NavigationDestination-url">destination.url</code> if there is one.</p>
<p>If called more than once, or called after automatic post-transition scroll processing has
happened due to the <code data-x="dom-NavigationInterceptOptions-scroll">scroll</code> option
being left as "<code
data-x="dom-NavigationScrollBehavior-after-transition">after-transition</code>", or called
before the navigation has committed, this method will throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <code>NavigateEvent</code> has an <dfn
data-x="concept-NavigateEvent-interception-state">interception state</dfn>, which is either "<code
data-x="">none</code>", "<code data-x="">intercepted</code>", "<code data-x="">committed</code>",
"<code data-x="">scrolled</code>", or "<code data-x="">finished</code>", initially "<code
data-x="">none</code>".</p>
<p>Each <code>NavigateEvent</code> has a <dfn
data-x="concept-NavigateEvent-navigation-handler-list">navigation handler list</dfn>, a
<span>list</span> of <code>NavigationInterceptHandler</code> callbacks, initially empty.</p>
<p>Each <code>NavigateEvent</code> has a <dfn data-x="concept-NavigateEvent-focusReset">focus
reset behavior</dfn>, a <code>NavigationFocusReset</code>-or-null, initially null.</p>
<p>Each <code>NavigateEvent</code> has a <dfn data-x="concept-NavigateEvent-scroll">scroll
behavior</dfn>, a <code>NavigationScrollBehavior</code>-or-null, initially null.</p>
<p>Each <code>NavigateEvent</code> has an <dfn
data-x="concept-NavigateEvent-abort-controller">abort controller</dfn>, an
<code>AbortController</code>-or-null, initially null.</p>
<p>Each <code>NavigateEvent</code> has a <dfn
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</dfn>, a
<span>serialized state</span> or null. It is only used in some cases where the event's <code
data-x="dom-NavigateEvent-navigationType">navigationType</code> is "<code
data-x="dom-NavigationType-push">push</code>" or "<code
data-x="dom-NavigationType-replace">replace</code>", and is set appropriately when the event is
<span data-x="concept-event-fire">fired</span>.</p>
<p>The <dfn attribute for="NavigateEvent"><code
data-x="dom-NavigateEvent-navigationType">navigationType</code></dfn>, <dfn attribute
for="NavigateEvent"><code data-x="dom-NavigateEvent-destination">destination</code></dfn>, <dfn
attribute for="NavigateEvent"><code
data-x="dom-NavigateEvent-canIntercept">canIntercept</code></dfn>, <dfn attribute
for="NavigateEvent"><code data-x="dom-NavigateEvent-userInitiated">userInitiated</code></dfn>,
<dfn attribute for="NavigateEvent"><code
data-x="dom-NavigateEvent-hashChange">hashChange</code></dfn>, <dfn attribute
for="NavigateEvent"><code data-x="dom-NavigateEvent-signal">signal</code></dfn>, <dfn attribute
for="NavigateEvent"><code data-x="dom-NavigateEvent-formData">formData</code></dfn>, <dfn
attribute for="NavigateEvent"><code
data-x="dom-NavigateEvent-downloadRequest">downloadRequest</code></dfn>, <dfn attribute
for="NavigateEvent"><code data-x="dom-NavigateEvent-info">info</code></dfn>, <dfn attribute
for="NavigateEvent"><code
data-x="dom-NavigateEvent-hasUAVisualTransition">hasUAVisualTransition</code></dfn>, and
<dfn attribute for="NavigateEvent"><code
data-x="dom-NavigateEvent-sourceElement">sourceElement</code></dfn> attributes
must return the values they are initialized to.</p>
<p>The <dfn method for="NavigateEvent"><code
data-x="dom-NavigateEvent-intercept">intercept(<var>options</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p><span data-x="NavigateEvent-perform-shared-checks">Perform shared checks</span> given
<span>this</span>.</p></li>
<li><p>If <span>this</span>'s <code data-x="dom-NavigateEvent-canIntercept">canIntercept</code>
attribute was initialized to false, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>dispatch flag</span> is unset, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p><span>Assert</span>: <span>this</span>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is either "<code
data-x="">none</code>" or "<code data-x="">intercepted</code>".</p></li>
<li><p>Set <span>this</span>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> to "<code
data-x="">intercepted</code>".</p></li>
<li><p>If <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-handler">handler</code>"] <span data-x="map
exists">exists</span>, then <span data-x="list append">append</span> it to <span>this</span>'s
<span data-x="concept-NavigateEvent-navigation-handler-list">navigation handler
list</span>.</p></li>
<li>
<p>If <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-focusReset">focusReset</code>"] <span data-x="map
exists">exists</span>, then:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-NavigateEvent-focusReset">focus reset
behavior</span> is not null, and it is not equal to <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-focusReset">focusReset</code>"], then the user agent may
<span>report a warning to the console</span> indicating that the <code
data-x="dom-NavigationInterceptOptions-focusReset">focusReset</code> option for a previous call
to <code data-x="dom-NavigateEvent-intercept">intercept()</code> was overridden by this new
value, and the previous value will be ignored.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-NavigateEvent-focusReset">focus reset
behavior</span> to <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-focusReset">focusReset</code>"].</p></li>
</ol>
</li>
<li>
<p>If <var>options</var>["<code data-x="dom-NavigationInterceptOptions-scroll">scroll</code>"]
<span data-x="map exists">exists</span>, then:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-NavigateEvent-scroll">scroll
behavior</span> is not null, and it is not equal to <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-scroll">scroll</code>"], then the user agent may
<span>report a warning to the console</span> indicating that the <code
data-x="dom-NavigationInterceptOptions-scroll">scroll</code> option for a previous call to
<code data-x="dom-NavigateEvent-intercept">intercept()</code> was overridden by this new value,
and the previous value will be ignored.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-NavigateEvent-scroll">scroll
behavior</span> to <var>options</var>["<code
data-x="dom-NavigationInterceptOptions-scroll">scroll</code>"].</p></li>
</ol>
</li>
</ol>
<p>The <dfn method for="NavigateEvent"><code
data-x="dom-NavigateEvent-scroll">scroll()</code></dfn> method steps are:</p>
<ol>
<li><p><span data-x="NavigateEvent-perform-shared-checks">Perform shared checks</span> given
<span>this</span>.</p></li>
<li><p>If <span>this</span>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is not "<code
data-x="">committed</code>", then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span>Process scroll behavior</span> given <span>this</span>.</p></li>
</ol>
<p>To <dfn data-x="NavigateEvent-perform-shared-checks">perform shared checks</dfn> for a
<code>NavigateEvent</code> <var>event</var>:</p>
<ol>
<li><p>If <var>event</var>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not <span>fully
active</span>, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <var>event</var>'s <code data-x="dom-Event-isTrusted">isTrusted</code> attribute was
initialized to false, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <var>event</var>'s <span>canceled flag</span> is set, then throw an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</div>
<h6>The <code>NavigationDestination</code> interface</h6>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigationDestination</dfn> {
readonly attribute USVString <span data-x="dom-NavigationDestination-url">url</span>;
readonly attribute DOMString <span data-x="dom-NavigationDestination-key">key</span>;
readonly attribute DOMString <span data-x="dom-NavigationDestination-id">id</span>;
readonly attribute long long <span data-x="dom-NavigationDestination-index">index</span>;
readonly attribute boolean <span data-x="dom-NavigationDestination-sameDocument">sameDocument</span>;
any <span data-x="dom-NavigationDestination-getState">getState</span>();
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-url">url</span></code></dt>
<dd><p>The URL being navigated to.</p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-key">key</span></code></dt>
<dd><p>The value of the <code data-x="dom-NavigationHistoryEntry-key">key</code> property of the
destination <code>NavigationHistoryEntry</code>, if this is a "<code
data-x="dom-NavigationType-traverse">traverse</code>" navigation, or the empty string otherwise. </p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-id">id</span></code></dt>
<dd><p>The value of the <code data-x="dom-NavigationHistoryEntry-id">id</code> property of the
destination <code>NavigationHistoryEntry</code>, if this is a "<code
data-x="dom-NavigationType-traverse">traverse</code>" navigation, or the empty string otherwise. </p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-index">index</span></code></dt>
<dd><p>The value of the <code data-x="dom-NavigationHistoryEntry-index">index</code> property of
the destination <code>NavigationHistoryEntry</code>, if this is a "<code
data-x="dom-NavigationType-traverse">traverse</code>" navigation, or −1 otherwise.
</p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-sameDocument">sameDocument</span></code></dt>
<dd>
<p>Indicates whether or not this navigation is to the same <code>Document</code> as the current
one, or not. This will be true, for example, in the case of fragment navigations or <code
data-x="dom-history-pushState">history.pushState()</code> navigations.</p>
<p>Note that this property indicates the original nature of the navigation. If a cross-document
navigation is converted into a same-document navigation using <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code>, that will not change the
value of this property.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-NavigateEvent-destination">destination</span>.<span data-x="dom-NavigationDestination-getState">getState</span>()</code></dt>
<dd>
<p>For "<code data-x="dom-NavigationType-traverse">traverse</code>" navigations, returns the
<span data-x="StructuredDeserialize">deserialization</span> of the state stored in the
destination <span>session history entry</span>.</p>
<p>For "<code data-x="dom-NavigationType-push">push</code>" or "<code
data-x="dom-NavigationType-replace">replace</code>" navigations, returns the <span
data-x="StructuredDeserialize">deserialization</span> of the state passed to <code
data-x="dom-Navigation-navigate">navigation.navigate()</code>, if the navigation was initiated
by that method, or undefined it if it wasn't.</p>
<p>For "<code data-x="dom-NavigationType-reload">reload</code>" navigations, returns the <span
data-x="StructuredDeserialize">deserialization</span> of the state passed to <code
data-x="dom-Navigation-reload">navigation.reload()</code>, if the reload was initiated by that
method, or undefined it if it wasn't.</p>
</dd>
</dl>
<div w-nodev>
<p>Each <code>NavigationDestination</code> has a <dfn
data-x="concept-NavigationDestination-url">URL</dfn>, which is a <span>URL</span>.</p>
<p>Each <code>NavigationDestination</code> has an <dfn
data-x="concept-NavigationDestination-entry">entry</dfn>, which is a
<code>NavigationHistoryEntry</code> or null.</p>
<p class="note">It will be non-null if and only if the <code>NavigationDestination</code>
corresponds to a "<code data-x="dom-NavigationType-traverse">traverse</code>" navigation.</p>
<p>Each <code>NavigationDestination</code> has a <dfn
data-x="concept-NavigationDestination-state">state</dfn>, which is a <span>serialized
state</span>.</p>
<p>Each <code>NavigationDestination</code> has an <dfn
data-x="concept-NavigationDestination-sameDocument">is same document</dfn>, which is a
boolean.</p>
<hr>
<p>The <dfn attribute for="NavigationDestination"><code
data-x="dom-NavigationDestination-url">url</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-NavigationDestination-url">URL</span>, <span
data-x="concept-url-serializer">serialized</span>.</p>
<p>The <dfn attribute for="NavigationDestination"><code
data-x="dom-NavigationDestination-key">key</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-NavigationDestination-entry">entry</span> is
null, then return the empty string.</p></li>
<li><p>Return <span>this</span>'s <span
data-x="concept-NavigationDestination-entry">entry</span>'s <span
data-x="concept-NavigationHistoryEntry-key">key</span>.</p></li>
</ol>
<p>The <dfn attribute for="NavigationDestination"><code
data-x="dom-NavigationDestination-id">id</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-NavigationDestination-entry">entry</span> is
null, then return the empty string.</p></li>
<li><p>Return <span>this</span>'s <span
data-x="concept-NavigationDestination-entry">entry</span>'s <span
data-x="concept-NavigationHistoryEntry-id">ID</span>.</p></li>
</ol>
<p>The <dfn attribute for="NavigationDestination"><code
data-x="dom-NavigationDestination-index">index</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-NavigationDestination-entry">entry</span> is
null, then return −1.</p></li>
<li><p>Return <span>this</span>'s <span
data-x="concept-NavigationDestination-entry">entry</span>'s <span
data-x="concept-NavigationHistoryEntry-index">index</span>.</p></li>
</ol>
<p>The <dfn attribute for="NavigationDestination"><code
data-x="dom-NavigationDestination-sameDocument">sameDocument</code></dfn> getter steps are to
return <span>this</span>'s <span data-x="concept-NavigationDestination-sameDocument">is same
document</span>.</p>
<p>The <dfn method for="NavigationDestination"><code
data-x="dom-NavigationDestination-getState">getState()</code></dfn> method steps are to return
<span>StructuredDeserialize</span>(<span>this</span>'s <span
data-x="concept-NavigationDestination-state">state</span>).</p>
<h6 id="navigate-event-firing">Firing the event</h6>
<p>Other parts of the standard fire the <code data-x="event-navigate">navigate</code> event,
through a series of wrapper algorithms given in this section.</p>
<p>To <dfn>fire a traverse <code data-x="event-navigate">navigate</code> event</dfn> at a
<code>Navigation</code> <var>navigation</var> given a <span>session history entry</span> <dfn
data-x="fire-navigate-traverse-destinationSHE"><var>destinationSHE</var></dfn> and an optional
<span>user navigation involvement</span> <dfn
data-x="fire-navigate-traverse-userInvolvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"):</p>
<ol>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> given
<code>NavigateEvent</code>, in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</span> to
null.</p></li>
<li><p>Let <var>destination</var> be a <span>new</span> <code>NavigationDestination</code>
created in <var>navigation</var>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-url">URL</span>
to <var>destinationSHE</var>'s <span data-x="she-url">URL</span>.</p></li>
<li><p>Let <var>destinationNHE</var> be the <code>NavigationHistoryEntry</code> in
<var>navigation</var>'s <span data-x="navigation-entry-list">entry list</span> whose <span
data-x="nhe-she">session history entry</span> is <var>destinationSHE</var>, or null if no such
<code>NavigationHistoryEntry</code> exists.</p></li>
<li>
<p>If <var>destinationNHE</var> is non-null, then:</p>
<ol>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span> to
<var>destinationNHE</var>.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-state">state</span> to <var>destinationSHE</var>'s <span
data-x="she-navigation-api-state">navigation API state</span>.</p></li>
</ol>
</li>
<li>
<p>Otherwise,</p>
<ol>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span> to null.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-state">state</span> to
<span>StructuredSerializeForStorage</span>(null).</p></li>
</ol>
</li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-sameDocument">is
same document</span> to true if <var>destinationSHE</var>'s <span
data-x="she-document">document</span> is equal to <var>navigation</var>'s <span>relevant global
object</span>'s <span data-x="concept-document-window">associated <code>Document</code></span>;
otherwise false.</p></li>
<li><p>Return the result of performing the <span>inner <code
data-x="event-navigate">navigate</code> event firing algorithm</span> given
<var>navigation</var>, "<code data-x="dom-NavigationType-traverse">traverse</code>",
<var>event</var>, <var>destination</var>, <var>userInvolvement</var>, null, null, and
null.</p></li>
</ol>
<p>To <dfn>fire a push/replace/reload <code data-x="event-navigate">navigate</code> event</dfn> at
a <code>Navigation</code> <var>navigation</var> given a <code>NavigationType</code> <dfn
data-x="fire-navigate-prr-navigationType"><var>navigationType</var></dfn>, a <span>URL</span> <dfn
data-x="fire-navigate-prr-destinationURL"><var>destinationURL</var></dfn>, a boolean <dfn
data-x="fire-navigate-prr-isSameDocument"><var>isSameDocument</var></dfn>, an optional <span>user
navigation involvement</span> <dfn
data-x="fire-navigate-prr-userInvolvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"), an optional <code>Element</code>-or-null <dfn
data-x="fire-navigate-prr-sourceElement"><var>sourceElement</var></dfn> (default null), an
optional <span>entry list</span>-or-null <dfn
data-x="fire-navigate-prr-formDataEntryList"><var>formDataEntryList</var></dfn> (default null), an
optional <span>serialized state</span> <dfn
data-x="fire-navigate-prr-navigationAPIState"><var>navigationAPIState</var></dfn> (default
<span>StructuredSerializeForStorage</span>(null)), and an optional <span>serialized
state</span>-or-null <dfn
data-x="fire-navigate-prr-classicHistoryAPIState"><var>classicHistoryAPIState</var></dfn> (default
null):</p>
<ol>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> given
<code>NavigateEvent</code>, in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</span> to
<var>classicHistoryAPIState</var>.</p></li>
<li><p>Let <var>destination</var> be a <span>new</span> <code>NavigationDestination</code>
created in <var>navigation</var>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-url">URL</span>
to <var>destinationURL</var>.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span> to null.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-state">state</span> to
<var>navigationAPIState</var>.</p></li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-sameDocument">is
same document</span> to <var>isSameDocument</var>.</p></li>
<li><p>Return the result of performing the <span>inner <code
data-x="event-navigate">navigate</code> event firing algorithm</span> given
<var>navigation</var>, <var>navigationType</var>, <var>event</var>, <var>destination</var>,
<var>userInvolvement</var>, <var>sourceElement</var>, <var>formDataEntryList</var>, and
null.</p></li>
</ol>
<p>To <dfn>fire a download request <code data-x="event-navigate">navigate</code> event</dfn> at a
<code>Navigation</code> <var>navigation</var> given a <span>URL</span> <dfn
data-x="fire-navigate-download-destinationURL"><var>destinationURL</var></dfn>, a <span>user
navigation involvement</span> <dfn
data-x="fire-navigate-download-userInvolvement"><var>userInvolvement</var></dfn>, an
<code>Element</code>-or-null <dfn
data-x="fire-navigate-download-sourceElement"><var>sourceElement</var></dfn>, and a string
<dfn data-x="fire-navigate-download-filename"><var>filename</var></dfn>:</p>
<ol>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> given
<code>NavigateEvent</code>, in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</span> to
null.</p></li>
<li><p>Let <var>destination</var> be a <span>new</span> <code>NavigationDestination</code>
created in <var>navigation</var>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-url">URL</span>
to <var>destinationURL</var>.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span> to null.</p></li>
<li><p>Set <var>destination</var>'s <span
data-x="concept-NavigationDestination-state">state</span> to
<span>StructuredSerializeForStorage</span>(null).</p></li>
<li><p>Set <var>destination</var>'s <span data-x="concept-NavigationDestination-sameDocument">is
same document</span> to false.</p></li>
<li><p>Return the result of performing the <span>inner <code
data-x="event-navigate">navigate</code> event firing algorithm</span> given
<var>navigation</var>, "<code data-x="dom-NavigationType-push">push</code>", <var>event</var>,
<var>destination</var>, <var>userInvolvement</var>, <var>sourceElement</var>, null, and
<var>filename</var>.</p></li>
</ol>
<p>The <dfn>inner <code data-x="event-navigate">navigate</code> event firing algorithm</dfn>
consists of the following steps, given a <code>Navigation</code> <var>navigation</var>, a
<code>NavigationType</code> <var>navigationType</var>, a <code>NavigateEvent</code>
<var>event</var>, a <code>NavigationDestination</code> <var>destination</var>, a <span>user
navigation involvement</span> <var>userInvolvement</var>, an <code>Element</code>-or-null
<var>sourceElement</var>, an <span>entry list</span>-or-null <var>formDataEntryList</var>, and a
string-or-null <var>downloadRequestFilename</var>:</p>
<ol>
<li>
<p>If <var>navigation</var> <span>has entries and events disabled</span>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>ongoing API method tracker</span> is
null.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>upcoming non-traverse API method
tracker</span> is null.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>upcoming traverse API method
trackers</span> <span data-x="list is empty">is empty</span>.</p></li>
<li><p>Return true.</p></li>
</ol>
<p class="note">These assertions holds because <code
data-x="dom-Navigation-traverseTo">traverseTo()</code>, <code
data-x="dom-Navigation-back">back()</code>, and <code
data-x="dom-Navigation-forward">forward()</code> will immediately fail when entries and events
are disabled (since there are no entries to traverse to), and if our starting point is instead
<code data-x="dom-Navigation-navigate">navigate()</code> or <code
data-x="dom-Navigation-reload">reload()</code>, then we <a
href="#dont-always-set-upcoming-non-traverse-api-method-tracker">avoided</a> setting the
<span>upcoming non-traverse API method tracker</span> in the first place.</p>
</li>
<li><p>Let <var>destinationKey</var> be null.</p></li>
<li><p>If <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span> is non-null, then set
<var>destinationKey</var> to <var>destination</var>'s <span
data-x="concept-NavigationDestination-entry">entry</span>'s <span
data-x="concept-NavigationHistoryEntry-key">key</span>.</p></li>
<li><p><span>Assert</span>: <var>destinationKey</var> is not the empty string.</p></li>
<li><p><span>Promote an upcoming API method tracker to ongoing</span> given
<var>navigation</var> and <var>destinationKey</var>.</p></li>
<li><p>Let <var>apiMethodTracker</var> be <var>navigation</var>'s <span>ongoing API method
tracker</span>.</p></li>
<li><p>Let <var>navigable</var> be <var>navigation</var>'s <span>relevant global object</span>'s
<span data-x="window navigable">navigable</span>.</p></li>
<li><p>Let <var>document</var> be <var>navigation</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> <span>can have its URL rewritten</span> to <var>destination</var>'s
<span data-x="concept-NavigationDestination-url">URL</span>, and either <var>destination</var>'s
<span data-x="concept-NavigationDestination-sameDocument">is same document</span> is true or
<var>navigationType</var> is not "<code data-x="dom-NavigationType-traverse">traverse</code>",
then initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-canIntercept">canIntercept</code> to true. Otherwise, initialize it to
false.</p></li>
<li id="navigate-event-traverse-can-be-canceled">
<p>Let <var>traverseCanBeCanceled</var> be true if all of the following are true:</p>
<ul>
<li><p><var>navigable</var> is a <span>top-level traversable</span>;</p></li>
<li><p><var>destination</var>'s <span data-x="concept-NavigationDestination-sameDocument">is
same document</span> is true; and</p></li>
<li><p>either <var>userInvolvement</var> is not "<code data-x="uni-browser-ui">browser
UI</code>", or <var>navigation</var>'s <span>relevant global object</span> has
<span>history-action activation</span>.</p></li>
</ul>
<p>Otherwise, let it be false.</p>
</li>
<li>
<p>If either:</p>
<ul>
<li><p><var>navigationType</var> is not "<code
data-x="dom-NavigationType-traverse">traverse</code>"; or</p></li>
<li><p><var>traverseCanBeCanceled</var> is true,</p></li>
</ul>
<p>then initialize <var>event</var>'s <code data-x="dom-Event-cancelable">cancelable</code> to
true. Otherwise, initialize it to false.</p>
</li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-Event-type">type</code> to "<code
data-x="event-navigate">navigate</code>".</p></li>
<li><p>Initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-navigationType">navigationType</code> to
<var>navigationType</var>.</p></li>
<li><p>Initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-destination">destination</code> to <var>destination</var>.</p></li>
<li><p>Initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-downloadRequest">downloadRequest</code> to
<var>downloadRequestFilename</var>.</p></li>
<li>
<p>If <var>apiMethodTracker</var> is not null, then initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-info">info</code> to <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-info">info</span>. Otherwise, initialize it to
undefined.</p>
<p class="note">At this point <var>apiMethodTracker</var>'s <span
data-x="navigation-api-method-tracker-info">info</span> is no longer needed and can be nulled
out instead of keeping it alive for the lifetime of the <span>navigation API method
tracker</span>.</p>
</li>
<li><p>Initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-hasUAVisualTransition">hasUAVisualTransition</code> to true if a visual
transition, to display a cached rendered state of the <var>document</var>'s <span>latest
entry</span>, was done by the user agent. Otherwise, initialize it to false.</p></li>
<li><p>Initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-sourceElement">sourceElement</code> to
<var>sourceElement</var>.</p></li>
<li><p>Set <var>event</var>'s <span data-x="concept-NavigateEvent-abort-controller">abort
controller</span> to a <span>new</span> <code>AbortController</code> created in
<var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-NavigateEvent-signal">signal</code> to
<var>event</var>'s <span data-x="concept-NavigateEvent-abort-controller">abort
controller</span>'s <span data-x="concept-AbortController-signal">signal</span>.</p></li>
<li><p>Let <var>currentURL</var> be <var>document</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>event</var>'s <span
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</span> is
null;</p></li>
<li><p><var>destination</var>'s <span data-x="concept-NavigationDestination-sameDocument">is
same document</span> is true;</p></li>
<li><p><var>destination</var>'s <span data-x="concept-NavigationDestination-url">URL</span>
<span data-x="concept-url-equals">equals</span> <var>currentURL</var> with <span data-x="url
equals exclude fragments"><i>exclude fragments</i></span> set to true; and</p></li>
<li><p><var>destination</var>'s <span data-x="concept-NavigationDestination-url">URL</span>'s
<span data-x="concept-url-fragment">fragment</span> is not <span>identical to</span>
<var>currentURL</var>'s <span data-x="concept-url-fragment">fragment</span>,</p></li>
</ul>
<p>then initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-hashChange">hashChange</code> to true. Otherwise, initialize it to
false.</p>
<p class="note">The first condition here means that <code
data-x="dom-NavigateEvent-hashChange">hashChange</code> will be true for <span
data-x="navigate-fragid">fragment navigations</span>, but false for cases like <code
data-x="">history.pushState(undefined, "", "#fragment")</code>.</p>
</li>
<li><p>If <var>userInvolvement</var> is not "<code data-x="uni-none">none</code>", then
initialize <var>event</var>'s <code data-x="dom-NavigateEvent-userInitiated">userInitiated</code>
to true. Otherwise, initialize it to false.</p></li>
<li><p>If <var>formDataEntryList</var> is not null, then initialize <var>event</var>'s <code
data-x="dom-NavigateEvent-formData">formData</code> to a <span>new</span> <code>FormData</code>
created in <var>navigation</var>'s <span data-x="concept-relevant-realm">relevant realm</span>,
associated to <var>formDataEntryList</var>. Otherwise, initialize it to null.</p></li>
<li><p><span>Assert</span>: <var>navigation</var>'s <span>ongoing <code
data-x="event-navigate">navigate</code> event</span> is null.</p></li>
<li><p>Set <var>navigation</var>'s <span>ongoing <code data-x="event-navigate">navigate</code>
event</span> to <var>event</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span>focus changed during ongoing navigation</span> to
false.</p></li>
<li><p>Set <var>navigation</var>'s <span>suppress normal scroll restoration during ongoing
navigation</span> to false.</p></li>
<li><p>Let <var>dispatchResult</var> be the result of <span
data-x="concept-event-dispatch">dispatching</span> <var>event</var> at
<var>navigation</var>.</p></li>
<li>
<p>If <var>dispatchResult</var> is false:</p>
<ol>
<li><p>If <var>navigationType</var> is "<code
data-x="dom-NavigationType-traverse">traverse</code>", then <span>consume history-action user
activation</span> given <var>navigation</var>'s <span>relevant global object</span>.</p></li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-abort-controller">abort
controller</span>'s <span data-x="concept-AbortController-signal">signal</span> is not <span
data-x="AbortSignal-aborted">aborted</span>, then <span>abort the ongoing navigation</span>
given <var>navigation</var>.</p></li>
<li><p>Return false.</p></li>
</ol>
</li>
<li><p>Let <var>endResultIsSameDocument</var> be true if <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is not "<code
data-x="">none</code>" or <var>event</var>'s <code
data-x="dom-NavigateEvent-destination">destination</code>'s <span
data-x="concept-NavigationDestination-sameDocument">is same document</span> is true.</p></li>
<li>
<p><span>Prepare to run script</span> given <var>navigation</var>'s <span>relevant settings
object</span>.</p>
<div class="note" id="note-suppress-microtasks-during-navigation-events">
<p>This is done to avoid the <span>JavaScript execution context stack</span> becoming empty
right after any <code data-x="event-currententrychange">currententrychange</code> event
handlers run as a result of the <span>URL and history update steps</span> that could soon
happen. If the stack were to become empty at that time, then it would immediately <span>perform
a microtask checkpoint</span>, causing various promise fulfillment handlers to run interleaved
with the event handlers and before any handlers passed to <code
data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code>. This is undesirable
since it means promise handler ordering vs. <code
data-x="event-currententrychange">currententrychange</code> event handler ordering vs. <code
data-x="dom-NavigateEvent-intercept">intercept()</code> handler ordering would be dependent on
whether the navigation is happening with an empty <span>JavaScript execution context
stack</span> (e.g., because the navigation was user-initiated) or with a nonempty one (e.g.,
because the navigation was caused by a JavaScript API call).</p>
<p>By inserting an otherwise-unnecessary <span>JavaScript execution context</span> onto the
stack in this step, we essentially suppress the <span>perform a microtask checkpoint</span>
algorithm until later, thus ensuring that the sequence is always: <code
data-x="event-currententrychange">currententrychange</code> event handlers, then <code
data-x="dom-NavigateEvent-intercept">intercept()</code> handlers, then promise handlers.</p>
</div>
</li>
<li>
<p>If <var>event</var>'s <span data-x="concept-NavigateEvent-interception-state">interception
state</span> is not "<code data-x="">none</code>":</p>
<ol>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> to "<code
data-x="">committed</code>".</p></li>
<li><p>Let <var>fromNHE</var> be the <span data-x="navigation-current-entry">current
entry</span> of <var>navigation</var>.</p></li>
<li><p><span>Assert</span>: <var>fromNHE</var> is not null.</p></li>
<li><p>Set <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> to a <span>new</span>
<code>NavigationTransition</code> created in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>, whose <span
data-x="concept-NavigationTransition-navigationType">navigation type</span> is
<var>navigationType</var>, whose <span data-x="concept-NavigationTransition-from">from entry</span>
is <var>fromNHE</var>, and whose <span data-x="concept-NavigationTransition-finished">finished
promise</span> is a new promise created in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p><span>Mark as handled</span> <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span>'s <span
data-x="concept-NavigationTransition-finished">finished promise</span>.</p>
<p class="note">See the <a href="#note-mark-as-handled-navigation-api-finished">discussion
about other finished promises</a> to understand why this is done.</p>
</li>
<li>
<p>If <var>navigationType</var> is "<code
data-x="dom-NavigationType-traverse">traverse</code>", then set <var>navigation</var>'s
<span>suppress normal scroll restoration during ongoing navigation</span> to true.</p>
<p class="note">If <var>event</var>'s <span data-x="concept-NavigateEvent-scroll">scroll
behavior</span> was set to "<code
data-x="dom-NavigationScrollBehavior-after-transition">after-transition</code>", then scroll
restoration will happen as part of <span data-x="NavigateEvent-finish">finishing</span> the
relevant <code>NavigateEvent</code>. Otherwise, there will be no scroll restoration. That is,
no navigation which is intercepted by <code
data-x="dom-NavigateEvent-intercept">intercept()</code> goes through the normal scroll
restoration process; scroll restoration for such navigations is either done manually, by the
web developer, or is done after the transition.</p>
</li>
<li>
<p>If <var>navigationType</var> is "<code data-x="dom-NavigationType-push">push</code>" or
"<code data-x="dom-NavigationType-replace">replace</code>", then run the <span>URL and history
update steps</span> given <var>document</var> and <var>event</var>'s <code
data-x="dom-NavigateEvent-destination">destination</code>'s <span
data-x="dom-NavigationDestination-url">URL</span>, with <i
data-x="uhus-serializedData">serializedData</i> set to <var>event</var>'s <span
data-x="concept-NavigateEvent-classic-history-API-state">classic history API state</span> and
<i data-x="uhus-historyHandling">historyHandling</i> set to <var>navigationType</var>.</p>
<li>
<p>Otherwise, if <var>navigationType</var> is "<code
data-x="dom-NavigationType-reload">reload</code>", then
<span>update the navigation API entries for a same-document navigation</span> given
<var>navigation</var>, <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>, and "<code
data-x="dom-NavigationType-reload">reload</code>".</p>
<p class="note">If <var>navigationType</var> is "<code
data-x="dom-NavigationType-traverse">traverse</code>", then this event firing is happening as
part of <span data-x="apply the traverse history step">the traversal process</span>, and that
process will take care of performing the appropriate session history entry updates.</p>
</li>
</ol>
</li>
<li>
<p>If <var>endResultIsSameDocument</var> is true:</p>
<ol>
<li><p>Let <var>promisesList</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>handler</var> of <var>event</var>'s <span
data-x="concept-NavigateEvent-navigation-handler-list">navigation handler list</span>:</p>
<ol>
<li><p><span data-x="list append">Append</span> the result of <span
data-x="es-invoking-callback-functions">invoking</span> <var>handler</var> with an empty
arguments list to <var>promisesList</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>promisesList</var>'s <span data-x="list size">size</span> is 0, then set
<var>promisesList</var> to « <span>a promise resolved with</span> undefined ».</p>
<p class="note">There is a subtle timing difference between how <span data-x="wait for
all">waiting for all</span> schedules its success and failure steps when given zero promises
versus ≥1 promises. For most uses of <span data-x="wait for all">waiting for all</span>,
this does not matter. However, with this API, there are so many events and promise handlers
which could fire around the same time that the difference is pretty easily observable: it can
cause the event/promise handler sequence to vary. (Some of the events and promises involved
include: <code data-x="event-navigatesuccess">navigatesuccess</code> / <code
data-x="event-navigateerror">navigateerror</code>, <code
data-x="event-currententrychange">currententrychange</code>, <code
data-x="event-dispose">dispose</code>, <var>apiMethodTracker</var>'s promises, and the <code
data-x="dom-NavigationTransition-finished">navigation.transition.finished</code> promise.)
</li>
<li>
<p><span>Wait for all</span> of <var>promisesList</var>, with the following success steps:</p>
<ol>
<li><p>If <var>event</var>'s <span>relevant global object</span> is not <span>fully
active</span>, then abort these steps.</p></li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-abort-controller">abort
controller</span>'s <span data-x="concept-AbortController-signal">signal</span> is <span
data-x="AbortSignal-aborted">aborted</span>, then abort these steps.</p></li>
<li><p><span>Assert</span>: <var>event</var> equals <var>navigation</var>'s <span>ongoing
<code data-x="event-navigate">navigate</code> event</span>.</p></li>
<li><p>Set <var>navigation</var>'s <span>ongoing <code
data-x="event-navigate">navigate</code> event</span> to null.</p></li>
<li><p><span data-x="NavigateEvent-finish">Finish</span> <var>event</var> given
true.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-navigatesuccess">navigatesuccess</code> at <var>navigation</var>.</p></li>
<li><p>If <var>apiMethodTracker</var> is non-null, then <span>resolve the finished
promise</span> for <var>apiMethodTracker</var>.</p></li>
<li><p>If <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> is not null, then resolve
<var>navigation</var>'s <span data-x="concept-Navigation-transition">transition</span>'s
<span data-x="concept-NavigationTransition-finished">finished promise</span> with
undefined.</p></li>
<li><p>Set <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> to null.</p></li>
</ol>
<p>and the following failure steps given reason <var>rejectionReason</var>:</p>
<ol>
<li><p>If <var>event</var>'s <span>relevant global object</span> is not <span>fully
active</span>, then abort these steps.</p></li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-abort-controller">abort
controller</span>'s <span data-x="concept-AbortController-signal">signal</span> is <span
data-x="AbortSignal-aborted">aborted</span>, then abort these steps.</p></li>
<li><p><span>Assert</span>: <var>event</var> equals <var>navigation</var>'s <span>ongoing
<code data-x="event-navigate">navigate</code> event</span>.</p></li>
<li><p>Set <var>navigation</var>'s <span>ongoing <code
data-x="event-navigate">navigate</code> event</span> to null.</p></li>
<li><p><span data-x="NavigateEvent-finish">Finish</span> <var>event</var> given
false.</p></li>
<li><p>Let <var>errorInfo</var> be the result of <span data-x="extract-error">extracting error
information</span> from <var>rejectionReason</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-navigateerror">navigateerror</code> at <var>navigation</var> using
<code>ErrorEvent</code>, with additional attributes initialized according to
<var>errorInfo</var>.</p></li>
<li><p>If <var>apiMethodTracker</var> is non-null, then <span>reject the finished
promise</span> for <var>apiMethodTracker</var> with <var>rejectionReason</var>.</p></li>
<li><p>If <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> is not null, then reject
<var>navigation</var>'s <span data-x="concept-Navigation-transition">transition</span>'s
<span data-x="concept-NavigationTransition-finished">finished promise</span> with
<var>rejectionReason</var>.</p></li>
<li><p>Set <var>navigation</var>'s <span
data-x="concept-Navigation-transition">transition</span> to null.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Otherwise, if <var>apiMethodTracker</var> is non-null, then <span
data-x="navigation-api-method-tracker-clean-up">clean up</span>
<var>apiMethodTracker</var>.</p></li>
<li>
<p><span>Clean up after running script</span> given <var>navigation</var>'s <span>relevant
settings object</span>.</p>
<p class="note">Per the <a href="#note-suppress-microtasks-during-navigation-events">previous
note</a>, this stops suppressing any potential promise handler microtasks, causing them to run
at this point or later.</p>
</li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-interception-state">interception
state</span> is "<code data-x="">none</code>", then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<h6 id="navigate-event-scroll-focus">Scroll and focus behavior</h6>
<p>By calling <code data-x="dom-NavigateEvent-intercept">navigateEvent.intercept()</code>, web
developers can suppress the normal scroll and focus behavior for same-document navigations,
instead invoking cross-document navigation-like behavior at a later time. The algorithms in this
section are called at those appropriate later points.</p>
<p>To <dfn data-x="NavigateEvent-finish">finish</dfn> a <code>NavigateEvent</code>
<var>event</var>, given a boolean <var>didFulfill</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is not "<code
data-x="">intercepted</code>" or "<code data-x="">finished</code>".</p></li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-interception-state">interception
state</span> is "<code data-x="">none</code>", then return.</p></li>
<li><p><span>Potentially reset the focus</span> given <var>event</var>.</p></li>
<li><p>If <var>didFulfill</var> is true, then <span>potentially process scroll behavior</span>
given <var>event</var>.</p></li>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> to "<code
data-x="">finished</code>".</p></li>
</ol>
<p>To <dfn>potentially reset the focus</dfn> given a <code>NavigateEvent</code>
<var>event</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is "<code
data-x="">committed</code>" or "<code data-x="">scrolled</code>".</p></li>
<li><p>Let <var>navigation</var> be <var>event</var>'s <span>relevant global object</span>'s
<span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>focusChanged</var> be <var>navigation</var>'s <span>focus changed during ongoing
navigation</span>.</p></li>
<li><p>Set <var>navigation</var>'s <span>focus changed during ongoing navigation</span> to
false.</p></li>
<li><p>If <var>focusChanged</var> is true, then return.</p></li>
<li>
<p>If <var>event</var>'s <span data-x="concept-NavigateEvent-focusReset">focus reset
behavior</span> is "<code data-x="dom-NavigationFocusReset-manual">manual</code>", then
return.</p>
<p class="note">If it was left as null, then we treat that as "<code
data-x="dom-NavigationFocusReset-after-transition">after-transition</code>", and continue
onward.</p>
</li>
<li><p>Let <var>document</var> be <var>event</var>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>focusTarget</var> be the <span>autofocus delegate</span> for
<var>document</var>.</p></li>
<li><p>If <var>focusTarget</var> is null, then set <var>focusTarget</var> to
<var>document</var>'s <span data-x="the body element">body element</span>.</p></li>
<li><p>If <var>focusTarget</var> is null, then set <var>focusTarget</var> to
<var>document</var>'s <span>document element</span>.</p></li>
<li><p>Run the <span>focusing steps</span> for <var>focusTarget</var>, with <var>document</var>'s
<span>viewport</span> as the <var>fallback target</var>.</p></li>
<li><p>Move the <span>sequential focus navigation starting point</span> to
<var>focusTarget</var>.</p></li>
</ol>
<p>To <dfn>potentially process scroll behavior</dfn> given a <code>NavigateEvent</code>
<var>event</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is "<code
data-x="">committed</code>" or "<code data-x="">scrolled</code>".</p></li>
<li><p>If <var>event</var>'s <span data-x="concept-NavigateEvent-interception-state">interception
state</span> is "<code data-x="">scrolled</code>", then return.</p></li>
<li>
<p>If <var>event</var>'s <span data-x="concept-NavigateEvent-scroll">scroll behavior</span> is
"<code data-x="dom-NavigationScrollBehavior-manual">manual</code>", then return.</p>
<p class="note">If it was left as null, then we treat that as "<code
data-x="dom-NavigationScrollBehavior-after-transition">after-transition</code>", and continue
onward.</p>
</li>
<li><p><span>Process scroll behavior</span> given <var>event</var>.</p>
</ol>
<p>To <dfn>process scroll behavior</dfn> given a <code>NavigateEvent</code> <var>event</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> is "<code
data-x="">committed</code>".</p></li>
<li><p>Set <var>event</var>'s <span
data-x="concept-NavigateEvent-interception-state">interception state</span> to "<code
data-x="">scrolled</code>".</p></li>
<li><p>If <var>event</var>'s <code
data-x="dom-NavigateEvent-navigationType">navigationType</code> was initialized to "<code
data-x="dom-NavigationType-traverse">traverse</code>" or "<code
data-x="dom-NavigationType-reload">reload</code>", then <span>restore scroll position data</span>
given <var>event</var>'s <span>relevant global object</span>'s <span data-x="window
navigable">navigable</span>'s <span data-x="nav-active-history-entry">active session history
entry</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>document</var> be <var>event</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var>'s <span>indicated part</span> is null, then <span>scroll to the
beginning of the document</span> given <var>document</var>. <ref>CSSOMVIEW</ref></p></li>
<li><p>Otherwise, <span>scroll to the fragment</span> given <var>document</var>.</p></li>
</ol>
</li>
</ol>
</div>
<h4 id="nav-traversal-event-interfaces">Event interfaces</h4>
<p class="note">The <code>NavigateEvent</code> interface has <a href="#the-navigate-event">its own
dedicated section</a>, due to its complexity.</p>
<h5>The <code>NavigationCurrentEntryChangeEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NavigationCurrentEntryChangeEvent</dfn> : <span>Event</span> {
constructor(DOMString type, <span>NavigationCurrentEntryChangeEventInit</span> eventInitDict);
readonly attribute <span>NavigationType</span>? <span data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</span>;
readonly attribute <span>NavigationHistoryEntry</span> <span data-x="dom-NavigationCurrentEntryChangeEvent-from">from</span>;
};
dictionary <dfn dictionary>NavigationCurrentEntryChangeEventInit</dfn> : <span>EventInit</span> {
<span>NavigationType</span>? <dfn dict-member for="NavigationCurrentEntryChangeEventInit" data-x="dom-NavigationCurrentEntryChangeEventInit-navigationType">navigationType</dfn> = null;
required <span>NavigationHistoryEntry</span> <dfn dict-member for="NavigationCurrentEntryChangeEventInit" data-x="dom-NavigationCurrentEntryChangeEventInit-from">from</dfn>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</span></code></dt>
<dd><p>Returns the type of navigation which caused the current entry to change, or null if the
change is due to <code
data-x="dom-Navigation-updateCurrentEntry">navigation.updateCurrentEntry()</code>.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-NavigationCurrentEntryChangeEvent-from">from</span></code></dt>
<dd>
<p>Returns the previous value of <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code>, before the current entry
changed.</p>
<p>If <code data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</code>
is null or "<code data-x="dom-NavigationType-reload">reload</code>", then this value will be the
same as <code data-x="dom-Navigation-currentEntry">navigation.currentEntry</code>. In that case,
the event signifies that the contents of the entry changed, even if we did not move to a new
entry or replace the current one.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="NavigationCurrentEntryChangeEvent"><code
data-x="dom-NavigationCurrentEntryChangeEvent-navigationType">navigationType</code></dfn> and <dfn
attribute for="NavigationCurrentEntryChangeEvent"><code
data-x="dom-NavigationCurrentEntryChangeEvent-from">from</code></dfn> attributes must return the
values they were initialized to.</p>
</div>
<h5>The <code>PopStateEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>PopStateEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>PopStateEventInit</span> eventInitDict = {});
readonly attribute any <span data-x="dom-PopStateEvent-state">state</span>;
readonly attribute boolean <span data-x="dom-PopStateEvent-hasUAVisualTransition">hasUAVisualTransition</span>;
};
dictionary <dfn dictionary>PopStateEventInit</dfn> : <span>EventInit</span> {
any <dfn dict-member for="PopStateEventInit" data-x="dom-PopStateEventInit-state">state</dfn> = null;
boolean <dfn dict-member for="PopStateEventInit" data-x="dom-PopStateEventInit-hasUAVisualTransition">hasUAVisualTransition</dfn> = false;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PopStateEvent-state">state</span></code></dt>
<dd><p>Returns a copy of the information that was provided to <code
data-x="dom-history-pushState">pushState()</code> or <code
data-x="dom-history-replaceState">replaceState()</code>.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PopStateEvent-hasUAVisualTransition">hasUAVisualTransition</span></code></dt>
<dd><p>Returns true if the user agent performed a visual transition for this navigation before
dispatching this event. If true, the best user experience will be given if the author
synchronously updates the DOM to the post-navigation state.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="PopStateEvent"><code
data-x="dom-PopStateEvent-state">state</code></dfn> attribute must return the value it was
initialized to. It represents the context information for the event, or null, if the state
represented is the initial state of the <code>Document</code>.</p>
<p>The <dfn attribute for="PopStateEvent"><code data-x="dom-PopStateEvent-hasUAVisualTransition">
hasUAVisualTransition</code></dfn> attribute must return the value it was initialized to.</p>
</div>
<h5>The <code>HashChangeEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HashChangeEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>HashChangeEventInit</span> eventInitDict = {});
readonly attribute USVString <span data-x="dom-HashChangeEvent-oldURL">oldURL</span>;
readonly attribute USVString <span data-x="dom-HashChangeEvent-newURL">newURL</span>;
};
dictionary <dfn dictionary>HashChangeEventInit</dfn> : <span>EventInit</span> {
USVString oldURL = "";
USVString newURL = "";
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-HashChangeEvent-oldURL">oldURL</span></code></dt>
<dd>
<p>Returns the <span>URL</span> of the <span>session history entry</span> that was previously
current.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-HashChangeEvent-newURL">newURL</span></code></dt>
<dd>
<p>Returns the <span>URL</span> of the <span>session history entry</span> that is now
current.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="HashChangeEvent"><code
data-x="dom-HashChangeEvent-oldURL">oldURL</code></dfn> attribute must return the value it was
initialized to. It represents context information for the event, specifically the URL of the
<span>session history entry</span> that was traversed from.</p>
<p>The <dfn attribute for="HashChangeEvent"><code
data-x="dom-HashChangeEvent-newURL">newURL</code></dfn> attribute must return the value it was
initialized to. It represents context information for the event, specifically the URL of the
<span>session history entry</span> that was traversed to.</p>
</div>
<h5>The <code>PageSwapEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>PageSwapEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>PageSwapEventInit</span> eventInitDict = {});
readonly attribute <code>NavigationActivation</code>? <span data-x="dom-PageSwapEvent-activation">activation</span>;
readonly attribute <code>ViewTransition</code>? <span data-x="dom-PageSwapEvent-viewTransition">viewTransition</span>;
};
dictionary <dfn dictionary>PageSwapEventInit</dfn> : <span>EventInit</span> {
<span>NavigationActivation</span>? <dfn dict-member for="PageSwapEventInit" data-x="dom-PageSwapEventInit-activation">activation</dfn> = null;
<code>ViewTransition</code>? <dfn dict-member for="PageSwapEventInit" data-x="dom-PageSwapEventInit-viewTransition">viewTransition</dfn> = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PageSwapEvent-activation">activation</span></code></dt>
<dd><p>A <code>NavigationActivation</code> object representing the destination and type of the
cross-document navigation. This would be null for cross-origin navigations.</p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-PageSwapEvent-activation">activation</span>.<span data-x="dom-NavigationActivation-entry">entry</span></code></dt>
<dd><p>A <code>NavigationHistoryEntry</code>, representing the <code>Document</code> that is
about to become active.</p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-PageSwapEvent-activation">activation</span>.<span data-x="dom-NavigationActivation-from">from</span></code></dt>
<dd><p>A <code>NavigationHistoryEntry</code>, equivalent to the value of the <code
data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> property at the moment the
event is fired.</p></dd>
<dt><code data-x=""><var>event</var>.<span data-x="dom-PageSwapEvent-activation">activation</span>.<span data-x="dom-NavigationActivation-navigationType">navigationType</span></code></dt>
<dd><p>One of "<code data-x="dom-NavigationType-push">push</code>", "<code
data-x="dom-NavigationType-replace">replace</code>", "<code
data-x="dom-NavigationType-reload">reload</code>", or "<code
data-x="dom-NavigationType-traverse">traverse</code>", indicating what type of navigation
that is about to result in a page swap.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PageSwapEvent-viewTransition">viewTransition</span></code></dt>
<dd>
<p>Returns the <code>ViewTransition</code> object that represents an outbound cross-document view
transition, if such transition is active when the event is fired. Otherwise, returns null.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="PageSwapEvent"><code
data-x="dom-PageSwapEvent-activation">activation</code></dfn> and <dfn attribute
for="PageSwapEvent"><code
data-x="dom-PageSwapEvent-viewTransition">viewTransition</code></dfn> attributes must return
the values they were initialized to.</p>
</div>
<h5>The <code>PageRevealEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>PageRevealEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>PageRevealEventInit</span> eventInitDict = {});
readonly attribute <code>ViewTransition</code>? <span data-x="dom-PageRevealEvent-viewTransition">viewTransition</span>;
};
dictionary <dfn dictionary>PageRevealEventInit</dfn> : <span>EventInit</span> {
<code>ViewTransition</code>? <dfn dict-member for="PageRevealEventInit" data-x="dom-PageRevealEventInit-viewTransition">viewTransition</dfn> = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PageRevealEvent-viewTransition">viewTransition</span></code></dt>
<dd>
<p>Returns the <code>ViewTransition</code> object that represents an inbound cross-document view
transition, if such transition is active when the event is fired. Otherwise, returns null.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="PageRevealEvent"><code
data-x="dom-PageRevealEvent-viewTransition">viewTransition</code></dfn> attribute must return the
value it was initialized to.</p>
</div>
<h5>The <code>PageTransitionEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>PageTransitionEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>PageTransitionEventInit</span> eventInitDict = {});
readonly attribute boolean <span data-x="dom-PageTransitionEvent-persisted">persisted</span>;
};
dictionary <dfn dictionary>PageTransitionEventInit</dfn> : <span>EventInit</span> {
boolean persisted = false;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-PageTransitionEvent-persisted">persisted</span></code></dt>
<dd>
<p>For the <code data-x="event-pageshow">pageshow</code> event, returns false if the page is
newly being loaded (and the <code data-x="event-load">load</code> event will fire). Otherwise,
returns true.</p>
<p>For the <code data-x="event-pagehide">pagehide</code> event, returns false if the page is
going away for the last time. Otherwise, returns true, meaning that the page might be reused if
the user navigates back to this page (if the <code>Document</code>'s <i
data-x="concept-document-salvageable">salvageable</i> state stays true). </p>
<p>Things that can cause the page to be unsalvageable include:</p>
<ul>
<li><p>The user agent decided to not keep the <code>Document</code> alive in a <span>session
history entry</span> after <span data-x="unload a document">unload</span></p></li>
<li><p>Having <code>iframe</code>s that are not <i
data-x="concept-document-salvageable">salvageable</i></p></li>
<li><p>Active <code>WebSocket</code> objects</p></li>
<li><p><span data-x="abort a document">Aborting a <code>Document</code></span></p></li>
</ul>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="PageTransitionEvent"><code
data-x="dom-PageTransitionEvent-persisted">persisted</code></dfn> attribute must return the value
it was initialized to. It represents the context information for the event.</p>
<p>To <dfn>fire a page transition event</dfn> named <var>eventName</var> at a <code>Window</code>
<var>window</var> with a boolean <var>persisted</var>, <span data-x="concept-event-fire">fire
an event</span> named <var>eventName</var> at <var>window</var>, using
<code>PageTransitionEvent</code>, with the <code
data-x="dom-PageTransitionEvent-persisted">persisted</code> attribute initialized to
<var>persisted</var>, the <code data-x="dom-Event-cancelable">cancelable</code> attribute
initialized to true, the <code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to
true, and <var>legacy target override flag</var> set.</p>
<p class="note">The values for <code data-x="dom-Event-cancelable">cancelable</code> and <code
data-x="dom-Event-bubbles">bubbles</code> don't make any sense, since canceling the event does
nothing and it's not possible to bubble past the <code>Window</code> object. They are set to true
for historical reasons.</p>
</div>
<h5>The <code>BeforeUnloadEvent</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>BeforeUnloadEvent</dfn> : <span>Event</span> {
attribute DOMString <span data-x="dom-BeforeUnloadEvent-returnValue">returnValue</span>;
};</code></pre>
<p class="note">There are no <code>BeforeUnloadEvent</code>-specific initialization methods.</p>
<p>The <code>BeforeUnloadEvent</code> interface is a legacy interface which allows <span>checking
if unloading is canceled</span> to be controlled not only by canceling the event, but by setting
the <code data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code> attribute to a value
besides the empty string. Authors should use the <code
data-x="dom-Event-preventDefault">preventDefault()</code> method, or other means of canceling
events, instead of using <code data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code>.</p>
<div w-nodev>
<p>The <dfn attribute for="BeforeUnloadEvent"><code
data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code></dfn> attribute controls the process
of <span>checking if unloading is canceled</span>. When the event is created, the
attribute must be set to the empty string. On getting, it must return the last value it was set
to. On setting, the attribute must be set to the new value.</p>
<p class="note">This attribute is a <code data-x="">DOMString</code> only for historical reasons.
Any value besides the empty string will be treated as a request to ask the user for
confirmation.</p>
</div>
<h4>The <code>NotRestoredReasons</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>NotRestoredReasonDetails</dfn> {
readonly attribute DOMString <span data-x="dom-not-restored-reason-details-reason">reason</span>;
[Default] object toJSON();
};
[Exposed=Window]
interface <dfn interface>NotRestoredReasons</dfn> {
readonly attribute USVString? <span data-x="dom-not-restored-reasons-src">src</span>;
readonly attribute DOMString? <span data-x="dom-not-restored-reasons-id">id</span>;
readonly attribute DOMString? <span data-x="dom-not-restored-reasons-name">name</span>;
readonly attribute USVString? <span data-x="dom-not-restored-reasons-url">url</span>;
readonly attribute FrozenArray<<span>NotRestoredReasonDetails</span>>? <span data-x="dom-not-restored-reasons-reasons">reasons</span>;
readonly attribute FrozenArray<<span>NotRestoredReasons</span>>? <span data-x="dom-not-restored-reasons-children">children</span>;
[Default] object toJSON();
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>notRestoredReasonDetails</var>.<span subdfn
data-x="dom-not-restored-reason-details-reason">reason</span></code></dt>
<dd><p>Returns a string that explains the reason that prevented the document from <a
href="#note-bfcache">being served from back/forward cache</a>. See the definition of <span
data-x="concept-document-bfcache-blocking-details">bfcache blocking details</span> for the
possible string values.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-src">src</span></code></dt>
<dd><p>Returns the <code data-x="attr-iframe-src">src</code> attribute of the document's <span>node
navigable</span>'s <span data-x="nav-container">container</span> if it is an <code>iframe</code>
element. This can be null if not set or if it is not an <code>iframe</code> element.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-id">id</span></code></dt>
<dd><p>Returns the <code data-x="attr-id">id</code> attribute of the document's <span>node
navigable</span>'s <span data-x="nav-container">container</span> if it is an <code>iframe</code>
element. This can be null if not set or if it is not an <code>iframe</code> element.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-name">name</span></code></dt>
<dd><p>Returns the <code data-x="attr-iframe-name">name</code> attribute of the document's
<span>node navigable</span>'s <span data-x="nav-container">container</span> if it is an
<code>iframe</code> element. This can be null if not set or if it is not an <code>iframe</code>
element.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-url">url</span></code></dt>
<dd><p>Returns the document's <span data-x="concept-document-url">URL</span>, or null if the
document is in a cross-origin <code>iframe</code>. This is reported in addition to <code
data-x="dom-not-restored-reasons-src">src</code> because it is possible <code>iframe</code>
navigated since the original <code data-x="attr-iframe-src">src</code> was set.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-reasons">reasons</span></code></dt>
<dd><p>Returns an array of <code>NotRestoredReasonDetails</code> for the document. This is null
if the document is in a cross-origin <code>iframe</code>.</p></dd>
<dt><code data-x=""><var>notRestoredReasons</var>.<span subdfn
data-x="dom-not-restored-reasons-children">children</span></code></dt>
<dd><p>Returns an array of <code>NotRestoredReasons</code> that are for the document’s
children. This is null if the document is in a cross-origin <code>iframe</code>.</p></dd>
</dl>
<p>A <code>NotRestoredReasonDetails</code> object has a <dfn
data-x="concept-not-restored-reason-details-backing-struct">backing struct</dfn>, a <span
data-x="nrr-details-struct">not restored reason details</span> or null, initially null.</p>
<p>The <dfn attribute for="NotRestoredReasonDetails"><code
data-x="dom-not-restored-reason-details-reason">reason</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reason-details-backing-struct">backing struct</span>'s <span
data-x="nrr-details-reason">reason</span>.</p>
<p>To <dfn>create a <code>NotRestoredReasonDetails</code> object</dfn> given a <span
data-x="nrr-details-struct">not restored reason details</span> <var>backingStruct</var> and a
<span>realm</span> <var>realm</var>:</p>
<ol>
<li><p>Let <var>notRestoredReasonDetails</var> be a new <code>NotRestoredReasonDetails</code>
object created in <var>realm</var>.</p></li>
<li><p>Set <var>notRestoredReasonDetails</var>'s <span
data-x="concept-not-restored-reason-details-backing-struct">backing struct</span> to
<var>backingStruct</var>.</p></li>
<li><p>Return <var>notRestoredReasonDetails</var>.</p></li>
</ol>
<p>A <dfn data-x="nrr-details-struct" export>not restored reason details</dfn> is a
<span>struct</span> with the following <span data-x="struct item">items</span>:</p>
<ul>
<li><p><dfn data-x="nrr-details-reason">reason</dfn>, a string, initially empty.</p></li>
</ul>
<p>The <span data-x="nrr-details-reason">reason</span> is a string that represents the reason that
prevented the page from being restored from <a href="#note-bfcache">back/forward cache</a>.
The string is one of the following:</p>
<dl>
<dt>"<dfn data-x="blocking-fetch"><code>fetch</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, a fetch initiated by this
<code>Document</code> was still ongoing and was canceled, so the page was not in a state that
could be stored in the <a href="#note-bfcache">back/forward cache</a>.</dd>
<dt>"<dfn data-x="blocking-navigation-failure"><code>navigation-failure</code></dfn>"</dt>
<dd>The original navigation that created this <code>Document</code> errored, so storing the
resulting error document in the <a href="#note-bfcache">back/forward cache</a> was
prevented.</dd>
<dt>"<dfn data-x="blocking-parser-aborted"><code>parser-aborted</code></dfn>"</dt>
<dd>The <code>Document</code> never finished its initial HTML parsing, so storing the unfinished
document in the <a href="#note-bfcache">back/forward cache</a> was prevented.</dd>
<dt>"<dfn data-x="blocking-websocket"><code>websocket</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, an open <code>WebSocket</code>
connection was shut down, so the page was not in a state that could be stored in the <a
href="#note-bfcache">back/forward cache</a>. <ref>WEBSOCKETS</ref></dd>
<dt>"<dfn data-x="blocking-weblock" export><code>lock</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, held <span>locks</span> and
<span>lock requests</span> were terminated, so the page was not in a state that could be stored
in the <a href="#note-bfcache">back/forward cache</a>. <ref>WEBLOCKS</ref></dd>
<dt>"<dfn data-x="blocking-masked" export><code>masked</code></dfn>"</dt>
<dd>This <code>Document</code> has children that are in a cross-origin <code>iframe</code>, and
they prevented <a href="#note-bfcache">back/forward cache</a>; or this <code>Document</code>
could not be <a href="#note-bfcache">back/forward cached</a> for user agent-specific reasons, and
the user agent has chosen not to use one of the more specific reasons from the list of <span
data-x="ua-specific-blocking-reasons">user-agent specific blocking reasons</span>.
</dl>
<p>In addition to the list above, a user agent might choose to expose a reason that prevented the
page from being restored from <a href="note-bfcache">back/forward cache</a> for <dfn
data-x="ua-specific-blocking-reasons">user-agent specific blocking reasons</dfn>. These are one of
the following strings:</p>
<dl>
<dt>"<dfn data-x="blocking-audio-capture" export><code>audio-capture</code></dfn>"</dt>
<dd>The <code>Document</code> requested audio capture permission by using <cite>Media Capture and
Streams</cite>'s <code>getUserMedia()</code> with audio. <ref>MEDIASTREAM</ref></dd>
<dt>"<dfn data-x="blocking-background-work" export><code>background-work</code></dfn>"</dt>
<dd>The <code>Document</code> requested background work by calling <code>SyncManager</code>'s
<code data-x="dom-SyncManager-register">register()</code> method,
<code>PeriodicSyncManager</code>'s <code
data-x="dom-PeriodicSyncManager-register">register()</code> method, or
<code>BackgroundFetchManager</code>'s <code
data-x="dom-BackgroundFetchManager-fetch">fetch()</code> method.</dd>
<dt>"<dfn data-x="blocking-broadcastchannel-message" export><code>broadcastchannel-message</code></dfn>"</dt>
<dd>While the page was stored in <a href="#note-bfcache">back/forward cache</a>, a
<code>BroadcastChannel</code> connection on the page received a message and <code
data-x="event-message">message</code> event was fired.</dd>
<dt>"<dfn data-x="blocking-idb-event" export><code>idbversionchangeevent</code></dfn>"</dt>
<dd>The <code>Document</code> had a pending <code>IDBVersionChangeEvent</code> while <span
data-x="unload a document">unloading</span>. <ref>INDEXEDDB</ref></dd>
<dt>"<dfn data-x="blocking-idledetector" export><code>idledetector</code></dfn>"</dt>
<dd>The <code>Document</code> had an active <code>IdleDetector</code> while <span data-x="unload
a document">unloading</span>.</dd>
<dt>"<dfn data-x="blocking-keyboard-lock" export><code>keyboardlock</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, keyboard lock was still active
because <code>Keyboard</code>'s <code data-x="dom-Keyboard-lock">lock()</code> method was
called.</dd>
<dt>"<dfn data-x="blocking-mediastream" export><code>mediastream</code></dfn>"</dt>
<dd>A <code>MediaStreamTrack</code> was in the <span>live state</span> upon <span data-x="unload
a document">unloading</span>. <ref>MEDIASTREAM</ref></dd>
<dt>"<dfn data-x="blocking-midi" export><code>midi</code></dfn>"</dt>
<dd>The <code>Document</code> requested a MIDI permission by calling <code
data-x="dom-Navigator-requestMIDIAccess">navigator.requestMIDIAccess()</code>.</dd>
<dt>"<dfn data-x="blocking-modals" export><code>modals</code></dfn>"</dt>
<dd><a href="#user-prompts">User prompts</a> were shown while <span data-x="unload a document">
unloading</span>.</dd>
<dt>"<dfn data-x="blocking-navigating" export><code>navigating</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, loading was still ongoing, and so
the <code>Document</code> was not in a state that could be stored in <a
href="#note-bfcache">back/forward cache</a>.</dd>
<dt>"<dfn data-x="blocking-navigation-canceled" export><code>navigation-canceled</code></dfn>"</dt>
<dd>The navigation request was canceled by calling <code
data-x="dom-window-stop">window.stop()</code> and the page was not in a state to be stored in <a
href="note-bfcache">back/forward cache</a>.</dd>
<dt>"<dfn data-x="blocking-non-trivial-bcg" export><code>non-trivial-browsing-context-group</code></dfn>"</dt>
<dd>The <span>browsing context group</span> of this <code>Document</code> had more than one
<span>top-level browsing context</span>.</dd>
<dt>"<dfn data-x="blocking-otp" export><code>otpcredential</code></dfn>"</dt>
<dd>The <code>Document</code> created an <code>OTPCredential</code>.</dd>
<dt>"<dfn data-x="blocking-outstanding-network-request" export><code>outstanding-network-request</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, the <code>Document</code> had
outstanding network requests and was not in a state that could be stored in <a
href="#note-bfcache">back/forward cache</a>.</dd>
<dt>"<dfn data-x="blocking-payment" export><code>paymentrequest</code></dfn>"</dt>
<dd>The <code>Document</code> had an active <code>PaymentRequest</code> while <span
data-x="unload a document">unloading</span>. <ref>PAYMENTREQUEST</ref></dd>
<dt>"<dfn data-x="blocking-picture-in-picture" export><code>pictureinpicturewindow</code></dfn>"</dt>
<dd>The <code>Document</code> had an active <code>PictureInPictureWindow</code> while <span
data-x="unload a document">unloading</span>. <ref>PICTUREINPICTURE</ref></dd>
<dt>"<dfn data-x="blocking-plugins" export><code>plugins</code></dfn>"</dt>
<dd>The <code>Document</code> contained <span data-x="plugin">plugins</span>.</dd>
<dt>"<dfn data-x="blocking-method-not-get" export><code>request-method-not-get</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP request whose <span
data-x="concept-request-method">method</span> was not `<code data-x="">GET</code>`.
<ref>FETCH</ref></dd>
<dt>"<dfn data-x="blocking-auth-required" export><code>response-auth-required</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP response that required HTTP
authentication.</dd>
<dt>"<dfn data-x="blocking-ccns" export><code>response-cache-control-no-store</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP response whose `<code
data-x="http-cache-control">Cache-Control</code>` header included the "<code
data-x="">no-store</code>" token. <ref>HTTP</ref></dd>
<dt>"<dfn data-x="blocking-ccnc" export><code>response-cache-control-no-cache</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP response whose `<code
data-x="http-cache-control">Cache-Control</code>` header included the "<code
data-x="">no-cache</code>" token. <ref>HTTP</ref></dd>
<dt>"<dfn data-x="blocking-keepalive" export><code>response-keep-alive</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP response that contained a `<code
data-x="">Keep-Alive</code>` header.</dd>
<dt>"<dfn data-x="blocking-not-http-https" export><code>response-scheme-not-http-or-https</code></dfn>"</dt>
<dd>The <code>Document</code> was created from a response whose <span
data-x="concept-response-url">URL</span>'s <span data-x="concept-url-scheme">scheme</span> was
not an <span>HTTP(S) scheme</span>. <ref>FETCH</ref></dd>
<dt>"<dfn data-x="blocking-response-not-ok" export><code>response-status-not-ok</code></dfn>"</dt>
<dd>The <code>Document</code> was created from an HTTP response whose <span
data-x="concept-response-status">status</span> was not an <span>ok status</span>.
<ref>FETCH</ref></dd>
<dt>"<dfn data-x="blocking-rtc" export><code>rtc</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, a <code>RTCPeerConnection</code> or
<code>RTCDataChannel</code> was shut down, so the page was not in a state that could be stored in
the <a href="#note-bfcache">back/forward cache</a>. <ref>WEBRTC</ref></dd>
<dt>"<dfn data-x="blocking-sensors" export><code>sensors</code></dfn>"</dt>
<dd>The <code>Document</code> <span data-x="request-sensor-access">requested sensor
access</span>.</dd>
<dt>"<dfn data-x="sw-added" export><code>serviceworker-added</code></dfn>"</dt>
<dd>The <code>Document</code>'s <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span> started to be
<span data-x="dfn-control">controlled</span> by a <code>ServiceWorker</code> while the page was
in <a href="#note-bfcache">back/forward cache</a>. <ref>SW</ref></dd>
<dt>"<dfn data-x="sw-claimed" export><code>serviceworker-claimed</code></dfn>"</dt>
<dd>The <code>Document</code>'s <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span>'s <span
data-x="concept-environment-active-service-worker">active service worker</span> was claimed while
the page was in <a href="#note-bfcache">back/forward cache</a>. <ref>SW</ref></dd>
<dt>"<dfn data-x="blocking-sw-message" export><code>serviceworker-postmessage</code></dfn>"</dt>
<dd>The <code>Document</code>'s <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span>'s <span
data-x="concept-environment-active-service-worker">active service worker</span> received a
message while the page was in <a href="#note-bfcache">back/forward cache</a>. <ref>SW</ref></dd>
<dt>"<dfn data-x="blocking-sw-activation" export><code>serviceworker-version-activated</code></dfn>"</dt>
<dd>The <code>Document</code>'s <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span>'s <span
data-x="concept-environment-active-service-worker">active service worker</span>'s version was
activated while the page was in <a href="#note-bfcache">back/forward cache</a>.
<ref>SW</ref></dd>
<dt>"<dfn data-x="blocking-sw-unregistered" export><code>serviceworker-unregistered</code></dfn>"</dt>
<dd>The <code>Document</code>'s <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span>'s <span
data-x="concept-environment-active-service-worker">active service worker</span>'s <span>service
worker registration</span> was <span data-x="service-worker-unregister">unregistered</span> while
the page was in <a href="#note-bfcache">back/forward cache</a>. <ref>SW</ref></dd>
<dt>"<dfn data-x="blocking-sharedworker" export><code>sharedworker</code></dfn>"</dt>
<dd>This <code>Document</code> was in the <span>owner set</span> of a
<code>SharedWorkerGlobalScope</code>.</dd>
<dt>"<dfn data-x="blocking-smartcard" export><code>smartcardconnection</code></dfn>"</dt>
<dd>The <code>Document</code> had an active <code>SmartCardConnection</code> while <span
data-x="unload a document">unloading</span>.</dd>
<dt>"<dfn data-x="blocking-speech-reco" export><code>speechrecognition</code></dfn>"</dt>
<dd>The <code>Document</code> had an active <code>SpeechRecognition</code> while <span
data-x="unload a document">unloading</span>.</dd>
<dt>"<dfn data-x="blocking-storage" export><code>storageaccess</code></dfn>"</dt>
<dd>The <code>Document</code> requested storage access permission by using the Storage Access
API.</dd>
<dt>"<dfn data-x="blocking-unload" export><code>unload-listener</code></dfn>"</dt>
<dd>The <code>Document</code> registered an <span>event listener</span> for the <code
data-x="event-unload">unload</code> event.</dd>
<dt>"<dfn data-x="blocking-video-capture" export><code>video-capture</code></dfn>"</dt>
<dd>The <code>Document</code> requested video capture permission by using <cite>Media Capture and
Streams</cite>'s <code>getUserMedia()</code> with video. <ref>MEDIASTREAM</ref></dd>
<dt>"<dfn data-x="blocking-webhid" export><code>webhid</code></dfn>"</dt>
<dd>The <code>Document</code> called the WebHID API's <code
data-x="request-device">requestDevice()</code> method.</dd>
<dt>"<dfn data-x="blocking-webshare" export><code>webshare</code></dfn>"</dt>
<dd>The <code>Document</code> used the Web Share API's <code
data-x="dom-Navigator-share">navigator.share()</code> method.</dd>
<dt>"<dfn data-x="blocking-webtransport" export><code>webtransport</code></dfn>"</dt>
<dd>While <span data-x="unload a document">unloading</span>, an open <code>WebTransport</code>
connection was shut down, so the page was not in a state that could be stored in the <a
href="#note-bfcache">back/forward cache</a>. <ref>WEBTRANSPORT</ref></dd>
<dt>"<dfn data-x="blocking-webxr" export><code>webxrdevice</code></dfn>"</dt>
<dd>The <code>Document</code> created a <code>XRSystem</code>.</dd>
</dl>
<hr>
<p>A <code>NotRestoredReasons</code> object has a <dfn
data-x="concept-not-restored-reasons-backing-struct">backing struct</dfn>,
a <span data-x="nrr-struct">not restored reasons</span> or null, initially null.</p>
<p>A <code>NotRestoredReasons</code> object has a <dfn
data-x="concept-not-restored-reasons-reasons">reasons array</dfn>, a
<code data-x="">FrozenArray<<code>NotRestoredReasonDetails</code>></code> or null,
initially null.</p>
<p>A <code>NotRestoredReasons</code> object has a <dfn
data-x="concept-not-restored-reasons-children">children array</dfn>, a
<code data-x="">FrozenArray<<span>NotRestoredReasons</span>></code> or null, initially
null.</p>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-src">src</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span>'s <span
data-x="nrr-src">src</span>.</p>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-id">id</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span>'s <span
data-x="nrr-id">id</span>.</p>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-name">name</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span>'s <span
data-x="nrr-name">name</span>.</p>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-url">url</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span>'s <span
data-x="nrr-url">URL</span> is null, then return null.</p></li>
<li><p>Return <span>this</span>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span>'s <span
data-x="nrr-url">URL</span>, <span data-x="concept-url-serializer">serialized</span>.</p></li>
</ol>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-reasons">reasons</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reasons-reasons">reasons array</span>.</p>
<p>The <dfn attribute for="NotRestoredReasons"><code
data-x="dom-not-restored-reasons-children">children</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-not-restored-reasons-children">children array</span>.</p>
<p>To <dfn export>create a <code>NotRestoredReasons</code> object</dfn> given a <span
data-x="nrr-struct">not restored reasons</span> <var>backingStruct</var> and a
<span>realm</span> <var>realm</var>:</p>
<ol>
<li><p>Let <var>notRestoredReasons</var> be a new <code>NotRestoredReasons</code> object created
in <var>realm</var>.</p></li>
<li><p>Set <var>notRestoredReasons</var>'s <span
data-x="concept-not-restored-reasons-backing-struct">backing struct</span> to
<var>backingStruct</var>.</p></li>
<li><p>If <var>backingStruct</var>'s <span data-x="nrr-reasons">reasons</span> is null, set
<var>notRestoredReasons</var>'s <span
data-x="concept-not-restored-reasons-reasons">reasons array</span> to null.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>reasonsArray</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>reason</var> of
<var>backingStruct</var>'s <span data-x="nrr-reasons">reasons</span>:</p>
<ol>
<li><p><span>Create a <code>NotRestoredReasonDetails</code> object</span> given
<var>reason</var> and <var>realm</var>, and <span data-x="list append">append</span>
it to <var>reasonsArray</var>.</p></li>
</ol>
</li>
<li><p>Set <var>notRestoredReasons</var>'s <span
data-x="concept-not-restored-reasons-reasons">reasons array</span> to the result of
<span>creating a frozen array</span> given <var>reasonsArray</var>.</p></li>
</ol>
</li>
<li><p>If <var>backingStruct</var>'s <span data-x="nrr-children">children</span> is null, set
<var>notRestoredReasons</var>'s <span
data-x="concept-not-restored-reasons-children">children array</span> to null.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>childrenArray</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>child</var> of
<var>backingStruct</var>'s <span data-x="nrr-children">children</span>:</p>
<ol>
<li><p><span>Create a <code>NotRestoredReasons</code> object</span> given <var>child</var>
and <var>realm</var> and <span data-x="list append">append</span> it to
<var>childrenArray</var>.</p></li>
</ol>
</li>
<li><p>Set <var>notRestoredReasons</var>'s <span
data-x="concept-not-restored-reasons-children">children array</span> to the result of
<span>creating a frozen array</span> given <var>childrenArray</var>.</p></li>
</ol>
</li>
<li><p>Return <var>notRestoredReasons</var>.</p></li>
</ol>
<p>A <dfn data-x="nrr-struct" export>not restored reasons</dfn> is a <span>struct</span> with
the following <span data-x="struct item">items</span>:</p>
<ul>
<li><p><dfn data-x="nrr-src">src</dfn>, a <span>scalar value string</span> or null, initially
null.</p></li>
<li><p><dfn data-x="nrr-id">id</dfn>, a string or null, initially null.</p></li>
<li><p><dfn data-x="nrr-name">name</dfn>, a string or null, initially null.</p></li>
<li><p><dfn data-x="nrr-url">url</dfn>, a <span>URL</span> or null, initially null.</p></li>
<li><p><dfn data-x="nrr-reasons">reasons</dfn>, null or a <span>list</span> of
<span data-x="nrr-details-struct">not restored reason details</span>, initially null.</p></li>
<li><p><dfn data-x="nrr-children">children</dfn>, null or a <span>list</span> of <span
data-x="nrr-struct">not restored reasons</span>, initially null.</p></li>
</ul>
<p>A <dfn data-x="concept-document-nrr" data-lt="not restored reasons" for="Document"
export><code>Document</code>'s not restored reasons</dfn> is its <span>node navigable</span>'s
<span data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-not-restored-reasons">not restored reasons</span>, if
<code>Document</code>'s <span>node navigable</span> is a <span>top-level traversable</span>;
otherwise null.</p>
<h3 split-filename="document-sequences">Infrastructure for sequences of documents</h3>
<p>This standard contains several related concepts for grouping sequences of documents. As a
brief, non-normative summary:</p>
<ul>
<li><p><span data-x="navigable">Navigables</span> are a user-facing representation of a sequence
of documents, i.e., they represent something that can be navigated between documents. Typical
examples are tabs or windows in a web browser, or <code>iframe</code>s<span w-nodev>, or
<code>frame</code>s in a <code>frameset</code></span>.</p></li>
<li><p><span data-x="traversable navigable">Traversable navigables</span> are a special type of
navigable which control the session history of themselves and of their descendant navigables.
That is, in addition to their own series of documents, they represent a tree of further series
of documents, plus the ability to linearly traverse back and forward through a flattened view of
this tree.</p></li>
<li><p><span data-x="browsing context">Browsing contexts</span> are a developer-facing
representation of a series of documents. They correspond 1:1 with <code>WindowProxy</code>
objects. Each navigable can present a series of browsing contexts, with <a
href="#browsing-context-group-switches-due-to-cross-origin-opener-policy">switches</a> between
those browsing contexts occuring under certain well-defined circumstances.</p></li>
</ul>
<p>Most of this standard works in the language of navigables, but certain APIs expose the
existence of browsing context switches, and so some parts of the standard need to work in terms
of browsing contexts.</p>
<h4>Navigables</h4>
<p>A <dfn export>navigable</dfn> presents a <code>Document</code> to the user via its <span
data-x="nav-active-history-entry">active session history entry</span>. Each navigable has:</p>
<ul>
<li><p>An <dfn data-x="nav-id">id</dfn>, a <span>new unique internal value</span>.</p></li>
<li><p id="parent-browsing-context">A <dfn data-x="nav-parent" export for=navigable>parent</dfn>,
a <span>navigable</span> or null.</p></li>
<li>
<p id="current-entry">A <dfn data-x="nav-current-history-entry">current session history
entry</dfn>, a <span>session history entry</span>.</p>
<p>This can only be modified within the <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span> of the
parent <span>traversable navigable</span>.</p>
</li>
<li>
<p>An <dfn data-x="nav-active-history-entry">active session history entry</dfn>, a
<span>session history entry</span>.</p>
<p>This can only be modified from the event loop of the <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document">document</span>.</p>
</li>
<li>
<p>An <dfn>is closing</dfn> boolean, initially false.</p>
<p class="note">This is only ever set to true for <span data-x="top-level
traversable">top-level traversable navigables</span>.</p>
</li>
<li>
<p>An <dfn id="delaying-load-events-mode">is delaying <code data-x="event-load">load</code>
events</dfn> boolean, initially false.</p>
<p class="note">This is only ever set to true in cases where the navigable's <span
data-x="nav-parent">parent</span> is non-null.</p>
</ul>
<p>The <span data-x="nav-current-history-entry">current session history entry</span> and the
<span data-x="nav-active-history-entry">active session history entry</span> are usually the same,
but they get out of sync when:</p>
<ul>
<li><p>Synchronous navigations are performed. This causes the <span
data-x="nav-active-history-entry">active session history entry</span> to temporarily step ahead
of the <span data-x="nav-current-history-entry">current session history entry</span>.</p></li>
<li><p>A non-displayable, non-error response is received when <span data-x="apply the history
step">applying the history step</span>. This updates the <span
data-x="nav-current-history-entry">current session history entry</span> but leaves the <span
data-x="nav-active-history-entry">active session history entry</span> as-is.</p></li>
</ul>
<hr>
<p>A <span>navigable</span>'s <dfn export for="navigable" data-x="nav-document">active
document</dfn> is its <span data-x="nav-active-history-entry">active session history
entry</span>'s <span data-x="she-document">document</span>.</p>
<p class="note">This can be safely read from within the <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span> of the
navigable's <span data-x="nav-top">top-level traversable</span>. Although a
<span>navigable</span>'s <span data-x="nav-active-history-entry">active history entry</span> can
change synchronously, the new entry will always have the same <code>Document</code>.</p>
<p>A <span>navigable</span>'s <dfn export for="navigable" data-x="nav-bc">active browsing
context</dfn> is its <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-bc">browsing context</span>. If this <span>navigable</span> is a
<span>traversable navigable</span>, then its <span data-x="nav-bc">active browsing context</span>
will be a <span>top-level browsing context</span>.</p>
<p>A <span>navigable</span>'s <dfn data-x="nav-wp">active <code>WindowProxy</code></dfn> is its
<span data-x="nav-bc">active browsing context</span>'s associated <code>WindowProxy</code>.</p>
<p>A <span>navigable</span>'s <dfn export for="navigable" data-x="nav-window">active window</dfn>
is its <span data-x="nav-wp">active <code>WindowProxy</code></span>'s <span
data-x="concept-windowproxy-window">[[Window]]</span>.</p>
<p class="note">This will always equal the navigable's <span data-x="nav-document">active
document</span>'s <span>relevant global object</span>; this is kept in sync by the <span>make
active</span> algorithm.</p>
<p id="browsing-context-name">A <span>navigable</span>'s <dfn data-x="nav-target">target
name</dfn> is its <span data-x="nav-active-history-entry">active session history entry</span>'s
<span data-x="she-document-state">document state</span>'s <span
data-x="document-state-nav-target-name">navigable target name</span>.</p>
<hr>
<p>To get the <dfn export>node navigable</dfn> of a <span>node</span> <var>node</var>, return the
<span>navigable</span> whose <span data-x="nav-document">active document</span> is
<var>node</var>'s <span>node document</span>, or null if there is no such
<span>navigable</span>.</p>
<hr>
<p>To <dfn>initialize the navigable</dfn> <span>navigable</span> <var>navigable</var>, given a
<span>document state</span> <var>documentState</var> and an optional
<span>navigable</span>-or-null <var>parent</var> (default null):</p>
<ol>
<li><p><span>Assert</span>: <var>documentState</var>'s <span
data-x="document-state-document">document</span> is non-null.</p></li>
<li>
<p>Let <var>entry</var> be a new <span>session history entry</span>, with</p>
<dl class="props">
<dt><span data-x="she-url">URL</span></dt>
<dd><var>documentState</var>'s <span data-x="document-state-document">document</span>'s <span
data-x="concept-document-url">URL</span></dd>
<dt><span data-x="she-document-state">document state</span></dt>
<dd><var>documentState</var></dd>
</dl>
<p class="note">The caller of this algorithm is responsible for initializing <var>entry</var>'s
<span data-x="she-step">step</span>; it will be left as "<code data-x="">pending</code>" until
that is complete.</p>
</li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-current-history-entry">current session
history entry</span> to <var>entry</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span> to <var>entry</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-parent">parent</span> to
<var>parent</var>.</p></li>
</ol>
<h5>Traversable navigables</h5>
<p>A <dfn export>traversable navigable</dfn> is a <span>navigable</span> that also controls which
<span>session history entry</span> should be the <span data-x="nav-current-history-entry">current
session history entry</span> and <span data-x="nav-active-history-entry">active session history
entry</span> for itself and its descendant <span data-x="navigable">navigables</span>.</p>
<p>In addition to the properties of a <span>navigable</span>, a <span>traversable
navigable</span> has:</p>
<ul>
<li><p>A <dfn export data-x="tn-current-session-history-step">current session history
step</dfn>, a number, initially 0.</p></li>
<li><p id="session-history"><dfn data-x="tn-session-history-entries">Session history
entries</dfn>, a <span>list</span> of <span data-x="session history entry">session history
entries</span>, initially a new <span>list</span>.</p></li>
<li><p>A <dfn data-x="tn-session-history-traversal-queue">session history traversal queue</dfn>,
a <span>session history traversal parallel queue</span>, the result of <span>starting a new
session history traversal parallel queue</span>.</p></li>
<li><p>A <dfn data-x="tn-running-nested-apply-history-step">running nested apply history
step</dfn> boolean, initially false.</p></li>
<li>
<p>A <dfn>system visibility state</dfn>, which is either "<code data-x="">hidden</code>" or
"<code data-x="">visible</code>".</p>
<p>See the <a href="#page-visibility">page visibility</a> section for the requirements on this
item.</p>
</li>
</ul>
<p>To get the <dfn data-x="nav-traversable" export for="navigable">traversable navigable</dfn> of
a <span>navigable</span> <var>inputNavigable</var>:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>inputNavigable</var>.</p></li>
<li><p>While <var>navigable</var> is not a <span>traversable navigable</span>, set
<var>navigable</var> to <var>navigable</var>'s <span data-x="nav-parent">parent</span>.</p></li>
<li><p>Return <var>navigable</var>.</p></li>
</ol>
<h5>Top-level traversables</h5>
<p>A <dfn export>top-level traversable</dfn> is a <span>traversable navigable</span> with a null
<span data-x="nav-parent">parent</span>.</p>
<p class="note">Currently, all <span data-x="traversable navigable">traversable navigables</span>
are <span data-x="top-level traversable">top-level traversables</span>. Future proposals envision
introducing non-top-level traversables.</p>
<p>A user agent holds a <dfn export for="user agent">top-level traversable set</dfn> (a
<span>set</span> of <span data-x="top-level traversable">top-level traversables</span>). These are
typically presented to the user in the form of browser windows or browser tabs.</p>
<p>To get the <dfn export for="navigable" data-x="nav-top">top-level traversable</dfn> of a
<span>navigable</span> <var>inputNavigable</var>:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>inputNavigable</var>.</p></li>
<li><p>While <var>navigable</var>'s <span data-x="nav-parent">parent</span> is not null, set
<var>navigable</var> to <var>navigable</var>'s <span data-x="nav-parent">parent</span>.</p></li>
<li><p>Return <var>navigable</var>.</p></li>
</ol>
<p>To <dfn data-x="creating a new top-level traversable">create a new top-level traversable</dfn>
given a <span>browsing context</span>-or-null <var>opener</var>, a string
<var>targetName</var>, and an optional <span>navigable</span>
<var>openerNavigableForWebDriver</var>:</p>
<ol>
<li><p>Let <var>document</var> be null.</p></li>
<li><p>If <var>opener</var> is null, then set <var>document</var> to the second return value of
<span>creating a new top-level browsing context and document</span>.</p></li>
<li><p>Otherwise, set <var>document</var> to the second return value of <span>creating a new
auxiliary browsing context and document</span> given <var>opener</var>.</p></li>
<li>
<p>Let <var>documentState</var> be a new <span>document state</span>, with</p>
<dl class="props">
<dt><span data-x="document-state-document">document</span></dt>
<dd><var>document</var></dd>
<dt><span data-x="document-state-initiator-origin">initiator origin</span></dt>
<dd>null if <var>opener</var> is null; otherwise, <var>document</var>'s <span
data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="document-state-origin">origin</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="document-state-nav-target-name">navigable target name</span></dt>
<dd><var>targetName</var></dd>
<dt><span data-x="document-state-about-base-url">about base URL</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-about-base-url">about base
URL</span></dd>
</dl>
</li>
<li><p>Let <var>traversable</var> be a new <span>traversable navigable</span>.</p></li>
<li><p><span>Initialize the navigable</span> <var>traversable</var> given
<var>documentState</var>.</p></li>
<li><p>Let <var>initialHistoryEntry</var> be <var>traversable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>Set <var>initialHistoryEntry</var>'s <span data-x="she-step">step</span> to 0.</p></li>
<li><p><span data-x="list append">Append</span> <var>initialHistoryEntry</var> to
<var>traversable</var>'s <span data-x="tn-session-history-entries">session history
entries</span>.</p></li>
<li id="copy-session-storage"><p>If <var>opener</var> is non-null, then <span>legacy-clone a
traversable storage shed</span> given <var>opener</var>'s <span data-x="bc-traversable">top-level
traversable</span> and <var>traversable</var>. <ref>STORAGE</ref></p></li>
<li><p><span data-x="list append">Append</span> <var>traversable</var> to the user agent's
<span>top-level traversable set</span>.</p></li>
<li><p>Invoke <span>WebDriver BiDi navigable created</span> with <var>traversable</var>
and <var>openerNavigableForWebDriver</var>.</p></li>
<li><p>Return <var>traversable</var>.</p></li>
</ol>
<p>To <dfn export>create a fresh top-level traversable</dfn> given a <span>URL</span>
<var>initialNavigationURL</var> and an optional <span>POST resource</span>-or-null
<var>initialNavigationPostResource</var> (default null):</p>
<ol>
<li><p>Let <var>traversable</var> be the result of <span>creating a new top-level
traversable</span> given null and the empty string.</p></li>
<li>
<p><span>Navigate</span> <var>traversable</var> to <var>initialNavigationURL</var> using
<var>traversable</var>'s <span data-x="nav-document">active document</span>, with <i
data-x="navigation-resource">documentResource</i> set to
<var>initialNavigationPostResource</var>.</p>
<p class="note">We treat these initial navigations as <var>traversable</var> navigating itself,
which will ensure all relevant security checks pass.</p>
</li>
<li><p>Return <var>traversable</var>.</p></li>
</ol>
<h5>Child navigables</h5>
<p id="browsing-context-container">Certain elements (for example, <code>iframe</code> elements)
can present a <span>navigable</span> to the user. These elements are called <dfn export
data-lt="navigable container" data-x="navigable container">navigable containers</dfn>.</p>
<p id="nested-browsing-context">Each <span>navigable container</span> has a <dfn export
for="navigable container">content navigable</dfn>, which is either a <span>navigable</span> or
null. It is initially null.</p>
<p id="bc-container">The <dfn export for="navigable" data-x="nav-container">container</dfn> of a
<span>navigable</span> <var>navigable</var> is the <span>navigable container</span> whose
<span>content navigable</span> is <var>navigable</var>, or null if there is no such element.</p>
<p id="bc-container-document">The <dfn export for="navigable"
data-x="nav-container-document">container document</dfn> of a <span>navigable</span>
<var>navigable</var> is the result of running these steps:</p>
<ol>
<li><p>If <var>navigable</var>'s <span data-x="nav-container">container</span> is null, then
return null.</p></li>
<li>
<p>Return <var>navigable</var>'s <span data-x="nav-container">container</span>'s <span>node
document</span>.</p>
<p class="note">This is equal to <var>navigable</var>'s <span
data-x="nav-container">container</span>'s <span>shadow-including root</span> as
<var>navigable</var>'s <span data-x="nav-container">container</span> has to be
<span>connected</span>.</p>
</li>
</ol>
<p>The <dfn data-x="doc-container-document">container document</dfn> of a <code>Document</code>
<var>document</var> is the result of running these steps:</p>
<ol>
<li><p>If <var>document</var>'s <span>node navigable</span> is null, then return null.</p></li>
<li><p>Return <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-container-document">container document</span>.</p></li>
</ol>
<p id="child-browsing-context">A <span>navigable</span> <var>navigable</var> is a <dfn
export>child navigable</dfn> of another navigable <var>potentialParent</var> when
<var>navigable</var>'s <span data-x="nav-parent">parent</span> is <var>potentialParent</var>. We
can also just say that a <span>navigable</span> "is a <span>child navigable</span>", which means
that its <span data-x="nav-parent">parent</span> is non-null.</p>
<p class="note">All <span data-x="child navigable">child navigables</span> are the <span>content
navigable</span> of their <span data-x="nav-container">container</span>.</p>
<p>The <dfn id="concept-bcc-content-document">content document</dfn> of a <span>navigable
container</span> <var>container</var> is the result of running these steps:</p>
<ol>
<li><p>If <var>container</var>'s <span>content navigable</span> is null, then return
null.</p></li>
<li><p>Let <var>document</var> be <var>container</var>'s <span>content navigable</span>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p>If <var>document</var>'s <span data-x="concept-document-origin">origin</span> and
<var>container</var>'s <span>node document</span>'s <span
data-x="concept-document-origin">origin</span> are not <span>same origin-domain</span>, then
return null.</p></li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p>The <dfn>content window</dfn> of a <span>navigable container</span> <var>container</var> is the
result of running these steps:</p>
<ol>
<li><p>If <var>container</var>'s <span>content navigable</span> is null, then return
null.</p></li>
<li><p>Return <var>container</var>'s <span>content navigable</span>'s <span
data-x="nav-wp">active <code>WindowProxy</code></span>'s object.</p></li>
</ol>
<hr>
<p id="creating-a-new-nested-browsing-context">To <dfn>create a new child navigable</dfn>, given
an element <var>element</var>:</p>
<ol>
<li><p>Let <var>parentNavigable</var> be <var>element</var>'s <span>node
navigable</span>.</p></li>
<li><p>Let <var>group</var> be <var>element</var>'s <span>node document</span>'s <span
data-x="concept-document-bc">browsing context</span>'s <span data-x="bc-tlbc">top-level browsing
context</span>'s <span data-x="tlbc group">group</span>.</p></li>
<li><p>Let <var>browsingContext</var> and <var>document</var> be the result of <span>creating a
new browsing context and document</span> given <var>element</var>'s <span>node document</span>,
<var>element</var>, and <var>group</var>.</p></li>
<li><p>Let <var>targetName</var> be null.</p></li>
<li><p>If <var>element</var> has a <code data-x="">name</code> content attribute, then set
<var>targetName</var> to the value of that attribute.</p></li>
<li>
<p>Let <var>documentState</var> be a new <span>document state</span>, with</p>
<dl class="props">
<dt><span data-x="document-state-document">document</span></dt>
<dd><var>document</var></dd>
<dt><span data-x="document-state-initiator-origin">initiator origin</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="document-state-origin">origin</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="document-state-nav-target-name">navigable target name</span></dt>
<dd><var>targetName</var></dd>
<dt><span data-x="document-state-about-base-url">about base URL</span></dt>
<dd><var>document</var>'s <span data-x="concept-document-about-base-url">about base
URL</span></dd>
</dl>
</li>
<li><p>Let <var>navigable</var> be a new <span>navigable</span>.</p></li>
<li><p><span>Initialize the navigable</span> <var>navigable</var> given <var>documentState</var>
and <var>parentNavigable</var>.</p></li>
<li><p>Set <var>element</var>'s <span>content navigable</span> to <var>navigable</var>.</p></li>
<li><p>Let <var>historyEntry</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>Let <var>traversable</var> be <var>parentNavigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session
history traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p>Let <var>parentDocState</var> be <var>parentNavigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>.</p></li>
<li><p>Let <var>parentNavigableEntries</var> be the result of <span>getting session history
entries</span> for <var>parentNavigable</var>.</p></li>
<li><p>Let <var>targetStepSHE</var> be the first <span>session history entry</span> in
<var>parentNavigableEntries</var> whose <span data-x="she-document-state">document
state</span> equals <var>parentDocState</var>.</p></li>
<li><p>Set <var>historyEntry</var>'s <span data-x="she-step">step</span> to
<var>targetStepSHE</var>'s <span data-x="she-step">step</span>.</p></li>
<li><p>Let <var>nestedHistory</var> be a new <span>nested history</span> whose <span
data-x="nested-history-id">id</span> is <var>navigable</var>'s <span data-x="nav-id">id</span>
and <span data-x="nested-history-entries">entries list</span> is « <var>historyEntry</var>
».</p></li>
<li><p><span data-x="list append">Append</span> <var>nestedHistory</var> to
<var>parentDocState</var>'s <span data-x="document-state-nested-histories">nested
histories</span>.</p></li>
<li><p><span>Update for navigable creation/destruction</span> given
<var>traversable</var>.</p></li>
</ol>
</li>
<li><p>Invoke <span>WebDriver BiDi navigable created</span> with <var>traversable</var>.</p></li>
</ol>
<h5>Jake diagrams</h5>
<p>A useful method for visualizing sequences of documents, and in particular <span
data-x="navigable">navigables</span> and their <span data-x="session history entry">session
history entries</span>, is the <dfn>Jake diagram</dfn>. A typical Jake diagram is the
following:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAxCnRvcAogIDAtMjogL3QtYSB8IGRvYzEKICAzOiAvdC1hI2ZvbyB8IGRvYzEKICA0OiAvdC1iCmZyYW1lc1swXQogIDA6IC9pLTAtYQogIDEtMzogL2ktMC1iCmZyYW1lc1sxXQogIDAtMTogL2ktMS1hCiAgMi0zOiAvaS0xLWIK -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step current">1</th><th class="step">2</th><th class="step">3</th><th class="step">4</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="3" class="doc-0 current next-is-same-doc">/t-a</td><td colspan="1" class="doc-0 prev-is-same-doc">/t-a#foo</td><td colspan="1" class="doc-1">/t-b</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-2">/i-0-a</td><td colspan="3" class="doc-3 current">/i-0-b</td></tr><tr><th><code data-x="">frames[1]</code></th><td colspan="2" class="doc-4 current">/i-1-a</td><td colspan="2" class="doc-5">/i-1-b</td></tr></tbody></table>
<p>Here, each numbered column denotes a possible value for the traversable's <span
data-x="tn-current-session-history-step">session history step</span>. Each labeled row depicts a
<span>navigable</span>, as it transitions between different URLs and documents. The first,
labeled <code data-x="">top</code>, being the <span>top-level traversable</span>, and the others
being <span data-x="child navigable">child navigables</span>. The documents are given by the
background color of each cell, with a new background color indicating a new document in that
<span>navigable</span>. The URLs are given by the text content of the cells; usually they are
given as <span data-x="relative URL">relative URLs</span> for brevity, unless a cross-origin case
is specifically under investigation. A given navigable might not exist at a given step, in which
case the corresponding cells are empty. The bold-italic step number depicts the <span
data-x="tn-current-session-history-step">current session history step</span> of the traversable,
and all cells with bold-italic URLs represent the <span
data-x="nav-current-history-entry">current session history entry</span> for that row's
navigable.</p>
<p>Thus, the above Jake diagram depicts the following sequence of events:</p>
<ol start="0">
<li><p>A <span>top-level traversable</span> is created, starting a the URL <code
data-x="">/t-a</code>, with two <span data-x="child navigable">child navigables</span>
starting at <code data-x="">/i-0-a</code> and <code data-x="">/i-1-a</code>
respectively.</p></li>
<li><p>The first child navigable is <span data-x="navigate">navigated</span> to another
document, with URL <code data-x="">/i-0-b</code>.</p></li>
<li><p>The second child navigable is <span data-x="navigate">navigated</span> to another
document, with URL <code data-x="">/i-1-b</code>.</p></li>
<li><p>The top-level traversable is <span data-x="navigate">navigated</span> to the
<em>same</em> document, updating its URL to <code data-x="">/t-a#foo</code>.</p></li>
<li><p>The top-level traversable is <span data-x="navigate">navigated</span> to another
document, with URL <code data-x="">/t-b</code>. (Notice how this document, of course, does not
carry over the old document's child navigables.)</p></li>
<li><p>The traversable was <span data-x="traverse the history by a delta">traversed by a
delta</span> of −3, back to step 1.</p></li>
</ol>
<p><span data-x="Jake diagram">Jake diagrams</span> are a powerful tool for visualizing the
interactions of multiple navigables, navigations, and traversals. They cannot capture every
possible interaction — for example, they only work with a single level of nesting —
but we will have ocassion to use them to illustrate several complex situations throughout this
standard.</p>
<p class="note"><span data-x="Jake diagram">Jake diagrams</span> are named after their creator,
the inimitable Jake Archibald.</p>
<h5>Related navigable collections</h5>
<p>It is often helpful in this standard's algorithms to look at collections of <span
data-x="navigable">navigables</span> starting at a given <code>Document</code>. This section
contains a curated set of algorithms for collecting those navigables.</p>
<p class="note">The return values of these algorithms are ordered so that parents appears before
their children. Callers rely on this ordering.</p>
<p class="note">Starting with a <code>Document</code>, rather than a <span>navigable</span>, is
generally better because it makes the caller cognizant of whether they are starting with a
<span>fully active</span> <code>Document</code> or not. Although non-<span>fully active</span>
<code>Document</code>s do have ancestor and descendant navigables, they often behave as if they
don't (e.g., in the <code data-x="dom-parent">window.parent</code> getter).</p>
<p>The <dfn export for="Document">ancestor navigables</dfn> of a <code>Document</code>
<var>document</var> are given by these steps:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-parent">parent</span>.</p></li>
<li><p>Let <var>ancestors</var> be an empty list.</p>
<li>
<p>While <var>navigable</var> is not null:</p>
<ol>
<li><p><span data-x="list prepend">Prepend</span> <var>navigable</var> to
<var>ancestors</var>.</p></li>
<li><p>Set <var>navigable</var> to <var>navigable</var>'s <span
data-x="nav-parent">parent</span>.</p></li>
</ol>
</li>
<li><p>Return <var>ancestors</var>.</p></li>
</ol>
<p>The <dfn export for="Document">inclusive ancestor navigables</dfn> of a <code>Document</code>
<var>document</var> are given by these steps:</p>
<ol>
<li><p>Let <var>navigables</var> be <var>document</var>'s <span>ancestor
navigables</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>document</var>'s <span>node
navigable</span> to <var>navigables</var>.</p></li>
<li><p>Return <var>navigables</var>.</p></li>
</ol>
<p id="list-of-the-descendant-browsing-contexts">The <dfn export for="Document">descendant
navigables</dfn> of a <code>Document</code> <var>document</var> are given by these steps:</p>
<ol>
<li><p>Let <var>navigables</var> be new <span>list</span>.</p></li>
<li><p>Let <var>navigableContainers</var> be a <span>list</span> of all <span
data-x="shadow-including descendant">shadow-including descendants</span> of <var>document</var>
that are <span data-x="navigable container">navigable containers</span>, in
<span>shadow-including tree order</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigableContainer</var> of
<var>navigableContainers</var>:</p>
<ol>
<li><p>If <var>navigableContainer</var>'s <span>content navigable</span> is null, then
continue.</p></li>
<li><p><span data-x="list extend">Extend</span> <var>navigables</var> with
<var>navigableContainer</var>'s <span>content navigable</span>'s <span
data-x="nav-document">active document</span>'s <span>inclusive descendant
navigables</span>.</p></li>
</ol>
</li>
<li><p>Return <var>navigables</var>.</p></li>
</ol>
<p>The <dfn export for="Document">inclusive descendant navigables</dfn> of a
<code>Document</code> <var>document</var> are given by these steps:</p>
<ol>
<li><p>Let <var>navigables</var> be « <var>document</var>'s <span>node navigable</span>
».</p></li>
<li><p><span data-x="list extend">Extend</span> <var>navigables</var> with <var>document</var>'s
<span>descendant navigables</span>.</p></li>
<li><p>Return <var>navigables</var>.</p></li>
</ol>
<p class="note">These descendant-collecting algorithms are described as looking at the DOM tree
of descendant <code>Document</code> objects. In reality, this is often not feasible since the DOM
tree can be in another process from the caller of the algorithm. Instead, implementations
generally replicate the appropriate trees across processes.</p>
<p id="document-tree-child-browsing-context">The <dfn>document-tree child navigables</dfn> of a
<code>Document</code> <var>document</var> are given by these steps:</p>
<ol>
<li><p>If <var>document</var>'s <span>node navigable</span> is null, then return the empty
list.</p></li>
<li><p>Let <var>navigables</var> be new <span>list</span>.</p></li>
<li><p>Let <var>navigableContainers</var> be a <span>list</span> of all <span
data-x="descendant">descendants</span> of <var>document</var> that are <span data-x="navigable
container">navigable containers</span>, in <span>tree order</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigableContainer</var> of
<var>navigableContainers</var>:</p>
<ol>
<li><p>If <var>navigableContainer</var>'s <span>content navigable</span> is null, then
<span>continue</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>navigableContainer</var>'s <span>content
navigable</span> to <var>navigables</var>.</p></li>
</ol>
</li>
<li><p>Return <var>navigables</var>.</p></li>
</ol>
<h5 id="garbage-collection-and-browsing-contexts">Navigable destruction</h5>
<p>To <dfn>destroy a child navigable</dfn> given a <span>navigable container</span>
<var>container</var>:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>container</var>'s <span>content
navigable</span>.</p></li>
<li><p>If <var>navigable</var> is null, then return.</p></li>
<li><p>Set <var>container</var>'s <span>content navigable</span> to null.</p></li>
<li><p><span>Inform the navigation API about child navigable destruction</span> given
<var>navigable</var>.</p></li>
<li><p><span>Destroy a document and its descendants</span> given <var>navigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p>Let <var>parentDocState</var> be <var>container</var>'s <span>node navigable</span>'s
<span data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>.</p></li>
<li><p><span data-x="list remove">Remove</span> the <span>nested history</span> from
<var>parentDocState</var>'s <span data-x="document-state-nested-histories">nested
histories</span> whose <span data-x="nested-history-id">id</span> equals
<var>navigable</var>'s <span data-x="nav-id">id</span>.</p></li>
<li><p>Let <var>traversable</var> be <var>container</var>'s <span>node navigable</span>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session
history traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p><span>Update for navigable creation/destruction</span> given
<var>traversable</var>.</p></li>
</ol>
</li>
<li><p>Invoke <span>WebDriver BiDi navigable destroyed</span> with <var>navigable</var>.</p></li>
</ol>
<p>To <dfn data-x="destroy a top-level traversable">destroy</dfn> a <span>top-level
traversable</span> <var>traversable</var>:</p>
<ol>
<li><p>Let <var>browsingContext</var> be <var>traversable</var>'s <span
data-x="nav-bc">active browsing context</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>historyEntry</var> in
<var>traversable</var>'s <span data-x="tn-session-history-entries">session history
entries</span> <span class="XXX" data-x="">in what order?</span>:</p>
<ol>
<li><p>Let <var>document</var> be <var>historyEntry</var>'s <span
data-x="she-document">document</span>.</p></li>
<li><p>If <var>document</var> is not null, then <span>destroy a document and its
descendants</span> given <var>document</var>.</p></li>
</ol>
</li>
<li><p><span data-x="bcg remove">Remove</span> <var>browsingContext</var>.</p></li>
<li><p>Remove <var>traversable</var> from the user interface (e.g., close or hide its tab in
a tabbed browser).</p></li>
<li><p><span data-x="list remove">Remove</span> <var>traversable</var> from the user agent's
<span>top-level traversable set</span>.</p></li>
<li><p>Invoke <span>WebDriver BiDi navigable destroyed</span> with <var>traversable</var>.</p></li>
</ol>
<p>User agents may <span>destroy a top-level traversable</span> at any time (typically, <a
href="#nav-traversal-ui">in response to user requests</a>).</p>
<p id="closing-browsing-contexts"><span id="close-a-browsing-context"></span>To <dfn export
id="close-a-top-level-traversable" for="top-level traversable" data-x="close a top-level
traversable">close</dfn> a <span>top-level traversable</span> <var>traversable</var>:</p>
<ol>
<li><p>If <var>traversable</var>'s <span>is closing</span> is true, then return.</p></li>
<li><p><span data-x="definitely close a top-level traversable">Definitely close</span>
<var>traversable</var>.</p></li>
</ol>
<p>To <dfn data-x="definitely close a top-level traversable">definitely close</dfn> a
<span>top-level traversable</span> <var>traversable</var>:</p>
<ol>
<li><p>Let <var>toUnload</var> be <var>traversable</var>'s <span data-x="nav-document">active
document</span>'s <span>inclusive descendant navigables</span>.</p></li>
<li><p>If the result of <span>checking if unloading is canceled</span> for <var>toUnload</var> is
true, then return.</p></li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session history
traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p>Let <var>afterAllUnloads</var> be an algorithm step which <span data-x="destroy a
top-level traversable">destroys</span> <var>traversable</var>.</p></li>
<li><p><span>Unload a document and its descendants</span> given <var>traversable</var>'s <span
data-x="nav-document">active document</span>, null, and <var>afterAllUnloads</var>.</p></li>
</ol>
</li>
</ol>
<p class="note">The <span data-x="close a top-level traversable">close</span> vs. <span
data-x="definitely close a top-level traversable">definitely close</span> separation allows other
specifications to call <span data-x="close a top-level traversable">close</span> and have it be a
no-op if the top-level traversable is already closing due to JavaScript code calling <code
data-x="dom-window-close">window.close()</code>.</p>
<h5><span id="browsing-context-names"></span>Navigable target names</h5>
<p><span data-x="navigable">Navigables</span> can be given <span data-x="nav-target">target
names</span>, which are strings allowing certain APIs (such as <code
data-x="dom-open">window.open()</code> or the <code>a</code> element's <code
data-x="attr-hyperlink-target">target</code> attribute) to target <span
data-x="navigate">navigations</span> at that navigable.</p>
<p id="valid-browsing-context-name">A <dfn>valid navigable target name</dfn> is any string with at
least one character that does not contain both an <span>ASCII tab or newline</span> and a U+003C
(<), and it does not start with a U+005F (_). (Names starting with a U+005F (_) are reserved
for special keywords.)</p>
<p id="valid-browsing-context-name-or-keyword">A <dfn>valid navigable target name or
keyword</dfn> is any string that is either a <span>valid navigable target name</span> or that is
an <span>ASCII case-insensitive</span> match for one of: <code data-x="">_blank</code>, <code
data-x="">_self</code>, <code data-x="">_parent</code>, or <code data-x="">_top</code>.</p>
<p>These values have different meanings based on whether the page is sandboxed or not, as
summarized in the following (non-normative) table. In this table, "current" means the
<span>navigable</span> that the link or script is in, "parent" means the <span
data-x="nav-parent">parent</span> of the <span>navigable</span> that the link or script is in,
"top" means the <span data-x="nav-top">top-level traversable</span> of the <span>navigable</span>
that the link or script is in, "new" means a new <span>traversable navigable</span> with a null
<span data-x="nav-parent">parent</span> (which may use an <span>auxiliary browsing
context</span>, subject to various user preferences and user agent policies), "none" means that
nothing will happen, and "maybe new" means the same as "new" if the "<code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code>" keyword is also specified on the
<code data-x="attr-iframe-sandbox">sandbox</code> attribute (or if the user overrode the
sandboxing), and the same as "none" otherwise.</p>
<table>
<thead>
<tr>
<th rowspan=2>Keyword
<th rowspan=2>Ordinary effect
<th colspan=2>Effect in an <code>iframe</code> with...
<tr> <!-- nothing -->
<th><code data-x="">sandbox=""</code>
<th><code data-x="">sandbox="allow-top-navigation"</code>
<tbody>
<tr>
<td>none specified, for links and form submissions <!-- same as empty string -->
<td>current
<td>current
<td>current
<tr>
<td>empty string
<td>current
<td>current
<td>current
<tr>
<td><code data-x="">_blank</code>
<td>new
<td>maybe new
<td>maybe new
<tr>
<td><code data-x="">_self</code>
<td>current
<td>current
<td>current
<tr>
<td><code data-x="">_parent</code> if there isn't a parent
<td>current
<td>current
<td>current
<tr>
<td><code data-x="">_parent</code> if parent is also top
<td>parent/top
<td>none
<td>parent/top
<tr>
<td><code data-x="">_parent</code> if there is one and it's not top
<td>parent
<td>none
<td>none
<tr>
<td><code data-x="">_top</code> if top is current
<td>current
<td>current
<td>current
<tr>
<td><code data-x="">_top</code> if top is not current
<td>top
<td>none
<td>top
<tr>
<td>name that doesn't exist
<td>new
<td>maybe new
<td>maybe new
<tr>
<td>name that exists and is a descendant
<td>specified descendant
<td>specified descendant
<td>specified descendant
<tr>
<td>name that exists and is current
<td>current
<td>current
<td>current
<tr>
<td>name that exists and is an ancestor that is top
<td>specified ancestor
<td>none
<td>specified ancestor/top
<tr>
<td>name that exists and is an ancestor that is not top
<td>specified ancestor
<td>none
<td>none
<tr>
<td>other name that exists with common top
<td>specified
<td>none
<td>none
<tr>
<td>name that exists with different top, if <span data-x="familiar with">familiar</span> and <span>one permitted sandboxed navigator</span>
<td>specified
<td>specified
<td>specified
<tr>
<td>name that exists with different top, if <span data-x="familiar with">familiar</span> but not <span>one permitted sandboxed navigator</span>
<td>specified
<td>none
<td>none
<tr>
<td>name that exists with different top, not <span data-x="familiar with">familiar</span>
<td>new
<td>maybe new
<td>maybe new
</table>
<p class="tablenote"><small>Most of the restrictions on sandboxed browsing contexts are applied by
other algorithms, e.g. the <span data-x="navigate">navigation</span> algorithm, not <span>the
rules for choosing a navigable</span> given below.</small></p>
<hr>
<p>To <dfn>find a navigable by target name</dfn> given a string <var>name</var> and a
<span>navigable</span> <var>currentNavigable</var>:</p>
<ol>
<li><p>Let <var>currentDocument</var> be <var>currentNavigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p>Let <var>sourceSnapshotParams</var> be the result of <span>snapshotting source snapshot
params</span> given <var>currentDocument</var>.</p></li>
<li>
<p>Let <var>subtreesToSearch</var> be an <span>implementation-defined</span> choice of one of
the following:</p>
<ul>
<li><p>« <var>currentNavigable</var>'s <span data-x="nav-traversable">traversable
navigable</span>, <var>currentNavigable</var> »</p></li>
<li><p>the <span>inclusive ancestor navigables</span> of <var>currentDocument</var></p></li>
</ul>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/10848">Issue #10848</a> tracks
settling on one of these two possibilities, to achieve interoperability.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>subtreeToSearch</var> of
<var>subtreesToSearch</var>, in reverse order:</p>
<ol>
<li><p>Let <var>documentToSearch</var> be <var>subtreeToSearch</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of the <span>inclusive
descendant navigables</span> of <var>documentToSearch</var>:</p>
<ol>
<li>
<p>If <var>currentNavigable</var> is not <span>allowed by sandboxing to navigate</span>
<var>navigable</var> given <var>sourceSnapshotParams</var>, then optionally
<span>continue</span>.</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/10849">Issue #10849</a> tracks
making this check required, to achieve interoperability.</p>
</li>
<li><p>If <var>navigable</var>'s <span data-x="nav-target">target name</span> is
<var>name</var>, then return <var>navigable</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>currentTopLevelBrowsingContext</var> be <var>currentNavigable</var>'s <span
data-x="nav-bc">active browsing context</span>'s <span data-x="bc-tlbc">top-level browsing
context</span>.</p></li>
<li><p>Let <var>group</var> be <var>currentTopLevelBrowsingContext</var>'s <span data-x="tlbc
group">group</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>topLevelBrowsingContext</var> of
<var>group</var>'s <span>browsing context set</span>, in an <span>implementation-defined</span>
order (the user agent should pick a consistent ordering, such as the most recently opened, most
recently focused, or more closely related):</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/10850">Issue #10850</a> tracks
picking a specific ordering, to achieve interoperability.</p>
<ol>
<li><p>If <var>currentTopLevelBrowsingContext</var> is <var>topLevelBrowsingContext</var>, then
<span>continue</span>.</p></li>
<li><p>Let <var>documentToSearch</var> be <var>topLevelBrowsingContext</var>'s <span>active
document</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of the <span>inclusive
descendant navigables</span> of <var>documentToSearch</var>:</p>
<ol>
<li><p>If <var>currentNavigable</var>'s <span data-x="nav-bc">active browsing context</span>
is not <span>familiar with</span> <var>navigable</var>'s <span data-x="nav-bc">active
browsing context</span>, then <span>continue</span>.</p></li>
<li>
<p>If <var>currentNavigable</var> is not <span>allowed by sandboxing to navigate</span>
<var>navigable</var> given <var>sourceSnapshotParams</var>, then optionally
<span>continue</span>.</p>
<p class="XXX"><a href="https://github.com/whatwg/html/issues/10849">Issue #10849</a> tracks
making this check required, to achieve interoperability.</p>
</li>
<li><p>If <var>navigable</var>'s <span data-x="nav-target">target name</span> is
<var>name</var>, then return <var>navigable</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return null.</p></li>
</ol>
<p id="the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name"><dfn>The rules
for choosing a navigable</dfn>, given a string <var>name</var>, a <span>navigable</span>
<var>currentNavigable</var>, and a boolean <var>noopener</var> are as follows:</p>
<ol>
<li><p>Let <var>chosen</var> be null.</p></li>
<li><p>Let <var>windowType</var> be "<code data-x="">existing or none</code>".</p></li>
<li><p>Let <var>sandboxingFlagSet</var> be <var>currentNavigable</var>'s <span
data-x="nav-document">active document</span>'s <span>active sandboxing flag set</span>.</p></li>
<li><p>If <var>name</var> is the empty string or an <span>ASCII case-insensitive</span> match
for "<code data-x="">_self</code>", then set <var>chosen</var> to
<var>currentNavigable</var>.</p></li>
<li><p>Otherwise, if <var>name</var> is an <span>ASCII case-insensitive</span> match for "<code
data-x="">_parent</code>", set <var>chosen</var> to <var>currentNavigable</var>'s <span
data-x="nav-parent">parent</span>, if any, and <var>currentNavigable</var> otherwise.</p></li>
<li><p>Otherwise, if <var>name</var> is an <span>ASCII case-insensitive</span> match for "<code
data-x="">_top</code>", set <var>chosen</var> to <var>currentNavigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li><p>Otherwise, if <var>name</var> is not an <span>ASCII case-insensitive</span> match for
"<code data-x="">_blank</code>", and there exists a <span>navigable</span> that is the result of
<span data-x="find a navigable by target name">finding a navigable by target name</span> given
<var>name</var> and <var>currentNavigable</var>, set <var>chosen</var> to that
navigable.</p></li>
<li>
<p>Otherwise, a new <span>top-level traversable</span> is being requested, and what happens
depends on the user agent's configuration and abilities — it is determined by the rules
given for the first applicable option from the following list:</p>
<dl class="switch">
<dt id="popup-blocker">If <var>currentNavigable</var>'s <span data-x="nav-window">active
window</span> does not have <span>transient activation</span> and the user agent has been
configured to not show popups (i.e., the user agent has a "popup blocker" enabled)</dt>
<dd><p>The user agent may inform the user that a popup has been blocked.</p></dd>
<dt id="sandboxWindowOpen">If <var>sandboxingFlagSet</var> has the <span>sandboxed auxiliary
navigation browsing context flag</span> set</dt>
<dd><p>The user agent may report to a developer console that a popup has been blocked.</p></dd>
<dt>If the user agent has been configured such that in this instance it will create a new <span>top-level traversable</span></dt>
<dd>
<ol>
<li><p><span>Consume user activation</span> of <var>currentNavigable</var>'s <span
data-x="nav-window">active window</span>.</p></li>
<li><p>Set <var>windowType</var> to "<code data-x="">new and unrestricted</code>".</p></li>
<li><p>Let <var>currentDocument</var> be <var>currentNavigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li>
<p>If <var>currentDocument</var>'s <span data-x="concept-document-coop">opener
policy</span>'s <span data-x="coop-struct-value">value</span> is "<code
data-x="coop-same-origin">same-origin</code>" or "<code
data-x="coop-same-origin-plus-coep">same-origin-plus-COEP</code>", and
<var>currentDocument</var>'s <span data-x="concept-document-origin">origin</span> is not
<span>same origin</span> with <var>currentDocument</var>'s <span>relevant settings
object</span>'s <span>top-level origin</span>, then:</p>
<ol>
<li><p>Set <var>noopener</var> to true.</p></li>
<li><p>Set <var>name</var> to "<code data-x="">_blank</code>".</p></li>
<li><p>Set <var>windowType</var> to "<code data-x="">new with no opener</code>".</p>
</ol>
<p class="note">In the presence of an <span>opener policy</span>, nested documents that are
cross-origin with their top-level browsing context's active document always set
<var>noopener</var> to true.</p>
</li>
<li><p>Let <var>chosen</var> be null.</p></li>
<li><p>Let <var>targetName</var> be the empty string.</p></li>
<li><p>If <var>name</var> is not an <span>ASCII case-insensitive</span> match for "<code
data-x="">_blank</code>", then set <var>targetName</var> to <var>name</var>.</p></li>
<li id="noopener"><p>If <var>noopener</var> is true, then set <var>chosen</var> to the
result of <span>creating a new top-level traversable</span> given null,
<var>targetName</var>, and <var>currentNavigable</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Set <var>chosen</var> to the result of <span>creating a new top-level
traversable</span> given <var>currentNavigable</var>'s <span data-x="nav-bc">active
browsing context</span>, <var>targetName</var>, and <var>currentNavigable</var>.</p></li>
<li><p>If <var>sandboxingFlagSet</var>'s <span>sandboxed navigation browsing context
flag</span> is set, then set <var>chosen</var>'s <span data-x="nav-bc">active browsing
context</span>'s <span>one permitted sandboxed navigator</span> to
<var>currentNavigable</var>'s <span data-x="nav-bc">active browsing
context</span>.</p></li>
</ol>
</li>
<li><p>If <var>sandboxingFlagSet</var>'s <span>sandbox propagates to auxiliary browsing
contexts flag</span> is set, then all the flags that are set in <var>sandboxingFlagSet</var>
must be set in <var>chosen</var>'s <span data-x="nav-bc">active browsing context</span>'s
<span>popup sandboxing flag set</span>.</p></li>
</ol>
<p class="note">If the newly created <span>navigable</span> <var>chosen</var> is immediately
<span data-x="navigate">navigated</span>, then the navigation will be done as a "<code
data-x="NavigationHistoryBehavior-replace">replace</code>" navigation.</p>
</dd>
<dt>If the user agent has been configured such that in this instance it will choose <var>currentNavigable</var></dt>
<dd><p>Set <var>chosen</var> to <var>currentNavigable</var>.</p></dd>
<dt>If the user agent has been configured such that in this instance it will not find a navigable</dt>
<dd><p>Do nothing.</p></dd>
</dl>
<p class="note">User agents are encouraged to provide a way for users to configure the user
agent to always choose <var>currentNavigable</var>.</p>
</li>
<li><p>Return <var>chosen</var> and <var>windowType</var>.</p></li>
</ol>
<h4 id="windows">Browsing contexts</h4>
<p>A <dfn export>browsing context</dfn> is a programmatic representation of a series of documents,
multiple of which can live within a single <span>navigable</span>. Each <span>browsing
context</span> has a corresponding <code>WindowProxy</code> object, as well as the following:</p>
<ul>
<li><p>An <dfn export>opener browsing context</dfn>, a <span>browsing context</span> or null,
initially null.</p></li>
<li><p>An <dfn data-x="opener-origin-at-creation">opener origin at creation</dfn>, an
<span>origin</span> or null, initially null.</p>
<li>
<p>An <dfn>is popup</dfn> boolean, initially false.</p>
<p class="note">The only mandatory impact in this specification of <span>is popup</span> is on
the <code data-x="dom-BarProp-visible">visible</code> getter of the relevant
<code>BarProp</code> objects. However, user agents might also use it for <a
href="#nav-traversal-ui">user interface considerations</a>.</p>
</li>
<li><p>An <dfn>is auxiliary</dfn> boolean, initially false.</p></li>
<li><p>An <dfn data-x="browsing-context-initial-url">initial URL</dfn>, a <span>URL</span> or
null, initially null.</p></li>
<li><p>A <dfn data-x="virtual-browsing-context-group-id">virtual browsing context group ID</dfn>
integer, initially 0. This is used by <span data-x="coop-struct-report-only-value">opener policy
reporting</span>, to keep track of the browsing context group switches that would have happened
if the report-only policy had been enforced.</p></li>
</ul>
<p>A <span>browsing context</span>'s <dfn>active window</dfn> is its <code>WindowProxy</code>
object's <span data-x="concept-windowproxy-window">[[Window]]</span> internal slot value. A
<span>browsing context</span>'s <dfn>active document</dfn> is its <span>active window</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p>
<p>A <span>browsing context</span>'s <dfn export for="browsing context"
data-x="bc-traversable">top-level traversable</dfn> is its <span>active document</span>'s
<span>node navigable</span>'s <span data-x="nav-top">top-level traversable</span>.</p>
<p>A <span>browsing context</span> whose <span>is auxiliary</span> is true is known as an <dfn
export>auxiliary browsing context</dfn>. Auxiliary browsing contexts are always <span
data-x="top-level browsing context">top-level browsing contexts</span>.</p>
<p class="XXX">It's unclear whether a separate <span>is auxiliary</span> concept is necessary. In
<a href="https://github.com/whatwg/html/issues/5680">issue #5680</a>, it is indicated that we may
be able to simplify this by using whether or not the <span>opener browsing context</span> is
null.</p>
<p class="warning" id="warning-avoid-using-bcs">Modern specifications should avoid using the
<span>browsing context</span> concept in most cases, unless they are dealing with the subtleties
of <a href="#browsing-context-group-switches-due-to-cross-origin-opener-policy">browsing context
group switches</a> and <span data-x="agent cluster map">agent cluster allocation</span>. Instead,
the <code>Document</code> and <span>navigable</span> concepts are usually more appropriate.</p>
<hr>
<p>A <dfn data-x="concept-document-bc" data-lt="browsing context" for="Document"
export><code>Document</code>'s browsing context</dfn> is a <span>browsing context</span> or null,
initially null.</p>
<p class="note">A <code>Document</code> does not necessarily have a non-null <span
data-x="concept-document-bc">browsing context</span>. In particular, data mining tools are likely
to never instantiate browsing contexts. A <code>Document</code> created using an API such as <code
data-x="dom-DOMImplementation-createDocument">createDocument()</code> never has a non-null <span
data-x="concept-document-bc">browsing context</span>. And the <code>Document</code> originally
created for an <code>iframe</code> element, which has since been <span data-x="node is removed
from a document">removed from the document</span>, has no associated browsing context, since that
browsing context was <span data-x="destroy a document">nulled out</span>.</p>
<p class="note">In general, there is a 1-to-1 mapping from the <code>Window</code> object to the
<code>Document</code> object, as long as the <code>Document</code> object has a non-null <span
data-x="concept-document-bc">browsing context</span>. There is one exception. A
<code>Window</code> can be reused for the presentation of a second <code>Document</code> in the
same <span>browsing context</span>, such that the mapping is then 1-to-2. This occurs when a
<span>browsing context</span> is <span data-x="navigate">navigated</span> from the <span
data-x="is initial about:blank">initial <code>about:blank</code></span> <code>Document</code> to
another, which will be done with <span
data-x="NavigationHistoryBehavior-replace">replacement</span>.</p>
<h5>Creating browsing contexts</h5>
<p>To <dfn id="creating-a-new-browsing-context" data-x="creating a new browsing context and
document">create a new browsing context and document</dfn>, given null or a <code>Document</code>
object <var>creator</var>, null or an element <var>embedder</var>, and a <span>browsing context
group</span> <var>group</var>:</p>
<!-- Note: Do not append the new browsing context to group as we might be creating a nested
browsing context and not a top level browsing context -->
<ol>
<li><p>Let <var>browsingContext</var> be a new <span>browsing context</span>.</p></li>
<li><p>Let <var>unsafeContextCreationTime</var> be the
<span>unsafe shared current time</span>.</p></li>
<li><p>Let <var>creatorOrigin</var> be null.</p>
<li><p>Let <var>creatorBaseURL</var> be null.</p></li>
<li id="creator-browsing-context">
<p>If <var>creator</var> is non-null, then:</p>
<ol>
<li><p>Set <var>creatorOrigin</var> to <var>creator</var>'s <span
data-x="concept-document-origin">origin</span>.</p></li>
<li><p>Set <var>creatorBaseURL</var> to <var>creator</var>'s <span>document base
URL</span>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span> to
<var>creator</var>'s <span data-x="concept-document-bc">browsing context</span>'s <span
data-x="bc-tlbc">top-level browsing context</span>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span>.</p></li>
</ol>
</li>
<li><p>Let <var>sandboxFlags</var> be the result of <span>determining the creation sandboxing
flags</span> given <var>browsingContext</var> and <var>embedder</var>.</p></li>
<li id="about-blank-origin"><p>Let <var>origin</var> be the result of <span>determining the
origin</span> given <code>about:blank</code>, <var>sandboxFlags</var>, and
<var>creatorOrigin</var>.</p></li>
<li>
<p>Let <var>permissionsPolicy</var> be the result of <span>creating a permissions policy</span>
given <var>embedder</var> and <var>origin</var>. <ref>PERMISSIONSPOLICY</ref></p>
</li>
<li><p>Let <var>agent</var> be the result of <span
data-x="obtain-similar-origin-window-agent">obtaining a similar-origin window agent</span> given
<var>origin</var>, <var>group</var>, and false.</p></li>
<li>
<p>Let <var>realm execution context</var> be the result of <span>creating a new realm</span>
given <var>agent</var> and the following customizations:</p>
<ul>
<li><p>For the global object, create a new <code>Window</code> object.</p></li>
<li><p>For the global <b>this</b> binding, use <var>browsingContext</var>'s
<code>WindowProxy</code> object.</li>
</ul>
</li>
<li><p>Let <var>topLevelCreationURL</var> be <code>about:blank</code> if <var>embedder</var> is
null; otherwise <var>embedder</var>'s <span>relevant settings object</span>'s <span>top-level
creation URL</span>.</p></li>
<li><p>Let <var>topLevelOrigin</var> be <var>origin</var> if <var>embedder</var> is null;
otherwise <var>embedder</var>'s <span>relevant settings object</span>'s <span>top-level
origin</span>.</p></li>
<li><p><span>Set up a window environment settings object</span> with <code>about:blank</code>,
<var>realm execution context</var>, null, <var>topLevelCreationURL</var>, and
<var>topLevelOrigin</var>.</p></li>
<li><p>Let <var>loadTimingInfo</var> be a new <span>document load timing info</span> with
its <span>navigation start time</span> set to the result of calling <span>coarsen time</span>
with <var>unsafeContextCreationTime</var> and the new <span>environment settings object</span>'s
<span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p></li>
<li>
<p>Let <var>document</var> be a new <code>Document</code>, with:</p>
<dl class="props">
<dt><span data-x="concept-document-type">type</span></dt>
<dd>"<code data-x="">html</code>"</dd>
<dt><span data-x="concept-document-content-type">content type</span></dt>
<dd>"<code>text/html</code>"</dd>
<dt><span data-x="concept-document-mode">mode</span></dt>
<dd>"<code data-x="">quirks</code>"</dd>
<dt><span data-x="concept-document-origin">origin</span></dt>
<dd><var>origin</var></dd>
<dt><span data-x="concept-document-bc">browsing context</span></dt>
<dd><var>browsingContext</var>
<dt><span data-x="concept-document-permissions-policy">permissions policy</span></dt>
<dd><var>permissionsPolicy</var></dd>
<dt><span>active sandboxing flag set</span></dt>
<dd><var>sandboxFlags</var></dd>
<dt><span>load timing info</span></dt>
<dd><var>loadTimingInfo</var></dd>
<dt><span>is initial <code>about:blank</code></span></dt>
<dd>true</dd>
<dt><span data-x="concept-document-about-base-URL">about base URL</span></dt>
<dd><var>creatorBaseURL</var></dd>
<dt><span data-x="concept-document-allow-declarative-shadow-roots">allow declarative shadow
roots</span></dt>
<dd>true</dd>
</dl>
</li>
<li>
<p>If <var>creator</var> is non-null, then:</p>
<ol>
<li><p>Set <var>document</var>'s <span data-x="the document's referrer">referrer</span> to the
<span data-x="concept-url-serializer">serialization</span> of <var>creator</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-policy-container">policy
container</span> to a <span data-x="clone a policy container">clone</span> of
<var>creator</var>'s <span data-x="concept-document-policy-container">policy
container</span>.</p></li>
<li><p>If <var>creator</var>'s <span data-x="concept-document-origin">origin</span> is
<span>same origin</span> with <var>creator</var>'s <span>relevant settings object</span>'s
<span>top-level origin</span>, then set <var>document</var>'s <span
data-x="concept-document-coop">opener policy</span> to <var>creator</var>'s <span
data-x="concept-document-bc">browsing context</span>'s <span data-x="bc-tlbc">top-level
browsing context</span>'s <span>active document</span>'s <span
data-x="concept-document-coop">opener policy</span>.</p></li>
</ol>
</li>
<li><p><span>Assert</span>: <var>document</var>'s <span data-x="concept-document-url">URL</span>
and <var>document</var>'s <span>relevant settings object</span>'s <span
data-x="concept-environment-creation-url">creation URL</span> are
<code>about:blank</code>.</p></li>
<li><p>Mark <var>document</var> as <span>ready for post-load tasks</span>.</p></li>
<li><p><span>Populate with <code>html</code>/<code>head</code>/<code>body</code></span> given
<var>document</var>.</p></li>
<li><p><span>Make active</span> <var>document</var>.</p></li>
<li><p><span>Completely finish loading</span> <var>document</var>.</p></li>
<li><p>Return <var>browsingContext</var> and <var>document</var>.</p></li>
</ol>
<p>To <dfn id="creating-a-new-top-level-browsing-context" data-x="creating a new top-level
browsing context and document">create a new top-level browsing context and document</dfn>:</p>
<ol>
<li><p>Let <var>group</var> and <var>document</var> be the result of <span>creating a new
browsing context group and document</span>.</p></li>
<li><p>Return <var>group</var>'s <span>browsing context set</span>[0] and
<var>document</var>.</p></li>
</ol>
<p>To <dfn id="creating-a-new-auxiliary-browsing-context" data-x="creating a new auxiliary
browsing context and document">create a new auxiliary browsing context and document</dfn>, given
a <span>browsing context</span> <var>opener</var>:</p>
<ol>
<li><p>Let <var>openerTopLevelBrowsingContext</var> be <var>opener</var>'s <span
data-x="bc-traversable">top-level traversable</span>'s <span data-x="nav-bc">active browsing
context</span>.</p></li>
<li><p>Let <var>group</var> be <var>openerTopLevelBrowsingContext</var>'s <span data-x="tlbc
group">group</span>.</p></li>
<li><p><span>Assert</span>: <var>group</var> is non-null, as <span
data-x="navigate">navigating</span> invokes this directly.</p></li>
<li><p>Let <var>browsingContext</var> and <var>document</var> be the result of <span>creating a
new browsing context and document</span> with <var>opener</var>'s <span
data-x="nav-document">active document</span>, null, and <var>group</var>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span>is auxiliary</span> to true.</p></li>
<li><p><span data-x="bcg append">Append</span> <var>browsingContext</var> to
<var>group</var>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span>opener browsing context</span> to
<var>opener</var>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span data-x="virtual-browsing-context-group-id">virtual
browsing context group ID</span> to <var>openerTopLevelBrowsingContext</var>'s <span
data-x="virtual-browsing-context-group-id">virtual browsing context group ID</span>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span data-x="opener-origin-at-creation">opener origin
at creation</span> to <var>opener</var>'s <span data-x="nav-document">active document</span>'s
<span data-x="concept-document-origin">origin</span>.</p></li>
<li><p>Return <var>browsingContext</var> and <var>document</var>.</p></li>
</ol>
<p>To <dfn data-x="determining the origin">determine the origin</dfn>, given a <span>URL</span>
<var>url</var>, a <span>sandboxing flag set</span> <var>sandboxFlags</var>, and an
<span>origin</span>-or-null <var>sourceOrigin</var>:</p>
<ol>
<li id="sandboxOrigin"><p>If <var>sandboxFlags</var> has its <span>sandboxed origin browsing
context flag</span> set, then return a new <span data-x="concept-origin-opaque">opaque
origin</span>.</p></li>
<li><p>If <var>url</var> is null, then return a new <span data-x="concept-origin-opaque">opaque
origin</span>.</p></li>
<li>
<p>If <var>url</var> is <code>about:srcdoc</code>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>sourceOrigin</var> is non-null.</p></li>
<li><p>Return <var>sourceOrigin</var>.</p></li>
</ol>
</li>
<li><p>If <var>url</var> <span>matches <code>about:blank</code></span> and
<var>sourceOrigin</var> is non-null, then return <var>sourceOrigin</var>.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-origin">origin</span>.</p></li>
</ol>
<p class="note">The cases that return <var>sourceOrigin</var> result in two
<code>Document</code>s that end up with the same underlying <span
data-x="concept-document-origin">origin</span>, meaning that <code
data-x="dom-document-domain">document.domain</code> affects both.</p>
<h5 id="nested-browsing-contexts">Related browsing contexts</h5>
<p>A <span>browsing context</span> <var>potentialDescendant</var> is said to be an <dfn
data-x="ancestor browsing context">ancestor</dfn> of a browsing context
<var>potentialAncestor</var> if the following algorithm returns true:</p>
<ol>
<li><p>Let <var>potentialDescendantDocument</var> be <var>potentialDescendant</var>'s
<span>active document</span>.</p></li>
<li><p>If <var>potentialDescendantDocument</var> is not <span>fully active</span>, then return
false.</p></li>
<li><p>Let <var>ancestorBCs</var> be the list obtained by taking the <span
data-x="concept-document-bc">browsing context</span> of the <span data-x="nav-document">active
document</span> of each member of <var>potentialDescendantDocument</var>'s <span>ancestor
navigables</span>.</p></li>
<li><p>If <var>ancestorBCs</var> <span data-x="list contains">contains</span>
<var>potentialAncestor</var>, then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>A <dfn export>top-level browsing context</dfn> is a <span>browsing context</span> whose
<span>active document</span>'s <span>node navigable</span> is a <span>traversable
navigable</span>.</p>
<p class="note">It is <em>not</em> required to be a <span>top-level traversable</span>.</p>
<p>The <dfn data-x="bc-tlbc">top-level browsing context</dfn> of a <span>browsing context</span>
<var>start</var> is the result of the following algorithm:</p>
<ol>
<li><p>If <var>start</var>'s <span>active document</span> is not <span>fully active</span>, then
return null.</p></li>
<li><p>Let <var>navigable</var> be <var>start</var>'s <span>active document</span>'s <span>node
navigable</span>.</p></li>
<li><p>While <var>navigable</var>'s <span data-x="nav-parent">parent</span> is not null, set
<var>navigable</var> to <var>navigable</var>'s <span data-x="nav-parent">parent</span>.</p></li>
<li><p>Return <var>navigable</var>'s <span data-x="nav-bc">active browsing
context</span>.</p></li>
</ol>
<div class="warning" id="warning-avoid-related-bc-terms">
<p>The terms <span>ancestor browsing context</span> and <span>top-level browsing context</span>
are rarely useful, since <span data-x="browsing context">browsing contexts</span> in general are
<a href="#warning-avoid-using-bcs">usually the inappropriate specification concept to use</a>.
Note in particular that when a <span>browsing context</span>'s <span>active document</span> is
not <span>fully active</span>, it never counts as an ancestor or top-level browsing context, and
as such these concepts are not useful when <a href="#note-bfcache">bfcache</a> is in play.</p>
<p>Instead, use concepts such as the <span>ancestor navigables</span> collection, the <span
data-x="nav-parent">parent navigable</span>, or a navigable's <span
data-x="nav-traversable">top-level traversable</span>.</p>
</div>
<hr>
<p id="security-1"><span id="security-nav"></span>A <span>browsing context</span> <var>A</var> is
<dfn>familiar with</dfn> a second <span>browsing context</span> <var>B</var> if the following
algorithm returns true:</p>
<ol>
<li><p>If <var>A</var>'s <span>active document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin</span> with <var>B</var>'s
<span>active document</span>'s <span data-x="concept-document-origin">origin</span>, then return
true.</p></li>
<li><p>If <var>A</var>'s <span data-x="bc-tlbc">top-level browsing context</span> is
<var>B</var>, then return true.</p></li>
<li><p>If <var>B</var> is an <span>auxiliary browsing context</span> and <var>A</var> is
<span>familiar with</span> <var>B</var>'s <span>opener browsing context</span>, then return
true.</p></li>
<li>
<p>If there exists an <span>ancestor browsing context</span> of <var>B</var> whose <span>active
document</span> has the <span data-x="same origin">same</span> <span
data-x="concept-document-origin">origin</span> as the <span>active document</span> of
<var>A</var>, then return true.</p>
<p class="note">This includes the case where <var>A</var> is an <span>ancestor browsing
context</span> of <var>B</var>.</p>
</li>
<li><p>Return false.</p></li>
</ol>
<h5>Groupings of browsing contexts</h5>
<p>A <span>top-level browsing context</span> has an associated <dfn data-x="tlbc
group">group</dfn> (null or a <span>browsing context group</span>). It is initially null.</p>
<p>A user agent holds a <dfn>browsing context group set</dfn> (a <span>set</span> of <span
data-x="browsing context group">browsing context groups</span>).</p>
<p>A <dfn>browsing context group</dfn> holds a <dfn>browsing context set</dfn> (a <span>set</span>
of <span data-x="top-level browsing context">top-level browsing contexts</span>).</p>
<p class="note">A <span>top-level browsing context</span> is added to the <span data-x="browsing
context group">group</span> when the group is <span data-x="creating a new browsing context group
and document">created</span>. All subsequent <span data-x="top-level browsing context">top-level
browsing contexts</span> added to the <span data-x="browsing context group">group</span> will be
<span data-x="auxiliary browsing context">auxiliary browsing contexts</span>.</p>
<p>A <span>browsing context group</span> has an associated <dfn>agent cluster map</dfn> (a weak
<span data-x="ordered map">map</span> of <span data-x="agent cluster key">agent cluster
keys</span> to <span data-x="agent cluster">agent clusters</span>). User agents are responsible
for collecting agent clusters when it is deemed that nothing can access them anymore.</p>
<p>A <span>browsing context group</span> has an associated <dfn>historical agent cluster key
map</dfn>, which is a <span data-x="ordered map">map</span> of <span
data-x="origin">origins</span> to <span data-x="agent cluster key">agent cluster keys</span>. This
map is used to ensure the consistency of the <a href="#origin-keyed-agent-clusters">origin-keyed
agent clusters</a> feature by recording what agent cluster keys were previously used for a given
origin.</p>
<p class="note">The <span>historical agent cluster key map</span> only ever gains entries over the
lifetime of the browsing context group.</p>
<p>A <span>browsing context group</span> has a <dfn
data-x="bcg-cross-origin-isolation">cross-origin isolation mode</dfn>, which is a
<span>cross-origin isolation mode</span>. It is initially "<code
data-x="cross-origin-isolation-none">none</code>".</p>
<p>A <dfn>cross-origin isolation mode</dfn> is one of three possible values: "<dfn><code
data-x="cross-origin-isolation-none">none</code></dfn>", "<dfn><code
data-x="cross-origin-isolation-logical">logical</code></dfn>", or "<dfn><code
data-x="cross-origin-isolation-concrete">concrete</code></dfn>".</p>
<div class="note">
<p>"<code data-x="cross-origin-isolation-logical">logical</code>" and "<code
data-x="cross-origin-isolation-concrete">concrete</code>" are similar. They are both used for
<span data-x="browsing context group">browsing context groups</span> where:</p>
<ul>
<li><p>every top-level <code>Document</code> has `<code
data-x=""><span>Cross-Origin-Opener-Policy</span>: <span
data-x="coop-same-origin">same-origin</span></code>`, and</p></li>
<li><p>every <code>Document</code> has a `<code>Cross-Origin-Embedder-Policy</code>` header
whose value is <span>compatible with cross-origin isolation</span>.</p></li>
</ul>
<p>On some platforms, it is difficult to provide the security properties required to grant safe
access to the APIs gated by the <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>. As a result, only "<code
data-x="cross-origin-isolation-concrete">concrete</code>" can grant access that capability.
"<code data-x="cross-origin-isolation-logical">logical</code>" is used on platform not supporting
this capability, where various restrictions imposed by cross-origin isolation will still apply,
but the capability is not granted.</p>
</div>
<p id="creating-a-new-browsing-context-group">To <dfn data-x="creating a new browsing context
group and document">create a new browsing context group and document</dfn>:</p>
<ol>
<li><p>Let <var>group</var> be a new <span>browsing context group</span>.</p></li>
<li><p><span data-x="set append">Append</span> <var>group</var> to the user agent's
<span>browsing context group set</span>.</p></li>
<li><p>Let <var>browsingContext</var> and <var>document</var> be the result of <span>creating a
new browsing context and document</span> with null, null, and <var>group</var>.</p></li>
<li><p><span data-x="bcg append">Append</span> <var>browsingContext</var> to
<var>group</var>.</p></li>
<li><p>Return <var>group</var> and <var>document</var>.</p></li>
</ol>
<p>To <dfn data-x="bcg append">append</dfn> a <span>top-level browsing context</span>
<var>browsingContext</var> to a <span>browsing context group</span> <var>group</var>:</p>
<ol>
<li><p><span data-x="set append">Append</span> <var>browsingContext</var> to <var>group</var>'s
<span>browsing context set</span>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span data-x="tlbc group">group</span> to
<var>group</var>.</p></li>
</ol>
<p>To <dfn data-x="bcg remove">remove</dfn> a <span>top-level browsing context</span>
<var>browsingContext</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>browsingContext</var>'s <span data-x="tlbc group">group</span>
is non-null.</p></li>
<li><p>Let <var>group</var> be <var>browsingContext</var>'s <span data-x="tlbc
group">group</span>.</p></li>
<li><p>Set <var>browsingContext</var>'s <span data-x="tlbc group">group</span> to null.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>browsingContext</var> from
<var>group</var>'s <span>browsing context set</span>.</p></li>
<li><p>If <var>group</var>'s <span>browsing context set</span> <span data-x="list is empty">is
empty</span>, then <span data-x="list remove">remove</span> <var>group</var> from the user
agent's <span>browsing context group set</span>.</p></li>
</ol>
<p class="note"><span data-x="bcg append">Append</span> and <span data-x="bcg
remove">remove</span> are primitive operations that help define the lifetime of a <span>browsing
context group</span>. They are called by higher-level creation and destruction operations for
<code>Document</code>s and <span data-x="browsing context">browsing contexts</span>.</p>
<p id="a-browsing-context-is-discarded">When there are no <code>Document</code> objects whose
<span data-x="concept-document-bc">browsing context</span> equals a given <span>browsing
context</span> (i.e., all such <code>Document</code>s have been <span data-x="destroy a
document">destroyed</span>), and that <span>browsing context</span>'s <code>WindowProxy</code> is
eligible for garbage collection, then the <span>browsing context</span> will never be accessed
again. If it is a <span>top-level browsing context</span>, then at this point the user agent must
<span data-x="bcg remove">remove</span> it.</p>
<h4>Fully active documents</h4>
<p>A <code>Document</code> <var>d</var> is said to be <dfn export for="Document">fully
active</dfn> when <var>d</var> is the <span data-x="nav-document">active document</span> of a
<span>navigable</span> <var>navigable</var>, and either <var>navigable</var> is a <span>top-level
traversable</span> or <var>navigable</var>'s <span data-x="nav-container-document">container
document</span> is <span>fully active</span>.</p>
<p>Because they are associated with an element, <span data-x="child navigable">child
navigables</span> are always tied to a specific <code>Document</code>, their <span
data-x="nav-container-document">container document</span>, in their <span
data-x="nav-parent">parent navigable</span>. User agents must not allow the user to interact with
<span data-x="child navigable">child navigables</span> whose <span
data-x="nav-container-document">container documents</span> are not themselves <span>fully
active</span>.</p>
<div class="example">
<p>The following example illustrates how a <code>Document</code> can be the <span
data-x="nav-document">active document</span> of its <span>node navigable</span>, while not being
<span>fully active</span>. Here <code data-x="">a.html</code> is loaded into a browser window,
<code data-x="">b-1.html</code> starts out loaded into an <code>iframe</code> as shown, and
<code data-x="">b-2.html</code> and <code data-x="">c.html</code> are omitted (they can simply
be an empty document).</p>
<pre><code data-x="" class="html"><!-- a.html -->
<!DOCTYPE html>
<html lang="en">
<title>Navigable A</title>
<iframe src="b-1.html"></iframe>
<button onclick="frames[0].location.href = 'b-2.html'">Click me</button>
<!-- b-1.html -->
<!DOCTYPE html>
<html lang="en">
<title>Navigable B</title>
<iframe src="c.html"></iframe></code></pre>
<p>At this point, the documents given by <code data-x="">a.html</code>, <code
data-x="">b-1.html</code>, and <code data-x="">c.html</code> are all the <span
data-x="nav-document">active documents</span> of their respective <span data-x="node
navigable">node navigables</span>. They are also all <span>fully active</span>.</p>
<p>After clicking on the <code>button</code>, and thus loading a new <code>Document</code> from
<code data-x="">b-2.html</code> into navigable B, we have the following results:</p>
<ul>
<li><p>The <code data-x="">a.html</code> <code>Document</code> remains both the <span
data-x="nav-document">active document</span> of navigable A, and <span>fully
active</span>.</p></li>
<li><p>The <code data-x="">b-1.html</code> <code>Document</code> is now <em>not</em> the <span
data-x="nav-document">active document</span> of navigable B. As such it is also not <span>fully
active</span>.</p></li>
<li><p>The new <code data-x="">b-2.html</code> <code>Document</code> is now the <span
data-x="nav-document">active document</span> of navigable B, and is also <span>fully
active</span>.</p></li>
<li><p>The <code data-x="">c.html</code> <code>Document</code> is still the <span
data-x="nav-document">active document</span> of navigable C. However, since C's <span
data-x="nav-container-document">container document</span> is the <code
data-x="">b-1.html</code> <code>Document</code>, which is itself not <span>fully active</span>,
this means the <code data-x="">c.html</code> <code>Document</code> is now not <span>fully
active</span>.</p></li>
</ul>
</div>
<h3 split-filename="browsing-the-web"><span id="history"></span>Navigation and session
history</h3>
<p>Welcome to the dragon's maw. Navigation, session history, and the traversal through that
session history are some of the most complex parts of this standard.</p>
<p>The basic concept may not seem so difficult:</p>
<ul>
<li><p>The user is looking at a <span>navigable</span> that is presenting its <span
data-x="nav-document">active document</span>. They <span>navigate</span> it to another
<span>URL</span>.</p></li>
<li><p>The browser fetches the given URL from the network, using it to <span data-x="attempt to
populate the history entry's document">populate</span> a new <span>session history entry</span>
with a newly-<span data-x="create-the-document-object">created</span>
<code>Document</code>.</p></li>
<li><p>The browser updates the <span>navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span> to the newly-populated
one, and thus updates the <span data-x="nav-document">active document</span> that it is showing
to the user.</p></li>
<li><p>At some point later, the user <span data-x="traverse the history by a delta">presses the
browser back button</span> to go back to the previous <span>session history
entry</span>.</p></li>
<li><p>The browser looks at the <span data-x="she-url">URL</span> stored in that <span>session
history entry</span>, and uses it to re-fetch and <span data-x="attempt to populate the history
entry's document">populate</span> that entry's <span
data-x="she-document">document</span>.</p></li>
<li><p>The browser again updates the <span>navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
</ul>
<p>You can see some of the intertwined complexity peeking through here, in how traversal can
cause a navigation (i.e., a network fetch to a stored URL), and how a navigation necessarily
needs to interface with the session history list to ensure that when it finishes the user is
looking at the right thing. But the real problems come in with the various edge cases and
interacting web platform features:</p>
<ul>
<li><p><span data-x="child navigable">Child navigables</span> (e.g., those contained in
<code>iframe</code>s) can also navigate and traverse, but those navigations need to be
linearized into <span data-x="tn-session-history-entries">a single session history list</span>
since the user only has a single back/forward interface for the entire <span>traversable
navigable</span> (e.g., browser tab).</p></li>
<li><p>Since the user can traverse back more than a single step in the session history (e.g., by
holding down their back button), they can end up traversing multiple <span
data-x="navigable">navigables</span> at the same time when <span data-x="child
navigable">child navigables</span> are involved. This needs to be synchronized across all of
the involved navigables, which might involve multiple <span data-x="event loop">event
loops</span> or even <span data-x="agent cluster">agent clusters</span>.</p></li>
<li><p>During navigation, servers can respond with 204 or 205 status codes or with `<code
data-x="http-content-disposition">Content-Disposition: attachment</code>` headers, which cause
navigation to abort and the <span>navigable</span> to stay on its original <span data-x="active
document">active document</span>. (This is much worse if it happens during a traversal-initiated
navigation!)</p></li>
<li><p>Various other HTTP headers, such as `<code data-x="">Location</code>`,
`<code>Refresh</code>`, `<code>X-Frame-Options</code>`, and those for Content Security Policy,
contribute to either the <span data-x="create navigation params by fetching">fetching
process</span>, or the <span data-x="create-the-document-object"><code>Document</code>-creation
process</span>, or both. The `<code>Cross-Origin-Opener-Policy</code>` header even contributes
to the <a href="#browsing-context-group-switches-due-to-cross-origin-opener-policy">browsing
context selection and creation</a> process!</p></li>
<li><p>Some navigations (namely <a href="#scroll-to-fragid">fragment navigations</a> and <a
href="#navigate-non-frag-sync">single-page app navigations</a>) are synchronous, meaning that
JavaScript code expects to observe the navigation's results instantly. This then needs to be
synchronized with the view of the session history that all other <span
data-x="navigable">navigables</span> in the tree see, which can be subject to race conditions
and necessitate resolving conflicting views of the session history.</p></li>
<li><p>The platform has accumulated various exciting navigation-related features that need
special-casing, such as <code data-x="javascript protocol">javascript:</code> URLs, <code
data-x="attr-iframe-srcdoc">srcdoc</code> <code>iframe</code>s, and the <code
data-x="event-beforeunload">beforeunload</code> event.</p></li>
</ul>
<p>In what follows, we have attempted to guide the reader through these complexities by
appropriately cordoning them off into labeled sections and algorithms, and giving appropriate
words of introduction where possible. Nevertheless, if you wish to truly understand navigation
and session history, <a href="#how-to-read-this-specification">the usual advice</a> will be
invaluable.</p>
<h4 id="session-history-infrastructure"><span id="the-session-history-of-browsing-contexts"></span>Session history</h4>
<h5>Session history entries</h5>
<p>A <dfn>session history entry</dfn> is a <span>struct</span> with the following <span
data-x="struct item">items</span>:</p>
<ul>
<li><p><dfn data-x="she-step">step</dfn>, a non-negative integer or "<code
data-x="">pending</code>", initially "<code data-x="">pending</code>".</p></li>
<li><p><dfn data-x="she-url">URL</dfn>, a <span>URL</span></p></li>
<li><p><dfn data-x="she-document-state">document state</dfn>, a <span>document
state</span>.</p></li>
<li><p id="she-serialized-state"><dfn data-x="she-classic-history-api-state">classic history API
state</dfn>, which is <span>serialized state</span>, initially
<span>StructuredSerializeForStorage</span>(null).</p></li>
<li><p><dfn data-x="she-navigation-api-state">navigation API state</dfn>, which is a
<span>serialized state</span>, initially
<span>StructuredSerializeForStorage</span>(undefined).</p></li>
<li><p><dfn data-x="she-navigation-api-key">navigation API key</dfn>, which is a string,
initially set to the result of <span>generating a random UUID</span>.</p></li>
<li><p><dfn data-x="she-navigation-api-id">navigation API ID</dfn>, which is a string, initially
set to the result of <span>generating a random UUID</span>.</p></li>
<li><p><dfn data-x="she-scroll-restoration-mode">scroll restoration mode</dfn>, a <span>scroll
restoration mode</span>, initially "<code
data-x="dom-ScrollRestoration-auto">auto</code>".</p></li>
<li><p><dfn data-x="she-scroll-position">scroll position data</dfn>, which is scroll position
data for the <span data-x="she-document">document</span>'s <span>restorable scrollable
regions</span>.</p></li>
<li>
<p id="an-entry-with-persisted-user-state"><dfn data-x="she-other">persisted user state</dfn>,
which is <span>implementation-defined</span>, initially null</p>
<p class="example">For example, some user agents might want to persist the values of form
controls.</p>
<p class="note">User agents that persist the value of form controls are encouraged to also
persist their directionality (the value of the element's <code data-x="attr-dir">dir</code>
attribute). This prevents values from being displayed incorrectly after a history traversal
when the user had originally entered the values with an explicit, non-default
directionality.</p>
</li>
</ul>
<p>To get a <span>session history entry</span>'s <dfn data-x="she-document">document</dfn>,
return its <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span>.</p>
<hr>
<p id="state-object"><dfn>Serialized state</dfn> is a serialization (via
<span>StructuredSerializeForStorage</span>) of an object representing a user interface state. We
sometimes informally refer to "state objects", which are the objects representing user interface
state supplied by the author, or alternately the objects created by deserializing (via
<span>StructuredDeserialize</span>) serialized state.</p>
<p>Pages can <span data-x="dom-history-pushState">add</span> <span>serialized state</span> to the
session history. These are then <span data-x="StructuredDeserialize">deserialized</span> and <span
data-x="event-popstate">returned to the script</span> when the user (or script) goes back in the
history, thus enabling authors to use the "navigation" metaphor even in one-page applications.</p>
<div class="note">
<p><span>Serialized state</span> is intended to be used for two main purposes: first, storing a
preparsed description of the state in the <span>URL</span> so that in the simple case an author
doesn't have to do the parsing (though one would still need the parsing for handling <span
data-x="URL">URLs</span> passed around by users, so it's only a minor optimization). Second, so
that the author can store state that one wouldn't store in the URL because it only applies to the
current <code>Document</code> instance and it would have to be reconstructed if a new
<code>Document</code> were opened.</p>
<p>An example of the latter would be something like keeping track of the precise coordinate from
which a popup <code>div</code> was made to animate, so that if the user goes back, it can be made
to animate to the same location. Or alternatively, it could be used to keep a pointer into a
cache of data that would be fetched from the server based on the information in the
<span>URL</span>, so that when going back and forward, the information doesn't have to be fetched
again.</p>
</div>
<hr>
<p>A <dfn>scroll restoration mode</dfn> indicates whether the user agent should restore the
persisted scroll position (if any) when traversing to an <span data-x="session history
entry">entry</span>. A scroll restoration mode is one of the following:</p>
<dl>
<dt>"<dfn enum-value for="ScrollRestoration"><code subdfn
data-x="dom-ScrollRestoration-auto">auto</code></dfn>"</dt>
<dd>The user agent is responsible for restoring the scroll position upon navigation.</dd>
<dt>"<dfn enum-value for="ScrollRestoration"><code subdfn
data-x="dom-ScrollRestoration-manual">manual</code></dfn>"</dt>
<dd>The page is responsible for restoring the scroll position and the user agent does not
attempt to do so automatically</dd>
</dl>
<h5>Document state</h5>
<p><dfn>Document state</dfn> holds state inside a <span>session history entry</span> regarding
how to present and, if necessary, recreate, a <code>Document</code>. It has:</p>
<ul>
<li>
<p>A <dfn data-x="document-state-document">document</dfn>, a <code>Document</code> or null,
initially null.</p>
<div class="note" id="note-bfcache">
<p>When a history entry is <span data-x="nav-active-history-entry">active</span>, it has a
<code>Document</code> in its <span data-x="she-document-state">document state</span>. However,
when a <code>Document</code> is not <span>fully active</span>, it's possible for it to be
<span data-x="destroy a Document">destroyed</span> to free resources. In such cases, this
<span data-x="document-state-document">document</span> item will be nulled out. The <span
data-x="she-url">URL</span> and other data in the <span>session history entry</span> and <span
data-x="she-document-state">document state</span> is then used to bring a new
<code>Document</code> into being to take the place of the original, in the case where the user
agent finds itself having to traverse to the entry.</p>
<p>If the <code>Document</code> is <em>not</em> <span data-x="destroy a
Document">destroyed</span>, then during <span data-x="traverse the history by a delta">history
traversal</span>, it can be <span data-x="reactivate a document">reactivated</span>. The cache
in which browsers store such <code>Document</code>s is often called a <em>back-forward
cache</em>, or <em>bfcache</em> (or perhaps <a
href="https://bugzilla.mozilla.org/show_bug.cgi?id=274784">"blazingly fast"</a> cache).</p>
</div>
</li>
<li><p id="she-policy-container">A <dfn data-x="document-state-history-policy-container">history
policy container</dfn>, a <span>policy container</span> or null, initially null.</p></li>
<li><p>A <dfn data-x="document-state-request-referrer">request referrer</dfn>, which is "<code
data-x="">no-referrer</code>", "<code data-x="">client</code>", or a <span>URL</span>, initially
"<code data-x="">client</code>".</p></li>
<li>
<p>A <dfn data-x="document-state-request-referrer-policy">request referrer policy</dfn>, which
is a <span>referrer policy</span>, initially the <span>default referrer policy</span>.</p>
<p class="note">The <span data-x="document-state-request-referrer-policy">request referrer
policy</span> is distinct from the <span
data-x="document-state-history-policy-container">history policy container</span>'s <span
data-x="policy-container-referrer-policy">referrer policy</span>. The former is used for
fetches <em>of</em> this document, whereas the latter controls fetches <em>by</em> this
document.</p>
</li>
<li>
<p>An <dfn data-x="document-state-initiator-origin">initiator origin</dfn>, which is an
<span>origin</span> or null, initially null.</p>
</li>
<li>
<p>An <dfn data-x="document-state-origin">origin</dfn>, which is an <span>origin</span> or
null, initially null.</p>
<p class="note">This is the origin that we set "<code data-x="">about:</code>"-schemed
<code>Document</code>s' <span data-x="concept-document-origin">origin</span> to. We store it
here because it is also used when restoring these <code>Document</code>s during traversal,
since they are reconstructed locally without visiting the network. It is also used to compare
the origin before and after the <span>session history entry</span> is <span data-x="attempt to
populate the history entry's document">repopulated</span>. If the origins change, the <span
data-x="document-state-nav-target-name">navigable target name</span> is cleared.</p>
</li>
<li>
<p>An <dfn data-x="document-state-about-base-url">about base URL</dfn>, which is a
<span>URL</span> or null, initially null.</p>
<p class="note">This will be populated only for "<code data-x="">about:</code>"-schemed
<code>Document</code>s and will be the <span>fallback base URL</span> for those
<code>Document</code>s. It is a snapshot of the initiator <code>Document</code>'s <span>document
base URL</span>.</p>
</li>
<li><p><dfn data-x="document-state-nested-histories">Nested histories</dfn>, a <span>list</span>
of <span data-x="nested history">nested histories</span>, initially an empty
<span>list</span>.</p></li>
<li>
<p>A <dfn data-x="document-state-resource">resource</dfn>, a string, <span>POST resource</span>
or null, initially null.</p>
<p class="note">A string is treated as HTML. It's used to store the source of an <span
data-x="an iframe srcdoc document"><code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span>.</p>
</li>
<li><p>A <dfn data-x="document-state-reload-pending">reload pending</dfn> boolean, initially
false.</p></li>
<li><p>An <dfn data-x="document-state-ever-populated">ever populated</dfn> boolean, initially
false.</p></li>
<li><p id="she-bc-name">A <dfn data-x="document-state-nav-target-name">navigable target
name</dfn> string, initially the empty string.</p></li>
<li><p>A <dfn data-x="document-state-not-restored-reasons">not restored reasons</dfn>, a
<span data-x="nrr-struct">not restored reasons</span> or null, initially null.</p></li>
</ul>
<p>User agents may <span>destroy a document and its descendants</span> given the <span
data-x="document-state-document">documents</span> of <span data-x="document state">document
states</span> with non-null <span data-x="document-state-document">documents</span>, as long as
the <code>Document</code> is not <span>fully active</span>.</p>
<p>Apart from that restriction, this standard does not specify when user agents should destroy
the <span data-x="document-state-document">document</span> stored in a <span>document
state</span>, versus keeping it cached.</p>
<hr>
<p>A <dfn export>POST resource</dfn> has:</p>
<ul>
<li>
<p>A <dfn export for="POST resource" data-x="post-resource-request-body">request body</dfn>, a
<span>byte sequence</span> or failure.</p>
<p>This is only ever accessed <span>in parallel</span>, so it doesn't need to be stored in
memory. However, it must return the same <span>byte sequence</span> each time. If this isn't
possible due to resources changing on disk, or if resources can no longer be accessed, then
this must be set to failure.</p>
</li>
<li><p>A <dfn export for="POST resource" data-x="post-resource-request-content-type">request
content-type</dfn>, which is `<code>application/x-www-form-urlencoded</code>`,
`<code>multipart/form-data</code>`, or `<code>text/plain</code>`.</p></li>
</ul>
<hr>
<p>A <dfn>nested history</dfn> has:</p>
<ul>
<li>
<p>An <dfn data-x="nested-history-id">id</dfn>, a <span>unique internal value</span>.</p>
<p class="note">This is used to associate the <span>nested history</span> with a
<span>navigable</span>.</p>
</li>
<li><p><dfn data-x="nested-history-entries">Entries</dfn>, a <span>list</span> of <span
data-x="session history entry">session history entries</span>.</p></li>
</ul>
<p class="XXX">This will later contain ways to identify a child navigable across reloads.</p>
<hr>
<hr>
<p>Several contiguous entries in a session history can share the same <span
data-x="she-document-state">document state</span>. This can occur when the initial entry is
reached via normal <span data-x="navigate">navigation</span>, and the following entry is added
via <code data-x="dom-history-pushState">history.pushState()</code>. Or it can occur via <span
data-x="navigate-fragid">navigation to a fragment</span>.</p>
<p class="note">All entries that share the same <span data-x="she-document-state">document
state</span> (and that are therefore merely different states of one particular document) are
contiguous by construction.</p>
<hr>
<p>A <code>Document</code> has a <dfn>latest entry</dfn>, a <span>session history entry</span> or
null.</p>
<p class="note">This is the entry that was most recently represented by a given
<code>Document</code>. A single <code>Document</code> can represent many <span data-x="session
history entry">session history entries</span> over time, as many contiguous <span data-x="session
history entry">session history entries</span> can share the same <span
data-x="she-document-state">document state</span> as explained above.</p>
<h5>Centralized modifications of session history</h5>
<p>To maintain a single source of truth, all modifications to a <span>traversable
navigable</span>'s <span data-x="tn-session-history-entries">session history entries</span> need
to be synchronized. This is especially important due to how session history is influenced by all
of the descendant <span data-x="navigable">navigables</span>, and thus by multiple <span
data-x="event loop">event loops</span>. To accomplish this, we use the <span>session history
traversal parallel queue</span> structure.</p>
<p id="session-history-traversal-queue">A <dfn>session history traversal parallel queue</dfn> is
very similar to a <span>parallel queue</span>. It has an <dfn
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</dfn>, an <span
data-x="set">ordered set</span>.</p>
<p>The <span data-x="list item">items</span> in a <span>session history traversal parallel
queue</span>'s <span data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm
set</span> are either algorithm steps, or <dfn
data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous navigation
steps</dfn>, which are a particular brand of algorithm steps involving a <dfn
data-x="session-history-traversal-parallel-queue-sync-nav-steps-target-nav">target
navigable</dfn> (a <span>navigable</span>).</p>
<p>To <dfn data-x="tn-append-session-history-traversal-steps">append session history traversal
steps</dfn> to a <span>traversable navigable</span> <var>traversable</var> given algorithm steps
<var>steps</var>, <span data-x="list append">append</span> <var>steps</var> to
<var>traversable</var>'s <span data-x="tn-session-history-traversal-queue">session history
traversal queue</span>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span>.</p>
<p>To <dfn data-x="tn-append-session-history-sync-nav-steps">append session history synchronous
navigation steps</dfn> involving a <span>navigable</span> <var>targetNavigable</var> to a
<span>traversable navigable</span> <var>traversable</var> given algorithm steps <var>steps</var>,
<span data-x="list append">append</span> <var>steps</var> as <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous navigation
steps</span> targeting <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps-target-nav">target
navigable</span> <var>targetNavigable</var> to <var>traversable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span>.</p>
<p id="session-history-event-loop">To <dfn data-x="starting a new session history traversal
parallel queue">start a new session history traversal parallel queue</dfn>:</p>
<ol>
<li><p>Let <var>sessionHistoryTraversalQueue</var> be a new <span>session history traversal
parallel queue</span>.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li>
<p>While true:</p>
<ol>
<li><p>If <var>sessionHistoryTraversalQueue</var>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span> is
empty, then <span>continue</span>.</p></li>
<li><p>Let <var>steps</var> be the result of <span data-x="dequeue">dequeuing</span> from
<var>sessionHistoryTraversalQueue</var>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm
set</span>.</p></li>
<li><p>Run <var>steps</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>sessionHistoryTraversalQueue</var>.</p></li>
</ol>
<p id="sync-navigation-steps-queue-jumping-examples"><span
data-x="session-history-traversal-parallel-queue-sync-nav-steps">Synchronous navigation
steps</span> are tagged in the <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span> to allow
them to conditionally "jump the queue". This is handled <a
href="#sync-navigations-jump-queue">within apply the history step</a>.</p>
<div class="example" id="example-sync-navigation-steps-queue-jumping-basic">
<p>Imagine the joint session history depicted by this <span>Jake diagram</span>:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAxCnRvcAogIDA6IC9hCiAgMTogL2I= -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step current">1</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="1" class="doc-0">/a</td><td colspan="1" class="doc-1 current">/b</td></tr></tbody></table>
<p>And the following code runs at the top level:</p>
<pre><code class="js">history.back();
location.href = '#foo';</code></pre>
<p>The desired result is:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAwCnRvcAogIDA6IC9hCiAgMTogL2IgfCBkb2MxCiAgMjogL2IjZm9vIHwgZG9jMQ== -->
<table class="jake-diagram"><thead><tr><td></td><th class="step current">0</th><th class="step">1</th><th class="step">2</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="1" class="doc-0 current">/a</td><td colspan="1" class="doc-1 next-is-same-doc">/b</td><td colspan="1" class="doc-1 prev-is-same-doc">/b#foo</td></tr></tbody></table>
<p>This isn't straightforward, as the sync navigation wins the race in terms of being
observable, whereas the traversal wins the race in terms of queuing steps on the <span>session
history traversal parallel queue</span>. To achieve this result, the following happens:</p>
<ol>
<li><p><code data-x="dom-history-back">history.back()</code> <span
data-x="tn-append-session-history-traversal-steps">appends steps</span> intended to traverse by
a delta of −1.</p></li>
<li><p><code data-x="dom-location-href">location.href = '#foo'</code> synchronously changes the
<span data-x="nav-active-history-entry">active session history entry</span> entry to a
newly-created one, with the URL <code data-x="">/b#foo</code>, and <span
data-x="tn-append-session-history-sync-nav-steps">appends synchronous steps</span> to notify
the central source of truth about that new entry. Note that this does <em>not</em> yet update
the <span data-x="nav-current-history-entry">current session history entry</span>, <span
data-x="tn-current-session-history-step">current session history step</span>, or the <span
data-x="tn-session-history-entries">session history entries</span> list; those updates cannot
be done synchronously, and instead must be done as part of the queued steps.</p></li>
<li>
<p>On the <span>session history traversal parallel queue</span>, the steps queued by <code
data-x="dom-history-back">history.back()</code> run:</p>
<ol>
<li><p>The target history step is determined to be 0: the <span
data-x="tn-current-session-history-step">current session history step</span> (i.e., 1) plus
the intended delta of −1.</p></li>
<li>
<p>We enter the main <span>apply the history step</span> algorithm.</p>
<p>The entry at step 0, for the <code data-x="">/a</code> URL, has its <span
data-x="she-document">document</span> <span data-x="attempt to populate the history entry's
document">populated</span>.</p>
<p>Meanwhile, the queue is checked for <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous navigation
steps</span>. The steps queued by the <code data-x="dom-location-href">location.href</code>
setter now run, and block the traversal from performing effects beyond document population
(such as, unloading documents and switching active history entries) until they are finished.
Those steps cause the following to happen:</p>
<ol>
<li><p>The entry with URL <code data-x="">/b#foo</code> is added, with its <span
data-x="she-step">step</span> determined to be 2: the <span
data-x="tn-current-session-history-step">current session history step</span> (i.e., 1) plus
1.</p></li>
<li><p>We fully switch to that newly added entry, including a nested call to <span>apply
the history step</span>. This ultimately results in <span data-x="update document for
history step application">updating the document</span> by dispatching events like <code
data-x="event-hashchange">hashchange</code>.</p></li>
</ol>
<p>Only once that is all complete, and the <code data-x="">/a</code> history entry has been
fully populated with a <span data-x="she-document">document</span>, do we move on with
applying the history step given the target step of 0.</p>
<p>At this point, the <code>Document</code> with URL <code data-x="">/b#foo</code> <span
data-x="unload a document">unloads</span>, and we finish moving to our target history step
0, which makes the entry with URL <code data-x="">/a</code> become the <span
data-x="nav-active-history-entry">active session history entry</span> and 0 become the <span
data-x="tn-current-session-history-step">current session history step</span>.</p>
</li>
</ol>
</li>
</ol>
</div>
<div class="example" id="example-sync-navigation-steps-queue-jumping-complex">
<p>Here is another more complex example, involving races between populating two different
<code>iframe</code>s, and a synchronous navigation once one of those iframes loads. We start
with this setup:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAyCnRvcAogIDAtMjogL3QKZnJhbWVzWzBdCiAgMDogL2ktMC1hCiAgMS0yOiAvaS0wLWIKZnJhbWVzWzFdCiAgMC0xOiAvaS0xLWEKICAyOiAvaS0xLWIK -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step current">2</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="3" class="doc-0 current">/t</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-1">/i-0-a</td><td colspan="2" class="doc-2 current">/i-0-b</td></tr><tr><th><code data-x="">frames[1]</code></th><td colspan="2" class="doc-3">/i-1-a</td><td colspan="1" class="doc-4 current">/i-1-b</td></tr></tbody></table>
<p>and then call <code data-x="dom-history-go">history.go(-2)</code>. The following then
occurs:</p>
<ol>
<li>
<p><code data-x="dom-history-go">history.go(-2)</code> <span
data-x="tn-append-session-history-traversal-steps">appends steps</span> intended to traverse
by a delta of −2. Once those steps run:</p>
<ol>
<li><p>The target step is determined to be 2 + (−2) = 0.</p></li>
<li>
<p>In parallel, the fetches are made to <span data-x="attempt to populate the history
entry's document">populate</span> the two iframes, fetching <code data-x="">/i-0-a</code>
and <code data-x="">/i-1-a</code> respectively.</p>
<p>Meanwhile, the queue is checked for <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous navigation
steps</span>. There aren't any right now.</p>
</li>
<li><p>In the fetch race, the fetch for <code data-x="">/i-0-a</code> wins. We proceed onward
to finish all of <span>apply the history step</span>'s work for how the traversal impacts the
<code data-x="">frames[0]</code> <span>navigable</span>, including updating its <span
data-x="nav-active-history-entry">active session history entry</span> to the entry with URL
<code data-x="">/i-0-a</code>.</p></li>
<li>
<p>Before the fetch for <code data-x="">/i-1-a</code> finishes, we reach the point where
<span>scripts may run for the newly-created document</span> in the <code
data-x="">frames[0]</code> <span>navigable</span>'s <span data-x="nav-document">active
document</span>. Some such script does run:</p>
<pre><code class="js">location.href = '#foo'</code></pre>
<p>This synchronously changes the <code data-x="">frames[0]</code> navigable's <span
data-x="nav-active-history-entry">active session history entry</span> entry to a
newly-created one, with the URL <code data-x="">/i-0-a#foo</code>, and <span
data-x="tn-append-session-history-sync-nav-steps">appends synchronous steps</span> to notify
the central source of truth about that new entry.</p>
<p>Unlike in the <a href="#example-sync-navigation-steps-queue-jumping-basic">previous
example</a>, these synchronous steps do <em>not</em> "jump the queue" and update the <span
data-x="traversable navigable">traversable</span> before we finish the fetch for <code
data-x="">/i-1-a</code>. This is because the navigable in question, <code
data-x="">frames[0]</code>, has already been altered as part of the traversal, so we know
that with the <span data-x="tn-current-session-history-step">current session history
step</span> being 2, adding the new entry as a step 3 doesn't make sense.</p>
</li>
<li><p>Once the fetch for <code data-x="">/i-1-a</code> finally finishes, we proceed to finish
updating the <code data-x="">frames[1]</code> <span>navigable</span> for the traversal,
including updating its <span data-x="nav-active-history-entry">active session history
entry</span> to the entry with URL <code data-x="">/i-1-a</code>.</p></li>
<li><p>Now that both navigables have finished processing the traversal, we update the <span
data-x="tn-current-session-history-step">current session history step</span> to the target
step of 0.</p></li>
</ol>
</li>
<li>
<p>Now we can process the steps that were queued for the synchronous navigation:</p>
<ol>
<li><p>The <code data-x="">/i-0-a#foo</code> entry is added, with its <span
data-x="she-step">step</span> determined to be 1: the <span
data-x="tn-current-session-history-step">current session history step</span> (i.e., 0) plus
1. This also <span data-x="clear the forward session history">clears existing forward
history</span>.</p></li>
<li><p>We fully switch to that newly added entry, including calling <span>apply the history
step</span>. This ultimately results in <span data-x="update document for history step
application">updating the document</span> by dispatching events like <code
data-x="event-hashchange">hashchange</code>, as well as updating the <span
data-x="tn-current-session-history-step">current session history step</span> to the target
step of 1.</p></li>
</ol>
</li>
</ol>
<p>The end result is:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAxCiFza2lwRG9jQ29sb3JzID0gMgoKdG9wCiAgMC0xOiAvdApmcmFtZXNbMF0KICAwOiAvaS0wLWEgfCBkb2MxCiAgMTogL2ktMC1hI2ZvbyB8IGRvYzEKZnJhbWVzWzFdCiAgMC0xOiAvaS0xLWEK -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step current">1</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="2" class="doc-0 current">/t</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-1 next-is-same-doc">/i-0-a</td><td colspan="1" class="doc-1 current prev-is-same-doc">/i-0-a#foo</td></tr><tr><th><code data-x="">frames[1]</code></th><td colspan="2" class="doc-3 current">/i-1-a</td></tr></tbody></table>
</div>
<h5>Low-level operations on session history</h5>
<p>This section contains a miscellaneous grab-bag of operations that we perform throughout the
standard when manipulating session history. The best way to get a sense of what they do is to
look at their call sites.</p>
<p>To <dfn data-x="getting session history entries">get session history entries</dfn> of a
<span>navigable</span> <var>navigable</var>:</p>
<ol>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li><p><span>Assert</span>: this is running within <var>traversable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>If <var>navigable</var> is <var>traversable</var>, return <var>traversable</var>'s <span
data-x="tn-session-history-entries">session history entries</span>.</p></li>
<li><p>Let <var>docStates</var> be an empty <span data-x="set">ordered set</span> of <span
data-x="document state">document states</span>.</p></li>
<li><p>For each <var>entry</var> of <var>traversable</var>'s <span
data-x="tn-session-history-entries">session history entries</span>, <span data-x="set
append">append</span> <var>entry</var>'s <span data-x="she-document-state">document state</span>
to <var>docStates</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>docState</var> of <var>docStates</var>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>nestedHistory</var> of
<var>docState</var>'s <span data-x="document-state-nested-histories">nested
histories</span>:</p>
<ol>
<li><p>If <var>nestedHistory</var>'s <span data-x="nested-history-id">id</span> equals
<var>navigable</var>'s <span data-x="nav-id">id</span>, return <var>nestedHistory</var>'s
<span data-x="nested-history-entries">entries</span>.</p></li>
<li><p>For each <var>entry</var> of <var>nestedHistory</var>'s <span
data-x="nested-history-entries">entries</span>, <span data-x="set append">append</span>
<var>entry</var>'s <span data-x="she-document-state">document state</span> to
<var>docStates</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p><span>Assert</span>: this step is not reached.</p></li>
</ol>
<p>To <dfn data-x="getting session history entries for the navigation API">get session history
entries for the navigation API</dfn> of a <span>navigable</span> <var>navigable</var> given an
integer <var>targetStep</var>:</p>
<ol>
<li><p>Let <var>rawEntries</var> be the result of <span>getting session history entries</span>
for <var>navigable</var>.</p></li>
<li><p>Let <var>entriesForNavigationAPI</var> be a new empty <span>list</span>.</p></li>
<li>
<p>Let <var>startingIndex</var> be the index of the <span>session history entry</span> in
<var>rawEntries</var> who has the greatest <span data-x="she-step">step</span> less than or
equal to <var>targetStep</var>.</p>
<p class="note">See <a href="#example-getting-the-target-history-entry">this example</a> to
understand why it's the greatest step less than or equal to <var>targetStep</var>.</p>
</li>
<li><p><span data-x="list append">Append</span> <var>rawEntries</var>[<var>startingIndex</var>]
to <var>entriesForNavigationAPI</var>.</p></li>
<li><p>Let <var>startingOrigin</var> be <var>rawEntries</var>[<var>startingIndex</var>]'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span>.</p></li>
<li><p>Let <var>i</var> be <var>startingIndex</var> − 1.</p></li>
<li>
<p>While <var>i</var> > 0:</p>
<ol>
<li><p>If <var>rawEntries</var>[<var>i</var>]'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-origin">origin</span> is not <span>same
origin</span> with <var>startingOrigin</var>, then <span>break</span>.</p></li>
<li><p><span data-x="list prepend">Prepend</span> <var>rawEntries</var>[<var>i</var>] to
<var>entriesForNavigationAPI</var>.</p></li>
<li><p>Set <var>i</var> to <var>i</var> − 1.</p></li>
</ol>
</li>
<li><p>Set <var>i</var> to <var>startingIndex</var> + 1.</p></li>
<li>
<p>While <var>i</var> < <var>rawEntries</var>'s <span data-x="list size">size</span>:</p>
<ol>
<li><p>If <var>rawEntries</var>[<var>i</var>]'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-origin">origin</span> is not <span>same
origin</span> with <var>startingOrigin</var>, then <span>break</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>rawEntries</var>[<var>i</var>] to
<var>entriesForNavigationAPI</var>.</p></li>
<li><p>Set <var>i</var> to <var>i</var> + 1.</p></li>
</ol>
</li>
<li><p>Return <var>entriesForNavigationAPI</var>.</p></li>
</ol>
<p>To <dfn>clear the forward session history</dfn> of a <span>traversable navigable</span>
<var>navigable</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running within <var>navigable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>Let <var>step</var> be the <var>navigable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span>.</p></li>
<li><p>Let <var>entryLists</var> be the <span data-x="set">ordered set</span> «
<var>navigable</var>'s <span data-x="tn-session-history-entries">session history entries</span>
».</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>entryList</var> of
<var>entryLists</var>:</p>
<ol>
<li><p><span data-x="list remove">Remove</span> every <span>session history entry</span> from
<var>entryList</var> that has a <span data-x="she-step">step</span> greater than
<var>step</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>entryList</var>:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <var>nestedHistory</var> of
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-nested-histories">nested histories</span>, <span data-x="set
append">append</span> <var>nestedHistory</var>'s <span
data-x="nested-history-entries">entries list</span> to <var>entryLists</var>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p>To <dfn data-x="getting all used history steps">get all used history steps</dfn> that are part
of <span>traversable navigable</span> <var>traversable</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running within <var>traversable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>Let <var>steps</var> be an empty <span data-x="set">ordered set</span> of non-negative
integers.</p></li>
<li><p>Let <var>entryLists</var> be the <span data-x="set">ordered set</span> «
<var>traversable</var>'s <span data-x="tn-session-history-entries">session history
entries</span> ».</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>entryList</var> of
<var>entryLists</var>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>entry</var> of <var>entryList</var>:</p>
<ol>
<li><p><span data-x="set append">Append</span> <var>entry</var>'s <span
data-x="she-step">step</span> to <var>steps</var>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>nestedHistory</var> of
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-nested-histories">nested histories</span>, <span data-x="set
append">append</span> <var>nestedHistory</var>'s <span
data-x="nested-history-entries">entries list</span> to <var>entryLists</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>steps</var>, <span data-x="list sort">sorted</span>.</p></li>
</ol>
<h4 id="navigating-across-documents"><span id="browsing-the-web"></span>Navigation</h4>
<p>Certain actions cause a <span>navigable</span> to <i data-x="navigate">navigate</i> to
a new resource.</p>
<p class="example">For example, <span data-x="following hyperlinks">following a hyperlink</span>,
<span data-x="concept-form-submit">form submission</span>, and the <code
data-x="dom-open">window.open()</code> and <code
data-x="dom-location-assign">location.assign()</code> methods can all cause navigation.</p>
<div class="note" id="note-meaning-of-navigate">
<p>Although in this standard the word "navigation" refers specifically to the
<span>navigate</span> algorithm, this doesn't always line up with web developer or user
perceptions. For example:</p>
<ul>
<li><p>The <span>URL and history update steps</span> are often used during so-called
"single-page app navigations" or "same-document navigations", but they do not trigger the
<span>navigate</span> algorithm.</p></li>
<li><p><span data-x="reload">Reloads</span> and <span data-x="traverse the history by a
delta">traversals</span> are sometimes talked about as a type of navigation, since all three
will often <span>attempt to populate the history entry's document</span> and thus could perform
navigational fetches. See, e.g., the APIs exposed <cite>Navigation Timing</cite>. But they have
their own entry point algorithms, separate from the <span>navigate</span> algorithm.
<ref>NAVIGATIONTIMING</ref></p></li>
<li><p>Although <span data-x="navigate-fragid">fragment navigations</span> are always done
through the <span>navigate</span> algorithm, a user might perceive them as more like jumping
around a single page, than as a true navigation.</p></li>
</ul>
</div>
<h5 id="navigation-supporting-concepts">Supporting concepts</h5>
<p>Before we can jump into the <span data-x="navigate">navigation algorithm</span> itself, we
need to establish several important structures that it uses.</p>
<p>The <dfn>source snapshot params</dfn> <span>struct</span> is used to capture data from a
<code>Document</code> initiating a navigation. It is snapshotted at the beginning of a navigation
and used throughout the navigation's lifetime. It has the following <span data-x="struct
item">items</span>:</p>
<dl>
<dt><dfn data-x="source-snapshot-params-activation">has transient activation</dfn></dt>
<dd>a boolean</dd>
<dt><dfn data-x="source-snapshot-params-sandbox">sandboxing flags</dfn></dt>
<dd>a <span>sandboxing flag set</span></dd>
<dt><dfn data-x="source-snapshot-params-download">allows downloading</dfn></dt>
<dd>a boolean</dd>
<dt><dfn data-x="source-snapshot-params-client">fetch client</dfn></dt>
<dd>an <span>environment settings object</span>, only to be used as a <span
data-x="concept-request-client">request client</span></dd>
<dt><dfn data-x="source-snapshot-params-policy-container">source policy container</dfn></dt>
<dd>a <span>policy container</span></dd>
</dl>
<p>To <dfn data-x="snapshotting source snapshot params">snapshot source snapshot params</dfn>
given a <code>Document</code> <var>sourceDocument</var>, return a new <span>source snapshot
params</span> with</p>
<dl class="props">
<dt><span data-x="source-snapshot-params-activation">has transient activation</span></dt>
<dd>true if <var>sourceDocument</var>'s <span>relevant global object</span> has <span>transient
activation</span>; otherwise false</dd>
<dt><span data-x="source-snapshot-params-sandbox">sandboxing flags</span></dt>
<dd><var>sourceDocument</var>'s <span>active sandboxing flag set</span></dd>
<dt><span data-x="source-snapshot-params-download">allows downloading</span></dt>
<dd>false if <var>sourceDocument</var>'s <span>active sandboxing flag set</span> has the
<span>sandboxed downloads browsing context flag</span> set; otherwise true</dd>
<dt><span data-x="source-snapshot-params-client">fetch client</span></dt>
<dd><var>sourceDocument</var>'s <span>relevant settings object</span></dd>
<dt><span data-x="source-snapshot-params-policy-container">source policy container</span></dt>
<dd>a <span data-x="clone a policy container">clone</span> of <var>sourceDocument</var>'s <span
data-x="concept-document-policy-container">policy container</span></dd>
</dl>
<hr>
<p>The <dfn>target snapshot params</dfn> <span>struct</span> is used to capture data from a
<span>navigable</span> being navigated. Like <span>source snapshot params</span>, it is
snapshotted at the beginning of a navigation and used throughout the navigation's lifetime. It
has the following <span data-x="struct item">items</span>:</p>
<dl>
<dt><dfn data-x="target-snapshot-params-sandbox">sandboxing flags</dfn></dt>
<dd>a <span>sandboxing flag set</span></dd>
</dl>
<p>To <dfn data-x="snapshotting target snapshot params">snapshot target snapshot params</dfn>
given a <span>navigable</span> <var>targetNavigable</var>, return a new <span>target snapshot
params</span> with <span data-x="target-snapshot-params-sandbox">sandboxing flags</span> set to
the result of <span>determining the creation sandboxing flags</span> given
<var>targetNavigable</var>'s <span data-x="nav-bc">active browsing context</span> and
<var>targetNavigable</var>'s <span data-x="nav-container">container</span>.</p>
<hr>
<p>Much of the navigation process is concerned with determining how to create a new
<code>Document</code>, which ultimately happens in the <span
data-x="create-the-document-object">create and initialize a <code>Document</code> object</span>
algorithm. The parameters to that algorithm are tracked via a <dfn>navigation params</dfn>
<span>struct</span>, which has the following <span data-x="struct item">items</span>:</p>
<!--
These struct items are roughly ordered/grouped like so:
* Very basic concepts, shared with non-fetch scheme navigation params
* Fetch-related stuff
* Other stuff that affects the process but isn't directly used during new Document creation
* Stuff used directly during new Document creation
* Core stuff first
* Then policy stuff
* Then other stuff
Try to keep this sort of grouping in mind when adding to this struct.
-->
<dl>
<dt><dfn data-x="navigation-params-id">id</dfn></dt>
<dd>null or a <span>navigation ID</span></dd>
<dt><dfn data-x="navigation-params-navigable">navigable</dfn></dt>
<dd>the <span>navigable</span> to be navigated</dd>
<dt><dfn data-x="navigation-params-request">request</dfn></dt>
<dd>null or a <span data-x="concept-request">request</span> that started the navigation</dd>
<dt><dfn data-x="navigation-params-response">response</dfn></dt>
<dd>a <span data-x="concept-response">response</span> that ultimately was navigated to
(potentially a <span>network error</span>)</dd>
<dt><dfn data-x="navigation-params-fetch-controller">fetch controller</dfn></dt>
<dd>null or a <span>fetch controller</span></dd>
<dt><dfn data-x="navigation-params-commit-early-hints">commit early hints</dfn></dt>
<dd>null or an algorithm accepting a <code>Document</code>, once it has been created</dd>
<dt><dfn data-x="navigation-params-coop-enforcement-result">COOP enforcement result</dfn></dt>
<dd>an <span data-x="coop-enforcement-result">opener policy enforcement result</span>, used for
reporting and potentially for causing a <a
href="#browsing-context-group-switches-due-to-cross-origin-opener-policy">browsing context
group switch</a></dd>
<dt><dfn data-x="navigation-params-reserved-environment">reserved environment</dfn></dt>
<dd>null or an <span>environment</span> reserved for the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-origin">origin</dfn></dt>
<dd>an <span>origin</span> to use for the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-policy-container">policy container</dfn></dt>
<dd>a <span>policy container</span> to use for the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-sandboxing">final sandboxing flag set</dfn></dt>
<dd>a <span>sandboxing flag set</span> to impose on the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-coop">opener policy</dfn></dt>
<dd>an <span>opener policy</span> to use for the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-nav-timing-type">navigation timing type</dfn></dt>
<dd>a <code>NavigationTimingType</code> used for <span data-x="create the navigation timing
entry">creating the navigation timing entry</span> for the new <code>Document</code></dd>
<dt><dfn data-x="navigation-params-about-base-url">about base URL</dfn></dt>
<dd>a <span>URL</span> or null used to populate the new <code>Document</code>'s <span
data-x="concept-document-about-base-url">about base URL</span></dd>
<dt><dfn data-x="navigation-params-user-involvement">user involvement</dfn></dt>
<dd>a <span>user navigation involvement</span> used when <span
data-x="obtain-browsing-context-navigation">obtaining a browsing context</span> for the new
<code>Document</code></dd>
</dl>
<p class="note">Once a <span>navigation params</span> struct is created, this standard does not
mutate any of its <span data-x="struct item">items</span>. They are only passed onward to other
algorithms.</p>
<hr>
<p>A <dfn>navigation ID</dfn> is a UUID string generated during navigation. It is used to
interface with the <cite>WebDriver BiDi</cite> specification as well as to track the <span>ongoing
navigation</span>. <ref>WEBDRIVERBIDI</ref></p>
<hr>
<p>After <code>Document</code> creation, the relevant <span>traversable navigable</span>'s <span
data-x="tn-session-history-entries">session history</span> gets updated. The
<code>NavigationHistoryBehavior</code> enumeration is used to indicate the desired type of session
history update to the <span>navigate</span> algorithm. It is one of the following:</p>
<dl>
<dt id="hh-default"><span id="hh-push"></span>"<dfn enum-value for="NavigationHistoryBehavior" data-x="NavigationHistoryBehavior-push"><code>push</code></dfn>"</dt>
<dd>A regular navigation which adds a new <span>session history entry</span>, and will
<span>clear the forward session history</span>.</dd>
<dt id="hh-replace">"<dfn enum-value for="NavigationHistoryBehavior" data-x="NavigationHistoryBehavior-replace"><code>replace</code></dfn>"</dt>
<dd>A navigation that will replace the <span data-x="nav-active-history-entry">active session
history entry</span>.</dd>
<dt>"<dfn enum-value for="NavigationHistoryBehavior" data-x="NavigationHistoryBehavior-auto"><code>auto</code></dfn>"</dt>
<dd>The default value, which will be converted very early in the <span>navigate</span> algorithm
into "<code data-x="NavigationHistoryBehavior-push">push</code>" or "<code
data-x="NavigationHistoryBehavior-replace">replace</code>". Usually it becomes "<code
data-x="NavigationHistoryBehavior-push">push</code>", but under <a
href="#navigate-convert-to-replace">certain circumstances</a> it becomes "<code
data-x="NavigationHistoryBehavior-replace">replace</code>" instead.</dd>
</dl>
<p>A <dfn>history handling behavior</dfn> is a <code>NavigationHistoryBehavior</code> that is
either "<code data-x="NavigationHistoryBehavior-push">push</code>" or "<code
data-x="NavigationHistoryBehavior-replace">replace</code>", i.e., that has been resolved away from
any initial "<code data-x="NavigationHistoryBehavior-auto">auto</code>" value.</p>
<p><dfn>The navigation must be a replace</dfn>, given a <span>URL</span> <var>url</var> and a
<code>Document</code> <var>document</var>, if any of the following are true:</p>
<ul>
<li><p><var>url</var>'s <span data-x="concept-url-scheme">scheme</span> is "<code
data-x="javascript protocol">javascript</code>"; or</p></li>
<li><p><var>document</var>'s <span>is initial <code>about:blank</code></span> is true.</p></li>
</ul>
<div class="note">
<p>Other cases that often, but not always, force a "<code
data-x="NavigationHistoryBehavior-replace">replace</code>" navigation are:</p>
<ul>
<li><p>if the <code>Document</code> is not <span>completely loaded</span>; or</p></li>
<li><p>if the target <span>URL</span> equals the <code>Document</code>'s <span
data-x="concept-document-url">URL</span>.</p></li>
</ul>
</div>
<hr>
<p>Various parts of the platform track whether a user is involved in a navigation. A <dfn
export>user navigation involvement</dfn> is one of the following:</p>
<dl>
<dt>"<dfn export for="user navigation involvement"
data-x="uni-browser-ui"><code>browser UI</code></dfn>"</dt>
<dd>The navigation was initiated by the user via browser UI mechanisms.</dd>
<dt>"<dfn export for="user navigation involvement"
data-x="uni-activation"><code>activation</code></dfn>"</dt>
<dd>The navigation was initiated by the user via the <span>activation behavior</span> of an
element.</dd>
<dt>"<dfn export for="user navigation involvement"
data-x="uni-none"><code>none</code></dfn>"</dt>
<dd>The navigation was not initiated by the user.</dd>
</dl>
<p>For convenience at certain call sites, the <dfn for="Event" data-x="event-uni">user navigation
involvement</dfn> for an <code>Event</code> <var>event</var> is defined as follows:</p>
<ol>
<li><p><span>Assert</span>: this algorithm is being called as part of an <span>activation
behavior</span> definition.</p></li>
<li><p><span>Assert</span>: <var>event</var>'s <code data-x="dom-Event-type">type</code> is
"<code data-x="event-click">click</code>".</p></li>
<li><p>If <var>event</var>'s <code data-x="dom-Event-isTrusted">isTrusted</code> is initialized
to true, then return "<code data-x="uni-activation">activation</code>".</p></li>
<li><p>Return "<code data-x="uni-none">none</code>".</p></li>
</ol>
<h5>Beginning navigation</h5>
<!-- NAVIGATE <dfn>navigate</dfn> -->
<!-- For places that _call_ this, as opposed to just referring to
it, search for "DONAV" -->
<p>To <dfn export>navigate</dfn> a <span>navigable</span> <var>navigable</var> to a
<span>URL</span> <var>url</var> using a <code>Document</code> <var
id="source-browsing-context">sourceDocument</var>, with an optional <span>POST resource</span>,
string, or null <dfn for="navigate" data-x="navigation-resource"
export><var>documentResource</var></dfn> (default null), an optional <span
data-x="concept-response">response</span>-or-null <dfn for="navigate"
data-x="navigation-response" export><var>response</var></dfn> (default null), an optional boolean
<dfn for="navigate" id="exceptions-enabled" export><var>exceptionsEnabled</var></dfn> (default
false), an optional <code>NavigationHistoryBehavior</code> <dfn for="navigate"
data-x="navigation-hh" export><var>historyHandling</var></dfn> (default "<code
data-x="NavigationHistoryBehavior-auto">auto</code>"), an optional <span>serialized
state</span>-or-null <dfn for="navigate" data-x="navigation-navigation-api-state"
export><var>navigationAPIState</var></dfn> (default null), an optional <span>entry list</span> or
null <dfn for="navigate" data-x="navigation-form-data-entry-list"
export><var>formDataEntryList</var></dfn> (default null), an optional <span>referrer
policy</span> <dfn data-x="navigation-referrer-policy"><var>referrerPolicy</var></dfn> (default
the empty string), an optional <span>user navigation involvement</span> <dfn
data-x="navigation-user-involvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"), and an optional <code>Element</code> <dfn
data-x="navigation-source-element"><var>sourceElement</var></dfn> (default null):</p>
<ol>
<li><p>Let <var>cspNavigationType</var> be "<code data-x="">form-submission</code>" if
<var>formDataEntryList</var> is non-null; otherwise "<code data-x="">other</code>".</p></li>
<li><p>Let <var>sourceSnapshotParams</var> be the result of <span>snapshotting source snapshot
params</span> given <var>sourceDocument</var>.</p></li>
<li><p>Let <var>initiatorOriginSnapshot</var> be <var>sourceDocument</var>'s <span
data-x="concept-document-origin">origin</span>.</p></li>
<li><p>Let <var>initiatorBaseURLSnapshot</var> be <var>sourceDocument</var>'s <span>document base
URL</span>.</p></li>
<li id="sandboxLinks">
<p>If <var>sourceDocument</var>'s <span>node navigable</span> is not <span>allowed by
sandboxing to navigate</span> <var>navigable</var> given <var>sourceSnapshotParams</var>,
then:</p>
<ol>
<li><p>If <var>exceptionsEnabled</var> is true, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>navigationId</var> be the result of <span>generating a random UUID</span>.
<ref>WEBCRYPTO</ref></p></li>
<li>
<p>If the <span>surrounding agent</span> is equal to <var>navigable</var>'s <span
data-x="nav-document">active document</span>'s <span>relevant agent</span>, then continue these
steps. Otherwise, <span>queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>navigable</var>'s <span data-x="nav-window">active window</span> to
continue these steps.</p>
<div class="note">
<p>We do this because we are about to look at a lot of properties of <var>navigable</var>'s
<span data-x="nav-document">active document</span>, which are in theory only accessible over
in the appropriate <span>event loop</span>. (But, we do not want to unconditionally queue a
task, since — for example — same-event-loop <span
data-x="navigate-fragid">fragment navigations</span> need to take effect synchronously.)</p>
<p>Another implementation strategy would be to replicate the relevant information across event
loops, or into a canonical "browser process", so that it can be consulted without queueing a
task. This could give different results than what we specify here in edge cases, where the
relevant properties have changed over in the target event loop but not yet been replicated.
Further testing is needed to determine which of these strategies best matches browser
behavior, in such racy edge cases.</p>
</div>
</li>
<li><p>If <var>navigable</var>'s <span data-x="nav-document">active document</span>'s
<span>unload counter</span> is greater than 0, then invoke <span>WebDriver BiDi navigation
failed</span> with <var>navigable</var> and a <span>WebDriver BiDi navigation status</span> whose
<span data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>url</var>, and return.</p></li>
<!--
this stops pages from hijacking the back/forward button, among other things
https://www.hixie.ch/tests/adhoc/html/navigation/unload/
https://github.com/whatwg/html/issues/1213
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1946 to 1955 -->
<li><p>Let <var>container</var> be <var>navigable</var>'s <span
data-x="nav-container">container</span>.</p></li>
<li><p>If <var>container</var> is an <code>iframe</code> element and <span>will lazy load
element steps</span> given <var>container</var> returns true, then <span>stop
intersection-observing a lazy loading element</span> <var>container</var> and set
<var>container</var>'s <span>lazy load resumption steps</span> to null.</p></li>
<li id="navigate-convert-to-replace">
<p>If <var>historyHandling</var> is "<code data-x="NavigationHistoryBehavior-auto">auto</code>",
then:</p>
<ol>
<li><p>If <var>url</var> <span data-x="concept-url-equals">equals</span>
<var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-url">URL</span>, and <var>initiatorOriginSnapshot</var> is <span>same
origin</span> with <var>targetNavigable</var>'s <span data-x="nav-document">active
document</span>'s <span data-x="concept-document-origin">origin</span>, then set
<var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li><p>Otherwise, set <var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-push">push</code>".</p></li>
</ol>
</li>
<li><p>If <span>the navigation must be a replace</span> given <var>url</var> and
<var>navigable</var>'s <span data-x="nav-document">active document</span>, then set
<var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li id="navigate-fragid-step">
<p>If all of the following are true:</p>
<ul>
<li><p><var>documentResource</var> is null;</p></li>
<li><p><var>response</var> is null;</p></li>
<li><p><var>url</var> <span data-x="concept-url-equals">equals</span> <var>navigable</var>'s
<span data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-url">URL</span> with <span data-x="url equals exclude fragments"><i>exclude
fragments</i></span> set to true; and</p></li>
<li><p><var>url</var>'s <span data-x="concept-url-fragment">fragment</span> is
non-null,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p><span data-x="navigate-fragid">Navigate to a fragment</span> given <var>navigable</var>,
<var>url</var>, <var>historyHandling</var>, <var>userInvolvement</var>,
<var>sourceElement</var>, <var>navigationAPIState</var>, and <var>navigationId</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>If <var>navigable</var>'s <span data-x="nav-parent">parent</span> is non-null, then set
<var>navigable</var>'s <span>is delaying <code data-x="event-load">load</code> events</span> to
true.</p></li>
<li><p>Let <var>targetSnapshotParams</var> be the result of <span>snapshotting target snapshot
params</span> given <var>navigable</var>.</p></li>
<li><p>Invoke <span>WebDriver BiDi navigation started</span> with <var>navigable</var> and a new
<span>WebDriver BiDi navigation status</span> whose <span data-x="navigation-status-id">id</span>
is <var>navigationId</var>, <span data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-pending">pending</code>", and <span
data-x="navigation-status-url">url</span> is <var>url</var>.</p></li>
<li>
<p>If <var>navigable</var>'s <span>ongoing navigation</span> is "<code
data-x="">traversal</code>", then:</p>
<ol>
<li><p>Invoke <span>WebDriver BiDi navigation failed</span> with <var>navigable</var> and a new
<span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>url</var>.</p></li>
<li><p>Return.</p></li>
</ol>
<p class="note">Any attempts to navigate a <span>navigable</span> that is currently <span
data-x="apply the traverse history step">traversing</span> are ignored.</p>
</li>
<li>
<p><span>Set the ongoing navigation</span> for <var>navigable</var> to
<var>navigationId</var>.</p>
<p class="note">This will have the effect of aborting other ongoing navigations of
<var>navigable</var>, since at certain points during navigation changes to the <span>ongoing
navigation</span> will cause further work to be abandoned.</p>
</li>
<li>
<p>If <var>url</var>'s <span data-x="concept-url-scheme">scheme</span> is "<code
data-x="javascript protocol">javascript</code>", then:</p>
<ol>
<li><p><span>Queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>navigable</var>'s <span data-x="nav-window">active window</span> to
<span>navigate to a <code>javascript:</code> URL</span> given <var>navigable</var>,
<var>url</var>, <var>historyHandling</var>, <var>sourceSnapshotParams</var>,
<var>initiatorOriginSnapshot</var>, <var>userInvolvement</var>, and
<var>cspNavigationType</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>userInvolvement</var> is not "<code data-x="uni-browser-ui">browser
UI</code>";</p></li>
<li><p><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin-domain</span> with
<var>sourceDocument</var>'s <span data-x="concept-document-origin">origin</span>;</p></li>
<li><p><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span>is
initial <code>about:blank</code></span> is false; and</p></li>
<li><p><var>url</var>'s <span data-x="concept-url-scheme">scheme</span> is a <span>fetch
scheme</span>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>entryListForFiring</var> be <var>formDataEntryList</var> if
<var>documentResource</var> is a <span>POST resource</span>; otherwise, null.</p></li>
<li><p>Let <var>navigationAPIStateForFiring</var> be <var>navigationAPIState</var> if
<var>navigationAPIState</var> is not null; otherwise,
<span>StructuredSerializeForStorage</span>(undefined).</p></li>
<li><p>Let <var>continue</var> be the result of <span data-x="fire a push/replace/reload
navigate event">firing a push/replace/reload <code data-x="event-navigate">navigate</code>
event</span> at <var>navigation</var> with <i
data-x="fire-navigate-prr-navigationType">navigationType</i> set to <var>historyHandling</var>,
<i data-x="fire-navigate-prr-isSameDocument">isSameDocument</i> set to false, <i
data-x="fire-navigate-prr-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>, <i data-x="fire-navigate-prr-sourceElement">sourceElement</i> set
to <var>sourceElement</var>, <i
data-x="fire-navigate-prr-formDataEntryList">formDataEntryList</i> set to
<var>entryListForFiring</var>, <i data-x="fire-navigate-prr-destinationURL">destinationURL</i>
set to <var>url</var>, and <i
data-x="fire-navigate-prr-navigationAPIState">navigationAPIState</i> set to
<var>navigationAPIStateForFiring</var>.</p></li>
<li><p>If <var>continue</var> is false, then return.</p>
</ol>
<p class="note">It is possible for navigations with <var>userInvolvement</var> of "<code
data-x="uni-browser-ui">browser UI</code>" or initiated by a <span data-x="same
origin-domain">cross origin-domain</span> <var>sourceDocument</var> to fire <code
data-x="event-navigate">navigate</code> events, if they go through the earlier <span
data-x="navigate-fragid">navigate to a fragment</span> path.</p>
</li>
<li>
<p><span>In parallel</span>, run these steps:</p>
<ol>
<li><p>Let <var>unloadPromptCanceled</var> be the result of <span>checking if unloading is
canceled</span> for <var>navigable</var>'s <span data-x="nav-document">active
document</span>'s <span>inclusive descendant navigables</span>.</p>
<li>
<p>If <var>unloadPromptCanceled</var> is true, or <var>navigable</var>'s <span>ongoing
navigation</span> is no longer <var>navigationId</var>, then:</p>
<ol>
<li><p>Invoke <span>WebDriver BiDi navigation failed</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>url</var>.</p></li>
<li><p>Abort these steps.</p></li>
</ol>
</li>
<li><p><span>Queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>navigable</var>'s <span data-x="nav-window">active window</span> to
<span>abort a document and its descendants</span> given <var>navigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li id="navigation-create-document-state">
<p>Let <var>documentState</var> be a new <span>document state</span> with</p>
<dl class="props">
<dt><span data-x="document-state-request-referrer-policy">request referrer policy</span></dt>
<dd><var>referrerPolicy</var></dd>
<dt><span data-x="document-state-initiator-origin">initiator origin</span></dt>
<dd><var>initiatorOriginSnapshot</var></dd>
<dt><span data-x="document-state-resource">resource</span></dt>
<dd><var>documentResource</var></dd>
<dt><span data-x="document-state-nav-target-name">navigable target name</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-target">target name</span></dd>
</dl>
<p class="note">The <span data-x="document-state-nav-target-name">navigable target
name</span> can get cleared under various conditions later in the navigation process, before
the document state is finalized.</p>
</li>
<li>
<p>If <var>url</var> <span>matches <code>about:blank</code></span> or
is <code>about:srcdoc</code>, then:</p>
<ol>
<li><p>Set <var>documentState</var>'s <span data-x="document-state-origin">origin</span> to
<var>initiatorOriginSnapshot</var>.</p></li>
<li><p>Set <var>documentState</var>'s <span data-x="document-state-about-base-url">about base
URL</span> to <var>initiatorBaseURLSnapshot</var>.</p></li>
</ol>
</li>
<li><p>Let <var>historyEntry</var> be a new <span>session history entry</span>, with its <span
data-x="she-url">URL</span> set to <var>url</var> and its <span
data-x="she-document-state">document state</span> set to
<var>documentState</var>.</p></li>
<li><p>Let <var>navigationParams</var> be null.</p></li>
<li>
<p>If <var>response</var> is non-null:</p>
<p class="note" id="note-navigate-called-with-response">The <span>navigate</span> algorithm
is only supplied with a <span data-x="concept-response">response</span> as part of the
<code>object</code> and <code>embed</code> processing models, or for processing parts of
<span data-x="navigate-multipart-x-mixed-replace"><code>multipart/x-mixed-replace</code>
responses</span> after the initial response.</p>
<ol>
<li><p>Let <var>policyContainer</var> be the result of <span data-x="determining navigation
params policy container">determining navigation params policy container</span> given <span
data-x="concept-response">response</span>'s <span data-x="concept-response-url">URL</span>,
null, a <span data-x="clone a policy container">clone</span> of the
<var>sourceDocument</var>'s <span data-x="concept-document-policy-container">policy
container</span>, <var>navigable</var>'s <span data-x="nav-container-document">container
document</span>'s <span data-x="concept-document-policy-container">policy container</span>,
and null.</p></li>
<li><p>Let <var>finalSandboxFlags</var> be the <span data-x="set union">union</span> of
<var>targetSnapshotParams</var>'s <span data-x="target-snapshot-params-sandbox">sandboxing
flags</span> and <var>policyContainer</var>'s <span data-x="policy-container-csp-list">CSP
list</span>'s <span>CSP-derived sandboxing flags</span>.</p></li>
<li><p>Let <var>responseOrigin</var> be the result of <span>determining the origin</span>
given <var>response</var>'s <span data-x="concept-response-url">URL</span>,
<var>finalSandboxFlags</var>, and <var>documentState</var>'s <span
data-x="document-state-initiator-origin">initiator origin</span>.</p></li>
<li><p>Let <var>coop</var> be a new <span>opener policy</span>.</p></li>
<li>
<p>Let <var>coopEnforcementResult</var> be a new <span
data-x="coop-enforcement-result">opener policy enforcement result</span>
with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>response</var>'s <span data-x="concept-response-url">URL</span></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
</dl>
</li>
<li>
<p>Set <var>navigationParams</var> to a new <span>navigation params</span>, with</p>
<dl class="props">
<dt><span data-x="navigation-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="navigation-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="navigation-params-request">request</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-response">response</span></dt>
<dd><var>response</var></dd>
<dt><span data-x="navigation-params-fetch-controller">fetch controller</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-commit-early-hints">commit early hints</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span></dt>
<dd><var>coopEnforcementResult</var></dd>
<dt><span data-x="navigation-params-reserved-environment">reserved environment</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="navigation-params-policy-container">policy container</span></dt>
<dd><var>policyContainer</var></dd>
<dt><span data-x="navigation-params-sandboxing">final sandboxing flag set</span></dt>
<dd><var>finalSandboxFlags</var></dd>
<dt><span data-x="navigation-params-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
<dt><span data-x="navigation-params-nav-timing-type">navigation timing type</span></dt>
<dd>"<code data-x="dom-navigationtimingtype-navigate">navigate</code>"</dd>
<dt><span data-x="navigation-params-about-base-url">about base URL</span></dt>
<dd><var>documentState</var>'s <span data-x="document-state-about-base-url">about base
URL</span></dd>
<dt><span data-x="navigation-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
</ol>
</li>
<li>
<p><span>Attempt to populate the history entry's document</span> for <var>historyEntry</var>,
given <var>navigable</var>, "<code
data-x="dom-navigationtimingtype-navigate">navigate</code>", <var>sourceSnapshotParams</var>,
<var>targetSnapshotParams</var>, <var>userInvolvement</var>, <var>navigationId</var>,
<var>navigationParams</var>, <var>cspNavigationType</var>, with <i
data-x="attempt-to-populate-allow-post">allowPOST</i> set to true and <i
data-x="attempt-to-populate-completion-steps">completionSteps</i> set to the following
step:</p>
<ol>
<li><p><span data-x="tn-append-session-history-traversal-steps">Append session history
traversal steps</span> to <var>navigable</var>'s <span
data-x="nav-traversable">traversable</span> to <span>finalize a cross-document
navigation</span> given <var>navigable</var>, <var>historyHandling</var>,
<var>userInvolvement</var>, and <var>historyEntry</var>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<h5>Ending navigation</h5>
<p>Although the usual cross-document navigation case will first foray into <a
href="#populating-a-session-history-entry">populating a session history entry</a> with a
<code>Document</code>, all navigations that don't get aborted will ultimately end up calling into
one of the below algorithms.</p>
<h6>The usual cross-document navigation case</h6>
<p>To <dfn>finalize a cross-document navigation</dfn> given a <span>navigable</span>
<var>navigable</var>, a <span>history handling behavior</span> <var>historyHandling</var>, a
<span>user navigation involvement</span> <var>userInvolvement</var>, and a <span>session history
entry</span> <var>historyEntry</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running on <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable's</span> <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>Set <var>navigable</var>'s <span>is delaying <code data-x="event-load">load</code>
events</span> to false.</p></li>
<li>
<p>If <var>historyEntry</var>'s <span data-x="she-document">document</span> is null, then
return.</p>
<p class="note">This means that <span data-x="attempt to populate the history entry's
document">attempting to populate the history entry's document</span> ended up not creating a
document, as a result of e.g., the navigation being canceled by a subsequent navigation, a 204
No Content response, etc.</p>
</li>
<li id="resetBCName">
<p>If all of the following are true:</p>
<ul>
<li><p><var>navigable</var>'s <span data-x="nav-parent">parent</span> is null;</p></li>
<li><p><var>historyEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-bc">browsing context</span> is not an <span>auxiliary browsing
context</span> whose <span>opener browsing context</span> is non-null; and</p></li>
<li><p><var>historyEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-origin">origin</span> is not <var>navigable</var>'s <span
data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span>,</p></li>
</ul>
<p>then set <var>historyEntry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-nav-target-name">navigable target name</span> to the empty
string.</p>
</li>
<li><p>Let <var>entryToReplace</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span> if
<var>historyHandling</var> is "<code data-x="NavigationHistoryBehavior-replace">replace</code>",
otherwise null.</p></li>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li><p>Let <var>targetStep</var> be null.</p></li>
<li><p>Let <var>targetEntries</var> be the result of <span>getting session history
entries</span> for <var>navigable</var>.</p></li>
<li>
<p>If <var>entryToReplace</var> is null, then:</p>
<ol>
<li><p><span>Clear the forward session history</span> of <var>traversable</var>.</p></li>
<li><p>Set <var>targetStep</var> to <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span> + 1.</p></li>
<li><p>Set <var>historyEntry</var>'s <span data-x="she-step">step</span> to
<var>targetStep</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>historyEntry</var> to
<var>targetEntries</var>.</p></li>
</ol>
<p>Otherwise:</p>
<ol>
<li><p><span data-x="list replace">Replace</span> <var>entryToReplace</var> with
<var>historyEntry</var> in <var>targetEntries</var>.</p></li>
<li><p>Set <var>historyEntry</var>'s <span data-x="she-step">step</span> to
<var>entryToReplace</var>'s <span data-x="she-step">step</span>.</p></li>
<li><p>If <var>historyEntry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-origin">origin</span> is <span>same origin</span> with
<var>entryToReplace</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span>, then set <var>historyEntry</var>'s <span
data-x="she-navigation-api-key">navigation API key</span> to <var>entryToReplace</var>'s <span
data-x="she-navigation-api-key">navigation API key</span>.</p></li>
<li><p>Set <var>targetStep</var> to <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span>.</p></li>
</ol>
</li>
<li><p><span>Apply the push/replace history step</span> <var>targetStep</var> to
<var>traversable</var> given <var>historyHandling</var> and <var>userInvolvement</var>.</p></li>
</ol>
<h6><dfn data-x="javascript protocol">The <code>javascript:</code> URL special case</dfn></h6>
<p class="XXX"><code data-x="javascript protocol">javascript:</code> URLs have a <a
href="https://github.com/whatwg/html/labels/topic%3A%20javascript%3A%20URLs">dedicated label</a>
on the issue tracker documenting various problems with their specification.</p>
<p>To <dfn>navigate to a <code>javascript:</code> URL</dfn>, given a <span>navigable</span>
<var>targetNavigable</var>, a <span>URL</span> <var>url</var>, a <span>history handling
behavior</span> <var>historyHandling</var>, a <span>source snapshot params</span>
<var>sourceSnapshotParams</var>, an <span>origin</span> <var>initiatorOrigin</var>, a <span>user
navigation involvement</span> <var>userInvolvement</var>, and a string
<var>cspNavigationType</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>historyHandling</var> is "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p></li>
<li><p><span>Set the ongoing navigation</span> for <var>targetNavigable</var> to null.</p></li>
<li><p>If <var>initiatorOrigin</var> is not <span>same origin-domain</span> with
<var>targetNavigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span>, then return.</p></li>
<li>
<p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>url</var> and whose <span
data-x="concept-request-policy-container">policy container</span> is
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-policy-container">source
policy container</span>.</p>
<p class="note">This is a synthetic <span data-x="concept-request">request</span> solely for
plumbing into the next step. It will never hit the network.</p>
</li>
<li><p>If the result of <span>should navigation request of type be blocked by Content Security
Policy?</span> given <var>request</var> and <var>cspNavigationType</var> is "<code
data-x="">Blocked</code>", then return. <ref>CSP</ref></p></li>
<li><p>Let <var>newDocument</var> be the result of <span data-x="evaluate a javascript:
URL">evaluating a <code>javascript:</code> URL</span> given <var>targetNavigable</var>,
<var>url</var>, <var>initiatorOrigin</var>, and <var>userInvolvement</var>.</p></li>
<li>
<p>If <var>newDocument</var> is null, then return.</p>
<p class="note">In this case, some JavaScript code was executed, but no new
<code>Document</code> was created, so we will not perform a navigation.</p>
</li>
<li><p><span>Assert</span>: <var>initiatorOrigin</var> is <var>newDocument</var>'s <span
data-x="concept-document-origin">origin</span>.</p></li>
<li><p>Let <var>entryToReplace</var> be <var>targetNavigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>Let <var>oldDocState</var> be <var>entryToReplace</var>'s <span
data-x="she-document-state">document state</span>.</p></li>
<li>
<p>Let <var>documentState</var> be a new <span>document state</span> with</p>
<dl class="props">
<dt><span data-x="document-state-document">document</span></dt>
<dd><var>newDocument</var></dd>
<dt><span data-x="document-state-history-policy-container">history policy container</span></dt>
<dd>a <span data-x="clone a policy container">clone</span> of the <var>oldDocState</var>'s
<span data-x="document-state-history-policy-container">history policy container</span> if it is
non-null; null otherwise</dd>
<dt><span data-x="document-state-request-referrer">request referrer</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-request-referrer">request
referrer</span></dd>
<dt><span data-x="document-state-request-referrer-policy">request referrer policy</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-request-referrer-policy">request
referrer policy</span> <span class="XXX">or should this be the <var>referrerPolicy</var> that
was passed to <span>navigate</span>?</span></dd>
<dt><span data-x="document-state-initiator-origin">initiator origin</span></dt>
<dd><var>initiatorOrigin</var></dd>
<dt><span data-x="document-state-origin">origin</span></dt>
<dd><var>initiatorOrigin</var></dd>
<dt><span data-x="document-state-about-base-url">about base URL</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-about-base-url">about base
URL</span></dd>
<dt><span data-x="document-state-resource">resource</span></dt>
<dd>null</dd>
<dt><span data-x="document-state-ever-populated">ever populated</span></dt>
<dd>true</dd>
<dt><span data-x="document-state-nav-target-name">navigable target name</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-nav-target-name">navigable target
name</span></dd>
</dl>
</li>
<li>
<p>Let <var>historyEntry</var> be a new <span>session history entry</span>, with</p>
<dl class="props">
<dt><span data-x="she-url">URL</span></dt>
<dd><var>entryToReplace</var>'s <span data-x="she-url">URL</span></dd>
<dt><span data-x="she-document-state">document state</span></dt>
<dd><var>documentState</var></dd>
</dl>
<p class="note">For the <span data-x="she-url">URL</span>, we do <em>not</em> use
<var>url</var>, i.e. the actual <code data-x="javascript protocol">javascript:</code> URL that
the <span>navigate</span> algorithm was called with. This means <code data-x="javascript
protocol">javascript:</code> URLs are never stored in session history, and so can never be
traversed to.</p>
</li>
<li><p><span data-x="tn-append-session-history-traversal-steps">Append session history traversal
steps</span> to <var>targetNavigable</var>'s <span data-x="nav-traversable">traversable</span>
to <span>finalize a cross-document navigation</span> with <var>targetNavigable</var>,
<var>historyHandling</var>, <var>userInvolvement</var>, and <var>historyEntry</var>.</p></li>
</ol>
<p>To <dfn>evaluate a <code>javascript:</code> URL</dfn> given a <span>navigable</span>
<var>targetNavigable</var>, a <span>URL</span> <var>url</var>, an <span>origin</span>
<var>newDocumentOrigin</var>, and a <span>user navigation involvement</span>
<var>userInvolvement</var>:</p>
<ol>
<li><p>Let <var>urlString</var> be the result of running the <span
data-x="concept-url-serializer">URL serializer</span> on <var>url</var>.</p></li>
<li><p>Let <var>encodedScriptSource</var> be the result of removing the leading "<code
data-x="">javascript:</code>" from <var>urlString</var>.</p></li>
<li><p>Let <var>scriptSource</var> be the <span data-x="UTF-8 decode">UTF-8 decoding</span> of
the <span data-x="percent-decode">percent-decoding</span> of
<var>encodedScriptSource</var>.</p></li>
<!-- <body onload="w('test')"> and javascript:%EF%BB%BF'test' both work, so we assume
that JavaScript is stripping the BOM, and we don't have to -->
<!-- https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2639 -> about:blank
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2640 -> javascript:'test' in
Firefox, about:blank otherwise -->
<li><p>Let <var>settings</var> be <var>targetNavigable</var>'s <span
data-x="nav-document">active document</span>'s <span>relevant settings object</span>.</p></li>
<li><p>Let <var>baseURL</var> be <var>settings</var>'s <span>API base URL</span>.</p></li>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> given
<var>scriptSource</var>, <var>settings</var>, <var>baseURL</var>, and the <span>default script
fetch options</span>.</p></li>
<li><p>Let <var>evaluationStatus</var> be the result of <span data-x="run a classic
script">running the classic script</span> <var>script</var>.</p></li>
<li><p>Let <var>result</var> be null.</p></li>
<li><p>If <var>evaluationStatus</var> is a normal completion, and
<var>evaluationStatus</var>.[[Value]] is a String, then set <var>result</var> to
<var>evaluationStatus</var>.[[Value]].</p></li>
<li><p>Otherwise, return null.</p></li>
<li>
<p>Let <var>response</var> be a new <span data-x="concept-response">response</span> with</p>
<dl class="props">
<dt><span data-x="concept-response-url">URL</span></dt>
<dd><var>targetNavigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-url">URL</span></dd>
<dt><span data-x="concept-response-header-list">header list</span></dt>
<dd>« (`<code>Content-Type</code>`, `<code data-x="">text/html;charset=utf-8</code>`) »</dd>
<dt><span data-x="concept-response-body">body</span></dt>
<dd>the <span data-x="UTF-8 encode">UTF-8 encoding</span> of <var>result</var>, <span>as a
body</span></dd>
</dl>
<p class="note">The encoding to UTF-8 means that unpaired <span
data-x="surrogate">surrogates</span> will not roundtrip, once the HTML parser decodes the
response body.</p>
</li>
<li><p>Let <var>policyContainer</var> be <var>targetNavigable</var>'s <span
data-x="nav-document">active document</span>'s <span
data-x="concept-document-policy-container">policy container</span>.</p>
<li><p>Let <var>finalSandboxFlags</var> be <var>policyContainer</var>'s <span
data-x="policy-container-csp-list">CSP list</span>'s <span>CSP-derived sandboxing
flags</span>.</p></li>
<li><p>Let <var>coop</var> be <var>targetNavigable</var>'s <span data-x="nav-document">active
document</span>'s <span data-x="concept-document-coop">opener policy</span>.</p></li>
<li>
<p>Let <var>coopEnforcementResult</var> be a new <span data-x="coop-enforcement-result">opener
policy enforcement result</span> with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>url</var></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>newDocumentOrigin</var></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
</dl>
</li>
<li>
<p>Let <var>navigationParams</var> be a new <span>navigation params</span>, with</p>
<dl class="props">
<dt><span data-x="navigation-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="navigation-params-navigable">navigable</span></dt>
<dd><var>targetNavigable</var></dd>
<dt><span data-x="navigation-params-request">request</span></dt>
<dd>null <span class="XXX">this will cause the referrer of the resulting <code>Document</code>
to be null; is that correct?</span></dd>
<dt><span data-x="navigation-params-response">response</span></dt>
<dd><var>response</var></dd>
<dt><span data-x="navigation-params-fetch-controller">fetch controller</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-commit-early-hints">commit early hints</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span></dt>
<dd><var>coopEnforcementResult</var></dd>
<dt><span data-x="navigation-params-reserved-environment">reserved environment</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-origin">origin</span></dt>
<dd><var>newDocumentOrigin</var></dd>
<dt><span data-x="navigation-params-policy-container">policy container</span></dt>
<dd><var>policyContainer</var></dd>
<dt><span data-x="navigation-params-sandboxing">final sandboxing flag set</span></dt>
<dd><var>finalSandboxFlags</var></dd>
<dt><span data-x="navigation-params-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
<dt><span data-x="navigation-params-nav-timing-type">navigation timing type</span></dt>
<dd>"<code data-x="dom-navigationtimingtype-navigate">navigate</code>"</dd>
<dt><span data-x="navigation-params-about-base-url">about base URL</span></dt>
<dd><var>targetNavigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-about-base-url">about base URL</span></dd>
<dt><span data-x="navigation-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
<li><p>Return the result of <span data-x="navigate-html">loading an HTML document</span> given
<var>navigationParams</var>.</p></li>
</ol>
<h6 id="scroll-to-fragid">Fragment navigations</h6>
<p>To <dfn data-x="navigate-fragid">navigate to a fragment</dfn> given a <span>navigable</span>
<var>navigable</var>, a <span>URL</span> <var>url</var>, a <span>history handling behavior</span>
<var>historyHandling</var>, a <span>user navigation involvement</span> <var>userInvolvement</var>,
an <code>Element</code>-or-null <var>sourceElement</var>, a <span>serialized state</span>-or-null
<var>navigationAPIState</var>, and a <span>navigation ID</span> <var>navigationId</var>:</p>
<ol>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>destinationNavigationAPIState</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-navigation-api-state">navigation API state</span>.</p></li>
<li><p>If <var>navigationAPIState</var> is not null, then set
<var>destinationNavigationAPIState</var> to <var>navigationAPIState</var>.</p></li>
<li><p>Let <var>continue</var> be the result of <span data-x="fire a push/replace/reload navigate
event">firing a push/replace/reload <code data-x="event-navigate">navigate</code> event</span> at
<var>navigation</var> with <i data-x="fire-navigate-prr-navigationType">navigationType</i> set to
<var>historyHandling</var>, <i data-x="fire-navigate-prr-isSameDocument">isSameDocument</i> set
to true, <i data-x="fire-navigate-prr-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>, <i data-x="fire-navigate-prr-sourceElement">sourceElement</i> set
to <var>sourceElement</var>, <i data-x="fire-navigate-prr-destinationURL">destinationURL</i>
set to <var>url</var>, and <i
data-x="fire-navigate-prr-navigationAPIState">navigationAPIState</i> set to
<var>destinationNavigationAPIState</var>.</p></li>
<li><p>If <var>continue</var> is false, then return.</p>
<li>
<p>Let <var>historyEntry</var> be a new <span>session history entry</span>, with</p>
<dl class="props">
<dt><span data-x="she-url">URL</span></dt>
<dd><var>url</var></dd>
<dt><span data-x="she-document-state">document state</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span>'s <span data-x="she-document-state">document state</span></dd>
<dt><span data-x="she-navigation-api-state">navigation API state</span></dt>
<dd><var>destinationNavigationAPIState</var></dd>
<dt><span data-x="she-scroll-restoration-mode">scroll restoration mode</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span>'s <span data-x="she-scroll-restoration-mode">scroll restoration mode</span></dd>
</dl>
<div class="note">
<p>For navigations peformed with <code
data-x="dom-Navigation-navigate">navigation.navigate()</code>, the value provided by the <code
data-x="dom-NavigationNavigateOptions-state">state</code> option is used for the new <span
data-x="she-navigation-api-state">navigation API state</span>. (This will set it to the
serialization of undefined, if no value is provided for that option.) For other fragment
navigations, including user-initiated ones, the <span
data-x="she-navigation-api-state">navigation API state</span> is carried over from the previous
entry.</p>
<p>The <span data-x="she-classic-history-api-state">classic history API state</span> is never
carried over.</p>
</div>
</li>
<li><p>Let <var>entryToReplace</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span> if
<var>historyHandling</var> is "<code data-x="NavigationHistoryBehavior-replace">replace</code>",
otherwise null.</p></li>
<li><p>Let <var>history</var> be <var>navigable</var>'s <span data-x="nav-document">active
document</span>'s <span data-x="doc-history">history object</span>.</p></li>
<li><p>Let <var>scriptHistoryIndex</var> be <var>history</var>'s <span
data-x="concept-history-index">index</span>.</p></li>
<li><p>Let <var>scriptHistoryLength</var> be <var>history</var>'s <span
data-x="concept-history-length">length</span>.</p></li>
<li>
<p>If <var>historyHandling</var> is "<code data-x="NavigationHistoryBehavior-push">push</code>",
then:</p>
<ol>
<li><p>Set <var>history</var>'s <span data-x="concept-history-state">state</span> to
null.</p></li>
<li><p>Increment <var>scriptHistoryIndex</var>.</p></li>
<li><p>Set <var>scriptHistoryLength</var> to <var>scriptHistoryIndex</var> + 1.</p></li>
</ol>
</li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-url">URL</span> to <var>url</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span> to <var>historyEntry</var>.</p></li>
<li>
<p><span>Update document for history step application</span> given <var>navigable</var>'s
<span data-x="nav-document">active document</span>, <var>historyEntry</var>, true,
<var>scriptHistoryIndex</var>, <var>scriptHistoryLength</var>, and
<var>historyHandling</var>.</p>
<p class="note">This algorithm will be called twice as a result of a single fragment
navigation: once synchronously, where best-guess values <var>scriptHistoryIndex</var> and
<var>scriptHistoryLength</var> are set, <code data-x="dom-history-state">history.state</code>
is nulled out, and various events are fired; and once asynchronously, where the final values for
index and length are set, <code data-x="dom-history-state">history.state</code> remains
untouched, and no events are fired.</p>
</li>
<li>
<p><span>Scroll to the fragment</span> given <var>navigable</var>'s <span
data-x="nav-document">active document</span>.</p>
<p class="note">If the scrolling fails because the <code>Document</code> is new and the
relevant <span data-x="concept-id">ID</span> has not yet been parsed, then the second
asynchronous call to <span>update document for history step application</span> will take
care of scrolling.</p>
</li>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li>
<p><span data-x="tn-append-session-history-sync-nav-steps">Append the following session history
synchronous navigation steps</span> involving <var>navigable</var> to
<var>traversable</var>:</p>
<ol>
<li><p><span>Finalize a same-document navigation</span> given <var>traversable</var>,
<var>navigable</var>, <var>historyEntry</var>, <var>entryToReplace</var>,
<var>historyHandling</var>, and <var>userInvolvement</var>.</p></li>
<li><p>Invoke <span>WebDriver BiDi fragment navigated</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-url">url</span> is <var>url</var>, and <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>".</p></li>
</ol>
</li>
</ol>
<p>To <dfn>finalize a same-document navigation</dfn> given a <span>traversable navigable</span>
<var>traversable</var>, a <span>navigable</span> <var>targetNavigable</var>, a <span>session
history entry</span> <var>targetEntry</var>, a <span>session history entry</span>-or-null
<var>entryToReplace</var>, a <span>history handling behavior</span> <var>historyHandling</var>,
and a <span>user navigation involvement</span> <var>userInvolvement</var>:</p>
<p class="note">This is used by both <span data-x="navigate-fragid">fragment navigations</span>
and by the <span>URL and history update steps</span>, which are the only synchronous updates to
session history. By virtue of being synchronous, those algorithms are performed outside of the
<span>top-level traversable</span>'s <span data-x="tn-session-history-traversal-queue">session
history traversal queue</span>. This puts them out of sync with the <span>top-level
traversable</span>'s <span data-x="tn-current-session-history-step">current session history
step</span>, so this algorithm is used to resolve conflicts due to race conditions.</p>
<ol>
<li><p><span>Assert</span>: this is running on <var>traversable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>If <var>targetNavigable</var>'s <span data-x="nav-active-history-entry">active session
history entry</span> is not <var>targetEntry</var>, then return.</p></li>
<li><p>Let <var>targetStep</var> be null.</p></li>
<li><p>Let <var>targetEntries</var> be the result of <span>getting session history
entries</span> for <var>targetNavigable</var>.</p></li>
<li>
<p>If <var>entryToReplace</var> is null, then:</p>
<ol>
<li><p><span>Clear the forward session history</span> of <var>traversable</var>.</p></li>
<li><p>Set <var>targetStep</var> to <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span> + 1.</p></li>
<li><p>Set <var>targetEntry</var>'s <span data-x="she-step">step</span> to
<var>targetStep</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>targetEntry</var> to
<var>targetEntries</var>.</p></li>
</ol>
<p>Otherwise:</p>
<ol>
<li><p><span data-x="list replace">Replace</span> <var>entryToReplace</var> with
<var>targetEntry</var> in <var>targetEntries</var>.</p></li>
<li><p>Set <var>targetEntry</var>'s <span data-x="she-step">step</span> to
<var>entryToReplace</var>'s <span data-x="she-step">step</span>.</p></li>
<li><p>Set <var>targetStep</var> to <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span>.</p></li>
</ol>
</li>
<li>
<p><span>Apply the push/replace history step</span> <var>targetStep</var> to
<var>traversable</var> given <var>historyHandling</var> and <var>userInvolvement</var>.</p>
<p class="note">This is done even for "<code
data-x="NavigationHistoryBehavior-replace">replace</code>" navigations, as it resolves race
conditions across multiple synchronous navigations.</p>
</li>
</ol>
<h6>Non-fetch schemes and external software</h6>
<p>The input to <span>attempt to create a non-fetch scheme document</span> is the <dfn>non-fetch
scheme navigation params</dfn> <span>struct</span>. It is a lightweight version of
<span>navigation params</span> which only carries parameters relevant to the non-<span>fetch
scheme</span> navigation case. It has the following <span data-x="struct item">items</span>:</p>
<!--
If modifying this struct, try to keep it somewhat parallel to the normal navigation params
struct, where that makes sense. See the comment there.
-->
<dl>
<dt><dfn data-x="non-fetch-scheme-params-id">id</dfn></dt>
<dd>null or a <span>navigation ID</span></dd>
<dt><dfn data-x="non-fetch-scheme-params-navigable">navigable</dfn></dt>
<dd>the <span>navigable</span> experiencing the navigation</dd>
<dt><dfn data-x="non-fetch-scheme-params-url">URL</dfn></dt>
<dd>a <span>URL</span></dd>
<dt><dfn data-x="non-fetch-scheme-params-target-sandbox">target snapshot sandboxing flags</dfn></dt>
<dd>the <span>target snapshot params</span>'s <span
data-x="target-snapshot-params-sandbox">sandboxing flags</span> present during navigation</dd>
<dt><dfn data-x="non-fetch-scheme-params-source-activation">source snapshot has transient activation</dfn></dt>
<dd>a copy of the <span>source snapshot params</span>'s <span
data-x="source-snapshot-params-activation">has transient activation</span> boolean present during
activation</dd>
<dt><dfn data-x="non-fetch-scheme-params-initiator-origin">initiator origin</dfn></dt>
<dd>
<p>an <span>origin</span> possibly for use in a user-facing prompt to confirm the invocation of
an external software package</p>
<p class="note">This differs slightly from a <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-initiator-origin">initiator origin</span> in that a
<span>non-fetch scheme navigation params</span>'s <span
data-x="non-fetch-scheme-params-initiator-origin">initiator origin</span> follows redirects up
to the last <span>fetch scheme</span> URL in a redirect chain that ends in a non-<span>fetch
scheme</span> URL.</p>
</dd>
<dt><dfn data-x="non-fetch-scheme-params-nav-timing-type">navigation timing type</dfn></dt>
<dd>a <code>NavigationTimingType</code> used for <span data-x="create the navigation timing
entry">creating the navigation timing entry</span> for the new <code>Document</code> (if one is
created)</dd>
<dt><dfn data-x="non-fetch-scheme-params-user-involvement">user involvement</dfn></dt>
<dd>a <span>user navigation involvement</span> used when <span
data-x="obtain-browsing-context-navigation">obtaining a browsing context</span> for the new
<code>Document</code> (if one is created)</dd>
</dl>
<p id="process-a-navigate-url-scheme">To <dfn>attempt to create a non-fetch scheme document</dfn>,
given a <span>non-fetch scheme navigation params</span> <var>navigationParams</var>:</p>
<ol>
<li>Let <var>url</var> be <var>navigationParams</var>'s <span
data-x="non-fetch-scheme-params-url">URL</span>.</li>
<li>Let <var>navigable</var> be <var>navigationParams</var>'s <span
data-x="non-fetch-scheme-params-navigable">navigable</span>.</li>
<li>
<p>If <var>url</var> is to be handled using a mechanism that does not affect
<var>navigable</var>, e.g., because <var>url</var>'s <span
data-x="concept-url-scheme">scheme</span> is handled externally, then:</p>
<ol>
<li><p><span>Hand-off to external software</span> given <var>url</var>, <var>navigable</var>,
<var>navigationParams</var>'s <span data-x="non-fetch-scheme-params-target-sandbox">target
snapshot sandboxing flags</span>, <var>navigationParams</var>'s <span
data-x="non-fetch-scheme-params-source-activation">source snapshot has transient
activation</span>, and <var>navigationParams</var>'s <span
data-x="non-fetch-scheme-params-initiator-origin">initiator origin</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
</li>
<li>
<p>Handle <var>url</var> by displaying some sort of inline content, e.g., an error message
because the specified scheme is not one of the supported protocols, or an inline prompt to allow
the user to select <span data-x="dom-navigator-registerProtocolHandler">a registered
handler</span> for the given scheme. Return the result of <span
data-x="navigate-ua-inline">displaying the inline content</span> given <var>navigable</var>,
<var>navigationParams</var>'s <span data-x="non-fetch-scheme-params-id">id</span>,
<var>navigationParams</var>'s <span data-x="non-fetch-scheme-params-nav-timing-type">navigation
timing type</span>, and <var>navigationParams</var>'s <span
data-x="non-fetch-scheme-params-user-involvement">user involvement</span>.</p>
<p class="note">In the case of a registered handler being used, <span>navigate</span> will be
invoked with a new URL.</p>
</li>
</ol>
<p>To <dfn>hand-off to external software</dfn> given a <span>URL</span> or <span
data-x="concept-response">response</span> <var>resource</var>, a <span>navigable</span>
<var>navigable</var>, a <span>sandboxing flag set</span> <var>sandboxFlags</var>, a boolean
<var>hasTransientActivation</var>, and an <span>origin</span> <var>initiatorOrigin</var>, user
agents should:</p>
<ol>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>navigable</var> is not a <span>top-level traversable</span>;</p></li>
<li><p><var>sandboxFlags</var> has its <span>sandboxed custom protocols navigation browsing
context flag</span> set; and</p></li>
<li><p><var>sandboxFlags</var> has its <span>sandboxed top-level navigation with user
activation browsing context flag</span> set, or <var>hasTransientActivation</var> is
false,</p></li>
</ul>
<p>then return without invoking the external software package.</p>
<p class="note">Navigation inside an iframe toward external software can be seen by users as a
new popup or a new top-level navigation. That's why its is allowed in sandboxed
<code>iframe</code> only when one of <code
data-x="attr-iframe-sandbox-allow-popups">allow-popups</code>, <code
data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code>, <code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>,
or <code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code>
is specified.</p>
</li>
<li>
<p>Perform the appropriate handoff of <var>resource</var> while attempting to mitigate the risk
that this is an attempt to exploit the target software. For example, user agents could prompt
the user to confirm that <var>initiatorOrigin</var> is to be allowed to invoke the external
software in question. In particular, if <var>hasTransientActivation</var> is false, then the
user agent should not invoke the external software package without prior user confirmation.</p>
<p class="example">For example, there could be a vulnerability in the target software's URL
handler which a hostile page would attempt to exploit by tricking a user into clicking a
link.</p>
</li>
</ol>
<h5>Preventing navigation</h5>
<p>A couple of scenarios can intervene early in the navigation process and put the whole thing to
a halt. This can be especially exciting when multiple <span data-x="navigable">navigables</span>
are navigating at the same time, due to a session history traversal.</p>
<p>A <span>navigable</span> <var>source</var> is <dfn id="allowed-to-navigate">allowed by
sandboxing to navigate</dfn> a second <span>navigable</span> <var>target</var>, given a
<span>source snapshot params</span> <var>sourceSnapshotParams</var>, if the following steps
return true:</p>
<ol>
<li><p>If <var>source</var> is <var>target</var>, then return true.</p></li>
<li><p>If <var>source</var> is an ancestor of <var>target</var>, then return true.</p></li>
<li>
<p>If <var>target</var> is an ancestor of <var>source</var>, then:</p>
<ol>
<li><p>If <var>target</var> is not a <span>top-level traversable</span>, then return
true.</p></li>
<li><p>If <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-activation">has transient activation</span> is true, and
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-sandbox">sandboxing
flags</span>'s <span>sandboxed top-level navigation with user activation browsing context
flag</span> is set, then return false.</p></li>
<li><p>If <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-activation">has transient activation</span> is false, and
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-sandbox">sandboxing
flags</span>'s <span>sandboxed top-level navigation without user activation browsing context
flag</span> is set, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
</li>
<li>
<p>If <var>target</var> is a <span>top-level traversable</span>:</p>
<ol>
<li><p>If <var>source</var> is the <span>one permitted sandboxed navigator</span> of
<var>target</var>, then return true.</p></li>
<li><p>If <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-sandbox">sandboxing flags</span>'s <span>sandboxed navigation
browsing context flag</span> is set, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
</li>
<li><p>If <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-sandbox">sandboxing flags</span>'s <span>sandboxed navigation
browsing context flag</span> is set, then return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p id="prompt-to-unload-a-document"><span id="prompt-to-unload"></span><span
id="checking-if-unloading-is-user-canceled"></span>To <dfn data-x="checking if unloading is
canceled">check if unloading is canceled</dfn> for a <span>list</span> of <span
data-x="navigable">navigables</span> <var>navigablesThatNeedBeforeUnload</var>, given an optional
<span>traversable navigable</span> <var>traversable</var>, an optional integer
<var>targetStep</var>, and an optional <span>user navigation involvement</span>
<var>userInvolvementForNavigateEvent</var>, run these steps. They return "<code
data-x="">canceled-by-beforeunload</code>", "<code data-x="">canceled-by-navigate</code>", or
"<code data-x="">continue</code>".</p>
<ol>
<li><p>Let <var>documentsToFireBeforeunload</var> be the <span data-x="nav-document">active
document</span> of each <span data-x="list item">item</span> in
<var>navigablesThatNeedBeforeUnload</var>.</p></li>
<li><p>Let <var>unloadPromptShown</var> be false.</p></li>
<li><p>Let <var>finalStatus</var> be "<code data-x="">continue</code>".</p></li>
<li>
<p>If <var>traversable</var> was given, then:</p>
<ol>
<li><p><span>Assert</span>: <var>targetStep</var> and
<var>userInvolvementForNavigateEvent</var> were given.</p></li>
<li><p>Let <var>targetEntry</var> be the result of <span>getting the target history
entry</span> given <var>traversable</var> and <var>targetStep</var>.</p></li>
<li>
<p>If <var>targetEntry</var> is not <var>traversable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span>, and
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span> is the <span data-x="same origin">same</span> as
<var>traversable</var>'s <span data-x="nav-current-history-entry">current session history
entry</span>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span>, then:</p>
<div class="note">
<p>In this case, we're going to fire the <code data-x="event-navigate">navigate</code> event
for <var>traversable</var> here. Because <a
href="#navigate-event-traverse-can-be-canceled">under some circumstances</a> it might be
canceled, we need to do this separately from <a
href="#descendant-navigable-traversal-navigate-events">other traversal <code
data-x="event-navigate">navigate</code> events</a>, which happen later.</p>
<p>Additionally, because we want <code data-x="event-beforeunload">beforeunload</code> events
to fire before <code data-x="event-navigate">navigate</code> events, this means we need to
fire <code data-x="event-beforeunload">beforeunload</code> for <var>traversable</var> here
(if applicable), instead of doing it as part of the below loop over
<var>documentsToFireBeforeunload</var>.</p>
</div>
<ol>
<li><p>Let <var>eventsFired</var> be false.</p></li>
<li><p>Let <var>needsBeforeunload</var> be true if <var>navigablesThatNeedBeforeUnload</var>
<span data-x="list contains">contains</span> <var>traversable</var>; otherwise
false.</p></li>
<li><p>If <var>needsBeforeunload</var> is true, then <span data-x="list remove">remove</span>
<var>traversable</var>'s <span data-x="nav-document">active document</span> from
<var>documentsToFireBeforeunload</var>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>traversable</var>'s <span data-x="nav-window">active window</span> to perform the
following steps:</p>
<ol>
<li>
<p>If <var>needsBeforeunload</var> is true, then:</p>
<ol>
<li><p>Let (<var>unloadPromptShownForThisDocument</var>,
<var>unloadPromptCanceledByThisDocument</var>) be the result of running the <span>steps
to fire <code data-x="event-beforeunload">beforeunload</code></span> given
<var>traversable</var>'s <span data-x="nav-document">active document</span> and
false.</p></li>
<li><p>If <var>unloadPromptShownForThisDocument</var> is true, then set
<var>unloadPromptShown</var> to true.</p></li>
<li><p>If <var>unloadPromptCanceledByThisDocument</var> is true, then set
<var>finalStatus</var> to "<code data-x="">canceled-by-beforeunload</code>".</p></li>
</ol>
</li>
<li><p>If <var>finalStatus</var> is "<code data-x="">canceled-by-beforeunload</code>", then
abort these steps.</p></li>
<li><p>Let <var>navigation</var> be <var>traversable</var>'s <span
data-x="nav-window">active window</span>'s <span data-x="window-navigation-api">navigation
API</span>.</p></li>
<li><p>Let <var>navigateEventResult</var> be the result of <span data-x="fire a traverse
navigate event">firing a traverse <code data-x="event-navigate">navigate</code>
event</span> at <var>navigation</var> given <var>targetEntry</var> and
<var>userInvolvementForNavigateEvent</var>.</p></li>
<li><p>If <var>navigateEventResult</var> is false, then set <var>finalStatus</var> to
"<code data-x="">canceled-by-navigate</code>".</p></li>
<li><p>Set <var>eventsFired</var> to true.</p></li>
</ol>
</li>
<li><p>Wait until <var>eventsFired</var> is true.</p></li>
<li><p>If <var>finalStatus</var> is not "<code data-x="">continue</code>", then return
<var>finalStatus</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>totalTasks</var> be the <span data-x="list size">size</span> of
<var>documentsToFireBeforeunload</var>.</p></li>
<li><p>Let <var>completedTasks</var> be 0.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>document</var> of <var>documentsToFireBeforeunload</var>,
<span>queue a global task</span> on the <span>navigation and traversal task source</span> given
<var>document</var>'s <span>relevant global object</span> to run the steps:</p>
<ol>
<li><p>Let (<var>unloadPromptShownForThisDocument</var>,
<var>unloadPromptCanceledByThisDocument</var>) be the result of running the <span>steps to fire
<code data-x="event-beforeunload">beforeunload</code></span> given <var>document</var> and
<var>unloadPromptShown</var>.</p></li>
<li><p>If <var>unloadPromptShownForThisDocument</var> is true, then set
<var>unloadPromptShown</var> to true.</p></li>
<li><p>If <var>unloadPromptCanceledByThisDocument</var> is true, then set
<var>finalStatus</var> to "<code data-x="">canceled-by-beforeunload</code>".</p></li>
<li><p>Increment <var>completedTasks</var>.</p></li>
</ol>
</li>
<li><p>Wait for <var>completedTasks</var> to be <var>totalTasks</var>.</p></li>
<li><p>Return <var>finalStatus</var>.</p></li>
</ol>
<p>The <dfn>steps to fire <code data-x="event-beforeunload">beforeunload</code></dfn> given a
<code>Document</code> <var>document</var> and a boolean <var>unloadPromptShown</var> are:</p>
<ol>
<li><p>Let <var>unloadPromptCanceled</var> be false.</p></li>
<li><p>Increase the <var>document</var>'s <span>unload counter</span> by 1.</p></li>
<li><p>Increase <var>document</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>termination nesting level</span> by
1.</p></li>
<li><p>Let <var>eventFiringResult</var> be the result of <span data-x="concept-event-fire">firing
an event</span> named <code data-x="event-beforeunload">beforeunload</code> at
<var>document</var>'s <span>relevant global object</span>, using <code>BeforeUnloadEvent</code>,
with the <code data-x="dom-Event-cancelable">cancelable</code> attribute initialized to
true.</p></li>
<li><p>Decrease <var>document</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>termination nesting level</span> by
1.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>unloadPromptShown</var> is false;</p></li>
<li><p><var>document</var>'s <span>active sandboxing flag set</span> does not have its
<span>sandboxed modals flag</span> set;</p></li>
<li><p><var>document</var>'s <span>relevant global object</span> has <span>sticky
activation</span>;</p></li>
<li><p><var>eventFiringResult</var> is false, or the <code
data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code> attribute of <var>event</var> is
not the empty string; and</p></li>
<li><p>showing an unload prompt is unlikely to be annoying, deceptive, or pointless,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Set <var>unloadPromptShown</var> to true.</p></li>
<li><p>Let <var>userPromptHandler</var> be the result of <span>WebDriver BiDi user prompt
opened</span> with <var>document</var>'s <span>relevant global object</span>,
"<code data-x="">beforeunload</code>", and "".</p></li>
<li><p>If <var>userPromptHandler</var> is "<code data-x="">dismiss</code>", then set
<var>unloadPromptCanceled</var> to true.</p></li>
<li>
<p>If <var>userPromptHandler</var> is "<code data-x="">none</code>", then:</p>
<ul>
<li>
<p>Ask the user to confirm that they wish to unload the document, and <span>pause</span>
while waiting for the user's response.</p>
<p class="note">The message shown to the user is not customizable, but instead determined by
the user agent. In particular, the actual value of the <code
data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code> attribute is ignored.</p>
</li>
<li><p>If the user did not confirm the page navigation, then set
<var>unloadPromptCanceled</var> to true.</p></li>
</ul>
<li><p>Invoke <span>WebDriver BiDi user prompt closed</span> with <var>document</var>'s
<span>relevant global object</span>, "<code data-x="">beforeunload</code>", and true
if <var>unloadPromptCanceled</var> is false or false otherwise.</p></li>
</ol>
</li>
<li><p>Decrease <var>document</var>'s <span>unload counter</span> by 1.</p></li>
<li><p>Return (<var>unloadPromptShown</var>, <var>unloadPromptCanceled</var>).</p></li>
</ol>
<h5>Aborting navigation</h5>
<p id="concept-navigate-mature">Each <span>navigable</span> has an <dfn>ongoing navigation</dfn>,
which is a <span>navigation ID</span>, "<code data-x="">traversal</code>", or null, initially
null. It is used to track navigation aborting and to prevent any navigations from taking place
during <span data-x="apply the traverse history step">traversal</span>.</p>
<p>To <dfn>set the ongoing navigation</dfn> for a <span>navigable</span> <var>navigable</var> to
<var>newValue</var>:</p>
<ol>
<li><p>If <var>navigable</var>'s <span>ongoing navigation</span> is equal to <var>newValue</var>,
then return.</p></li>
<li><p><span>Inform the navigation API about aborting navigation</span> given
<var>navigable</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span>ongoing navigation</span> to
<var>newValue</var>.</p></li>
</ol>
<h4>Reloading and traversing</h4>
<p>To <dfn>reload</dfn> a <span>navigable</span> <var>navigable</var> given an optional
<span>serialized state</span>-or-null <dfn
data-x="reload-navigation-api-state"><var>navigationAPIState</var></dfn> (default null) and an
optional <span>user navigation involvement</span> <dfn
data-x="reload-user-involvement"><var>userInvolvement</var></dfn> (default "<code
data-x="uni-none">none</code>"):</p>
<ol>
<li>
<p>If <var>userInvolvement</var> is not "<code data-x="uni-browser-ui">browser UI</code>",
then:</p>
<ol>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span data-x="nav-window">active
window</span>'s <span data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>destinationNavigationAPIState</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-navigation-api-state">navigation API state</span>.</p></li>
<li><p>If <var>navigationAPIState</var> is not null, then set
<var>destinationNavigationAPIState</var> to <var>navigationAPIState</var>.</p></li>
<li><p>Let <var>continue</var> be the result of <span data-x="fire a push/replace/reload
navigate event">firing a push/replace/reload <code data-x="event-navigate">navigate</code>
event</span> at <var>navigation</var> with <i
data-x="fire-navigate-prr-navigationType">navigationType</i> set to "<code
data-x="dom-NavigationType-reload">reload</code>", <i
data-x="fire-navigate-prr-isSameDocument">isSameDocument</i> set to false, <i
data-x="fire-navigate-prr-userInvolvement">userInvolvement</i> set to
<var>userInvolvement</var>, <i data-x="fire-navigate-prr-destinationURL">destinationURL</i>
set to <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span>'s <span data-x="she-url">URL</span>, and <i
data-x="fire-navigate-prr-navigationAPIState">navigationAPIState</i> set to
<var>destinationNavigationAPIState</var>.</p></li>
<li><p>If <var>continue</var> is false, then return.</p></li>
</ol>
</li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> to true.</p></li>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session
history traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p><span>Apply the reload history step</span> to <var>traversable</var> given
<var>userInvolvement</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>traverse the history by a delta</dfn> given a <span>traversable navigable</span>
<var>traversable</var>, an integer <var>delta</var>, and an optional <code>Document</code> <dfn
data-x="traverse-sourceDocument"><var>sourceDocument</var></dfn>:</p>
<ol>
<li><p>Let <var>sourceSnapshotParams</var> and <var>initiatorToCheck</var> be null.</p></li>
<li><p>Let <var>userInvolvement</var> be "<code data-x="uni-browser-ui">browser
UI</code>".</p></li>
<li>
<p>If <var>sourceDocument</var> is given, then:</p>
<ol>
<li><p>Set <var>sourceSnapshotParams</var> to the result of <span>snapshotting source snapshot
params</span> given <var>sourceDocument</var>.</p></li>
<li><p>Set <var>initiatorToCheck</var> to <var>sourceDocument</var>'s <span>node
navigable</span>.</p></li>
<li><p>Set <var>userInvolvement</var> to "<code data-x="uni-none">none</code>".</p></li>
</ol>
</li>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session
history traversal steps</span> to <var>traversable</var>:</p>
<ol>
<li><p>Let <var>allSteps</var> be the result of <span>getting all used history steps</span>
for <var>traversable</var>.</p></li>
<li><p>Let <var>currentStepIndex</var> be the index of <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span> within
<var>allSteps</var>.</p></li>
<li><p>Let <var>targetStepIndex</var> be <var>currentStepIndex</var> plus
<var>delta</var>.</p></li>
<li><p>If <var>allSteps</var>[<var>targetStepIndex</var>] does not <span data-x="list
contains">exist</span>, then abort these steps.</p></li>
<li><p><span>Apply the traverse history step</span>
<var>allSteps</var>[<var>targetStepIndex</var>] to <var>traversable</var>, given
<var>sourceSnapshotParams</var>, <var>initiatorToCheck</var>, and
<var>userInvolvement</var>.</p></li>
</ol>
</li>
</ol>
<h4 id="navigate-non-frag-sync">Non-fragment synchronous "navigations"</h4>
<p>Apart from the <span>navigate</span> algorithm, <span data-x="session history entry">session
history entries</span> can be pushed or replaced via one more mechanism, the <span>URL and
history update steps</span>. The most well-known callers of these steps are the <code
data-x="dom-history-replaceState">history.replaceState()</code> and <code
data-x="dom-history-pushState">history.pushState()</code> APIs, but various other parts of the
standard also need to perform updates to the <span data-x="nav-active-history-entry">active
history entry</span>, and they use these steps to do so.</p>
<p id="history-1">The <dfn>URL and history update steps</dfn>, given a <code>Document</code>
<var>document</var>, a <span>URL</span> <var>newURL</var>, an optional <span>serialized
state</span>-or-null <dfn data-x="uhus-serializedData"><var>serializedData</var></dfn> (default
null), and an optional <span>history handling behavior</span> <dfn
data-x="uhus-historyHandling"><var id="uhus-ispush">historyHandling</var></dfn> (default "<code
data-x="NavigationHistoryBehavior-replace">replace</code>"), are:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>document</var>'s <span>node navigable</span>.</p></li>
<li><p>Let <var>activeEntry</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li>
<p>Let <var>newEntry</var> be a new <span>session history entry</span>, with</p>
<dl class="props">
<dt><span data-x="she-url">URL</span></dt>
<dd><var>newURL</var></dd>
<dt><span data-x="she-classic-history-api-state">serialized state</span></dt>
<dd>if <var>serializedData</var> is not null, <var>serializedData</var>; otherwise
<var>activeEntry</var>'s <span data-x="she-classic-history-api-state">classic history API
state</span></dd>
<dt><span data-x="she-document-state">document state</span></dt>
<dd><var>activeEntry</var>'s <span data-x="she-document-state">document state</span></dd>
<dt><span data-x="she-scroll-restoration-mode">scroll restoration mode</span></dt>
<dd><var>activeEntry</var>'s <span data-x="she-scroll-restoration-mode">scroll restoration
mode</span></dd>
<dt><span data-x="she-other">persisted user state</span></dt>
<dd><var>activeEntry</var>'s <span data-x="she-other">persisted user state</span></dd>
</dl>
</li>
<li>
<p>If <var>document</var>'s <span>is initial <code>about:blank</code></span> is true, then set
<var>historyHandling</var> to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
<p class="note">This means that <code data-x="dom-history-pushState">pushState()</code> on an
<span data-x="is initial about:blank">initial <code>about:blank</code></span>
<code>Document</code> behaves as a <code
data-x="dom-history-replaceState">replaceState()</code> call.</p>
</li>
<li><p>Let <var>entryToReplace</var> be <var>activeEntry</var> if <var>historyHandling</var> is
"<code data-x="NavigationHistoryBehavior-replace">replace</code>", otherwise null.</p></li>
<li>
<p>If <var>historyHandling</var> is "<code data-x="NavigationHistoryBehavior-push">push</code>",
then:</p>
<ol>
<li><p>Increment <var>document</var>'s <span data-x="doc-history">history object</span>'s
<span data-x="concept-history-index">index</span>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-length">length</span> to its <span
data-x="concept-history-index">index</span> + 1.</p></li>
</ol>
<p class="note">These are temporary best-guess values for immediate synchronous access.</p>
</li>
<li><p>If <var>serializedData</var> is not null, then <span>restore the history object
state</span> given <var>document</var> and <var>newEntry</var>.</p></li>
<li>
<p>Set <var>document</var>'s <span data-x="concept-document-url">URL</span> to
<var>newURL</var>.</p>
<p class="note">Since this is neither a <span data-x="navigate">navigation</span> nor a <span
data-x="traverse the history by a delta">history traversal</span>, it does not cause a <code
data-x="event-hashchange">hashchange</code> event to be fired.</p>
</li>
<li><p>Set <var>document</var>'s <span>latest entry</span> to <var>newEntry</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span> to <var>newEntry</var>.</p></li>
<li><p><span>Update the navigation API entries for a same-document navigation</span> given
<var>document</var>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>, <var>newEntry</var>, and
<var>historyHandling</var>.</p></li>
<li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>.</p></li>
<li>
<p><span data-x="tn-append-session-history-sync-nav-steps">Append the following session history
synchronous navigation steps</span> involving <var>navigable</var> to
<var>traversable</var>:</p>
<ol>
<li><p><span>Finalize a same-document navigation</span> given <var>traversable</var>,
<var>navigable</var>, <var>newEntry</var>, <var>entryToReplace</var>,
<var>historyHandling</var>, and "<code data-x="uni-none">none</code>".</p></li>
<li><p>Invoke <span>WebDriver BiDi history updated</span> with <var>navigable</var>.</p></li>
</ol>
</li>
</ol>
<p class="note">Although both <span data-x="navigate-fragid">fragment navigation</span> and the
<span>URL and history update steps</span> perform synchronous history updates, only fragment
navigation contains a synchronous call to <span>update document for history step
application</span>. The <span>URL and history update steps</span> instead perform a few select
updates inside the above algorithm, omitting others. This is somewhat of an unfortunate
historical accident, and generally leads to <a
href="https://github.com/whatwg/html/issues/5562">web-developer sadness</a> about the
inconsistency. For example, this means that <code data-x="event-popstate">popstate</code> events
fire for fragment navigations, but not for <code
data-x="dom-history-pushState">history.pushState()</code> calls.</p>
<h4><span id="history-traversal"></span><span id="traverse-the-history"></span>Populating a session history entry</h4>
<p>As explained in <a href="#history">the overview</a>, both <a
href="#navigating-across-documents">navigation</a> and <a
href="#reloading-and-traversing">traversal</a> involve creating a <span>session history
entry</span> and then attempting to populate its <span data-x="she-document">document</span>
member, so that it can be presented inside the <span>navigable</span>.</p>
<p>This involves either: using <a href="#note-navigate-called-with-response">an already-given
response</a>; using the <span data-x="document-state-resource">srcdoc resource</span> stored in
the <span>session history entry</span>; or <span data-x="create navigation params by
fetching">fetching</span>. The process has several failure modes, which can either result in
doing nothing (leaving the <span>navigable</span> on its currently-<span
data-x="nav-document">active</span> <code>Document</code>) or can result in populating the
<span>session history entry</span> with an <span data-x="navigate-ua-inline">error
document</span>.</p>
<p>To <dfn>attempt to populate the history entry's document</dfn> for a <span>session history
entry</span> <var>entry</var>, given a <span>navigable</span> <var>navigable</var>, a
<code>NavigationTimingType</code> <var>navTimingType</var>, a <span>source snapshot params</span>
<var>sourceSnapshotParams</var>, a <span>target snapshot params</span>
<var>targetSnapshotParams</var>, a <span>user navigation involvement</span>
<var>userInvolvement</var>, an optional <span>navigation ID</span>-or-null <var>navigationId</var>
(default null), an optional <span>navigation params</span>-or-null <var>navigationParams</var>
(default null), an optional string <var>cspNavigationType</var> (default "<code
data-x="">other</code>"), an optional boolean <dfn
data-x="attempt-to-populate-allow-post"><var>allowPOST</var></dfn> (default false), and optional
algorithm steps <dfn
data-x="attempt-to-populate-completion-steps"><var>completionSteps</var></dfn> (default an empty
algorithm):</p>
<ol>
<li><p><span>Assert</span>: this is running <span>in parallel</span>.</p></li>
<li><p><span>Assert</span>: if <var>navigationParams</var> is non-null, then
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span> is
non-null.</p></li>
<li><p>Let <var>documentResource</var> be <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-resource">resource</span>.</p></li>
<li>
<p>If <var>navigationParams</var> is null, then:</p>
<ol>
<li><p>If <var>documentResource</var> is a string, then set <var>navigationParams</var> to the
result of <span data-x="create navigation params from a srcdoc resource">creating navigation
params from a srcdoc resource</span> given <var>entry</var>, <var>navigable</var>,
<var>targetSnapshotParams</var>, <var>userInvolvement</var>, <var>navigationId</var>, and
<var>navTimingType</var>.</p></li>
<li>
<p>Otherwise, if all of the following are true:
<ul>
<li><p><var>entry</var>'s <span data-x="she-url">URL</span>'s <span
data-x="concept-url-scheme">scheme</span> is a <span>fetch scheme</span>; and</p></li>
<li><p><var>documentResource</var> is null, or <var>allowPOST</var> is true and
<var>documentResource</var>'s <span data-x="post-resource-request-body">request body</span>
is not failure,</p></li>
</ul>
<p>then set <var>navigationParams</var> to the result of <span data-x="create navigation
params by fetching">creating navigation params by fetching</span> given <var>entry</var>,
<var>navigable</var>, <var>sourceSnapshotParams</var>, <var>targetSnapshotParams</var>,
<var>cspNavigationType</var>, <var>userInvolvement</var>, <var>navigationId</var>, and
<var>navTimingType</var>.</p>
</li>
<li>
<p>Otherwise, if <var>entry</var>'s <span data-x="she-url">URL</span>'s <span
data-x="concept-url-scheme">scheme</span> is not a <span>fetch scheme</span>, then set
<var>navigationParams</var> to a new <span>non-fetch scheme navigation params</span>,
with</p>
<dl class="props">
<dt><span data-x="non-fetch-scheme-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="non-fetch-scheme-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="non-fetch-scheme-params-url">URL</span></dt>
<dd><var>entry</var>'s <span data-x="she-url">URL</span></dd>
<dt><span data-x="non-fetch-scheme-params-target-sandbox">target snapshot sandboxing flags</span></dt>
<dd><var>targetSnapshotParams</var>'s <span
data-x="target-snapshot-params-sandbox">sandboxing flags</span></dd>
<dt><span data-x="non-fetch-scheme-params-source-activation">source snapshot has transient activation</span></dt>
<dd><var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-activation">has
transient activation</span></dd>
<dt><span data-x="non-fetch-scheme-params-initiator-origin">initiator origin</span></dt>
<dd><var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-initiator-origin">initiator origin</span></dd>
<dt><span data-x="non-fetch-scheme-params-nav-timing-type">navigation timing type</span></dt>
<dd><var>navTimingType</var></dd>
<dt><span data-x="non-fetch-scheme-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
</ol>
</li>
<li id="process-a-navigate-response">
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>,
given <var>navigable</var>'s <span>active window</span>, to run these steps:</p>
<ol>
<li><p>If <var>navigable</var>'s <span>ongoing navigation</span> no longer equals
<var>navigationId</var>, then run <var>completionSteps</var> and abort these steps.</p></li>
<li>
<p>Let <var>saveExtraDocumentState</var> be true.</p>
<div class="note">
<p>Usually, in the cases where we end up populating <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span>, we then want to save some of the state
from that <code>Document</code> into <var>entry</var>. This ensures that if there are future
traversals to <var>entry</var> where its <span
data-x="document-state-document">document</span> <a href="#note-bfcache">has been
destroyed</a>, we can use that state when creating a new <code>Document</code>.</p>
<p>However, in some specific cases, saving the state would be unhelpful. For those, we set
<var>saveExtraDocumentState</var> to false later in this algorithm.</p>
</div>
</li>
<li>
<p>If <var>navigationParams</var> is a <span>non-fetch scheme navigation params</span>,
then:</p>
<ol>
<li>
<p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> to the result of running <span>attempt to
create a non-fetch scheme document</span> given <var>navigationParams</var>.</p>
<p class="note">This can result in setting <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> to null, e.g., when <span data-x="hand-off
to external software">handing-off to external software</span>.</p>
</li>
<li><p>Set <var>saveExtraDocumentState</var> to false.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if any of the following are true:</p>
<ul>
<li><p><var>navigationParams</var> is null;</p></li>
<li><p>the result of <span>should navigation response to navigation request of type in
target be blocked by Content Security Policy?</span> given <var>navigationParams</var>'s
<span data-x="navigation-params-request">request</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-policy-container">policy container</span>'s <span
data-x="policy-container-csp-list">CSP list</span>, <var>cspNavigationType</var>, and
<var>navigable</var> is "<code data-x="">Blocked</code>";</p></li>
<li><p><var>navigationParams</var>'s <span
data-x="navigation-params-reserved-environment">reserved environment</span> is non-null and
the result of <span data-x="check a navigation response's adherence to its embedder
policy">checking a navigation response's adherence to its embedder policy</span> given
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>,
<var>navigable</var>, and <var>navigationParams</var>'s <span
data-x="navigation-params-policy-container">policy container</span>'s <span
data-x="policy-container-embedder-policy">embedder policy</span> is false; or </p></li>
<li><p>the result of <span data-x="check a navigation response's adherence to
`X-Frame-Options`">checking a navigation response's adherence to
`<code>X-Frame-Options</code>`</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, <var>navigable</var>,
<var>navigationParams</var>'s <span data-x="navigation-params-policy-container">policy
container</span>'s <span data-x="policy-container-csp-list">CSP list</span>, and
<var>navigationParams</var>'s <span data-x="navigation-params-origin">origin</span> is
false,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-document">document</span> to the result of <span
data-x="navigate-ua-inline">creating a document for inline content that doesn't have a
DOM</span>, given <var>navigable</var>, null, <var>navTimingType</var>, and
<var>userInvolvement</var>. The inline content should indicate to the user the sort of error
that occurred.</p></li>
<li><p><span>Make document unsalvageable</span> given <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> and "<code
data-x="blocking-navigation-failure">navigation-failure</code>".</p></li>
<li><p>Set <var>saveExtraDocumentState</var> to false.</p></li>
<li>
<p>If <var>navigationParams</var> is not null, then:</p>
<ol>
<li><p>Run the <span data-x="environment discarding steps">environment discarding
steps</span> for <var>navigationParams</var>'s <span
data-x="navigation-params-reserved-environment">reserved environment</span>.</p></li>
<li><p>Invoke <span>WebDriver BiDi navigation failed</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-url">URL</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li id="navigation-as-a-download">
<p>Otherwise, if <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header specifying the <code
data-x="">attachment</code> disposition type, then:</p>
<ol>
<li><p>Let <var>sourceAllowsDownloading</var> be <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-download">allows downloading</span>.</p></li>
<li><p>Let <var>targetAllowsDownloading</var> be false if <var>navigationParams</var>'s
<span data-x="navigation-params-sandboxing">final sandboxing flag set</span> has the
<span>sandboxed downloads browsing context flag</span> set; otherwise true.</p></li>
<li><p>Let <var>uaAllowsDownloading</var> be true.</p></li>
<li><p>Optionally, the user agent may set <var>uaAllowsDownloading</var> to false, if it
believes doing so would safeguard the user from a potentially hostile download.</p></li>
<li>
<p>If <var>sourceAllowsDownloading</var>, <var>targetAllowsDownloading</var>, and
<var>uaAllowsDownloading</var> are true, then:</p>
<ol>
<li><p>Let <var>suggestedFilename</var> be the result of <span data-x="handle as a
download">handling as a download</span> <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>.</p></li>
<li><p>Invoke <span>WebDriver BiDi download started</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>", <span
data-x="navigation-status-url">url</span> is <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-url">URL</span>, and <span
data-x="navigation-status-suggested-filename">suggestedFilename</span> is
<var>suggestedFilename</var>.</p></li>
</ol>
</li>
</ol>
<p class="note">This branch leaves <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> as null.</p>
</li>
<li>
<p>Otherwise, if <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-status">status</span> is not 204 and is not 205, then set
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> to the result of <span>loading a
document</span> given <var>navigationParams</var>, <var>sourceSnapshotParams</var>, and
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-initiator-origin">initiator origin</span>.</p>
<p class="note">This can result in setting <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> to null, e.g., when <span data-x="hand-off
to external software">handing-off to external software</span>.</p>
</li>
<li>
<p>If <var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> is not null, then:</p>
<ol>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-ever-populated">ever populated</span> to true.</p></li>
<li>
<p>If <var>saveExtraDocumentState</var> is true:</p>
<ol>
<li><p>Let <var>document</var> be <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span>.</p></li>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-origin">origin</span> to <var>document</var>'s <span
data-x="concept-document-origin">origin</span>.</p></li>
<li>
<p>If <var>document</var>'s <span data-x="concept-document-url">URL</span>
<span>requires storing the policy container in history</span>, then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigationParams</var> is a <span>navigation
params</span> (i.e., neither null nor a <span>non-fetch scheme navigation
params</span>).</p></li>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-history-policy-container">history policy container</span>
to <var>navigationParams</var>'s <span
data-x="navigation-params-policy-container">policy container</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>If <var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-request-referrer">request referrer</span> is "<code
data-x="">client</code>", and <var>navigationParams</var> is a <span>navigation
params</span> (i.e., neither null nor a <span>non-fetch scheme navigation params</span>),
then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigationParams</var>'s <span
data-x="navigation-params-request">request</span> is not null.</p></li>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-request-referrer">request referrer</span> to
<var>navigationParams</var>'s <span data-x="navigation-params-request">request</span>'s
<span data-x="concept-request-referrer">referrer</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Run <var>completionSteps</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>create navigation params from a srcdoc resource</dfn> given a <span>session history
entry</span> <var>entry</var>, a <span>navigable</span> <var>navigable</var>, a <span>target
snapshot params</span> <var>targetSnapshotParams</var>, a <span>user navigation involvement</span>
<var>userInvolvement</var>, a <span>navigation ID</span>-or-null <var>navigationId</var>, and a
<code>NavigationTimingType</code> <var>navTimingType</var>:</p>
<ol>
<li><p>Let <var>documentResource</var> be <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-resource">resource</span>.</p></li>
<li>
<p>Let <var>response</var> be a new <span data-x="concept-response">response</span> with</p>
<dl class="props">
<dt><span data-x="concept-response-url">URL</span></dt>
<dd><code>about:srcdoc</code></dd>
<dt><span data-x="concept-response-header-list">header list</span></dt>
<dd>« (`<code>Content-Type</code>`, `<code data-x="">text/html</code>`) »</dd>
<dt><span data-x="concept-response-body">body</span></dt>
<dd>the <span data-x="UTF-8 encode">UTF-8 encoding</span> of <var>documentResource</var>,
<span>as a body</span></dd>
</dl>
</li>
<li><p>Let <var>responseOrigin</var> be the result of <span>determining the origin</span> given
<var>response</var>'s <span data-x="concept-response-url">URL</span>,
<var>targetSnapshotParams</var>'s <span data-x="target-snapshot-params-sandbox">sandboxing
flags</span>, and <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-origin">origin</span>.</p></li>
<li><p>Let <var>coop</var> be a new <span>opener policy</span>.</p></li>
<li>
<p>Let <var>coopEnforcementResult</var> be a new <span data-x="coop-enforcement-result">opener
policy enforcement result</span> with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>response</var>'s <span data-x="concept-response-url">URL</span></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
</dl>
</li>
<li><p>Let <var>policyContainer</var> be the result of <span data-x="determining navigation
params policy container">determining navigation params policy container</span> given
<var>response</var>'s <span data-x="concept-response-url">URL</span>, <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-history-policy-container">history policy container</span>, null,
<var>navigable</var>'s <span data-x="nav-container-document">container document</span>'s <span
data-x="concept-document-policy-container">policy container</span>, and null.</p></li>
<li>
<p>Return a new <span>navigation params</span>, with</p>
<dl class="props">
<dt><span data-x="navigation-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="navigation-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="navigation-params-request">request</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-response">response</span></dt>
<dd><var>response</var></dd>
<dt><span data-x="navigation-params-fetch-controller">fetch controller</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-commit-early-hints">commit early hints</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span></dt>
<dd><var>coopEnforcementResult</var></dd>
<dt><span data-x="navigation-params-reserved-environment">reserved environment</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="navigation-params-policy-container">policy container</span></dt>
<dd><var>policyContainer</var></dd>
<dt><span data-x="navigation-params-sandboxing">final sandboxing flag set</span></dt>
<dd><var>targetSnapshotParams</var>'s <span data-x="target-snapshot-params-sandbox">sandboxing
flags</span></dd>
<dt><span data-x="navigation-params-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
<dt><span data-x="navigation-params-nav-timing-type">navigation timing type</span></dt>
<dd><var>navTimingType</var></dd>
<dt><span data-x="navigation-params-about-base-url">about base URL</span></dt>
<dd><var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-about-base-url">about base URL</span></dd>
<dt><span data-x="navigation-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
</ol>
<p id="process-a-navigate-fetch">To <dfn>create navigation params by fetching</dfn> given a
<span>session history entry</span> <var>entry</var>, a <span>navigable</span>
<var>navigable</var>, a <span>source snapshot params</span> <var>sourceSnapshotParams</var>, a
<span>target snapshot params</span> <var>targetSnapshotParams</var>, a string
<var>cspNavigationType</var>, a <span>user navigation involvement</span>
<var>userInvolvement</var>, a <span>navigation ID</span>-or-null <var>navigationId</var>, and a
<code>NavigationTimingType</code> <var>navTimingType</var>, perform the following steps. They
return a <span>navigation params</span>, a <span>non-fetch scheme navigation params</span>, or
null.</p>
<p class="note">This algorithm mutates <var>entry</var>.</p>
<ol>
<li><p><span>Assert</span>: this is running <span>in parallel</span>.</p></li>
<li><p>Let <var>documentResource</var> be <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-resource">resource</span>.</p></li>
<li>
<p>Let <var>request</var> be a new <span data-x="concept-request">request</span>, with</p>
<dl class="props">
<dt><span data-x="concept-request-url">url</span></dt>
<dd><var>entry</var>'s <span data-x="she-url">URL</span></dd>
<dt><span data-x="concept-request-client">client</span></dt>
<dd><var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-client">fetch
client</span></dd>
<dt><span data-x="concept-request-destination">destination</span></dt>
<dd>"<code data-x="">document</code>"</dd>
<dt><span data-x="concept-request-credentials-mode">credentials mode</span></dt>
<dd>"<code data-x="">include</code>"</dd>
<dt><span>use-URL-credentials flag</span></dt>
<dd>set</dd>
<dt><span data-x="concept-request-redirect-mode">redirect mode</span></dt>
<dd>"<code data-x="">manual</code>"</dd>
<dt><span data-x="concept-request-replaces-client-id">replaces client id</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span>relevant
settings object</span>'s <span data-x="concept-environment-id">id</span></dd>
<dt><span data-x="concept-request-mode">mode</span></dt>
<dd>"<code data-x="">navigate</code>"</dd>
<dt><span data-x="concept-request-referrer">referrer</span></dt>
<dd><var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-request-referrer">request referrer</span></dd>
<dt><span data-x="concept-request-referrer-policy">referrer policy</span></dt>
<dd><var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-request-referrer-policy">request referrer policy</span></dd>
<dt><span data-x="concept-request-policy-container">policy container</span></dt>
<dd><var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-policy-container">source policy container</span></dd>
</dl>
</li>
<li>
<p>If <var>documentResource</var> is a <span>POST resource</span>, then:</p>
<ol>
<li><p>Set <var>request</var>'s <span data-x="concept-request-method">method</span> to `<code
data-x="">POST</code>`.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-body">body</span> to
<var>documentResource</var>'s <span data-x="post-resource-request-body">request
body</span>.</p></li>
<li><p><span data-x="concept-header-list-set">Set</span> `<code data-x="">Content-Type</code>`
to <var>documentResource</var>'s <span data-x="post-resource-request-content-type">request
content-type</span> in <var>request</var>'s <span data-x="concept-request-header-list">header
list</span>.</p></li>
</ol>
</li>
<li><p>If <var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is true, then set
<var>request</var>'s <span data-x="concept-request-reload-navigation-flag">reload-navigation
flag</span>.</p></li>
<li><p>Otherwise, if <var>entry</var>'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-ever-populated">ever populated</span> is true, then
set <var>request</var>'s <span
data-x="concept-request-history-navigation-flag">history-navigation flag</span>.</p></li>
<li><p>If <var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-activation">has
transient activation</span> is true, then set <var>request</var>'s <span
data-x="concept-request-user-activation">user-activation</span> to true.</p></li>
<li>
<p>If <var>navigable</var>'s <span data-x="nav-container">container</span> is non-null:</p>
<ol>
<li><p>If the <var>navigable</var>'s <span data-x="nav-container">container</span> has a
<span>browsing context scope origin</span>, then set <var>request</var>'s <span
data-x="concept-request-origin">origin</span> to that <span>browsing context scope
origin</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-destination">destination</span>
to <var>navigable</var>'s <span data-x="nav-container">container</span>'s <span
data-x="concept-element-local-name">local name</span>.</p></li>
<li>
<p>If <var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-client">fetch
client</span> is <var>navigable</var>'s <span data-x="nav-container-document">container
document</span>'s <span>relevant settings object</span>, then set <var>request</var>'s <span
data-x="concept-request-initiator-type">initiator type</span> to <var>navigable</var>'s <span
data-x="nav-container">container</span>'s <span data-x="concept-element-local-name">local
name</span>.</p>
<p class="note">This ensure that only container-initiated navigations are reported to
resource timing.</p>
</li>
</ol>
</li>
<li><p>Let <var>response</var> be null.</p></li>
<li><p>Let <var>responseOrigin</var> be null.</p></li>
<li><p>Let <var>fetchController</var> be null.</p></li>
<li>
<p>Let <var>coopEnforcementResult</var> be a new <span data-x="coop-enforcement-result">opener
policy enforcement result</span>, with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-url">URL</span></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-coop">opener policy</span></dd>
<dt><span data-x="coop-enforcement-source">current context is navigation source</span></dt>
<dd>true if <var>navigable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin</span> with
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-initiator-origin">initiator origin</span> otherwise false</dd>
</dl>
</li>
<li><p>Let <var>finalSandboxFlags</var> be an empty <span>sandboxing flag set</span>.</p></li>
<li><p>Let <var>responsePolicyContainer</var> be null.</p></li>
<li><p>Let <var>responseCOOP</var> be a new <span>opener policy</span>.</p></li>
<li><p>Let <var>locationURL</var> be null.</p></li>
<li><p>Let <var>currentURL</var> be <var>request</var>'s <span
data-x="concept-request-current-url">current URL</span>.</p></li>
<li><p>Let <var>commitEarlyHints</var> be null.</p></li>
<li>
<p>While true:</p>
<ol>
<li>
<p>If <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span> is not null and <var>currentURL</var>'s <span
data-x="concept-url-origin">origin</span> is not the <span data-x="same origin">same</span>
as <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span>'s <span data-x="concept-environment-creation-url">creation URL</span>'s <span
data-x="concept-url-origin">origin</span>, then:</p>
<ol>
<li><p>Run the <span>environment discarding steps</span> for <var>request</var>'s <span
data-x="concept-request-reserved-client">reserved client</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span> to null.</p></li>
<li>
<p>Set <var>commitEarlyHints</var> to null.</p>
<p class="note">Preloaded links from <span data-x="early hints">early hint headers</span>
remain in the preload cache after a <span>same origin</span> redirect, but get discarded
when the redirect is cross-origin.</p>
</li>
</ol>
</li>
<li>
<p>If <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span> is null, then:</p>
<ol>
<li><p>Let <var>topLevelCreationURL</var> be <var>currentURL</var>.</p></li>
<li><p>Let <var>topLevelOrigin</var> be null.</p></li>
<li>
<p>If <var>navigable</var> is not a <span>top-level traversable</span>, then:</p>
<ol>
<li><p>Let <var>parentEnvironment</var> be <var>navigable</var>'s <span
data-x="nav-parent">parent</span>'s <span data-x="nav-document">active document</span>'s
<span>relevant settings object</span>.</p></li>
<li><p>Set <var>topLevelCreationURL</var> to <var>parentEnvironment</var>'s
<span>top-level creation URL</span>.</p></li>
<li><p>Set <var>topLevelOrigin</var> to <var>parentEnvironment</var>'s <span>top-level
origin</span>.</p></li>
</ol>
</li>
<li>
<p>Set <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span> to a new <span>environment</span> whose <span
data-x="concept-environment-id">id</span> is a unique opaque string, <span
data-x="concept-environment-target-browsing-context">target browsing context</span> is
<var>navigable</var>'s <span data-x="nav-bc">active browsing context</span>, <span
data-x="concept-environment-creation-url">creation URL</span> is <var>currentURL</var>,
<span>top-level creation URL</span> is <var>topLevelCreationURL</var>, and <span>top-level
origin</span> is <var>topLevelOrigin</var>.</p>
<p class="note">The created environment's <span
data-x="concept-environment-active-service-worker">active service worker</span> is set in
the <span data-x="on-fetch-request-algorithm">Handle Fetch</span> algorithm during the fetch
if the request URL matches a service worker registration. <ref>SW</ref></p>
</li>
</ol>
</li>
<li><p>If the result of <span>should navigation request of type be blocked by Content Security
Policy?</span> given <var>request</var> and <var>cspNavigationType</var> is "<code
data-x="">Blocked</code>", then set <var>response</var> to a <span>network error</span> and
<span>break</span>. <ref>CSP</ref></p></li>
<li><p>Set <var>response</var> to null.</p></li>
<li>
<p>If <var>fetchController</var> is null, then set <var>fetchController</var> to the result
of <!--FETCH--><span data-x="concept-fetch">fetching</span> <var>request</var>, with <i
data-x="processEarlyHintsResponse">processEarlyHintsResponse</i> set to
<var>processEarlyHintsResponse</var> as defined below, <i
data-x="processResponse">processResponse</i> set to <var>processResponse</var> as defined
below, and <i data-x="useParallelQueue">useParallelQueue</i> set to true.</p>
<p>Let <var>processEarlyHintsResponse</var> be the following algorithm given a <span
data-x="concept-response">response</span> <var>earlyResponse</var>:</p>
<ol>
<li><p>If <var>commitEarlyHints</var> is null, then set <var>commitEarlyHints</var> to the
result of <span data-x="process early hint headers">processing early hint headers</span>
given <var>earlyResponse</var> and <var>request</var>'s <span
data-x="concept-request-reserved-client">reserved client</span>.</p></li>
</ol>
<p>Let <var>processResponse</var> be the following algorithm given a <span
data-x="concept-response">response</span> <var>fetchedResponse</var>:</p>
<ol>
<li><p>Set <var>response</var> to <var>fetchedResponse</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, <span>process the next manual redirect</span> for
<var>fetchController</var>.</p>
<p class="note">This will result in calling the <i
data-x="processResponse">processResponse</i> we supplied above, during our first iteration
through the loop, and thus setting <var>response</var>.</p>
<p class="note">Navigation handles redirects manually as navigation is the only place in the
web platform that cares for redirects to <code data-x="mailto protocol">mailto:</code> URLs
and such.</p>
</li>
<li>
<p>Wait until either <var>response</var> is non-null, or <var>navigable</var>'s <span>ongoing
navigation</span> changes to no longer equal <var>navigationId</var>.</p>
<p>If the latter condition occurs, then <span data-x="fetch-controller-abort">abort</span>
<var>fetchController</var>, and return.</p>
<p>Otherwise, proceed onward.</p>
</li>
<li>
<p>If <var>request</var>'s <span data-x="concept-request-body">body</span> is null, then set
<var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-resource">resource</span> to null.</p>
<p class="note">Fetch unsets the <span data-x="concept-request-body">body</span> for
particular redirects.</p>
</li>
<li><p>Set <var>responsePolicyContainer</var> to the result of <span>creating a policy
container from a fetch response</span> given <var>response</var> and <var>request</var>'s
<span data-x="concept-request-reserved-client">reserved client</span>.</p></li>
<li><p>Set <var>finalSandboxFlags</var> to the <span data-x="set union">union</span> of
<var>targetSnapshotParams</var>'s <span data-x="target-snapshot-params-sandbox">sandboxing
flags</span> and <var>responsePolicyContainer</var>'s <span
data-x="policy-container-csp-list">CSP list</span>'s <span>CSP-derived sandboxing
flags</span>.</p></li>
<li>
<p>Set <var>responseOrigin</var> to the result of <span>determining the origin</span> given
<var>response</var>'s <span data-x="concept-response-url">URL</span>,
<var>finalSandboxFlags</var>, and <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-initiator-origin">initiator origin</span>.</p>
<p class="note">If <var>response</var> is a redirect, then <var>response</var>'s <span
data-x="concept-response-url">URL</span> will be the URL that led to the redirect to
<var>response</var>'s <span data-x="concept-response-location-url">location URL</span>; it
will not be the <span data-x="concept-response-location-url">location URL</span> itself.</p>
</li>
<li>
<p>If <var>navigable</var> is a <span>top-level traversable</span>, then:</p>
<ol>
<li><p>Set <var>responseCOOP</var> to the result of <span data-x="obtain-coop">obtaining an
opener policy</span> given <var>response</var> and <var>request</var>'s <span
data-x="concept-request-reserved-client">reserved client</span>.</p></li>
<li><p>Set <var>coopEnforcementResult</var> to the result of <span
data-x="coop-enforce">enforcing the response's opener policy</span> given
<var>navigable</var>'s <span data-x="nav-bc">active browsing context</span>,
<var>response</var>'s <span data-x="concept-response-url">URL</span>,
<var>responseOrigin</var>, <var>responseCOOP</var>, <var>coopEnforcementResult</var> and
<var>request</var>'s <span data-x="concept-request-referrer">referrer</span>.</p></li>
<li>
<p>If <var>finalSandboxFlags</var> is not empty and <var>responseCOOP</var>'s <span
data-x="coop-struct-value">value</span> is not "<code
data-x="coop-unsafe-none">unsafe-none</code>", then set <var>response</var> to an
appropriate <span>network error</span> and <span>break</span>.</p>
<p class="note">This results in a network error as one cannot simultaneously provide a clean
slate to a response using opener policy and sandbox the result of
navigating to that response.</p>
</li>
</ol>
</li>
<li>
<p>If <var>response</var> is not a <span>network error</span>, <var>navigable</var> is a
<span>child navigable</span>, and the result of performing a <span>cross-origin resource
policy check</span> with <var>navigable</var>'s <span
data-x="nav-container-document">container document</span>'s <span
data-x="concept-document-origin">origin</span>, <var>navigable</var>'s <span
data-x="nav-container-document">container document</span>'s <span>relevant settings
object</span>, <var>request</var>'s <span
data-x="concept-request-destination">destination</span>, <var>response</var>, and true is
<b>blocked</b>, then set <var>response</var> to a <span>network error</span> and
<span>break</span>.</p>
<p class="note">Here we're running the <span>cross-origin resource policy check</span>
against the <span data-x="nav-parent">parent navigable</span> rather than
<var>navigable</var> itself. This is because we care about the same-originness of the
embedded content against the parent context, not the navigation source.</p>
</li>
<li><p>Set <var>locationURL</var> to <var>response</var>'s <span
data-x="concept-response-location-url">location URL</span> given <var>currentURL</var>'s <span
data-x="concept-url-fragment">fragment</span>.</p></li>
<li><p>If <var>locationURL</var> is failure or null, then <span>break</span>.</p></li>
<li><p><span>Assert</span>: <var>locationURL</var> is a <span>URL</span>.</p></li>
<li><p>Set <var>entry</var>'s <span data-x="she-classic-history-api-state">classic history API
state</span> to <span>StructuredSerializeForStorage</span>(null).</p></li>
<li><p>Let <var>oldDocState</var> be <var>entry</var>'s <span
data-x="she-document-state">document state</span>.</p></li>
<li>
<p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span> to a new
<span>document state</span>, with
<dl class="props">
<dt><span data-x="document-state-history-policy-container">history policy container</span></dt>
<dd>a <span data-x="clone a policy container">clone</span> of the <var>oldDocState</var>'s
<span data-x="document-state-history-policy-container">history policy container</span> if it
is non-null; null otherwise</dd>
<dt><span data-x="document-state-request-referrer">request referrer</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-request-referrer">request
referrer</span></dd>
<dt><span data-x="document-state-request-referrer-policy">request referrer policy</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-request-referrer-policy">request
referrer policy</span></dd>
<dt><span data-x="document-state-initiator-origin">initiator origin</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-initiator-origin">initiator
origin</span></dd>
<dt><span data-x="document-state-origin">origin</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-origin">origin</span></dd>
<dt><span data-x="document-state-about-base-url">about base URL</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-about-base-url">about base URL</span></dd>
<dt><span data-x="document-state-resource">resource</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-resource">resource</span></dd>
<dt><span data-x="document-state-ever-populated">ever populated</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-ever-populated">ever
populated</span></dd>
<dt><span data-x="document-state-nav-target-name">navigable target name</span></dt>
<dd><var>oldDocState</var>'s <span data-x="document-state-nav-target-name">navigable target
name</span></dd>
</dl>
<!-- https://github.com/whatwg/html/issues/6680 -->
<p class="note">For the navigation case, only <var>entry</var> referenced
<var>oldDocState</var>, which was created <a href="#navigation-create-document-state">early
in the navigate algorithm</a>. So for navigations, this is functionally just an update to
<var>entry</var>'s <span data-x="she-document-state">document state</span>. For the traversal
case, it's possible adjacent <span data-x="session history entry">session history
entries</span> also reference <var>oldDocState</var>, in which case they will continue doing
so even after we've updated <var>entry</var>'s <span data-x="she-document-state">document
state</span>.</p>
<p class="note"><var>oldDocState</var>'s <span
data-x="document-state-history-policy-container">history policy container</span> is only ever
non-null here in the traversal case, after we've populated it during a navigation to a URL
that <span>requires storing the policy container in history</span>.</p>
<div class="example">
<p>The setup is given by the following <span>Jake diagram</span>:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAzCiFza2lwRG9jQ29sb3JzID0gMQp0b3AKICAwOiAvYSB8IGRvYzEKICAxOiAvYSNmb28gfCBkb2MxCiAgMjogL2EjYmFyIHwgZG9jMQogIDM6IC9i -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step">2</th><th class="step current">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="1" class="doc-0 next-is-same-doc">/a</td><td colspan="1" class="doc-0 prev-is-same-doc next-is-same-doc">/a#foo</td><td colspan="1" class="doc-0 prev-is-same-doc">/a#bar</td><td colspan="1" class="doc-2 current">/b</td></tr></tbody></table>
<p>Also assume that the <span data-x="she-document-state">document state</span> shared by
the entries in steps 0, 1, and 2 has a null <span
data-x="document-state-document">document</span>, i.e., <a href="#note-bfcache">bfcache</a>
is not in play.</p>
<p>Now consider the scenario where we traverse back to step 2, but this time when fetching
<code data-x="">/a</code>, the server responds with a `<code data-x="">Location</code>`
header pointing to <code data-x="">/c</code>. That is, <var>locationURL</var> points to
<code data-x="">/c</code> and so we have reached this step instead of <span
data-x="break">breaking</span> out of the loop.</p>
<p>In this case, we replace the <span data-x="she-document-state">document state</span> of
the <span>session history entry</span> occupying step 2, but we do <em>not</em> replace the
document state of the entries occupying steps 0 and 1. The resulting <span>Jake
diagram</span> looks like this:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAyCnRvcAogIDA6IC9hIHwgZG9jMQogIDE6IC9hI2ZvbyB8IGRvYzEKICAyOiAvYyNiYXIKICAzOiAvYg== -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step current">2</th><th class="step">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="1" class="doc-0 next-is-same-doc">/a</td><td colspan="1" class="doc-0 prev-is-same-doc">/a#foo</td><td colspan="1" class="doc-1 current">/c#bar</td><td colspan="1" class="doc-2">/b</td></tr></tbody></table>
<p>Note that we perform this replacement even if we end up in a redirect chain back to the
original URL, for example if <code data-x="">/c</code> itself had a `<code
data-x="">Location</code>` header pointing to <code data-x="">/a</code>. Such a case would
end up like so:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAyCnRvcAogIDA6IC9hIHwgZG9jMQogIDE6IC9hI2ZvbyB8IGRvYzEKICAyOiAvYSNiYXIKICAzOiAvYg== -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step current">2</th><th class="step">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="1" class="doc-0 next-is-same-doc">/a</td><td colspan="1" class="doc-0 prev-is-same-doc">/a#foo</td><td colspan="1" class="doc-1 current">/a#bar</td><td colspan="1" class="doc-2">/b</td></tr></tbody></table>
</div>
</li>
<li>
<p>If <var>locationURL</var>'s <span data-x="concept-url-scheme">scheme</span> is not an
<span>HTTP(S) scheme</span>, then:</p>
<ol>
<li><p>Set <var>entry</var>'s <span data-x="she-document-state">document state</span>'s
<span data-x="document-state-resource">resource</span> to null.</p></li>
<li><p><span>Break</span>.</p></li>
</ol>
</li>
<li><p>Set <var>currentURL</var> to <var>locationURL</var>.</p></li>
<li><p>Set <var>entry</var>'s <span data-x="she-url">URL</span> to
<var>currentURL</var>.</p></li>
</ol>
<div class="note">
<p>By the end of this loop we will be in one of these scenarios:</p>
<ul>
<li><p><var>locationURL</var> is failure, because of an unparseable `<code
data-x="">Location</code>` header.</p></li>
<li><p><var>locationURL</var> is null, either because <var>response</var> is a <span>network
error</span> or because we successfully fetched a non-<span>network error</span> HTTP(S)
response with no `<code data-x="">Location</code>` header.</p></li>
<li><p><var>locationURL</var> is a <span>URL</span> with a non-<span data-x="HTTP(S)
scheme">HTTP(S)</span> <span data-x="concept-url-scheme">scheme</span>.</p></li>
</ul>
</div>
</li>
<li>
<p>If <var>locationURL</var> is a <span>URL</span> whose <span
data-x="concept-url-scheme">scheme</span> is not a <span>fetch scheme</span>, then return a new
<span>non-fetch scheme navigation params</span>, with</p>
<dl class="props">
<dt><span data-x="non-fetch-scheme-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="non-fetch-scheme-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="non-fetch-scheme-params-url">URL</span></dt>
<dd><var>locationURL</var></dd>
<dt><span data-x="non-fetch-scheme-params-target-sandbox">target snapshot sandboxing flags</span></dt>
<dd><var>targetSnapshotParams</var>'s <span data-x="target-snapshot-params-sandbox">sandboxing
flags</span></dd>
<dt><span data-x="non-fetch-scheme-params-source-activation">source snapshot has transient activation</span></dt>
<dd><var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-activation">has
transient activation</span></dd>
<dt><span data-x="non-fetch-scheme-params-initiator-origin">initiator origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="non-fetch-scheme-params-nav-timing-type">navigation timing type</span></dt>
<dd><var>navTimingType</var></dd>
<dt><span data-x="non-fetch-scheme-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
<p class="note">At this point, <var>request</var>'s <span
data-x="concept-request-current-url">current URL</span> is the last <span>URL</span> in the
redirect chain with a <span data-x="fetch scheme">fetch</span> <span
data-x="concept-url-scheme">scheme</span> before redirecting to a non-<span>fetch scheme</span>
<span>URL</span>. It is this <span>URL</span>'s <span data-x="concept-url-origin">origin</span>
that will be used as the initiator origin for navigations to non-<span>fetch scheme</span>
<span data-x="url">URLs</span>.</p>
</li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>response</var> is a <span>network error</span>;</p></li>
<li><p><var>locationURL</var> is failure; or</p></li>
<li><p><var>locationURL</var> is a <span>URL</span> whose <span
data-x="concept-url-scheme">scheme</span> is a <span>fetch scheme</span>,</p></li>
</ul>
<p>then return null.</p>
<p class="note">We allow redirects to non-<span>fetch scheme</span> <span
data-x="URL">URLs</span>, but redirects to <span>fetch scheme</span> <span
data-x="URL">URLs</span> that aren't <span data-x="HTTP(S) scheme">HTTP(S)</span> are treated
like network errors.</p>
</li>
<li><p><span>Assert</span>: <var>locationURL</var> is null and <var>response</var> is not a
<span>network error</span>.</li>
<li><p>Let <var>resultPolicyContainer</var> be the result of <span>determining navigation params
policy container</span> given <var>response</var>'s <span
data-x="concept-response-url">URL</span>, <var>entry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-history-policy-container">history policy container</span>,
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-policy-container">source
policy container</span>, null, and <var>responsePolicyContainer</var>.</p></li>
<li>
<p>If <var>navigable</var>'s <span data-x="nav-container">container</span> is an
<code>iframe</code>, and <var>response</var>'s <span
data-x="concept-response-timing-allow-passed">timing allow passed flag</span> is set, then
set <span data-x="nav-container">container</span>'s <span
data-x="iframe-pending-resource-timing-start-time">pending resource-timing start time</span> to
null.</p>
<p class="note">If the <code>iframe</code> is allowed to report to resource timing,
we don't need to run its fallback steps as the normal reporting would happen.</p>
</li>
<li>
<p>Return a new <span>navigation params</span>, with</p>
<dl class="props">
<dt><span data-x="navigation-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="navigation-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="navigation-params-request">request</span></dt>
<dd><var>request</var></dd>
<dt><span data-x="navigation-params-response">response</span></dt>
<dd><var>response</var></dd>
<dt><span data-x="navigation-params-fetch-controller">fetch controller</span></dt>
<dd><var>fetchController</var></dd>
<dt><span data-x="navigation-params-commit-early-hints">commit early hints</span></dt>
<dd><var>commitEarlyHints</var></dd>
<dt><span data-x="navigation-params-coop">opener policy</span></dt>
<dd><var>responseCOOP</var></dd>
<dt><span data-x="navigation-params-reserved-environment">reserved environment</span></dt>
<dd><var>request</var>'s <span data-x="concept-request-reserved-client">reserved client</span></dd>
<dt><span data-x="navigation-params-origin">origin</span></dt>
<dd><var>responseOrigin</var></dd>
<dt><span data-x="navigation-params-policy-container">policy container</span></dt>
<dd><var>resultPolicyContainer</var></dd>
<dt><span data-x="navigation-params-sandboxing">final sandboxing flag set</span></dt>
<dd><var>finalSandboxFlags</var></dd>
<dt><span data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span></dt>
<dd><var>coopEnforcementResult</var></dd>
<dt><span data-x="navigation-params-nav-timing-type">navigation timing type</span></dt>
<dd><var>navTimingType</var></dd>
<dt><span data-x="navigation-params-about-base-url">about base URL</span></dt>
<dd><var>entry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-about-base-url">about base URL</span></dd>
<dt><span data-x="navigation-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
</ol>
<p>An element has a <dfn>browsing context scope origin</dfn> if its <code>Document</code>'s
<span>node navigable</span> is a <span>top-level traversable</span> or if all of its
<code>Document</code>'s <span>ancestor navigables</span> all have <span
data-x="nav-document">active documents</span> whose <span
data-x="concept-document-origin">origins</span> are the <span>same origin</span> as the element's
<span>node document</span>'s <span data-x="concept-document-origin">origin</span>. If an element
has a <span>browsing context scope origin</span>, then its value is the <span
data-x="concept-document-origin">origin</span> of the element's <span>node document</span>.</p>
<p class="XXX">This definition is broken and needs investigation to see what it was intended to
express: see <a href="https://github.com/whatwg/html/issues/4703">issue #4703</a>.</p>
<p>To <dfn data-x="loading a document">load a document</dfn> given <span>navigation params</span>
<var>navigationParams</var>, <span>source snapshot params</span> <var>sourceSnapshotParams</var>,
and <span>origin</span> <var>initiatorOrigin</var>, perform the following steps. They return a
<code>Document</code> or null.</p>
<ol>
<li><p>Let <var>type</var> be the <span data-x="Content-Type sniffing">computed type</span> of
<var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>.</p></li>
<li>
<p>If the user agent has been configured to process resources of the given <var>type</var>
using some mechanism other than rendering the content in a <span>navigable</span>, then
skip this step. Otherwise, if the <var>type</var> is one of the following types:</p>
<dl class="switch">
<dt>an <span>HTML MIME type</span></dt>
<dd>Return the result of <span data-x="navigate-html">loading an HTML document</span>, given
<var>navigationParams</var>.</dd>
<dt>an <span>XML MIME type</span> that is not an <span>explicitly supported XML MIME
type</span></dt>
<dd>Return the result of <span data-x="navigate-xml">loading an XML document</span> given
<var>navigationParams</var> and <var>type</var>.</dd>
<dt>a <span>JavaScript MIME type</span></dt>
<dt>a <span>JSON MIME type</span> that is not an <span>explicitly supported JSON MIME
type</span></dt>
<dt>"<code>text/css</code>"</dt>
<dt>"<code>text/plain</code>"</dt>
<dt>"<code>text/vtt</code>"</dt>
<dd>Return the result of <span data-x="navigate-text">loading a text document</span> given
<var>navigationParams</var> and <var>type</var>.</dd>
<dt>"<code>multipart/x-mixed-replace</code>"</dt>
<dd>Return the result of <span data-x="navigate-multipart-x-mixed-replace">loading a
<code>multipart/x-mixed-replace</code> document</span>, given <var>navigationParams</var>,
<var>sourceSnapshotParams</var>, and <var>initiatorOrigin</var>.</dd>
<dt>A supported image, video, or audio type</dt>
<dd>Return the result of <span data-x="navigate-media">loading a media document</span> given
<var>navigationParams</var> and <var>type</var>.</dd>
<dt>"<code data-x="">application/pdf</code>"</dt>
<dt>"<code data-x="">text/pdf</code>"</dt>
<dd>If the user agent's <span>PDF viewer supported</span> is true, return the result of <span
data-x="navigate-ua-inline">creating a document for inline content that doesn't have a
DOM</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-id">id</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-nav-timing-type">navigation timing type</span>, and
<var>navigationParams</var>'s <span data-x="navigation-params-user-involvement">user
involvement</span>.</dd>
</dl>
<p>Otherwise, proceed onward.</p>
<p>An <dfn>explicitly supported XML MIME type</dfn> is an <span>XML MIME type</span> for which
the user agent is configured to use an external application to render the content, or for which
the user agent has dedicated processing rules. For example, a web browser with a built-in Atom
feed viewer would be said to explicitly support the <code>application/atom+xml</code> MIME
type.</p>
<p>An <dfn>explicitly supported JSON MIME type</dfn> is a <span>JSON MIME type</span> for which
the user agent is configured to use an external application to render the content, or for which
the user agent has dedicated processing rules.</p>
<p class="note">In both cases, the external application or user agent will either <span
data-x="navigate-ua-inline">display the content inline</span> directly in
<var>navigationParams</var>'s <span data-x="navigation-params-navigable">navigable</span>, or
<span data-x="hand-off to external software">hand it off to external software</span>. Both
happen in the steps below.</p>
</li>
<li id="navigate-non-Document"><p>If, given <var>type</var>, the new resource is to be handled
by displaying some sort of inline content, e.g., a native rendering of the content or an error
message because the specified type is not supported, then return the result of <span
data-x="navigate-ua-inline">creating a document for inline content that doesn't have a
DOM</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-id">id</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-nav-timing-type">navigation timing type</span>, and
<var>navigationParams</var>'s <span data-x="navigation-params-user-involvement">user
involvement</span>.</p></li>
<li><p>Otherwise, the document's <var>type</var> is such that the resource will not affect
<var>navigationParams</var>'s <span data-x="navigation-params-navigable">navigable</span>, e.g.,
because the resource is to be handed to an external application or because it is an unknown type
that will be processed by <span>handle as a download</span>. <span>Hand-off to external
software</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-sandboxing">final sandboxing flag set</span>,
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-activation">has transient
activation</span>, and <var>initiatorOrigin</var>.</p></li>
<li><p>Return null.</p></li>
</ol>
<h4>Applying the history step</h4>
<p>For both navigation and traversal, once we have an idea of where we want to head to in the
session history, much of the work comes about in applying that notion to the <span>traversable
navigable</span> and the relevant <code>Document</code>. For navigations, this work generally
occurs toward the end of the process; for traversals, it is the beginning.</p>
<h5>Updating the traversable</h5>
<p>Ensuring a <span data-x="traversable navigable">traversable</span> ends up at the right
session history step is particularly complex, as it can involve coordinating across multiple
<span>navigable</span> descendants of the traversable, <a
href="#populating-a-session-history-entry">populating</a> them in parallel, and then
synchronizing back up to ensure everyone has the same view of the result. This is further
complicated by the existence of synchronous same-document navigations being mixed together with
cross-document navigations, and how web pages have come to have certain relative timing
expectations.</p>
<p>A <dfn>changing navigable continuation state</dfn> is used to store information during the
<span>apply the history step</span> algorithm, allowing parts of the algorithm to continue only
after other parts have finished. It is a <span>struct</span> with:</p>
<dl>
<dt><dfn data-x="changing-nav-continuation-displayed-document">displayed document</dfn></dt>
<dd>A <code>Document</code></dd>
<dt><dfn data-x="changing-nav-continuation-target-entry">target entry</dfn></dt>
<dd>A <span>session history entry</span></dd>
<dt><dfn data-x="changing-nav-continuation-navigable">navigable</dfn></dt>
<dd>A <span>navigable</span></dd>
<dt><dfn data-x="changing-nav-continuation-update-only">update only</dfn></dt>
<dd>A boolean</dd>
</dl>
<hr>
<p>Although all updates to the <span>traversable navigable</span> end up in the same <span>apply
the history step</span> algorithm, each possible entry point comes along with some minor
customizations:</p>
<p>To <dfn>update for navigable creation/destruction</dfn> given a <span>traversable
navigable</span> <var>traversable</var>:</p>
<ol>
<li><p>Let <var>step</var> be <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span>.</p></li>
<li><p>Return the result of <span data-x="apply the history step">applying the history
step</span> <var>step</var> to <var>traversable</var> given false, null, null, "<code
data-x="uni-none">none</code>", and null.</p></li>
</ol>
<p>To <dfn>apply the push/replace history step</dfn> given a non-negative integer <var>step</var>
to a <span>traversable navigable</span> <var>traversable</var>, given a <span>history handling
behavior</span> <var>historyHandling</var> and a <span>user navigation involvement</span>
<var>userInvolvement</var>:</p>
<ol>
<li><p>Return the result of <span data-x="apply the history step">applying the history
step</span> <var>step</var> to <var>traversable</var> given false, null, null,
<var>userInvolvement</var>, and <var>historyHandling</var>.</p></li>
</ol>
<p class="note"><span>Apply the push/replace history step</span> never passes <span>source
snapshot params</span> or an initiator <span>navigable</span> to <span>apply the history
step</span>. This is because those checks are done earlier in the <span
data-x="navigate">navigation</span> algorithm.</p>
<p>To <dfn>apply the reload history step</dfn> to a <span>traversable navigable</span>
<var>traversable</var> given <span>user navigation involvement</span>
<var>userInvolvement</var>:</p>
<ol>
<li><p>Let <var>step</var> be <var>traversable</var>'s <span
data-x="tn-current-session-history-step">current session history step</span>.</p></li>
<li><p>Return the result of <span data-x="apply the history step">applying the history
step</span> <var>step</var> to <var>traversable</var> given true, null, null,
<var>userInvolvement</var>, and "<code
data-x="dom-NavigationType-reload">reload</code>".</p></li>
</ol>
<p class="note"><span>Apply the reload history step</span> never passes <span>source snapshot
params</span> or an initiator <span>navigable</span> to <span>apply the history step</span>. This
is because reloading is always treated as if it were done by the <span>navigable</span> itself,
even in cases like <code data-x="">parent.location.reload()</code>.</p>
<p>To <dfn>apply the traverse history step</dfn> given a non-negative integer <var>step</var> to a
<span>traversable navigable</span> <var>traversable</var>, with <span>source snapshot
params</span> <var>sourceSnapshotParams</var>, <span>navigable</span> <var>initiatorToCheck</var>,
and <span>user navigation involvement</span> <var>userInvolvement</var>:</p>
<ol>
<li><p>Return the result of <span data-x="apply the history step">applying the history
step</span> <var>step</var> to <var>traversable</var> given true,
<var>sourceSnapshotParams</var>, <var>initiatorToCheck</var>,
<var>userInvolvement</var>, and "<code
data-x="dom-NavigationType-traverse">traverse</code>".</p></li>
</ol>
<hr>
<p>Now for the algorithm itself.</p>
<p id="update-the-session-history-with-the-new-page">To <dfn>apply the history step</dfn> given a
non-negative integer <var>step</var> to a <span>traversable navigable</span>
<var>traversable</var>, with boolean <var>checkForCancelation</var>, <span>source snapshot
params</span>-or-null <var>sourceSnapshotParams</var>, <span>navigable</span>-or-null
<var>initiatorToCheck</var>, <span>user navigation involvement</span> <var>userInvolvement</var>,
and <code>NavigationType</code>-or-null <var>navigationType</var>, perform the following steps.
They return "<code data-x="">initiator-disallowed</code>", "<code
data-x="">canceled-by-beforeunload</code>", "<code data-x="">canceled-by-navigate</code>", or
"<code data-x="">applied</code>".</p>
<ol>
<li><p><span>Assert</span>: This is running within <var>traversable</var>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>Let <var>targetStep</var> be the result of <span>getting the used step</span> given
<var>traversable</var> and <var>step</var>.</p></li>
<li>
<p>If <var>initiatorToCheck</var> is not null, then:</p>
<ol>
<li><p><span>Assert</span>: <var>sourceSnapshotParams</var> is not null.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>navigable</var> of <span>get all
navigables whose current session history entry will change or reload</span>: if
<var>initiatorToCheck</var> is not <span>allowed by sandboxing to navigate</span>
<var>navigable</var> given <var>sourceSnapshotParams</var>, then return "<code
data-x="">initiator-disallowed</code>".</p></li>
</ol>
</li>
<li><p>Let <var>navigablesCrossingDocuments</var> be the result of <span>getting all navigables
that might experience a cross-document traversal</span> given <var>traversable</var> and
<var>targetStep</var>.</p></li>
<li><p>If <var>checkForCancelation</var> is true, and the result of <span>checking if unloading
is canceled</span> given <var>navigablesCrossingDocuments</var>, <var>traversable</var>,
<var>targetStep</var>, and <var>userInvolvement</var> is not "<code data-x="">continue</code>",
then return that result.</p></li>
<li><p>Let <var>changingNavigables</var> be the result of <span>get all navigables whose current
session history entry will change or reload</span> given <var>traversable</var> and
<var>targetStep</var>.</p></li>
<li><p>Let <var>nonchangingNavigablesThatStillNeedUpdates</var> be the result of <span>getting
all navigables that only need history object length/index update</span> given
<var>traversable</var> and <var>targetStep</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>changingNavigables</var>:</p>
<ol>
<li><p>Let <var>targetEntry</var> be the result of <span>getting the target history
entry</span> given <var>navigable</var> and <var>targetStep</var>.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-current-history-entry">current session
history entry</span> to <var>targetEntry</var>.</p></li>
<li><p><span>Set the ongoing navigation</span> for <var>navigable</var> to "<code
data-x="">traversal</code>".</p></li>
</ol>
</li>
<li><p>Let <var>totalChangeJobs</var> be the <span data-x="list size">size</span> of
<var>changingNavigables</var>.</p></li>
<li><p>Let <var>completedChangeJobs</var> be 0.</p></li>
<li>
<p>Let <var>changingNavigableContinuations</var> be an empty <span>queue</span> of <span
data-x="changing navigable continuation state">changing navigable continuation
states</span>.</p>
<p class="note">This queue is used to split the operations on <var>changingNavigables</var>
into two parts. Specifically, <var>changingNavigableContinuations</var> holds data for the <a
href="#continuations-dequeue">second part</a>.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>changingNavigables</var>, <span>queue a global task</span> on the <span>navigation and
traversal task source</span> of <var>navigable</var>'s <span data-x="nav-window">active
window</span> to run the steps:</p>
<p class="note">This set of steps are split into two parts to allow synchronous navigations to
be processed before documents unload. State is stored in
<var>changingNavigableContinuations</var> for the <a href="#continuations-dequeue">second
part</a>.</p>
<ol>
<li><p>Let <var>displayedEntry</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>Let <var>targetEntry</var> be <var>navigable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span>.</p></li>
<li>
<p>Let <var>changingNavigableContinuation</var> be a <span>changing navigable continuation
state</span> with:</p>
<dl class="props">
<dt><span data-x="changing-nav-continuation-displayed-document">displayed document</span></dt>
<dd><var>displayedEntry</var>'s <span data-x="she-document">document</span></dd>
<dt><span data-x="changing-nav-continuation-target-entry">target entry</span></dt>
<dd><var>targetEntry</var></dd>
<dt><span data-x="changing-nav-continuation-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="changing-nav-continuation-update-only">update-only</span></dt>
<dd>false</dd>
</dl>
</li>
<li>
<p>If <var>displayedEntry</var> is <var>targetEntry</var> and <var>targetEntry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is false, then:</p>
<ol>
<li><p>Set <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-update-only">update-only</span> to true.</p></li>
<li><p><span>Enqueue</span> <var>changingNavigableContinuation</var> on
<var>changingNavigableContinuations</var>.</p></li>
<li><p>Abort these steps.</p></li>
</ol>
<p class="note">This case occurs due to a <span data-x="finalize a same-document
navigation">synchronous navigation</span> which already updated the <span
data-x="nav-active-history-entry">active session history entry</span>.</p>
</li>
<li>
<p>Switch on <var>navigationType</var>:</p>
<dl class=switch>
<dt>"<code data-x="dom-NavigationType-reload">reload</code>"</dt>
<dd><p><span>Assert</span>: <var>targetEntry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is true.</p></dd>
<dt>"<code data-x="dom-NavigationType-traverse">traverse</code>"</dt>
<dd><p><span>Assert</span>: <var>targetEntry</var>'s
<span data-x="she-document-state">document state</span>'s <span
data-x="document-state-ever-populated">ever populated</span> is true.</p></dd>
<dt>"<code data-x="dom-NavigationType-replace">replace</code>"</dt>
<dd><p><span>Assert</span>: <var>targetEntry</var>'s <span data-x="she-step">step</span>
is <var>displayedEntry</var>'s <span data-x="she-step">step</span> and
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-ever-populated">ever populated</span> is false.</p></dd>
<dt>"<code data-x="dom-NavigationType-push">push</code>"</dt>
<dd><p><span>Assert</span>: <var>targetEntry</var>'s <span data-x="she-step">step</span> is
<var>displayedEntry</var>'s <span data-x="she-step">step</span> + 1 and
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-ever-populated">ever populated</span> is false.</p></dd>
</dl>
</li>
<li><p>Let <var>oldOrigin</var> be <var>targetEntry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span>.</p></li>
<li id="descendant-navigable-traversal-navigate-events">
<p>If all of the following are true:</p>
<ul>
<li><p><var>navigable</var> is not <var>traversable</var>;</p></li>
<li><p><var>targetEntry</var> is not <var>navigable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span>; and</p></li>
<li><p><var>oldOrigin</var> is the <span data-x="same origin">same</span> as
<var>navigable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Let <var>navigation</var> be <var>navigable</var>'s <span
data-x="nav-window">active window</span>'s <span
data-x="window-navigation-api">navigation API.</span></p></li>
<li><p><span>Fire a traverse <code data-x="event-navigate">navigate</code> event</span> at
<var>navigation</var> given <var>targetEntry</var> and <var>userInvolvement</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>targetEntry</var>'s <span data-x="she-document">document</span> is null, or
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is true, then:</p>
<ol>
<li><p>Let <var>navTimingType</var> be "<code
data-x="dom-navigationtimingtype-back_forward">back_forward</code>" if
<var>targetEntry</var>'s <span data-x="she-document">document</span> is null; otherwise
"<code data-x="dom-navigationtimingtype-back_forward">reload</code>".</p></li>
<li><p>Let <var>targetSnapshotParams</var> be the result of <span>snapshotting target
snapshot params</span> given <var>navigable</var>.</p></li>
<li><p>Let <var>potentiallyTargetSpecificSourceSnapshotParams</var> be
<var>sourceSnapshotParams</var>.</p></li>
<li>
<p>If <var>potentiallyTargetSpecificSourceSnapshotParams</var> is null, then set it to the
result of <span>snapshotting source snapshot params</span> given <var>navigable</var>'s
<span data-x="nav-document">active document</span>.</p>
<p class="note">In this case there is no clear source of the traversal/reload. We treat this
situation as if <var>navigable</var> navigated itself, but note that some properties of
<var>targetEntry</var>'s original initiator are preserved in <var>targetEntry</var>'s <span
data-x="she-document-state">document state</span>, such as the <span
data-x="document-state-initiator-origin">initiator origin</span> and <span
data-x="document-state-request-referrer">referrer</span>, which will appropriately influence
the navigation.</p>
</li>
<li><p>Set <var>targetEntry</var>'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-reload-pending">reload pending</span> to
false.</p></li>
<li><p>Let <var>allowPOST</var> be <var>targetEntry</var>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span>.</p>
<li><p><span>In parallel</span>, <span>attempt to populate the history entry's
document</span> for <var>targetEntry</var>, given <var>navigable</var>,
<var>potentiallyTargetSpecificSourceSnapshotParams</var>, <var>targetSnapshotParams</var>,
<var>userInvolvement</var>, with <i data-x="attempt-to-populate-allow-post">allowPOST</i> set
to <var>allowPOST</var> and <span
data-x="attempt-to-populate-completion-steps"><i>completionSteps</i></span> set to
<span>queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>navigable</var>'s <span data-x="nav-window">active window</span> to run
<var>afterDocumentPopulated</var>.</p></li>
</ol>
<p>Otherwise, run <var>afterDocumentPopulated</var> <span>immediately</span>.</p>
<p>In both cases, let <var>afterDocumentPopulated</var> be the following steps:</p>
<ol>
<li>
<p>If <var>targetEntry</var>'s <span data-x="she-document">document</span> is null, then
set <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-update-only">update-only</span> to true.</p>
<p class="note">This means we tried to populate the document, but were unable to do so,
e.g. because of the server returning a 204.</p>
<div class="note">
<p>These kinds of failed navigations or traversals will not be signaled to the <a
href="#navigation-api">navigation API</a> (e.g., through the promises of any
<span>navigation API method tracker</span>, or the <code
data-x="event-navigateerror">navigateerror</code> event). Doing so would leak information
about the timing of responses from other origins, in the cross-origin case, and providing
different results in the cross-origin vs. same-origin cases was deemed too confusing.</p>
<p>However, implementations could use this opportunity to clear any promise handlers for
the <code data-x="dom-NavigationTransition-finished">navigation.transition.finished</code>
promise, as they are guaranteed at this point to never run. And, they might wish to
<span>report a warning to the console</span> if any part of the navigation API initiated
these navigations, to make it clear to the web developer why their promises will never
settle and events will never fire.</p>
</div>
</li>
<li>
<p>If <var>targetEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-origin">origin</span> is not <var>oldOrigin</var>, then set
<var>targetEntry</var>'s <span data-x="she-classic-history-api-state">classic history API
state</span> to <span>StructuredSerializeForStorage</span>(null).</p>
<p class="note">This clears history state when the origin changed vs a previous load of
<var>targetEntry</var> without a redirect occuring. This can happen due to a change in CSP
sandbox headers.</p>
</li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>navigable</var>'s <span data-x="nav-parent">parent</span> is null;</p></li>
<li><p><var>targetEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-bc">browsing context</span> is not an <span>auxiliary browsing
context</span> whose <span>opener browsing context</span> is non-null; and</p></li>
<li><p><var>targetEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-origin">origin</span> is not <var>oldOrigin</var>,</p></li>
</ul>
<p>then set <var>targetEntry</var>'s <span data-x="she-document-state">document
state</span>'s <span data-x="document-state-nav-target-name">navigable target name</span>
to the empty string.</p>
</li>
<li>
<p><span>Enqueue</span> <var>changingNavigableContinuation</var> on
<var>changingNavigableContinuations</var>.</p>
<p class="note">The rest of this job <a href="#continuations-dequeue">runs later</a> in
this algorithm.</p>
</li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>navigablesThatMustWaitBeforeHandlingSyncNavigation</var> be an empty
<span>set</span>.</p></li>
<li>
<p>While <var>completedChangeJobs</var> does not equal <var>totalChangeJobs</var>:</p>
<ol>
<li>
<p>If <var>traversable</var>'s <span data-x="tn-running-nested-apply-history-step">running
nested apply history step</span> is false, then:</p>
<ol>
<li id="sync-navigations-jump-queue">
<p>While <var>traversable</var>'s <span data-x="tn-session-history-traversal-queue">session
history traversal queue</span>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span> <span
data-x="list contains">contains</span> one or more <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous navigation
steps</span> with a <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps-target-nav">target
navigable</span> not <span data-x="list contains">contained</span> in
<var>navigablesThatMustWaitBeforeHandlingSyncNavigation</var>:</p>
<ol>
<li><p>Let <var>steps</var> be the first <span data-x="list item">item</span> in
<var>traversable</var>'s <span data-x="tn-session-history-traversal-queue">session history
traversal queue</span>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm set</span> that
is <span data-x="session-history-traversal-parallel-queue-sync-nav-steps">synchronous
navigation steps</span> with a <span
data-x="session-history-traversal-parallel-queue-sync-nav-steps-target-nav">target
navigable</span> not <span data-x="list contains">contained</span> in
<var>navigablesThatMustWaitBeforeHandlingSyncNavigation</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>steps</var> from
<var>traversable</var>'s <span data-x="tn-session-history-traversal-queue">session history
traversal queue</span>'s <span
data-x="session-history-traversal-parallel-queue-algorithm-set">algorithm
set</span>.</p></li>
<li><p>Set <var>traversable</var>'s <span
data-x="tn-running-nested-apply-history-step">running nested apply history step</span> to
true.</p></li>
<li><p>Run <var>steps</var>.</p></li>
<li><p>Set <var>traversable</var>'s <span
data-x="tn-running-nested-apply-history-step">running nested apply history step</span> to
false.</p></li>
</ol>
<p class="note">Synchronous navigations that are intended to take place before this
traversal jump the queue at this point, so they can be added to the correct place in
<var>traversable</var>'s <span data-x="tn-session-history-entries">session history
entries</span> before this traversal potentially unloads their document. <a
href="#sync-navigation-steps-queue-jumping-examples">More details can be found
here</a>.</p>
</li>
</ol>
</li>
<li id="continuations-dequeue"><p>Let <var>changingNavigableContinuation</var> be the result
of <span data-x="dequeue">dequeuing</span> from
<var>changingNavigableContinuations</var>.</p></li>
<li><p>If <var>changingNavigableContinuation</var> is nothing, then
<span>continue</span>.</p></li>
<li><p>Let <var>displayedDocument</var> be <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-displayed-document">displayed document</span>.</p></li>
<li><p>Let <var>targetEntry</var> be <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-target-entry">target entry</span>.</p></li>
<li><p>Let <var>navigable</var> be <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-navigable">navigable</span>.</p></li>
<li>
<p>Let (<var>scriptHistoryLength</var>, <var>scriptHistoryIndex</var>) be the result of
<span>getting the history object length and index</span> given <var>traversable</var> and
<var>targetStep</var>.</p>
<p class="note">These values might have changed since they were last calculated.</p>
</li>
<li>
<p><span data-x="list append">Append</span> <var>navigable</var> to
<var>navigablesThatMustWaitBeforeHandlingSyncNavigation</var>.</p>
<p class="note">Once a navigable has reached this point in traversal, additionally queued
synchronous navigation steps are likely to be intended to occur after this traversal rather
than before it, so they no longer jump the queue. <a
href="#sync-navigation-steps-queue-jumping-examples">More details can be found here</a>.</p>
</li>
<li><p>Let <var>entriesForNavigationAPI</var> be the result of <span>getting session history
entries for the navigation API</span> given <var>navigable</var> and
<var>targetStep</var>.</p></li>
<li>
<p>If <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-update-only">update-only</span> is true, or
<var>targetEntry</var>'s <span data-x="she-document">document</span> is
<var>displayedDocument</var>, then:</p>
<p class="note">This is a same-document navigation: we proceed without unloading.</p>
<ol>
<li>
<p><span>Set the ongoing navigation</span> for <var>navigable</var> to null.</p>
<p class="note">This allows new <span data-x="navigate">navigations</span> of
<var>navigable</var> to start, whereas during the traversal they were blocked.</p>
</li>
<li><p><span>Queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>navigable</var>'s <span data-x="nav-window">active window</span> to
perform <var>afterPotentialUnloads</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>navigationType</var> is not null.</p></li>
<li><p><span data-x="deactivate a document for a cross-document navigation">Deactivate</span>
<var>displayedDocument</var>, given <var>userInvolvement</var>, <var>targetEntry</var>,
<var>navigationType</var>, and <var>afterPotentialUnloads</var>.</p></li>
</ol>
</li>
<li>
<p>In both cases, let <var>afterPotentialUnloads</var> be the following steps:</p>
<ol>
<li><p>Let <var>previousEntry</var> be <var>navigable</var>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>If <var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-update-only">update-only</span> is false, then
<span>activate history entry</span> <var>targetEntry</var> for
<var>navigable</var>.</p></li>
<li><p>Let <var>updateDocument</var> be an algorithm step which performs <span>update
document for history step application</span> given <var>targetEntry</var>'s <span
data-x="she-document">document</span>, <var>targetEntry</var>,
<var>changingNavigableContinuation</var>'s <span
data-x="changing-nav-continuation-update-only">update-only</span>,
<var>scriptHistoryLength</var>, <var>scriptHistoryIndex</var>, <var>navigationType</var>,
<var>entriesForNavigationAPI</var>, and <var>previousEntry</var>.</p></li>
<li><p>If <var>targetEntry</var>'s <span data-x="she-document">document</span> is equal to
<var>displayedDocument</var>, then perform <var>updateDocument</var>.</p></li>
<li><p>Otherwise, <span>queue a global task</span> on the <span>navigation and traversal task
source</span> given <var>targetEntry</var>'s <span data-x="she-document">document</span>'s
<span>relevant global object</span> to perform <var>updateDocument</var>.</p></li>
<li><p>Increment <var>completedChangeJobs</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Let <var>totalNonchangingJobs</var> be the <span data-x="list size">size</span> of
<var>nonchangingNavigablesThatStillNeedUpdates</var>.</p>
<p class="note">This step onwards deliberately waits for all the previous operations to
complete, as they include <a href="#sync-navigations-jump-queue">processing synchronous
navigations</a> which will also post tasks to update history length and index.</p>
</li>
<li><p>Let <var>completedNonchangingJobs</var> be 0.</p></li>
<li><p>Let (<var>scriptHistoryLength</var>, <var>scriptHistoryIndex</var>) be the result of
<span>getting the history object length and index</span> given <var>traversable</var> and
<var>targetStep</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>nonchangingNavigablesThatStillNeedUpdates</var>, <span>queue a global task</span> on the
<span>navigation and traversal task source</span> given <var>navigable</var>'s <span
data-x="nav-window">active window</span> to run the steps:</p>
<ol>
<li><p>Let <var>document</var> be <var>navigable</var>'s <span data-x="nav-document">active
document</span>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-index">index</span> to <var>scriptHistoryIndex</var>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-length">length</span> to <var>scriptHistoryLength</var>.</p></li>
<li><p>Increment <var>completedNonchangingJobs</var>.</p></li>
</ol>
</li>
<li><p>Wait for <var>completedNonchangingJobs</var> to equal
<var>totalNonchangingJobs</var>.</p></li>
<li><p>Set <var>traversable</var>'s <span data-x="tn-current-session-history-step">current
session history step</span> to <var>targetStep</var>.</p></li>
<li><p>Return "<code data-x="">applied</code>".</p></li>
</ol>
<p>To <dfn>deactivate a document for a cross-document navigation</dfn> given a
<code>Document</code> <var>displayedDocument</var>, a <span>user navigation involvement</span>
<var>userNavigationInvolvement</var>, a <span>session history entry</span> <var>targetEntry</var>,
a <code>NavigationType</code> <var>navigationType</var>, and <var>afterPotentialUnloads</var>,
which is an algorithm that receives no arguments:</p>
<ol>
<li><p>Let <var>navigable</var> be <var>displayedDocument</var>'s
<span>node navigable</span>.</p></li>
<li><p>Let <var>potentiallyTriggerViewTransition</var> be false.</p></li>
<li><p>Let <var>isBrowserUINavigation</var> be true if
<var>userNavigationInvolvement</var> is "<code
data-x="uni-browser-ui">browser UI</code>"; otherwise false.</p></li>
<li><p>Set <var>potentiallyTriggerViewTransition</var> to the result of calling
<span>can navigation trigger a cross-document view-transition?</span> given
<var>displayedDocument</var>, <var>targetEntry</var>'s <span
data-x="she-document">document</span>, <var>navigationType</var>, and
<var>isBrowserUINavigation</var>.</p></li>
<li>
<p>If <var>potentiallyTriggerViewTransition</var> is false, then:</p>
<ol>
<li>
<p>Let <var>firePageSwapBeforeUnload</var> be the following step:</p>
<ol>
<li><p><span>Fire the <code data-x="event-pageswap">pageswap</code> event</span> given
<var>displayedDocument</var>, <var>targetEntry</var>, <var>navigationType</var>, and
null.</p></li>
</ol>
</li>
<li>
<p><span>Set the ongoing navigation</span> for <var>navigable</var> to null.</p>
<p class="note">This allows new <span data-x="navigate">navigations</span> of
<var>navigable</var> to start, whereas during the traversal they were blocked.</p>
</li>
<li><p><span>Unload a document and its descendants</span> given
<var>displayedDocument</var>, <var>targetEntry</var>'s <span
data-x="she-document">document</span>, <var>afterPotentialUnloads</var>, and
<var>firePageSwapBeforeUnload</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, <span>queue a global task</span> on the
<span>navigation and traversal task source</span> given <var>navigable</var>'s <span
data-x="nav-window">active window</span> to run the steps:</p>
<ol>
<li>
<p>Let <var>proceedWithNavigationAfterViewTransitionCapture</var> be the following
step:</p>
<ol>
<li>
<p><span data-x="tn-append-session-history-traversal-steps">Append the following session
history traversal steps</span> to <var>navigable</var>'s <span
data-x="nav-traversable">traversable navigable</span>:</p>
<ol>
<li>
<p><span>Set the ongoing navigation</span> for <var>navigable</var> to null.</p>
<p class="note">This allows new <span data-x="navigate">navigations</span> of
<var>navigable</var> to start, whereas during the traversal they were blocked.</p>
</li>
<li><p><span>Unload a document and its descendants</span> given
<var>displayedDocument</var>, <var>targetEntry</var>'s <span
data-x="she-document">document</span>, and <var>afterPotentialUnloads</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Let <var>viewTransition</var> be the result of
<span>setting up a cross-document view-transition</span> given
<var>displayedDocument</var>, <var>targetEntry</var>'s <span
data-x="she-document">document</span>, <var>navigationType</var>, and
<var>proceedWithNavigationAfterViewTransitionCapture</var>.</p></li>
<li><p><span>Fire the <code data-x="event-pageswap">pageswap</code> event</span> given
<var>displayedDocument</var>, <var>targetEntry</var>, <var>navigationType</var>, and
<var>viewTransition</var>.</p>
<li>
<p>If <var>viewTransition</var> is null, then run
<var>proceedWithNavigationAfterViewTransitionCapture</var>.</p>
<p class="note">In the case where a view transition started, the view transitions
algorithms are responsible for calling
<var>proceedWithNavigationAfterViewTransitionCapture</var>.</p>
</li>
</ol>
</li>
</ol>
<p>To <dfn>fire the <code data-x="event-pageswap">pageswap</code> event</dfn> given a
<code>Document</code> <var>displayedDocument</var>, a <span>session history entry</span>
<var>targetEntry</var>, a <code>NavigationType</code> <var>navigationType</var>, and a
<code>ViewTransition</code>-or-null <var>viewTransition</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running as part of a <span
data-x="concept-task">task</span> queued on <var>displayedDocument</var>'s
<span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Let <var>navigation</var> be <var>displayedDocument</var>'s
<span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>.</p></li>
<li><p>Let <var>activation</var> be null.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>targetEntry</var>'s <span data-x="she-document">document</span>'s <span
data-x="concept-document-origin">origin</span> is <span>same origin</span> with
<var>displayedDocument</var>'s <span data-x="concept-document-origin">origin</span>;
and</p></li>
<li><p><var>targetEntry</var>'s <span data-x="she-document">document</span>'s
<span>was created via cross-origin redirects</span> is false, or <var>targetEntry</var>'s
<span data-x="she-document">document</span>'s <span>latest entry</span> is not null,</p></li>
</ul>
<p>then:</p>
<ol>
<li>
<p>Let <var>destinationEntry</var> be determined by switching on
<var>navigationType</var>:</p>
<dl class="switch">
<dt>"<code data-x="dom-NavigationType-reload">reload</code>"</dt>
<dd><p>The <span data-x="navigation-current-entry">current entry</span> of
<var>navigation</var></p></dd>
<dt>"<code data-x="dom-NavigationType-traverse">traverse</code>"</dt>
<dd><p>The <code>NavigationHistoryEntry</code> in <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span> whose <span
data-x="nhe-she">session history entry</span> is <var>targetEntry</var></p></dd>
<dt>"<code data-x="dom-NavigationType-push">push</code>"</dt>
<dt>"<code data-x="dom-NavigationType-replace">replace</code>"</dt>
<dd><p>A new <code>NavigationHistoryEntry</code> in <var>displayedDocument</var>'s <span
data-x="concept-relevant-realm">relevant realm</span> with its <span
data-x="nhe-she">session history entry</span> set to <var>targetEntry</var>.</p></dd>
</dl>
</li>
<li>
<p>Set <var>activation</var> to a <span>new</span> <code>NavigationActivation</code>
created in <var>displayedDocument</var>'s <span data-x="concept-relevant-realm">relevant
realm</span>, with</p>
<dl class="props">
<dt><span data-x="nav-activation-old-entry">old entry</span></dt>
<dd>the <span data-x="navigation-current-entry">current entry</span> of
<var>navigation</var></dd>
<dt><span data-x="nav-activation-new-entry">new entry</span></dt>
<dd><var>destinationEntry</var></dd>
<dt><span data-x="nav-activation-navigation-type">navigation type</span></dt>
<dd><var>navigationType</var></dd>
</dl>
</li>
</ol>
<p class="note">This means that a cross-origin redirect during a navigation would result in a
null <code data-x="dom-PageSwapEvent-activation">activation</code> in the old document's
<code>PageSwapEvent</code>, unless the new document is being restored from <a
href="#note-bfcache">bfcache</a>.</p>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named
<code data-x="event-pageswap">pageswap</code> at <var>displayedDocument</var>'s
<span>relevant global object</span>, using <code>PageSwapEvent</code> with its <code
data-x="dom-PageSwapEvent-activation">activation</code> set to <var>activation</var>,
and its <code data-x="dom-PageSwapEvent-viewTransition">viewTransition</code> set to
<var>viewTransition</var>.</p></li>
</ol>
<p>To <dfn>activate history entry</dfn> <span>session history entry</span> <var>entry</var> for
<span>navigable</span> <var>navigable</var>:</p>
<ol>
<li><p><span>Save persisted state</span> to the <span>navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>.</p></li>
<li><p>Let <var>newDocument</var> be <var>entry</var>'s <span
data-x="she-document">document</span>.</p></li>
<li><p><span>Assert</span>: <var>newDocument</var>'s <span>is initial
<code>about:blank</code></span> is false, i.e., we never traverse back to the <span data-x="is
initial about:blank">initial <code>about:blank</code></span> <code>Document</code> because it
always gets <a href="#navigate-convert-to-replace">replaced</a> when we navigate away from
it.</p></li>
<li><p>Set <var>navigable</var>'s <span data-x="nav-active-history-entry">active session history
entry</span> to <var>entry</var>.</p></li>
<li><p><span>Make active</span> <var>newDocument</var>.</p></li>
</ol>
<p>To <dfn data-x="getting the used step">get the used step</dfn> given a <span>traversable
navigable</span> <var>traversable</var>, and a non-negative integer <var>step</var>, perform the
following steps. They return a non-negative integer.</p>
<ol>
<li><p>Let <var>steps</var> be the result of <span>getting all used history steps</span> within
<var>traversable</var>.</p></li>
<li>
<p>Return the greatest <span data-x="list item">item</span> in <var>steps</var> that is less
than or equal to <var>step</var>.</p>
<p class="note">This caters for situations where there's no <span>session history entry</span>
with <span data-x="she-step">step</span> <var>step</var>, due to the removal of a
<span>navigable</span>.</p>
</li>
</ol>
<p>To <dfn data-x="getting the history object length and index">get the history object length and
index</dfn> given a <span>traversable navigable</span> <var>traversable</var>, and a non-negative
integer <var>step</var>, perform the following steps. They return a <span>tuple</span> of two
non-negative integers.</p>
<ol>
<li><p>Let <var>steps</var> be the result of <span>getting all used history steps</span> within
<var>traversable</var>.</p></li>
<li><p>Let <var>scriptHistoryLength</var> be the <span data-x="list size">size</span> of
<var>steps</var>.</p></li>
<li>
<p><span>Assert</span>: <var>steps</var> <span data-x="list contains">contains</span>
<var>step</var>.</p>
<p class="note">It is assumed that <var>step</var> has been adjusted by <span>getting the used
step</span>.</p>
</li>
<li><p>Let <var>scriptHistoryIndex</var> be the index of <var>step</var> in
<var>steps</var>.</p></li>
<li><p>Return (<var>scriptHistoryLength</var>, <var>scriptHistoryIndex</var>).</p></li>
</ol>
<p>To <dfn>get all navigables whose current session history entry will change or reload</dfn>
given a <span>traversable navigable</span> <var>traversable</var>, and a non-negative integer
<var>targetStep</var>, perform the following steps. They return a <span>list</span> of <span
data-x="navigable">navigables</span>.</p>
<ol>
<li><p>Let <var>results</var> be an empty <span>list</span>.</p></li>
<li>
<p>Let <var>navigablesToCheck</var> be « <var>traversable</var> ».</p>
<p class="note">This list is extended in the loop below.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>navigablesToCheck</var>:</p>
<ol>
<li><p>Let <var>targetEntry</var> be the result of <span>getting the target history
entry</span> given <var>navigable</var> and <var>targetStep</var>.</p></li>
<li><p>If <var>targetEntry</var> is not <var>navigable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span> or
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is true, then <span data-x="list
append">append</span> <var>navigable</var> to <var>results</var>.</p></li>
<li>
<p>If <var>targetEntry</var>'s <span data-x="she-document">document</span> is
<var>navigable</var>'s <span data-x="nav-document">document</span>, and
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is false, then <span
data-x="list extend">extend</span> <var>navigablesToCheck</var> with the <span data-x="child
navigable">child navigables</span> of <var>navigable</var>.</p>
<p class="note">Adding <span data-x="child navigable">child navigables</span> to
<var>navigablesToCheck</var> means those navigables will also be checked by this loop. <span
data-x="child navigable">Child navigables</span> are only checked if the
<var>navigable</var>'s <span data-x="nav-document">active document</span> will not change as
part of this traversal.</p>
</li>
</ol>
</li>
<li><p>Return <var>results</var>.</p></li>
</ol>
<p>To <dfn data-x="getting all navigables that only need history object length/index update">get
all navigables that only need history object length/index update</dfn> given a <span>traversable
navigable</span> <var>traversable</var>, and a non-negative integer <var>targetStep</var>,
perform the following steps. They return a <span>list</span> of <span
data-x="navigable">navigables</span>.</p>
<p class="note">Other <span data-x="navigable">navigables</span> might not be impacted by the
traversal. For example, if the response is a 204, the currently active document will remain.
Additionally, going 'back' after a 204 will change the <span
data-x="nav-current-history-entry">current session history entry</span>, but the <span
data-x="nav-active-history-entry">active session history entry</span> will already be
correct.</p>
<ol>
<li><p>Let <var>results</var> be an empty <span>list</span>.</p></li>
<li>
<p>Let <var>navigablesToCheck</var> be « <var>traversable</var> ».</p>
<p class="note">This list is extended in the loop below.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>navigablesToCheck</var>:</p>
<ol>
<li><p>Let <var>targetEntry</var> be the result of <span>getting the target history
entry</span> given <var>navigable</var> and <var>targetStep</var>.</p></li>
<li>
<p>If <var>targetEntry</var> is <var>navigable</var>'s <span
data-x="nav-current-history-entry">current session history entry</span> and
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is false, then:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>navigable</var> to
<var>results</var>.</p></li>
<li>
<p><span data-x="list extend">Extend</span> <var>navigablesToCheck</var> with
<var>navigable</var>'s <span data-x="child navigable">child navigables</span>.</p>
<p class="note">Adding <span data-x="child navigable">child navigables</span> to
<var>navigablesToCheck</var> means those navigables will also be checked by this loop.
<span data-x="child navigable">child navigables</span> are only checked if the
<var>navigable</var>'s <span data-x="nav-document">active document</span> will not change
as part of this traversal.</p>
</li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>results</var>.</p></li>
</ol>
<p>To <dfn data-x="getting the target history entry">get the target history entry</dfn> given a
<span>navigable</span> <var>navigable</var>, and a non-negative integer <var>step</var>, perform
the following steps. They return a <span>session history entry</span>.</p>
<ol>
<li><p>Let <var>entries</var> be the result of <span>getting session history entries</span> for
<var>navigable</var>.</p></li>
<li><p>Return the <span data-x="list item">item</span> in <var>entries</var> that has the
greatest <span data-x="she-step">step</span> less than or equal to <var>step</var>.</p></li>
</ol>
<div class="example" id="example-getting-the-target-history-entry">
<p>To see why <span>getting the target history entry</span> returns the entry with the greatest
<span data-x="she-step">step</span> less than or equal to the input step, consider the following
<span>Jake diagram</span>:</p>
<!--https://domenic.github.io/jake-diagram-generator/#dG9wCiAgMC0yOiAvdCB8IGRvYzEKICAzOiAvdCNmb28gfCBkb2MxCmZyYW1lc1swXQogIDA6IC9pLTAtYQogIDEtMzogL2ktMC1i -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step">2</th><th class="step">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="3" class="doc-0">/t</td><td colspan="1" class="doc-0">/t#foo</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-1">/i-0-a</td><td colspan="3" class="doc-2">/i-0-b</td></tr></tbody></table>
<p>For the input step 1, the target history entry for the <code data-x="">top</code> navigable
is the <code data-x="">/t</code> entry, whose <span data-x="she-step">step</span> is 0, while the target history entry for the <code data-x="">frames[0]</code> navigable is the <code
data-x="">/i-0-b</code> entry, whose <span data-x="she-step">step</span> is 1:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAxCnRvcAogIDAtMjogL3QgfCBkb2MxCiAgMzogL3QjZm9vIHwgZG9jMQpmcmFtZXNbMF0KICAwOiAvaS0wLWEKICAxLTM6IC9pLTAtYg== -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step current">1</th><th class="step">2</th><th class="step">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="3" class="doc-0 current next-is-same-doc">/t</td><td colspan="1" class="doc-0 prev-is-same-doc">/t#foo</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-1">/i-0-a</td><td colspan="3" class="doc-2 current">/i-0-b</td></tr></tbody></table>
<p>Similarly, given the input step 3 we get the <code data-x="">top</code> entry whose <span
data-x="she-step">step</span> is 3, and the <code data-x="">frames[0]</code> entry whose <span
data-x="she-step">step</span> is 1:</p>
<!--https://domenic.github.io/jake-diagram-generator/#IWN1cnJlbnQgPSAzCnRvcAogIDAtMjogL3QgfCBkb2MxCiAgMzogL3QjZm9vIHwgZG9jMQpmcmFtZXNbMF0KICAwOiAvaS0wLWEKICAxLTM6IC9pLTAtYg== -->
<table class="jake-diagram"><thead><tr><td></td><th class="step">0</th><th class="step">1</th><th class="step">2</th><th class="step current">3</th></tr></thead><tbody><tr><th><code data-x="">top</code></th><td colspan="3" class="doc-0 next-is-same-doc">/t</td><td colspan="1" class="doc-0 current prev-is-same-doc">/t#foo</td></tr><tr><th><code data-x="">frames[0]</code></th><td colspan="1" class="doc-1">/i-0-a</td><td colspan="3" class="doc-2 current">/i-0-b</td></tr></tbody></table>
</div>
<p>To <dfn data-x="getting all navigables that might experience a cross-document traversal">get
all navigables that might experience a cross-document traversal</dfn> given a <span>traversable
navigable</span> <var>traversable</var>, and a non-negative integer <var>targetStep</var>,
perform the following steps. They return a <span>list</span> of <span
data-x="navigable">navigables</span>.</p>
<div class="note">
<p>From <var>traversable</var>'s <span data-x="tn-session-history-traversal-queue">session
history traversal queue</span>'s perspective, these documents are candidates for going
cross-document during the traversal described by <var>targetStep</var>. They will not experience
a cross-document traversal if the status code for their target document is HTTP 204 No Content.</p>
<p>Note that if a given <span>navigable</span> might experience a cross-document traversal, this
algorithm will return <span>navigable</span> but not its <span data-x="child navigable">child
navigables</span>. Those would end up <span data-x="unload a document">unloaded</span>, not
traversed.</p>
</div>
<ol>
<li><p>Let <var>results</var> be an empty <span>list</span>.</p></li>
<li>
<p>Let <var>navigablesToCheck</var> be « <var>traversable</var> ».</p>
<p class="note">This list is extended in the loop below.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of
<var>navigablesToCheck</var>:</p>
<ol>
<li><p>Let <var>targetEntry</var> be the result of <span>getting the target history
entry</span> given <var>navigable</var> and <var>targetStep</var>.</p></li>
<li>
<p>If <var>targetEntry</var>'s <span data-x="she-document">document</span> is not
<var>navigable</var>'s <span data-x="nav-document">document</span> or
<var>targetEntry</var>'s <span data-x="she-document-state">document state</span>'s <span
data-x="document-state-reload-pending">reload pending</span> is true, then <span data-x="list
append">append</span> <var>navigable</var> to <var>results</var>.</p>
<p class="note">Although <var>navigable</var>'s <span
data-x="nav-active-history-entry">active history entry</span> can change synchronously, the
new entry will always have the same <code>Document</code>, so accessing
<var>navigable</var>'s <span data-x="nav-document">document</span> is reliable.</p>
</li>
<li>
<p>Otherwise, <span data-x="list extend">extend</span> <var>navigablesToCheck</var> with
<var>navigable</var>'s <span data-x="child navigable">child navigables</span>.</p>
<p class="note">Adding <span data-x="child navigable">child navigables</span> to
<var>navigablesToCheck</var> means those navigables will also be checked by this loop. <span
data-x="child navigable">Child navigables</span> are only checked if the
<var>navigable</var>'s <span data-x="nav-document">active document</span> will not change as
part of this traversal.</p>
</li>
</ol>
</li>
<li><p>Return <var>results</var>.</p></li>
</ol>
<h5>Updating the document</h5>
<p>To <dfn>update document for history step application</dfn> given a <code>Document</code>
<var>document</var>, a <span>session history entry</span> <var>entry</var>, a boolean
<var>doNotReactivate</var>, integers <var>scriptHistoryLength</var> and
<var>scriptHistoryIndex</var>, <code>NavigationType</code>-or-null <var>navigationType</var>, an
optional <span>list</span> of <span data-x="session history entry">session history entries</span>
<var>entriesForNavigationAPI</var>, and an optional <span>session history entry</span>
<var>previousEntryForActivation</var>:</p>
<ol>
<li><p>Let <var>documentIsNew</var> be true if <var>document</var>'s <span>latest entry</span>
is null; otherwise false.</p></li>
<li><p>Let <var>documentsEntryChanged</var> be true if <var>document</var>'s <span>latest
entry</span> is not <var>entry</var>; otherwise false.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-index">index</span> to <var>scriptHistoryIndex</var>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-length">length</span> to <var>scriptHistoryLength</var>.</p></li>
<li><p>Let <var>navigation</var> be <var>history</var>'s <span>relevant global object</span>'s
<span data-x="window-navigation-api">navigation API</span>.</p></li>
<li>
<p>If <var>documentsEntryChanged</var> is true, then:</p>
<ol>
<li><p>Let <var>oldURL</var> be <var>document</var>'s <span>latest entry</span>'s <span
data-x="she-url">URL</span>.</p></li>
<li><p>Set <var>document</var>'s <span>latest entry</span> to <var>entry</var>.</p></li>
<li><p><span>Restore the history object state</span> given <var>document</var> and
<var>entry</var>.</p></li>
<li>
<p>If <var>documentIsNew</var> is false, then:</p>
<ol>
<li><p><span>Assert</span>: <var>navigationType</var> is not null.</p></li>
<li><p><span>Update the navigation API entries for a same-document navigation</span> given
<var>navigation</var>, <var>entry</var>, and <var>navigationType</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-popstate">popstate</code> at <var>document</var>'s <span>relevant global
object</span>, using <code>PopStateEvent</code>, with the <code
data-x="dom-PopStateEvent-state">state</code> attribute initialized to <var>document</var>'s
<span data-x="doc-history">history object</span>'s <span
data-x="concept-history-state">state</span> and <code
data-x="dom-PopStateEvent-hasUAVisualTransition">hasUAVisualTransition</code> initialized to
true if a visual transition, to display a cached rendered state of the <span>latest
entry</span>, was done by the user agent.</p>
<li><p><span>Restore persisted state</span> given <var>entry</var>.</p></li>
<li><p>If <var>oldURL</var>'s <span data-x="concept-url-fragment">fragment</span> is not
equal to <var>entry</var>'s <span data-x="she-url">URL</span>'s <span
data-x="concept-url-fragment">fragment</span>, then <span>queue a global task</span> on the
<span>DOM manipulation task source</span> given <var>document</var>'s <span>relevant global
object</span> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-hashchange">hashchange</code> at <var>document</var>'s <span>relevant global
object</span>, using <code>HashChangeEvent</code>, with the <code
data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to the <span
data-x="concept-url-serializer">serialization</span> of <var>oldURL</var> and the <code
data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to the <span
data-x="concept-url-serializer">serialization</span> of <var>entry</var>'s <span
data-x="she-url">URL</span>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>entriesForNavigationAPI</var> is given.</p></li>
<li><p><span>Restore persisted state</span> given <var>entry</var>.</p></li>
<li><p><span>Initialize the navigation API entries for a new document</span> given
<var>navigation</var>, <var>entriesForNavigationAPI</var>, and <var>entry</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>If all the following are true:</p>
<ul>
<li><p><var>previousEntryForActivation</var> is given;</p></li>
<li><p><var>navigationType</var> is non-null; and</p></li>
<li><p><var>navigationType</var> is "<code data-x="dom-NavigationType-reload">reload</code>" or
<var>previousEntryForActivation</var>'s <span data-x="she-document">document</span> is not
<var>document</var>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>If <var>navigation</var>'s <span
data-x="navigation-activation">activation</span> is null, then set <var>navigation</var>'s
<span data-x="navigation-activation">activation</span> to a new
<code>NavigationActivation</code> object in <var>navigation</var>'s
<span data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Let <var>previousEntryIndex</var> be the result of
<span>getting the navigation API entry index</span> of <var>previousEntryForActivation</var>
within <var>navigation</var>.</p></li>
<li><p>If <var>previousEntryIndex</var> is non-negative, then set <var>activation</var>'s
<span data-x="nav-activation-old-entry">old entry</span> to <var>navigation</var>'s <span
data-x="navigation-entry-list">entry list</span>[<var>previousEntryIndex</var>].</p></li>
<li>
<p>Otherwise, if all the following are true:</p>
<ul>
<li><p><var>navigationType</var> is "<code
data-x="dom-NavigationType-replace">replace</code>";</p></li>
<li><p><var>previousEntryForActivation</var>'s
<span data-x="she-document-state">document state</span>'s <span
data-x="document-state-origin">origin</span> is <span>same origin</span> with
<var>document</var>'s <span data-x="concept-document-origin">origin</span>; and</p></li>
<li><p><var>previousEntryForActivation</var>'s <span data-x="she-document">document</span>'s
<span data-x="is initial about:blank">initial <code>about:blank</code></span> is
false,</p></li>
</ul>
<p>then set <var>activation</var>'s <span data-x="nav-activation-old-entry">old entry</span>
to a new <code>NavigationHistoryEntry</code> in <var>navigation</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>, whose <span
data-x="nhe-she">session history entry</span> is
<var>previousEntryForActivation</var>.</p>
</li>
<li><p>Set <var>activation</var>'s <span data-x="nav-activation-new-entry">new entry</span> to
<var>navigation</var>'s <span data-x="navigation-current-entry">current entry</span>.</p></li>
<li><p>Set <var>activation</var>'s <span
data-x="nav-activation-navigation-type">navigation type</span> to
<var>navigationType</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>documentIsNew</var> is true, then:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span
data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span>
is not null.</p></li>
<li><p>Invoke <span>WebDriver BiDi navigation committed</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>document</var>'s <span
data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span>,
<span data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-committed">committed</code>", and <span
data-x="navigation-status-url">url</span> is <var>document</var>'s <span
data-x="concept-document-url">URL</span></p></li>
<li><p><span>Try to scroll to the fragment</span> for <var>document</var>.</p></li>
<li><p>At this point <dfn>scripts may run for the newly-created document</dfn>
<var>document</var>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, if <var>documentsEntryChanged</var> is false and <var>doNotReactivate</var> is
false, then:</p>
<ol>
<li><p><span>Assert</span>: <var>entriesForNavigationAPI</var> is given.</p></li>
<li><p><span data-x="reactivate a document">Reactivate</span> <var>document</var> given
<var>entry</var> and <var>entriesForNavigationAPI</var>.</p>
</ol>
<p class="note"><var>documentsEntryChanged</var> can be false for one of two reasons: either we
are restoring from <a href="#note-bfcache">bfcache</a>, or we are asynchronously finishing up a
synchronous navigation which already synchronously set <var>document</var>'s <span>latest
entry</span>. The <var>doNotReactivate</var> argument distinguishes between these two
cases.</p>
</li>
</ol>
<p>To <dfn>restore the history object state</dfn> given <code>Document</code>
<var>document</var> and <span>session history entry</span> <var>entry</var>:</p>
<ol>
<li><p>Let <var>targetRealm</var> be <var>document</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li><p>Let <var>state</var> be <span>StructuredDeserialize</span>(<var>entry</var>'s <span
data-x="she-classic-history-api-state">classic history API state</span>, <var>targetRealm</var>).
If this throws an exception, catch it and let <var>state</var> be null.</p></li>
<li><p>Set <var>document</var>'s <span data-x="doc-history">history object</span>'s <span
data-x="concept-history-state">state</span> to <var>state</var>.</p></li>
</ol>
<p>To <dfn>make active</dfn> a <code>Document</code> <var>document</var>:</p>
<ol>
<li><p>Let <var>window</var> be <var>document</var>'s <span>relevant global
object</span>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-bc">browsing context</span>'s
<code>WindowProxy</code>'s <span data-x="concept-windowproxy-window">[[Window]]</span> internal
slot value to <var>window</var>.</p></li>
<li><p>Set <var>document</var>'s <span>visibility state</span> to <var>document</var>'s
<span>node navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>'s
<span>system visibility state</span>.</p></li>
<li><p><span data-x="queue a performance entry">Queue</span> a new
<code>VisibilityStateEntry</code> whose <span data-x="VisibilityStateEntry-state">visibility
state</span> is <var>document</var>'s <span>visibility state</span> and whose <span
data-x="VisibilityStateEntry-timestamp">timestamp</span> is zero.</p></li>
<li><p>Set <var>window</var>'s <span>relevant settings object</span>'s <span
data-x="concept-environment-execution-ready-flag">execution ready flag</span>.</p></li>
</ol>
<p>To <dfn data-x="reactivate a document" export for="Document">reactivate</dfn> a
<code>Document</code> <var>document</var> given a <span>session history entry</span>
<var>reactivatedEntry</var> and a <span>list</span> of <span data-x="session history
entry">session history entries</span> <var>entriesForNavigationAPI</var>:</p>
<p class="note">This algorithm updates <var>document</var> after it has come out of <a
href="#note-bfcache">bfcache</a>, i.e., after it has been made <span>fully active</span>
again. Other specifications that want to watch for this change to the <span>fully
active</span> state are encouraged to add steps into this algorithm, so that the ordering
of events that happen in effect of the change is clear.</p>
<ol>
<li id="history-autocomplete"><p><span data-x="list iterate">For each</span>
<var>formControl</var> of form controls in <var>document</var> with an <span>autofill field
name</span> of "<code data-x="attr-fe-autocomplete-off">off</code>", invoke the <span
data-x="concept-form-reset-control">reset algorithm</span> for <var>formControl</var>.</p></li>
<li>
<p>If <var>document</var>'s <span>suspended timer handles</span> is not <span data-x="list
empty">empty</span>:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span>suspension time</span> is not
zero.</p></li>
<li><p>Let <var>suspendDuration</var> be the <span>current high resolution time</span> minus
<var>document</var>'s <span>suspension time</span>.</p></li>
<li><p>Let <var>activeTimers</var> be <var>document</var>'s <span>relevant global
object</span>'s <span>map of active timers</span>.</p></li>
<li><p>For each <var>handle</var> in <var>document</var>'s <span>suspended timer
handles</span>, if <var>activeTimers</var>[<var>handle</var>] <span data-x="map
exists">exists</span>, then increase <var>activeTimers</var>[<var>handle</var>] by
<var>suspendDuration</var>.</p></li>
</ol>
</li>
<li><p><span>Update the navigation API entries for reactivation</span> given
<var>document</var>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>, <var>entriesForNavigationAPI</var>, and
<var>reactivatedEntry</var>.</p></li>
<li>
<p>If <var>document</var>'s <span>current document readiness</span> is "<code
data-x="">complete</code>", and <var>document</var>'s <span>page showing</span> is false:</p>
<ol>
<li><p>Set <var>document</var>'s <span>page showing</span> to true.</p></li>
<li><p>Set <var>document</var>'s <span>has been revealed</span> to false.</p>
<li><p><span>Update the visibility state</span> of <var>document</var> to "<code
data-x="">visible</code>".</p></li>
<li><p><span>Fire a page transition event</span> named <code
data-x="event-pageshow">pageshow</code> at <var>document</var>'s <span>relevant global
object</span> with true.</p></li>
</ol>
<!-- an interesting thing to test would be to traverse back during onload, before the first
pageshow has fired, and then to traverse forward again, and see if we get _two_ pageshows. If
so, it indicates that browsers don't have a "page showing" flag like this and that the history
traversal task source has a higher priority than the DOM manipulation task source. -->
</li>
</ol>
<p>To <dfn>try to scroll to the fragment</dfn> for a <code>Document</code> <var>document</var>,
perform the following steps <span>in parallel</span>:</p>
<ol>
<li><p>Wait for an <span>implementation-defined</span> amount of time. (This is intended to allow
the user agent to optimize the user experience in the face of performance concerns.)</p></li>
<li>
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>document</var>'s <span>relevant global object</span> to run these steps:</p>
<ol>
<li><p>If <var>document</var> has no parser, or its parser has <span data-x="stop
parsing">stopped parsing</span>, or the user agent has reason to believe the user is no longer
interested in scrolling to the <span data-x="concept-url-fragment">fragment</span>, then abort
these steps.</p></li>
<li><p><span>Scroll to the fragment</span> given <var>document</var>.</p></li>
<li><p>If <var>document</var>'s <span>indicated part</span> is still null, then <span>try to
scroll to the fragment</span> for <var>document</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn export>make document unsalvageable</dfn>, given a <code>Document</code>
<var>document</var> and a string <var>reason</var>:</p>
<ol>
<li><p>Let <var>details</var> be a new <span
data-x="nrr-details-struct">not restored reason details</span> whose <span
data-x="nrr-details-reason">reason</span> is <var>reason</var>.</p></li>
<li><p><span data-x="set append">Append</span> <var>details</var> to <var>document</var>'s
<span data-x="concept-document-bfcache-blocking-details">bfcache blocking details</span>.</p></li>
<li><p>Set <var>document</var>'s <i data-x="concept-document-salvageable">salvageable</i>
state to false.</p></li>
</ol>
<p>To <dfn>build not restored reasons for document state</dfn> given <code>Document</code>
<var>document</var>:</p>
<ol>
<li><p>Let <var>notRestoredReasonsForDocument</var> be a new <span
data-x="nrr-struct">not restored reasons</span>.</p></li>
<li><p>Set <var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-url">URL</span> to
<var>document</var>'s <span data-x="concept-document-url">URL</span>.</p></li>
<li><p>Let <var>container</var> be <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-container">container</span>.</p></li>
<li>
<p>If <var>container</var> is an <code>iframe</code> element:</p>
<ol>
<li><p>Let <var>src</var> be the empty string.</p></li>
<li>
<p>If <var>container</var> has a <code data-x="dom-iframe-src">src</code> attribute:</p>
<ol>
<li><p>Let <var>src</var> be the result of <span>encoding-parsing-and-serializing a
URL</span> given <var>container</var>'s <code data-x="attr-iframe-src">src</code> attribute's
value, relative to <var>container</var>'s <span>node document</span>.</p></li>
<li><p>If <var>src</var> is failure, then set <var>src</var> to <var>container</var>'s <code
data-x="attr-iframe-src">src</code> attribute's value.</p></li>
</ol>
</li>
<li><p>Set <var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-src">src</span> to
<var>src</var>.</p></li>
<li><p>Set <var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-id">id</span> to
<var>container</var>'s <code data-x="attr-id">id</code> attribute's value, or the empty string
if it has no such attribute.</p></li>
<li><p>Set <var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-name">name</span> to
<var>container</var>'s <code data-x="attr-iframe-name">name</code> attribute's value, or the
empty string if it has no such attribute.</p></li>
</ol>
</li>
<li><p>Set <var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-reasons">reasons</span>
to a <span data-x="list clone">clone</span> of <var>document</var>'s <span
data-x="concept-document-bfcache-blocking-details">bfcache blocking details</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>navigable</var> of <var>document</var>'s
<span data-x="document-tree child navigables">document-tree child navigables</span>:</p>
<ol>
<li><p>Let <var>childDocument</var> be <var>navigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p><span>Build not restored reasons for document state</span> given
<var>childDocument</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>childDocument</var>'s <span
data-x="concept-document-nrr">not restored reasons</span> to
<var>notRestoredReasonsForDocument</var>'s <span data-x="nrr-children">children</span>.</p></li>
</ol>
</li>
<li><p>Set <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-not-restored-reasons">not restored reasons</span> to
<var>notRestoredReasonsForDocument</var>.</p></li>
</ol>
<p>To <dfn>build not restored reasons for a top-level traversable and its descendants</dfn>
given <span>top-level traversable</span> <var>topLevelTraversable</var>:
<ol>
<li><p><span>Build not restored reasons for document state</span> given
<var>topLevelTraversable</var>'s <span data-x="nav-document">active document</span>.</p></li>
<li><p>Let <var>crossOriginDescendants</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>childNavigable</var> of
<var>topLevelTraversable</var>'s <span data-x="nav-document">active document</span>'s
<span>descendant navigables</span>:</p>
<ol>
<li><p>If <var>childNavigable</var>'s <span data-x="nav-document">active document</span>'s
<span data-x="concept-document-origin">origin</span> is not <span>same origin</span> with
<var>topLevelTraversable</var>'s <span data-x="nav-document">active document</span>'s <span
data-x="concept-document-origin">origin</span>, then <span data-x="list append">append</span>
<var>childNavigable</var> to <var>crossOriginDescendants</var>.</p></li>
</ol>
</li>
<li><p>Let <var>crossOriginDescendantsPreventsBfcache</var> be false.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>crossOriginNavigable</var> of
<var>crossOriginDescendants</var>:</p>
<ol>
<li><p>Let <var>reasonsForCrossOriginChild</var> be <var>crossOriginNavigable</var>'s <span
data-x="nav-document">active document</span>'s <span>document state</span>'s <span
data-x="document-state-not-restored-reasons">not restored reasons</span>.</p></li>
<li><p>If <var>reasonsForCrossOriginChild</var>'s <span data-x="nrr-reasons">reasons</span>
is not empty, set <var>crossOriginDescendantsPreventsBfcache</var> to true.</p></li>
<li><p>Set <var>reasonsForCrossOriginChild</var>'s <span data-x="nrr-url">URL</span> to
null.</p></li>
<li><p>Set <var>reasonsForCrossOriginChild</var>'s <span data-x="nrr-reasons">reasons</span>
to null.</p></li>
<li><p>Set <var>reasonsForCrossOriginChild</var>'s <span data-x="nrr-children">children</span>
to null.</p></li>
</ol>
</li>
<li><p>If <var>crossOriginDescendantsPreventsBfcache</var> is true, <span>make document
unsalvageable</span> given <var>topLevelTraversable</var>'s <span
data-x="nav-document">active document</span> and "<code
data-x="blocking-masked">masked</code>".</p></li>
</ol>
<h5>Revealing the document</h5>
<p>A <code>Document</code> has a boolean <dfn>has been revealed</dfn>, initially false. It is used
to ensure that the <code data-x="event-pagereveal">pagereveal</code> event is fired once for each
activation of the <code>Document</code> (once when it's rendered initially, and once for each
<span data-x="reactivate a document">reactivation</span>).</p>
<p>To <dfn>reveal</dfn> a <code>Document</code> <var>document</var>:</p>
<ol>
<li><p>If <var>document</var>'s <span>has been revealed</span> is true, then return.</p></li>
<li><p>Set <var>document</var>'s <span>has been revealed</span> to true.</p></li>
<li><p>Let <var>transition</var> be the result of
<span>resolving inbound cross-document view-transition</span> for <var>document</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named
<code data-x="event-pagereveal">pagereveal</code> at <var>document</var>'s
<span>relevant global object</span>, using <code>PageRevealEvent</code> with its <code
data-x="dom-PageRevealEvent-viewTransition">viewTransition</code> set to
<var>transition</var>.</p></li>
<li>
<p>If <var>transition</var> is not null, then:</p>
<ol>
<li><p><span>Prepare to run script</span> given <var>document</var>'s
<span>relevant settings object</span>.</p></li>
<li><p><span data-x="activate view transition">Activate</span> <var>transition</var>.</p></li>
<li><p><span>Clean up after running script</span> given <var>document</var>'s
<span>relevant settings object</span>.</p></li>
</ol>
<p class="note">Activating a view transition might resolve/reject promises, so by wrapping the
activation with prepare/cleanup we ensure those promises are handled before the next rendering
step.</p>
</li>
</ol>
<p class="note">Though <code data-x="event-pagereveal">pagereveal</code> is guaranteed to be fired
during the first <span>update the rendering</span> step that displays an up-to-date version of the
page, user agents are free to display a cached frame of the page before firing it. This prevents
the presence of a <code data-x="event-pagereveal">pagereveal</code> handler from delaying the
presentation of such cached frame.</p>
<h5>Scrolling to a fragment</h5>
<p>To <dfn id="scroll-to-the-fragment-identifier">scroll to the fragment</dfn> given a
<code>Document</code> <var>document</var>:</p>
<ol>
<li><p>If <var>document</var>'s <span>indicated part</span> is null, then set
<var>document</var>'s <span>target element</span> to null.</p></li>
<li>
<p>Otherwise, if <var>document</var>'s <span>indicated part</span> is <span>top of the
document</span>, then:</p>
<ol>
<li><p>Set <var>document</var>'s <span>target element</span> to null.</p></li>
<li><p><span>Scroll to the beginning of the document</span> for <var>document</var>.
<ref>CSSOMVIEW</ref></p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span>indicated part</span> is an
element.</p></li>
<li><p>Let <var>target</var> be <var>document</var>'s <span>indicated part</span>.</p></li>
<li><p>Set <var>document</var>'s <span>target element</span> to <var>target</var>.</p></li>
<li><p>Run the <span>ancestor details revealing algorithm</span> on <var>target</var>.</p></li>
<li><p>Run the <span>ancestor hidden-until-found revealing algorithm</span> on
<var>target</var>.</p></li>
<li><p><span data-x="scroll a target into view">Scroll <var>target</var> into view</span>,
with <var>behavior</var> set to "auto", <var>block</var> set to "start", and <var>inline</var>
set to "nearest". <ref>CSSOMVIEW</ref></p></li>
<li><p>Run the <span>focusing steps</span> for <var>target</var>, with the
<code>Document</code>'s <span>viewport</span> as the <var>fallback target</var>.</p></li>
<li><p>Move the <span>sequential focus navigation starting point</span> to
<var>target</var>.</p></li>
</ol>
</li>
</ol>
<p>A <code>Document</code>'s <dfn id="the-indicated-part-of-the-document">indicated part</dfn> is
the one that its <span data-x="concept-document-url">URL</span>'s <span
data-x="concept-url-fragment">fragment</span> identifies, or null if the fragment does not
identify anything. The semantics of the <span data-x="concept-url-fragment">fragment</span> in
terms of mapping it to a node is defined by the specification that defines the <span>MIME
type</span> used by the <code>Document</code> (for example, the processing of <span
data-x="concept-url-fragment">fragments</span> for <span data-x="XML MIME type">XML MIME
types</span> is the responsibility of RFC7303). <ref>RFC7303</ref></p>
<p>There is also a <dfn>target element</dfn> for each <code>Document</code>, which is used in
defining the <code data-x="selector-target">:target</code> pseudo-class and is updated by the
above algorithm. It is initially null.</p>
<p>For an <span data-x="HTML documents">HTML document</span> <var>document</var>, its
<span>indicated part</span> is the result
of <span data-x="select the indicated part">selecting the indicated part</span> given
<var>document</var> and <var>document</var>'s <span
data-x="concept-document-url">URL</span>.</p>
<p>To <dfn>select the indicated part</dfn> given a <code>Document</code> <var>document</var> and a
<span>URL</span> <var>url</var>:</p>
<ol>
<li><p>If <var>document</var>'s <span
data-x="concept-document-url">URL</span> does not <span data-x="concept-url-equals">equal</span>
<var>url</var> with <i data-x="url equals exclude fragments">exclude fragments</i> set to
true, then return null.</p></li>
<li><p>Let <var>fragment</var> be <var>url</var>'s <span
data-x="concept-url-fragment">fragment</span>.</p></li>
<li><p>If <var>fragment</var> is the empty string, then return the special value <dfn>top of the
document</dfn>.</p></li>
<li><p>Let <var>potentialIndicatedElement</var> be the result of <span data-x="find a potential
indicated element">finding a potential indicated element</span> given <var>document</var> and
<var>fragment</var>.</p></li>
<li><p>If <var>potentialIndicatedElement</var> is not null, then return
<var>potentialIndicatedElement</var>.</p></li>
<li><p>Let <var>fragmentBytes</var> be the result of <span
data-x="percent-decode">percent-decoding</span> <var>fragment</var>.</p></li>
<li><p>Let <var>decodedFragment</var> be the result of running <span>UTF-8 decode without
BOM</span> on <var>fragmentBytes</var>.</p></li>
<li><p>Set <var>potentialIndicatedElement</var> to the result of <span data-x="find a potential
indicated element">finding a potential indicated element</span> given <var>document</var> and
<var>decodedFragment</var>.</p></li>
<li><p>If <var>potentialIndicatedElement</var> is not null, then return
<var>potentialIndicatedElement</var>.</p></li>
<li><p>If <var>decodedFragment</var> is an <span>ASCII case-insensitive</span> match for the
string <code data-x="">top</code>, then return the <span>top of the document</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>To <dfn>find a potential indicated element</dfn> given a <code>Document</code>
<var>document</var> and a string <var>fragment</var>, run these steps:</p>
<ol>
<li><p>If there is an element <span data-x="in a document tree">in the document tree</span>
whose <span>root</span> is <var>document</var> and that has an <span
data-x="concept-id">ID</span> equal to <var>fragment</var>, then return the first such element
in <span>tree order</span>.</p></li>
<li><p>If there is an <code>a</code> element <span data-x="in a document tree">in the document
tree</span> whose <span>root</span> is <var>document</var> that has a <code
data-x="attr-a-name">name</code> attribute whose value is equal to <var>fragment</var>, then
return the first such element in <span>tree order</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
<h5 id="persisted-user-state-restoration">Persisted history entry state</h5>
<p>To <dfn>save persisted state</dfn> to a <span>session history entry</span>
<var>entry</var>:</p>
<ol>
<li><p>Set the <span data-x="she-scroll-position">scroll position data</span> of <var>entry</var>
to contain the scroll positions for all of <var>entry</var>'s <span
data-x="she-document">document</span>'s <span>restorable scrollable regions</span>.</p></li>
<li><p>Optionally, update <var>entry</var>'s <span data-x="she-other">persisted user state</span>
to reflect any state that the user agent wishes to persist, such as the values of form
fields.</p></li>
</ol>
<p id="restore-persisted-user-state">To <dfn>restore persisted state</dfn> from a <span>session
history entry</span> <var>entry</var>:</p>
<ol>
<li>
<p>If <var>entry</var>'s <span data-x="she-scroll-restoration-mode">scroll restoration
mode</span> is "<code data-x="dom-ScrollRestoration-auto">auto</code>", and <var>entry</var>'s
<span data-x="she-document">document</span>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>'s <span>suppress normal scroll restoration
during ongoing navigation</span> is false, then <span>restore scroll position data</span> given
<var>entry</var>.</p>
<p class="note">The user agent not restoring scroll positions does not imply that scroll
positions will be left at any particular value (e.g., (0,0)). The actual scroll position depends
on the navigation type and the user agent's particular caching strategy. So web applications
cannot assume any particular scroll position but rather are urged to set it to what they want it
to be.</p>
<p class="note">If <span>suppress normal scroll restoration during ongoing navigation</span> is
true, then <span data-x="restore scroll position data">restoring scroll position data</span>
might still happen at a later point, as part of <span
data-x="NavigateEvent-finish">finishing</span> the relevant <code>NavigateEvent</code>, or via a
<code data-x="dom-NavigateEvent-scroll">navigateEvent.scroll()</code> method call.</p>
</li>
<li>
<p>Optionally, update other aspects of <var>entry</var>'s <span
data-x="she-document">document</span> and its rendering, for instance values of form fields,
that the user agent had previously recorded in <var>entry</var>'s <span
data-x="she-other">persisted user state</span>.</p>
<p class="note">This can even include updating the <code data-x="attr-dir">dir</code> attribute
of <code>textarea</code> elements or <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-text">Text</span>, <span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-tel">Telephone</span>, <span
data-x="attr-input-type-url">URL</span>, or <span data-x="attr-input-type-email">Email</span>
state, if the persisted state includes the directionality of user input in such controls.</p>
<p class="note">Restoring the value of form controls as part of this process does not fire any
<code data-x="event-input">input</code> or <code data-x="event-change">change</code> events, but
can trigger the <code data-x="">formStateRestoreCallback</code> of <span data-x="form-associated
custom element">form-associated custom elements</span>.</p>
</li>
</ol>
<hr>
<p>Each <code>Document</code> has a boolean <dfn>has been scrolled by the user</dfn>, initially
false. If the user scrolls the document, the user agent must set that document's <span>has been
scrolled by the user</span> to true.</p>
<p>The <dfn>restorable scrollable regions</dfn> of a <code>Document</code> <var>document</var>
are <var>document</var>'s <span>viewport</span>, and all of <var>document</var>'s scrollable
regions excepting any <span data-x="navigable container">navigable containers</span>.</p>
<p class="note"><span>Child navigable</span> scroll restoration is handled as part of state
restoration for the <span>session history entry</span> for those <span
data-x="navigable">navigables</span>' <code>Document</code>s.</p>
<p>To <dfn>restore scroll position data</dfn> given a <span>session history entry</span>
<var>entry</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>entry</var>'s <span
data-x="she-document">document</span>.</p></li>
<li><p>If <var>document</var>'s <span>has been scrolled by the user</span> is true, then the
user agent should return.</p></li>
<li>
<p>The user agent should attempt to use <var>entry</var>'s <span
data-x="she-scroll-position">scroll position data</span> to restore the scroll positions of
<var>entry</var>'s <span data-x="she-document">document</span>'s <span>restorable scrollable
regions</span>. The user agent may continue to attempt to do so periodically, until
<var>document</var>'s <span>has been scrolled by the user</span> becomes true.</p>
<p class="note">This is formulated as an <em>attempt</em>, which is potentially repeated until
success or until the user scrolls, due to the fact that relevant content indicated by the <span
data-x="she-scroll-position">scroll position data</span> might take some time to load from the
network.</p>
<p class="note">Scroll restoration might be affected by scroll anchoring.
<ref>CSSSCROLLANCHORING</ref></p>
</li>
</ol>
<h3 split-filename="document-lifecycle">Document lifecycle</h3>
<h4>Shared document creation infrastructure</h4>
<p>When loading a document using one of the below algorithms, we use the
following steps to <!--en-GB--><dfn id="initialise-the-document-object"
data-x="create-the-document-object">create and initialize a <code>Document</code> object</dfn>,
given a <span data-x="concept-document-type">type</span> <var>type</var>, <span
data-x="concept-document-content-type">content type</span> <var>contentType</var>, and
<span>navigation params</span> <var>navigationParams</var>:</p>
<p class="note"><code>Document</code> objects are also created when <span>creating a new browsing
context and document</span>; such <span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code> are never created by this algorithm. Also,
<span data-x="concept-document-bc">browsing context</span>-less <code>Document</code> objects can
be created via various APIs, such as <code
data-x="dom-DOMImplementation-createHTMLDocument">document.implementation.createHTMLDocument()</code>.</p>
<ol>
<li>
<p>Let <var>browsingContext</var> be the result of <span
data-x="obtain-browsing-context-navigation">obtaining a browsing context to use for a
navigation response</span> given <var>navigationParams</var>.</p>
<p class="note">This can result in a <a
href="#browsing-context-group-switches-due-to-cross-origin-opener-policy">browsing context
group switch</a>, in which case <var>browsingContext</var> will be a <span data-x="creating a
new browsing context and document">newly-created</span> <span>browsing context</span> instead
of being <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>'s <span data-x="nav-bc">active browsing
context</span>. In such a case, the created <code>Window</code>, <code>Document</code>, and
<span>agent</span> will not end up being used; because the created <code>Document</code>'s
<span data-x="concept-document-origin">origin</span> is <span
data-x="concept-origin-opaque">opaque</span>, we will end up creating a new <span>agent</span>
and <code>Window</code> <a href="#create-new-agent-and-window">later in this algorithm</a> to
go along with the new <code>Document</code>.</p>
</li>
<li>
<p>Let <var>permissionsPolicy</var> be the result of <span>creating a permissions policy from a
response</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>'s <span
data-x="nav-container">container</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-origin">origin</span>, and <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>. <ref>PERMISSIONSPOLICY</ref></p>
<div class="note">
<p>The <span>creating a permissions policy from a response</span> algorithm makes use of the
passed <span>origin</span>. If <code data-x="dom-document-domain">document.domain</code> has
been used for <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>'s <span
data-x="nav-container-document">container document</span>, then its <span
data-x="concept-document-origin">origin</span> cannot be <span>same origin-domain</span> with
the passed origin, because these steps run before the <var>document</var> is created, so it
cannot itself yet have used <code data-x="dom-document-domain">document.domain</code>. Note
that this means that Permissions Policy checks are less permissive compared to doing a
<span>same origin</span> check instead.</p>
<p>See below for some examples of this in action.</p>
</div>
</li>
<li><p>Let <var>creationURL</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-url">URL</span>.</p></li>
<li><p>If <var>navigationParams</var>'s <span data-x="navigation-params-request">request</span>
is non-null, then set <var>creationURL</var> to <var>navigationParams</var>'s <span
data-x="navigation-params-request">request</span>'s <span
data-x="concept-request-current-url">current URL</span>.</p></li>
<li><p>Let <var>window</var> be null.</p></li>
<li>
<p>If <var>browsingContext</var>'s <span>active document</span>'s <span>is initial
<code>about:blank</code></span> is true, and <var>browsingContext</var>'s <span>active
document</span>'s <span data-x="concept-document-origin">origin</span> is <span>same
origin-domain</span> with <var>navigationParams</var>'s <span
data-x="navigation-params-origin">origin</span>, then set <var>window</var> to
<var>browsingContext</var>'s <span>active window</span>.</p>
<p class="note">This means that both the <span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code>, and the new <code>Document</code> that
is about to be created, will share the same <code>Window</code> object.</p>
</li>
<li id="create-new-agent-and-window">
<p>Otherwise:</p>
<ol>
<li><p>Let <var>oacHeader</var> be the result of <span>getting a structured field value</span>
given `<code>Origin-Agent-Cluster</code>` and "<code data-x="">item</code>" from
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s
<span data-x="concept-response-header-list">header list</span>.</p></li>
<li><p>Let <var>requestsOAC</var> be true if <var>oacHeader</var> is not
null and <var>oacHeader</var>[0] is the <span
data-x="http-structured-header-boolean">boolean</span> true; otherwise false.</p></li>
<li><p>If <var>navigationParams</var>'s <span
data-x="navigation-params-reserved-environment">reserved environment</span> is a
<span>non-secure context</span>, then set <var>requestsOAC</var> to false.</p></li>
<li><p>Let <var>agent</var> be the result of <span
data-x="obtain-similar-origin-window-agent">obtaining a similar-origin window agent</span>
given <var>navigationParams</var>'s <span data-x="navigation-params-origin">origin</span>,
<var>browsingContext</var>'s <span data-x="tlbc group">group</span>, and
<var>requestsOAC</var>.</p></li>
<li>
<p>Let <var>realmExecutionContext</var> be the result of <span>creating a new realm</span>
given <var>agent</var> and the following customizations:</p>
<ul>
<li><p>For the global object, create a new <code>Window</code> object.</p></li>
<li><p>For the global <b>this</b> binding, use <var>browsingContext</var>'s
<code>WindowProxy</code> object.</p></li>
</ul>
</li>
<li><p>Set <var>window</var> to the <span data-x="concept-realm-global">global
object</span> of <var>realmExecutionContext</var>'s Realm component.</p></li>
<li><p>Let <var>topLevelCreationURL</var> be <var>creationURL</var>.</p></li>
<li><p>Let <var>topLevelOrigin</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-origin">origin</span>.</p></li>
<li>
<p>If <var>navigable</var>'s <span data-x="nav-container">container</span> is not null,
then:</p>
<ol>
<li><p>Let <var>parentEnvironment</var> be <var>navigable</var>'s <span
data-x="nav-container">container</span>'s <span>relevant settings object</span>.</p></li>
<li><p>Set <var>topLevelCreationURL</var> to <var>parentEnvironment</var>'s <span>top-level
creation URL</span>.</p></li>
<li><p>Set <var>topLevelOrigin</var> to <var>parentEnvironment</var>'s <span>top-level
origin</span>.</p></li>
</ol>
</li>
<li><p><span>Set up a window environment settings object</span> with <var>creationURL</var>,
<var>realmExecutionContext</var>, <var>navigationParams</var>'s <span
data-x="navigation-params-reserved-environment">reserved environment</span>,
<var>topLevelCreationURL</var>, and <var>topLevelOrigin</var>.</p></li>
</ol>
<p class="note">This is the usual case, where the new <code>Document</code> we're about to
create gets a new <code>Window</code> to go along with it.</p>
</li>
<li><p>Let <var>loadTimingInfo</var> be a new <span>document load timing info</span> with its
<span>navigation start time</span> set to <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-timing-info">timing info</span>'s <span
data-x="fetch-timing-info-start-time">start time</span>.</p></li>
<li>
<p>Let <var>document</var> be a new <code>Document</code>, with</p>
<dl class="props">
<dt><span data-x="concept-document-type">type</span></dt>
<dd><var>type</var></dd>
<dt><span data-x="concept-document-content-type">content type</span></dt>
<dd><var>contentType</var></dd>
<dt><span data-x="concept-document-origin">origin</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-origin">origin</span></dd>
<dt><span data-x="concept-document-bc">browsing context</span></dt>
<dd><var>browsingContext</var>
<dt><span data-x="concept-document-policy-container">policy container</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-policy-container">policy
container</span></dd>
<dt><span data-x="concept-document-permissions-policy">permissions policy</span></dt>
<dd><var>permissionsPolicy</var></dd>
<dt><span>active sandboxing flag set</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-sandboxing">final sandboxing
flag set</span></dd>
<dt><span data-x="concept-document-coop">opener policy</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-coop">cross-origin opener
policy</span></dd>
<dt><span>load timing info</span></dt>
<dd><var>loadTimingInfo</var></dd>
<dt><span>was created via cross-origin redirects</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s
<span data-x="concept-response-has-cross-origin-redirects">has cross-origin
redirects</span></dd>
<dt><span data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-id">id</span></dd>
<dt><span data-x="concept-document-url">URL</span></dt>
<dd><var>creationURL</var></dd>
<dt><span>current document readiness</span></dt>
<dd>"<code data-x="">loading</code>"</dd>
<dt><span data-x="concept-document-about-base-url">about base URL</span></dt>
<dd><var>navigationParams</var>'s <span data-x="navigation-params-about-base-URL">about base URL</span></dd>
<dt><span data-x="concept-document-allow-declarative-shadow-roots">allow declarative shadow
roots</span></dt>
<dd>true</dd>
</dl>
</li>
<li><p>Set <var>window</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span> to <var>document</var>.</p></li>
<li><p><span>Run CSP initialization for a <code data-x="">Document</code></span> given
<var>document</var>. <ref>CSP</ref></p>
<li>
<p>If <var>navigationParams</var>'s <span data-x="navigation-params-request">request</span> is
non-null, then:</p>
<ol>
<li><p>Set <var>document</var>'s <span data-x="the document's referrer">referrer</span> to the
empty string.</p></li>
<li><p>Let <var>referrer</var> be <var>navigationParams</var>'s <span
data-x="navigation-params-request">request</span>'s <span
data-x="concept-request-referrer">referrer</span>.</p></li>
<li>
<p>If <var>referrer</var> is a <span>URL record</span>, then set <var>document</var>'s <span
data-x="the document's referrer">referrer</span> to the <span
data-x="concept-url-serializer">serialization</span> of <var>referrer</var>.</p>
<p class="note">Per <cite>Fetch</cite>, <var>referrer</var> will be either a <span>URL
record</span> or "<code data-x="">no-referrer</code>" at this point.</p>
</li>
</ol>
</li>
<li>
<p>If <var>navigationParams</var>'s <span data-x="navigation-params-fetch-controller">fetch
controller</span> is not null, then:</p>
<ol>
<li><p>Let <var>fullTimingInfo</var> be the result of <span data-x="extract full timing
info">extracting the full timing info</span> from <var>navigationParams</var>'s <span
data-x="navigation-params-fetch-controller">fetch controller</span>.</p></li>
<li><p>Let <var>redirectCount</var> be 0 if <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-has-cross-origin-redirects">has cross-origin redirects</span> is
true; otherwise <var>navigationParams</var>'s <span
data-x="navigation-params-request">request</span>'s <span
data-x="concept-request-redirect-count">redirect count</span>.</p></li>
<li><p><span>Create the navigation timing entry</span> for <var>document</var>, given
<var>fullTimingInfo</var>, <var>redirectCount</var>, <var>navigationTimingType</var>,
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s
<span data-x="concept-response-service-worker-timing-info">service worker timing info</span>,
and <var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s
<span data-x="concept-response-body-info">body info</span>.</p></li>
</ol>
</li>
<li><p><span>Create the navigation timing entry</span> for <var>document</var>, with
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-timing-info">timing info</span>, <var>redirectCount</var>,
<var>navigationParams</var>'s <span data-x="navigation-params-nav-timing-type">navigation timing
type</span>, and <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-service-worker-timing-info">service worker timing info</span>.</p></li>
<li>
<p>If <var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>
has a `<code>Refresh</code>` header, then:</p>
<ol>
<li><p>Let <var>value</var> be the <span data-x="isomorphic decode">isomorphic decoding</span>
of the value of the header.</p></li>
<li><p>Run the <span>shared declarative refresh steps</span> with <var>document</var> and
<var>value</var>.</p></li>
</ol>
<p class="XXX">We do not currently have a spec for how to handle multiple `<code>Refresh</code>`
headers. This is tracked as <a
href="https://github.com/whatwg/html/issues/2900">issue #2900</a>.</p>
</li>
<li><p>If <var>navigationParams</var>'s <span
data-x="navigation-params-commit-early-hints">commit early hints</span> is not null, then call
<var>navigationParams</var>'s <span data-x="navigation-params-commit-early-hints">commit early
hints</span> with <var>document</var>.</p></li>
<li><p><span>Process link headers</span> given <var>document</var>,
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>, and
"<code data-x="">pre-media</code>".</p></li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<div class="example">
<p>In this example, the child document is not allowed to use <code>PaymentRequest</code>,
despite being <span>same origin-domain</span> at the time the child document tries to use
it. At the time the child document is initialized, only the parent document has set <code
data-x="dom-document-domain">document.domain</code>, and the child document has not.</p>
<pre><code class="html"><!-- https://foo.example.com/a.html -->
<!doctype html>
<script>
document.domain = 'example.com';
</script>
<iframe src=b.html></iframe></code></pre>
<pre><code class="html"><!-- https://bar.example.com/b.html -->
<!doctype html>
<script>
document.domain = 'example.com'; // This happens after the document is initialized
new PaymentRequest(…); // Not allowed to use
</script></code></pre>
</div>
<div class="example">
<p>In this example, the child document <em>is</em> allowed to use
<code>PaymentRequest</code>, despite not being <span>same origin-domain</span> at the time
the child document tries to use it. At the time the child document is initialized, none of
the documents have set <code data-x="dom-document-domain">document.domain</code> yet so
<span>same origin-domain</span> falls back to a normal <span>same origin</span> check.</p>
<pre><code class="html"><!-- https://example.com/a.html -->
<!doctype html>
<iframe src=b.html></iframe>
<!-- The child document is now initialized, before the script below is run. -->
<script>
document.domain = 'example.com';
</script></code></pre>
<pre><code class="html"><!-- https://example.com/b.html -->
<!doctype html>
<script>
new PaymentRequest(…); // Allowed to use
</script></code></pre>
</div>
<p>To <dfn>populate with <code>html</code>/<code>head</code>/<code>body</code></dfn> given a
<code>Document</code> <var>document</var>:</p>
<ol>
<li><p>Let <var>html</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">html</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p>Let <var>head</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">head</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p>Let <var>body</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">body</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>html</var> to
<var>document</var>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>head</var> to
<var>html</var>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>body</var> to
<var>html</var>.</p></li>
</ol>
<h4 id="read-html">Loading HTML documents</h4>
<p>To <dfn data-x="navigate-html">load an HTML document</dfn>, given <span>navigation
params</span> <var>navigationParams</var>:</p>
<ol>
<li><p>Let <var>document</var> be the result of <span
data-x="create-the-document-object">creating and initializing a <code>Document</code>
object</span> given "<code data-x="">html</code>", "<code data-x="">text/html</code>", and
<var>navigationParams</var>.</p></li>
<li>
<p>If <var>document</var>'s <span data-x="concept-document-url">URL</span> is
<code>about:blank</code>, then <span>populate with
<code>html</code>/<code>head</code>/<code>body</code></span> given <var>document</var>.</p>
<p class="note">This special case, where even non-<span data-x="is initial about:blank">initial
<code>about:blank</code></span> <code>Document</code>s are synchronously given their element
nodes, is necessary for compatible with deployed content. In other words, it is not compatible
to instead go down the "otherwise" branch and feed the empty <span>byte sequence</span> into
an <span>HTML parser</span> to asynchronously populate <var>document</var>.</p>
</li>
<!-- See https://github.com/whatwg/html/issues/8095 for improving this step. -->
<li>
<p>Otherwise, create an <span>HTML parser</span> and associate it with the <var>document</var>.
Each <span data-x="concept-task">task</span> that the <span>networking task source</span>
places on the <span>task queue</span> while fetching runs must then fill the parser's
<span>input byte stream</span> with the fetched bytes and cause the <span>HTML parser</span> to
perform the appropriate processing of the input stream.</p>
<p>The first <span data-x="concept-task">task</span> that the <span>networking task
source</span> places on the <span>task queue</span> while fetching runs must <span>process link
headers</span> given <var>document</var>, <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, and "<code data-x="">media</code>", after
the task has been processed by the <span>HTML parser</span>.</p>
<p>Before any script execution occurs, the user agent must wait for <span>scripts may run for
the newly-created document</span> to be true for <var>document</var>.</p>
<p class="note">The <span>input byte stream</span> converts bytes into characters for use in the
<span data-x="tokenization">tokenizer</span>. This process relies, in part, on character encoding
information found in the real <span data-x="Content-Type">Content-Type metadata</span> of the
resource; the computed type is not used for this purpose.</p>
<p>When no more bytes are available, the user agent must <span>queue a global task</span> on
the <span>networking task source</span> given <var>document</var>'s <span>relevant global
object</span> to have the parser process the implied EOF character, which eventually causes
a <code data-x="event-load">load</code> event to be fired.</p>
</li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<h4 id="read-xml"><dfn data-x="navigate-xml">Loading XML documents</dfn></h4>
<p>When faced with displaying an XML file inline, provided <span>navigation params</span>
<var>navigationParams</var> and a string <var>type</var>, user agents must follow the
requirements defined in <cite>XML</cite> and <cite>Namespaces in XML</cite>, <cite>XML Media
Types</cite>, <cite>DOM</cite>, and other relevant specifications to <span
data-x="create-the-document-object">create and initialize a <code>Document</code> object</span>
<var>document</var>, given "<code data-x="">xml</code>", <var>type</var>, and
<var>navigationParams</var>, and return that <code>Document</code>. They must also create a
corresponding <span>XML parser</span>. <ref>XML</ref> <ref>XMLNS</ref> <ref>RFC7303</ref>
<ref>DOM</ref></p>
<p class="note">At the time of writing, the XML specification community had not actually yet
specified how XML and the DOM interact.</p> <!--XMLPARSE-->
<p>The first <span data-x="concept-task">task</span> that the <span>networking task source</span>
places on the <span>task queue</span> while fetching runs must <span>process link headers</span>
given <var>document</var>, <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, and "<code data-x="">media</code>", after
the task has been processed by the <span>XML parser</span>.</p>
<p>The actual HTTP headers and other metadata, not the headers as mutated or implied by the
algorithms given in this specification, are the ones that must be used when determining the
character encoding according to the rules given in the above specifications. Once the character
encoding is established, the <span>document's character encoding</span> must be set to that
character encoding.</p>
<p>Before any script execution occurs, the user agent must wait for <span>scripts may run for the
newly-created document</span> to be true for the newly-created <code>Document</code>.</p>
<p>Once parsing is complete, the user agent must set <var>document</var>'s <span
data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span> to
null.</p>
<p class="note">For HTML documents this is reset when parsing is complete, after firing the load
event.</p>
<p>Error messages from the parse process (e.g., XML namespace well-formedness errors) may be
reported inline by mutating the <code>Document</code>.</p>
<h4 id="read-text">Loading text documents</h4>
<p>To <dfn data-x="navigate-text">load a text document</dfn>, given a <span>navigation
params</span> <var>navigationParams</var> and a string <var>type</var>:</p>
<ol>
<li><p>Let <var>document</var> be the result of <span
data-x="create-the-document-object">creating and initializing a <code>Document</code>
object</span> given "<code data-x="">html</code>", <var>type</var>, and
<var>navigationParams</var>.</p></li>
<li><p>Set <var>document</var>'s <span>parser cannot change the mode flag</span> to
true.</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-mode">mode</span>
to "<code data-x="">no-quirks</code>".</p></li>
<li>
<p>Create an <span>HTML parser</span> and associate it with the <var>document</var>. Act as
if the tokenizer had emitted a start tag token with the tag name "pre" followed by a single
U+000A LINE FEED (LF) character<!-- to get eaten, so that a leading LF in the text/plain stream
doesn't get eaten itself-->, and switch the <span>HTML parser</span>'s tokenizer to the
<span>PLAINTEXT state</span>. Each <span data-x="concept-task">task</span> that the
<span>networking task source</span> places on the <span>task queue</span> while fetching runs
must then fill the parser's <span>input byte stream</span> with the fetched bytes and cause the
<span>HTML parser</span> to perform the appropriate processing of the input stream.</p>
<p><var>document</var>'s <span data-x="document's character encoding">encoding</span> must be
set to the character encoding used to decode the document during parsing.</p>
<p>The first <span data-x="concept-task">task</span> that the <span>networking task
source</span> places on the <span>task queue</span> while fetching runs must <span>process link
headers</span> given <var>document</var>, <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, and "<code data-x="">media</code>", after
the task has been processed by the <span>HTML parser</span>.</p>
<p>Before any script execution occurs, the user agent must wait for <span>scripts may run for
the newly-created document</span> to be true for <var>document</var>.</p>
<p>When no more bytes are available, the user agent must <span>queue a global task</span> on
the <span>networking task source</span> given <var>document</var>'s <span>relevant global
object</span> to have the parser process the implied EOF character, which eventually causes
a <code data-x="event-load">load</code> event to be fired.</p>
</li>
<li>
<p>User agents may add content to the <code>head</code> element of <var>document</var>, e.g.,
linking to a style sheet, providing script, or giving the document a <code>title</code>.</p>
<p class="note">In particular, if the user agent supports the <code
data-x="">Format=Flowed</code> feature of RFC 3676 then the user agent would need to apply
extra styling to cause the text to wrap correctly and to handle the quoting feature. This could
be performed using, e.g., a CSS extension.</p>
</li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p>The rules for how to convert the bytes of the plain text document into actual characters, and
the rules for actually rendering the text to the user, are defined by the specifications for the
<span data-x="Content-Type sniffing">computed MIME type</span> of the resource (i.e.,
<var>type</var>).</p>
<h4 id="read-multipart-x-mixed-replace">Loading <code>multipart/x-mixed-replace</code>
documents</h4>
<p>To <dfn data-x="navigate-multipart-x-mixed-replace">load a
<code>multipart/x-mixed-replace</code> document</dfn>, given <span>navigation params</span>
<var>navigationParams</var>, <span>source snapshot params</span> <var>sourceSnapshotParams</var>,
and <span>origin</span> <var>initiatorOrigin</var>:</p>
<ol>
<li><p>Parse <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-body">body</span> using the rules for multipart types.
<ref>RFC2046</ref></p></li>
<li><p>Let <var>firstPartNavigationParams</var> be a copy of
<var>navigationParams</var>.</p></li>
<li><p>Set <var>firstPartNavigationParams</var>'s <span
data-x="navigation-params-response">response</span> to a new <span
data-x="concept-response">response</span> representing the first part of
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-body">body</span>'s multipart stream.</p></li>
<li>
<p>Let <var>document</var> be the result of <span>loading a document</span> given
<var>firstPartNavigationParams</var>, <var>sourceSnapshotParams</var>, and
<var>initiatorOrigin</var>.</p>
<p>For each additional body part obtained from <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, the user agent must <span>navigate</span>
<var>document</var>'s <span>node navigable</span> to <var>navigationParams</var>'s <span
data-x="navigation-params-request">request</span>'s <span
data-x="concept-request-url">URL</span>, using <var>document</var>, with <i
data-x="navigation-response">response</i> set to <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span> and <i
data-x="navigation-hh">historyHandling</i> set to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>".</p>
</li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p>For the purposes of algorithms processing these body parts as if they were complete
stand-alone resources, the user agent must act as if there were no more bytes for those resources
whenever the boundary following the body part is reached.</p>
<p class="note">Thus, <code data-x="event-load">load</code> events (and for that matter <code
data-x="event-unload">unload</code> events) do fire for each body part loaded.</p>
<h4 id="read-media">Loading media documents</h4>
<p>To <dfn data-x="navigate-media">load a media document</dfn>, given <var>navigationParams</var>
and a string <var>type</var>:</p>
<ol>
<li><p>Let <var>document</var> be the result of <span
data-x="create-the-document-object">creating and initializing a <code>Document</code>
object</span> given "<code data-x="">html</code>", <var>type</var>, and
<var>navigationParams</var>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-mode">mode</span>
to "<code data-x="">no-quirks</code>".</p></li>
<li><p><span>Populate with <code>html</code>/<code>head</code>/<code>body</code></span> given
<var>document</var>.</p></li>
<li><p>Append an element <var>host element</var> for the media, as described below, to the
<code>body</code> element.</p></li>
<li><p>Set the appropriate attribute of the element <var>host element</var>, as described below,
to the address of the image, video, or audio resource.</p></li>
<li><p>User agents may add content to the <code>head</code> element of <var>document</var>, or
attributes to <var>host element</var>, e.g., to link to a style sheet, to provide a script, to
give the document a <code>title</code>, or to make the media <span
data-x="attr-media-autoplay">autoplay</span>.</p></li>
<li><p><span>Process link headers</span> given <var>document</var>,
<var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>, and
"<code data-x="">media</code>".</p></li>
<li><p>Act as if the user agent had <span data-x="stop parsing">stopped parsing</span>
<var>document</var>.</p></li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p>The element <var>host element</var> to create for the media is the element given in
the table below in the second cell of the row whose first cell describes the media. The
appropriate attribute to set is the one given by the third cell in that same row.</p>
<table>
<thead>
<tr> <th> Type of media
<th> Element for the media
<th> Appropriate attribute
<tbody>
<tr> <td> Image
<td> <code>img</code>
<td> <code data-x="attr-img-src">src</code>
<tr> <td> Video
<td> <code>video</code>
<td> <code data-x="attr-media-src">src</code>
<tr> <td> Audio
<td> <code>audio</code>
<td> <code data-x="attr-media-src">src</code>
</table>
<p>Before any script execution occurs, the user agent must wait for <span>scripts may run for the
newly-created document</span> to be true for the <code>Document</code>.</p>
<h4 id="read-ua-inline"><span id="read-ua-plugin"></span><span id="navigate-plugin"></span><dfn
data-x="navigate-ua-inline">Loading a document for inline content that doesn't have a
DOM</dfn></h4>
<p>When the user agent is to create a document to display a user agent page or PDF viewer inline,
provided a <span>navigable</span> <var>navigable</var>, a <span>navigation ID</span>
<var>navigationId</var>, a <code>NavigationTimingType</code> <var>navTimingType</var>, and a
<span>user navigation involvement</span> <var>userInvolvement</var>, the user agent should:</p>
<ol>
<li><p>Let <var>origin</var> be a new <span data-x="concept-origin-opaque">opaque
origin</span>.</p></li>
<li><p>Let <var>coop</var> be a new <span>opener policy</span>.</p></li>
<li>
<p>Let <var>coopEnforcementResult</var> be a new <span data-x="coop-enforcement-result">opener
policy enforcement result</span> with</p>
<dl class="props">
<dt><span data-x="coop-enforcement-url">url</span></dt>
<dd><var>response</var>'s <span data-x="concept-response-url">URL</span></dd>
<dt><span data-x="coop-enforcement-origin">origin</span></dt>
<dd><var>origin</var></dd>
<dt><span data-x="coop-enforcement-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
</dl>
</li>
<li>
<p>Let <var>navigationParams</var> be a new <span>navigation params</span> with</p>
<dl class="props">
<dt><span data-x="navigation-params-id">id</span></dt>
<dd><var>navigationId</var></dd>
<dt><span data-x="navigation-params-navigable">navigable</span></dt>
<dd><var>navigable</var></dd>
<dt><span data-x="navigation-params-request">request</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-response">response</span></dt>
<dd>a new <span data-x="concept-response">response</span></dd>
<dt><span data-x="navigation-params-origin">origin</span></dt>
<dd><var>origin</var></dd>
<dt><span data-x="navigation-params-fetch-controller">fetch controller</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-commit-early-hints">commit early hints</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-coop-enforcement-result">COOP enforcement result</span></dt>
<dd><var>coopEnforcementResult</var></dd>
<dt><span data-x="navigation-params-reserved-environment">reserved environment</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-policy-container">policy container</span></dt>
<dd>a new <span>policy container</span></dd>
<dt><span data-x="navigation-params-sandboxing">final sandboxing flag set</span></dt>
<dd>an empty set</dd>
<dt><span data-x="navigation-params-coop">opener policy</span></dt>
<dd><var>coop</var></dd>
<dt><span data-x="navigation-params-nav-timing-type">navigation timing type</span></dt>
<dd><var>navTimingType</var></dd>
<dt><span data-x="navigation-params-about-base-url">about base URL</span></dt>
<dd>null</dd>
<dt><span data-x="navigation-params-user-involvement">user involvement</span></dt>
<dd><var>userInvolvement</var></dd>
</dl>
</li>
<li><p>Let <var>document</var> be the result of <span
data-x="create-the-document-object">creating and initializing a <code>Document</code>
object</span> given "<code data-x="">html</code>", "<code data-x="">text/html</code>", and
<var>navigationParams</var>.</p></li>
<li><p>Either associate <var>document</var> with a custom rendering that is not rendered using
the normal <code>Document</code> rendering rules, or mutate <var>document</var> until it
represents the content the user agent wants to render.</p></li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p class="note">Because we ensure the resulting <code>Document</code>'s <span
data-x="concept-document-origin">origin</span> is <span
data-x="concept-origin-opaque">opaque</span>, and the resulting <code>Document</code> cannot run
script with access to the DOM, the existence and properties of this <code>Document</code> are not
observable to web developer code. This means that most of the above values, e.g., the
<code>text/html</code> <span data-x="concept-document-type">type</span>, do not matter.
Similarly, most of the items in <var>navigationParams</var> don't have any observable effect,
besides preventing the <span data-x="create-the-document-object"><code>Document</code>-creation
algorithm</span> from getting confused, and so are set to default values.</p>
<p>Once the page has been set up, the user agent must act as if it had <span data-x="stop
parsing">stopped parsing</span>.</p>
<h4 id="loading-documents">Finishing the loading process</h4>
<p>A <code>Document</code> has a <dfn>completely loaded time</dfn> (a time or null), which is
initially null.</p>
<p>A <code>Document</code> is considered <dfn>completely loaded</dfn> if its <span>completely
loaded time</span> is non-null.
<p>To <dfn>completely finish loading</dfn> a <code>Document</code> <var>document</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var>'s <span data-x="concept-document-bc">browsing
context</span> is non-null.</p></li>
<li><p>Set <var>document</var>'s <span>completely loaded time</span> to the current
time.</p></li>
<li>
<p>Let <var>container</var> be <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-container">container</span>.</p>
<div class="note">
<p>This will be null in the case where <var>document</var> is the <span data-x="is initial
about:blank">initial <code>about:blank</code></span> <code>Document</code> in a
<code>frame</code> or <code>iframe</code>, since at the point of <span data-x="creating a new
browsing context and document">browsing context creation</span> which calls this algorithm,
the container relationship has not yet been established. (That happens in a subsequent step of
<span>create a new child navigable</span>.)</p>
<p>The consequence of this is that the following steps do nothing, i.e., we do not fire an
asynchronous <code data-x="event-load">load</code> event on the container element for such
cases. Instead, a synchronous <code data-x="event-load">load</code> event is fired in a special
initial-insertion case when <span data-x="process the iframe attributes">processing the
<code>iframe</code> attributes</span>.</p>
</div>
</li>
<li><p>If <var>container</var> is an <code>iframe</code> element, then <span>queue an element
task</span> on the <span>DOM manipulation task source</span> given <var>container</var> to run
the <span>iframe load event steps</span> given <var>container</var>.</p></li>
<li><p>Otherwise, if <var>container</var> is non-null, then <span>queue an element task</span> on
the <span>DOM manipulation task source</span> given <var>container</var> to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-load">load</code> at
<var>container</var>.</p>
</ol>
<h4>Unloading documents</h4>
<p>A <code>Document</code> has a <dfn
data-x="concept-document-salvageable"><i>salvageable</i></dfn> state, which must initially be
true, and a <dfn>page showing</dfn> boolean, which is initially false. The <span>page
showing</span> boolean is used to ensure that scripts receive <code
data-x="event-pageshow">pageshow</code> and <code data-x="event-pagehide">pagehide</code> events
in a consistent manner (e.g., that they never receive two <code
data-x="event-pagehide">pagehide</code> events in a row without an intervening <code
data-x="event-pageshow">pageshow</code>, or vice versa).</p>
<p>A <code>Document</code> has a <code>DOMHighResTimeStamp</code> <dfn>suspension time</dfn>,
initially 0.</p>
<p>A <code>Document</code> has a <span>list</span> of <dfn>suspended timer handles</dfn>,
initially empty.</p>
<p><span data-x="event loop">Event loops</span> have a <dfn>termination nesting level</dfn>
counter, which must initially be 0.</p>
<p id="ignore-opens-during-unload-counter"><code>Document</code> objects have an <dfn>unload
counter</dfn>, which is used to ignore certain operations while the below algorithms run.
Initially, the counter must be set to zero.</p>
<p>To <dfn data-x="unload a document">unload</dfn> a <code>Document</code>
<var>oldDocument</var>, given an optional <code>Document</code> <var>newDocument</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running as part of a <span data-x="concept-task">task</span>
queued on <var>oldDocument</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Let <var>unloadTimingInfo</var> be a new <span>document unload timing
info</span>.</p></li>
<li>
<p>If <var>newDocument</var> is not given, then set <var>unloadTimingInfo</var> to null.</p>
<p class="note">In this case there is no new document that needs to know about how long it took
<var>oldDocument</var> to unload.</p>
</li>
<li>
<p>Otherwise, if <var>newDocument</var>'s <span>event loop</span> is not
<var>oldDocument</var>'s <span>event loop</span>, then the user agent may be <span
data-x="unload a document">unloading</span> <var>oldDocument</var> <span>in parallel</span>. In
that case, the user agent should set <var>unloadTimingInfo</var> to null.</p>
<p class="note">In this case <var>newDocument</var>'s loading is not impacted by how long it
takes to unload <var>oldDocument</var>, so it would be meaningless to communicate that timing
info.</p>
</li>
<li>
<p>Let <var>intendToKeepInBfcache</var> be true if the user agent intends to keep
<var>oldDocument</var> alive in a <span>session history entry</span>, such that it can later be
<a href="#note-bfcache">used for history traversal</a>.</p>
<p>This must be false if <var>oldDocument</var> is not <i
data-x="concept-document-salvageable">salvageable</i>, or if there are any descendants of
<var>oldDocument</var> which the user agent does not intend to keep alive in the same way
(including due to their lack of <i
data-x="concept-document-salvageable">salvageability</i>).</p>
</li>
<li><p>Let <var>eventLoop</var> be <var>oldDocument</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Increase <var>eventLoop</var>'s <span>termination nesting level</span> by 1.</p></li>
<li><p>Increase <var>oldDocument</var>'s <span>unload counter</span> by 1.</p></li>
<li><p>If <var>intendToKeepInBfcache</var> is false, then set <var>oldDocument</var>'s <i
data-x="concept-document-salvageable">salvageable</i> state to false.</p></li>
<li>
<p>If <var>oldDocument</var>'s <span>page showing</span> is true:</p>
<ol>
<li><p>Set <var>oldDocument</var>'s <span>page showing</span> to false.</p></li>
<li><p><span>Fire a page transition event</span> named <code
data-x="event-pagehide">pagehide</code> at <var>oldDocument</var>'s <span>relevant global
object</span> with <var>oldDocument</var>'s <i
data-x="concept-document-salvageable">salvageable</i> state.</p></li>
<li><p><span>Update the visibility state</span> of <var>oldDocument</var> to
"<code data-x="">hidden</code>".</p></li>
</ol>
</li>
<li><p>If <var>unloadTimingInfo</var> is not null, then set <var>unloadTimingInfo</var>'s
<span>unload event start time</span> to the <span>current high resolution time</span> given
<var>newDocument</var>'s <span>relevant global object</span>, <span data-x="coarsen
time">coarsened</span> given <var>oldDocument</var>'s <span>relevant settings object</span>'s
<span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p></li>
<li><p>If <var>oldDocument</var>'s <i data-x="concept-document-salvageable">salvageable</i>
state is false, then <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-unload">unload</code> at <var>oldDocument</var>'s <span>relevant global
object</span>, with <var>legacy target override flag</var> set.</p></li>
<li><p>If <var>unloadTimingInfo</var> is not null, then set <var>unloadTimingInfo</var>'s
<span>unload event end time</span> to the <span>current high resolution time</span> given
<var>newDocument</var>'s <span>relevant global object</span>, <span data-x="coarsen
time">coarsened</span> given <var>oldDocument</var>'s <span>relevant settings object</span>'s
<span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p></li>
<li><p>Decrease <var>eventLoop</var>'s <span>termination nesting level</span> by 1.</p></li>
<li><p>Set <var>oldDocument</var>'s <span>suspension time</span> to the <span>current high
resolution time</span> given <var>document</var>'s <span>relevant global object</span>.</p></li>
<li><p>Set <var>oldDocument</var>'s <span>suspended timer handles</span> to the result of
<span data-x="map get the keys">getting the keys</span> for the
<span>map of active timers</span>.</p></li>
<li><p>Set <var>oldDocument</var>'s <span>has been scrolled by the user</span> to false.</p></li>
<li><p>Run any <span>unloading document cleanup steps</span> for <var>oldDocument</var> that are
defined by this specification and <span>other applicable specifications</span>.</p></li>
<li><p>If <var>oldDocument</var>'s <span>node navigable</span> is a <span>top-level
traversable</span>, <span>build not restored reasons for a top-level traversable and its
descendants</span> given <var>oldDocument</var>'s <span>node navigable</span>.</p></li>
<li><p>If <var>oldDocument</var>'s <i data-x="concept-document-salvageable">salvageable</i> state
is false, then <span data-x="destroy a document">destroy</span> <var>oldDocument</var>.</p></li>
<li><p>Decrease <var>oldDocument</var>'s <span>unload counter</span> by 1.</p></li>
<li><p>If <var>newDocument</var> is given, <var>newDocument</var>'s <span>was created via
cross-origin redirects</span> is false, and <var>newDocument</var>'s <span
data-x="concept-document-origin">origin</span> is the <span data-x="same origin">same</span> as
<var>oldDocument</var>'s <span data-x="concept-document-origin">origin</span>, then set
<var>newDocument</var>'s <span>previous document unload timing</span> to
<var>unloadTimingInfo</var>.</p></li>
</ol>
<p>To <dfn>unload a document and its descendants</dfn>, given a <code>Document</code>
<var>document</var>, an optional <code>Document</code>-or-null <var>newDocument</var> (default
null), an optional set of steps <var>afterAllUnloads</var>, and an optional set of steps
<var>firePageSwapSteps</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running within <var>document</var>'s <span>node
navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>'s <span
data-x="tn-session-history-traversal-queue">session history traversal queue</span>.</p></li>
<li><p>Let <var>childNavigables</var> be <var>document</var>'s <span data-x="child
navigable">child navigables</span>.</p></li>
<li><p>Let <var>numberUnloaded</var> be 0.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>childNavigable</var> of
<var>childNavigables</var> <span class="XXX" data-x="">in what order?</span>, <span>queue a
global task</span> on the <span>navigation and traversal task source</span> given
<var>childNavigable</var>'s <span data-x="nav-window">active window</span> to perform the
following steps:</p>
<ol>
<li><p>Let <var>incrementUnloaded</var> be an algorithm step which increments
<var>numberUnloaded</var>.</p></li>
<li><p><span>Unload a document and its descendants</span> given <var>childNavigable</var>'s
<span data-x="nav-document">active document</span>, null, and
<var>incrementUnloaded</var>.</p></li>
</ol>
</li>
<li><p>Wait until <var>numberUnloaded</var> equals <var>childNavigable</var>'s <span
data-x="list size">size</span>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>document</var>'s <span>relevant global object</span> to perform the following
steps:</p>
<ol>
<li><p>If <var>firePageSwapSteps</var> is given, then run <var>firePageSwapSteps</var>.</p></li>
<li><p><span data-x="unload a document">Unload</span> <var>document</var>, passing along
<var>newDocument</var> if it is not null.</p></li>
<li><p>If <var>afterAllUnloads</var> was given, then run it.</p></li>
</ol>
</li>
</ol>
<p>This specification defines the following <dfn export>unloading document cleanup steps</dfn>.
Other specifications can define more. Given a <code>Document</code> <var>document</var>:</p>
<ol>
<li><p>Let <var>window</var> be <var>document</var>'s <span>relevant global
object</span>.</p></li>
<li>
<p>For each <code>WebSocket</code> object <var>webSocket</var> whose <span>relevant global
object</span> is <var>window</var>, <span>make disappear</span> <var>webSocket</var>.</p>
<p>If this affected any <code>WebSocket</code> objects, then <span>make document
unsalvageable</span> given <var>document</var> and "<code
data-x="blocking-websocket">websocket</code>".</p>
</li>
<li><p>For each <code>WebTransport</code> object <var>transport</var> whose <span>relevant global
object</span> is <var>window</var>, run the <span>context cleanup steps</span> given
<var>transport</var>.</p></li>
<li>
<p>If <var>document</var>'s <i data-x="concept-document-salvageable">salvageable</i>
state is false, then:</p>
<ol>
<li><p>For each <code>EventSource</code> object <var>eventSource</var> whose <span>relevant
global object</span> is equal to <var>window</var>, <span
data-x="concept-EventSource-forcibly-close">forcibly close</span>
<var>eventSource</var>.</p></li>
<li><p><span data-x="map clear">Clear</span> <var>window</var>'s
<span>map of active timers</span>.</p></li>
</ol>
</li>
</ol>
<div class="XXX">
<p>It would be better if specification authors sent a pull request to add calls from here into
their specifications directly, instead of using the <span>unloading document cleanup
steps</span> hook, to ensure well-defined cross-specification call order. As of the time of this
writing the following specifications are known to have <span>unloading document cleanup
steps</span>, which will be run in an unspecified order: <cite>Fullscreen API</cite>, <cite>Web
NFC</cite>, <cite>WebDriver BiDi</cite>, <cite>Compute Pressure</cite>, <cite>File API</cite>,
<cite>Media Capture and Streams</cite>, <cite>Picture-in-Picture</cite>, <cite>Screen
Orientation</cite>, <cite>Service Workers</cite>, <cite>WebLocks API</cite>, <cite>WebAudio
API</cite>, <cite>WebRTC</cite>. <ref>FULLSCREEN</ref> <ref>WEBNFC</ref> <ref>WEBDRIVERBIDI</ref>
<ref>COMPUTEPRESSURE</ref> <ref>FILEAPI</ref> <ref>MEDIASTREAM</ref> <ref>PICTUREINPICTURE</ref>
<ref>SCREENORIENTATION</ref> <ref>SW</ref> <ref>WEBLOCKS</ref> <ref>WEBAUDIO</ref>
<ref>WEBRTC</ref>
<p><a href="https://github.com/whatwg/html/issues/8906">Issue #8906</a> tracks the work to make
the order of these steps clear.</p>
</div>
<h4>Destroying documents</h4>
<p id="discard-a-document">To <dfn data-x="destroy a document">destroy</dfn> a
<code>Document</code> <var>document</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running as part of a <span data-x="concept-task">task</span>
queued on <var>document</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p><span data-x="abort a document">Abort</span> <var>document</var>.</p></li>
<li><p>Set <var>document</var>'s <i data-x="concept-document-salvageable">salvageable</i> state
to false.</p></li>
<li><p>Let <var>ports</var> be the list of <code>MessagePort</code>s whose <span>relevant global
object</span>'s <span data-x="concept-document-window">associated <code>Document</code></span> is
<var>document</var>.</p></li>
<li><p>For each <var>port</var> in <var>ports</var>, <span>disentangle</span>
<var>port</var>.</p></li>
<li><p>Run any <span>unloading document cleanup steps</span> for <var>document</var> that
are defined by this specification and <span>other applicable specifications</span>.</p></li>
<li><p>Remove any <span data-x="concept-task">tasks</span> whose <span
data-x="concept-task-document">document</span> is <var>document</var> from any <span>task
queue</span> (without running those tasks).</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> to
null.</p></li>
<li><p>Set <var>document</var>'s <span>node navigable</span>'s <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-document">document</span> to null.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>document</var> from the
<span>owner set</span> of each <code>WorkerGlobalScope</code> object whose set <span
data-x="list contains">contains</span> <var>document</var>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>workletGlobalScope</var> in
<var>document</var>'s <span data-x="concept-Document-worklet-global-scopes">worklet global
scopes</span>, <span data-x="terminate a worklet global scope">terminate</span>
<var>workletGlobalScope</var>.</p></li>
</ol>
<p class="note">Even after destruction, the <code>Document</code> object itself might still be
accessible to script, in the case where we are <span data-x="destroy a child
navigable">destroying a child navigable</span>.</p>
<p>To <dfn>destroy a document and its descendants</dfn> given a <code>Document</code>
<var>document</var> and an optional set of steps <var>afterAllDestruction</var>, perform the
following steps <span>in parallel</span>:</p>
<ol>
<li>
<p>If <var>document</var> is not <span>fully active</span>, then:</p>
<ol>
<li><p>Let <var>reason</var> be a string from <span
data-x="ua-specific-blocking-reasons">user-agent specific blocking reasons</span>. If none
apply, then let <var>reason</var> be "<code data-x="blocking-masked">masked</code>".</p></li>
<li><p><span>Make document unsalvageable</span> given <var>document</var> and
<var>reason</var>.</p></li>
<li><p>If <var>document</var>'s <span>node navigable</span> is a
<span>top-level traversable</span>,
<span>build not restored reasons for a top-level traversable and its descendants</span>
given <var>document</var>'s <span>node navigable</span>.</p></li>
</ol>
</li>
<li><p>Let <var>childNavigables</var> be <var>document</var>'s <span data-x="child
navigable">child navigables</span>.</p></li>
<li><p>Let <var>numberDestroyed</var> be 0.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>childNavigable</var> of
<var>childNavigables</var> <span class="XXX" data-x="">in what order?</span>, <span>queue a
global task</span> on the <span>navigation and traversal task source</span> given
<var>childNavigable</var>'s <span data-x="nav-window">active window</span> to perform the
following steps:</p>
<ol>
<li><p>Let <var>incrementDestroyed</var> be an algorithm step which increments
<var>numberDestroyed</var>.</p></li>
<li><p><span>Destroy a document and its descendants</span> given <var>childNavigable</var>'s
<span data-x="nav-document">active document</span> and <var>incrementDestroyed</var>.</p></li>
</ol>
</li>
<li><p>Wait until <var>numberDestroyed</var> equals <var>childNavigable</var>'s <span
data-x="list size">size</span>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>navigation and traversal task source</span>
given <var>document</var>'s <span>relevant global object</span> to perform the following
steps:</p>
<ol>
<li><p><span data-x="destroy a document">Destroy</span> <var>document</var>.</p></li>
<li><p>If <var>afterAllDestruction</var> was given, then run it.</p></li>
</ol>
</li>
</ol>
<h4>Aborting a document load</h4>
<p>To <dfn data-x="abort a document">abort</dfn> a <code>Document</code> <var>document</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running as part of a <span data-x="concept-task">task</span>
queued on <var>document</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Cancel any instances of the <span data-x="concept-fetch">fetch</span> algorithm in the
context of <var>document</var>, discarding any <span data-x="concept-task">tasks</span> <span
data-x="queue a task">queued</span> for them, and discarding any further data received from the
network for them. If this resulted in any instances of the <span
data-x="concept-fetch">fetch</span> algorithm being canceled or any <span data-x="queue a
task">queued</span> <span data-x="concept-task">tasks</span> or any network data getting
discarded, then <span>make document unsalvageable</span> given <var>document</var> and
"<code data-x="blocking-fetch">fetch</code>".</p></li>
<li>
<p>If <var>document</var>'s <span data-x="concept-document-navigation-id">during-loading
navigation ID for WebDriver BiDi</span> is non-null, then:</p>
<ol>
<li><p>Invoke <span>WebDriver BiDi navigation aborted</span> with <var>document</var>'s
<span>node navigable</span> and a new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>document</var>'s <span
data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span>,
<span data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled" >canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>document</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>Set <var>document</var>'s <span data-x="concept-document-navigation-id">during-loading
navigation ID for WebDriver BiDi</span> to null.</p></li>
</ol>
</li>
<li>
<p>If <var>document</var> has an <span>active parser</span>, then:</p>
<ol>
<li><p>Set <var>document</var>'s <span>active parser was aborted</span> to true.</p></li>
<li><p><span data-x="abort a parser">Abort that parser</span>.</p></li>
<li><p>Set <var>document</var>'s <i data-x="concept-document-salvageable">salvageable</i> to
false.</p></li>
<li><p><span>Make document unsalvageable</span> given <var>document</var> and
"<code data-x="blocking-parser-aborted">parser-aborted</code>".</p></li>
</ol>
</li>
</ol>
<p>To <dfn>abort a document and its descendants</dfn> given a <code>Document</code>
<var>document</var>:</p>
<ol>
<li><p><span>Assert</span>: this is running as part of a <span data-x="concept-task">task</span>
queued on <var>document</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Let <var>descendantNavigables</var> be <var>document</var>'s <span>descendant
navigables</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>descendantNavigable</var> of
<var>descendantNavigables</var> <span class="XXX" data-x="">in what order?</span>, <span>queue
a global task</span> on the <span>navigation and traversal task source</span> given
<var>descendantNavigable</var>'s <span data-x="nav-window">active window</span> to perform the
following steps:</p>
<ol>
<li><p><span data-x="abort a document">Abort</span> <var>descendantNavigable</var>'s <span
data-x="nav-document">active document</span>.</p></li>
<li><p>If <var>descendantNavigable</var>'s <span data-x="nav-document">active
document</span>'s <i data-x="concept-document-salvageable">salvageable</i> is false, then set
<var>document</var>'s <i data-x="concept-document-salvageable">salvageable</i> to
false.</p></li>
</ol>
</li>
<li><p><span data-x="abort a document">Abort</span> <var>document</var>.</p></li>
</ol>
<p id="stop-document-loading">To <dfn data-x="nav-stop">stop loading</dfn> a
<span>navigable</span> <var>navigable</var>:</p>
<ol>
<li><p>Let <var>document</var> be <var>navigable</var>'s <span data-x="nav-document">active
document</span>.</p></li>
<li>
<p>If <var>document</var>'s <span>unload counter</span> is 0, and <var>navigable</var>'s
<span>ongoing navigation</span> is a <span>navigation ID</span>, then <span>set the ongoing
navigation</span> for <var>navigable</var> to null.</p>
<p class="note">This will have the effect of aborting any ongoing navigations of
<var>navigable</var>, since at certain points during navigation, changes to the <span>ongoing
navigation</span> will cause further work to be abandoned.</p>
</li>
<li><p><span>Abort a document and its descendants</span> given <var>document</var>.</p></li>
</ol>
<p class="XXX">Through their <a href="#nav-traversal-ui">user interface</a>, user agents also
allow stopping traversals, i.e. cases where the <span>ongoing navigation</span> is "<code
data-x="">traversal</code>". The above algorithm does not account for this. (On the other hand,
user agents do not allow <code data-x="dom-window-stop">window.stop()</code> to stop traversals,
so the above algorithm is correct for that caller.) See <a
href="https://github.com/whatwg/html/issues/6905">issue #6905</a>.</p>
<h3>The `<code>X-Frame-Options</code>` header</h3>
<p>The `<dfn http-header><code>X-Frame-Options</code></dfn>` HTTP response header is a way
of controlling whether and how a <code>Document</code> may be loaded inside of a <span>child
navigable</span>. For sites using CSP, the <code data-x="frame-ancestors
directive">frame-ancestors</code> directive provides more granular control over the
same situations. It was originally defined in <cite>HTTP Header Field X-Frame-Options</cite>, but
the definition<span w-nodev> and processing model</span> here supersedes that document.
<ref>CSP</ref> <ref>RFC7034</ref>
<p class="note">In particular, <cite>HTTP Header Field X-Frame-Options</cite> specified an `<code
data-x="">ALLOW-FROM</code>` variant of the header, but that is not to be implemented.</p>
<p class="note"><span w-nodev>Per the below processing model, if</span><span w-dev>If</span> both
a CSP <code data-x="frame-ancestors directive">frame-ancestors</code> directive and an
`<code>X-Frame-Options</code>` header are used in the same <span
data-x="concept-response">response</span>, then `<code>X-Frame-Options</code>` is ignored.</p>
<p>For web developers and conformance checkers, its value <span data-x="header-abnf">ABNF</span>
is:</p>
<pre><code data-x="" class="abnf">X-Frame-Options = "DENY" / "SAMEORIGIN"</code></pre>
<div w-nodev>
<p>To <dfn>check a navigation response's adherence to `<code>X-Frame-Options</code>`</dfn>, given
a <span data-x="concept-response">response</span> <var>response</var>, a <span>navigable</span>
<var>navigable</var>, a <span data-x="concept-csp-list">CSP list</span> <var>cspList</var>, and
an <span>origin</span> <var>destinationOrigin</var>:</p>
<ol>
<li><p>If <var>navigable</var> is not a <span>child navigable</span>, then return true.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>policy</var> of <var>cspList</var>:</p>
<ol>
<li><p>If <var>policy</var>'s <span data-x="csp-disposition">disposition</span> is not "<code
data-x="">enforce</code>", then <span>continue</span>.</p></li>
<li><p>If <var>policy</var>'s <span data-x="csp-directive-set">directive set</span> <span
data-x="list contains">contains</span> a <code data-x="frame-ancestors
directive">frame-ancestors</code> directive, then return true.</p></li>
</ol>
</li>
<li><p>Let <var>rawXFrameOptions</var> be the result of <span
data-x="concept-header-list-get-decode-split">getting, decoding, and splitting</span>
`<code>X-Frame-Options</code>` from <var>response</var>'s <span
data-x="concept-response-header-list">header list</span>.</p></li>
<li><p>Let <var>xFrameOptions</var> be a new <span>set</span>.</p></li>
<li><p><span data-x="list iterate">For each</span> <var>value</var> of
<var>rawXFrameOptions</var>, <span data-x="set append">append</span> <var>value</var>,
<span>converted to ASCII lowercase</span>, to <var>xFrameOptions</var>.</p></li>
<li>
<p>If <var>xFrameOptions</var>'s <span data-x="list size">size</span> is greater than 1, and
<var>xFrameOptions</var> <span data-x="list contains">contains</span> any of "<code
data-x="">deny</code>", "<code data-x="">allowall</code>", or "<code
data-x="">sameorigin</code>", then return false.</p>
<p class="note">The intention here is to block any attempts at applying
`<code>X-Frame-Options</code>` which were trying to do something valid, but appear confused.</p>
<p class="note">This is the only impact of the legacy `<code data-x="">ALLOWALL</code>` value
on the processing model.</p>
</li>
<li>
<p>If <var>xFrameOptions</var>'s <span data-x="list size">size</span> is greater than 1, then
return true.</p>
<p class="note">This means it contains multiple invalid values, which we treat the same way as
if the header was omitted entirely.</p>
</li>
<li><p>If <var>xFrameOptions</var>[0] is "<code data-x="">deny</code>", then return
false.</p></li>
<li>
<p>If <var>xFrameOptions</var>[0] is "<code data-x="">sameorigin</code>", then:</p>
<ol>
<li><p>Let <var>containerDocument</var> be <var>navigable</var>'s <span
data-x="nav-container-document">container document</span>.</p></li>
<li>
<p><span>While</span> <var>containerDocument</var> is not null:</p>
<ol>
<li><p>If <var>containerDocument</var>'s <span data-x="concept-document-origin">origin</span>
is not <span>same origin</span> with <var>destinationOrigin</var>, then return
false.</p></li>
<li><p>Set <var>containerDocument</var> to <var>containerDocument</var>'s <span
data-x="doc-container-document">container document</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Return true.</p>
<p class="note">If we've reached this point then we have a lone invalid value (which could
potentially be one the legacy `<code data-x="">ALLOWALL</code>` or `<code
data-x="">ALLOW-FROM</code>` forms). These are treated as if the header were omitted
entirely.</p>
</li>
</ol>
<hr>
</div>
<div class="example">
<p>The following table illustrates the processing of various values for the header, including
non-conformant ones:</p>
<table class="data">
<thead>
<tr>
<th>`<code>X-Frame-Options</code>`</th>
<th>Valid</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td>`<code data-x="">DENY</code>`</td>
<td>✅</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">SAMEORIGIN</code>`</td>
<td>✅</td>
<td>same-origin embedding allowed</td>
</tr>
<tr>
<td>`<code data-x="">INVALID</code>`</td>
<td>❌</td>
<td>embedding allowed</td>
</tr>
<tr>
<td>`<code data-x="">ALLOWALL</code>`</td>
<td>❌</td>
<td>embedding allowed</td>
</tr>
<tr>
<td>`<code data-x="">ALLOW-FROM=https://example.com/</code>`</td>
<td>❌</td>
<td>embedding allowed (from anywhere)</td>
</tr>
</tbody>
</table>
</div>
<div class="example">
<p>The following table illustrates how various non-conformant cases involving multiple values are
processed:</p>
<table class="data">
<thead>
<tr>
<th>`<code>X-Frame-Options</code>`</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td>`<code data-x="">SAMEORIGIN, SAMEORIGIN</code>`</td>
<td>same-origin embedding allowed</td>
</tr>
<tr>
<td>`<code data-x="">SAMEORIGIN, DENY</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">SAMEORIGIN,</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">SAMEORIGIN, ALLOWALL</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">SAMEORIGIN, INVALID</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">ALLOWALL, INVALID</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">ALLOWALL,</code>`</td>
<td>embedding disallowed</td>
</tr>
<tr>
<td>`<code data-x="">INVALID, INVALID</code>`</td>
<td>embedding allowed</td>
</tr>
</tbody>
</table>
<p>The same results are obtained whether the values are delivered in a single header whose value is comma-delimited,
or in multiple headers.</p>
</div>
<h3>The `<code>Refresh</code>` header</h3>
<p>The `<dfn http-header><code>Refresh</code></dfn>` HTTP response header is the HTTP-equivalent
to a <code>meta</code> element with an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute in the <span data-x="attr-meta-http-equiv-refresh">Refresh state</span>. It takes <a
href="#conformance-attr-meta-http-equiv-refresh">the same value</a> and works largely the
same.<span w-nodev> Its processing model is detailed in <span
data-x="create-the-document-object">create and initialize a <code>Document</code>
object</span>.</span></p>
<!-- This might be a retcon. -->
<h3 id="nav-traversal-ui"><span id="history-notes"></span>Browser user interface
considerations</h3>
<p>Browser user agents should provide the ability to <!-- DONAV browser UI
--><span>navigate</span>, <span>reload</span>, and <span data-x="nav-stop">stop loading</span>
any <span>top-level traversable</span> in their <span>top-level traversable set</span>.</p>
<p class="example">For example, via a location bar and reload/stop button UI.</p>
<p>Browser user agents should provide the ability to <span data-x="traverse the history by a
delta">traverse by a delta</span> any <span>top-level traversable</span> in their <span>top-level
traversable set</span>.</p>
<p class="example">For example, via back and forward buttons, possibly including long-press
abilities to change the delta.</p>
<p>It is suggested that such user agents allow traversal by deltas greater than one, to avoid
letting a page "trap" the user by stuffing the session history with spurious entries. (For
example, via repeated calls to <code data-x="dom-history-pushState">history.pushState()</code> or
<span data-x="navigate-fragid">fragment navigations</span>.)</p>
<p class="note">Some user agents have heuristics for translating a single "back" or "forward"
button press into a larger delta, specifically to overcome such abuses. We are contemplating
specifying these heuristics in <a href="https://github.com/whatwg/html/issues/7832">issue
#7832</a>.</p>
<p>Browser user agents should offer users the ability to <span>create a fresh top-level
traversable</span>, given a user-provided or user agent-determined initial <span>URL</span>.</p>
<p class="example">For example, via a "new tab" or "new window" button.</p>
<p>Browser user agents should offer users the ability to arbitrarily <span data-x="close a
top-level traversable">close</span> any <span>top-level traversable</span> in their
<span>top-level traversable set</span>.</p>
<p class="example">For example, by clicking a "close tab" button.</p>
<hr>
<p>Browser user agents may provide ways for the user to explicitly cause any
<span>navigable</span> (not just a <span>top-level traversable</span>) to <!-- DONAV browser UI
--><span>navigate</span>, <span>reload</span>, or <span data-x="nav-stop">stop
loading</span>.</p>
<p class="example">For example, via a context menu.</p>
<p>Browser user agents may provide the ability for users to <span>destroy a top-level
traversable</span>.</p>
<p class="example">For example, by force-closing a window containing one or more such <span
data-x="top-level traversable">top-level traversables</span>.</p>
<hr>
<p>When a user requests a <span>reload</span> of a <span>navigable</span> whose <span
data-x="nav-active-history-entry">active session history entry</span>'s <span
data-x="she-document-state">document state</span>'s <span
data-x="document-state-resource">resource</span> is a <span>POST resource</span>, the user agent
should prompt the user to confirm the operation first, since otherwise transactions (e.g.,
purchases or database modifications) could be repeated.</p>
<p>When a user requests a <span>reload</span> of a <span>navigable</span>, user agents may provide
a mechanism for ignoring any caches when reloading.</p>
<hr>
<p>All calls to <span>navigate</span> initiated by the mechanisms mentioned above must have the <i
data-x="navigation-user-involvement">userInvolvement</i> argument set to "<code
data-x="uni-browser-ui">browser UI</code>".</p>
<p>All calls to <span>reload</span> initiated by the mechanisms mentioned above must have the <i
data-x="reload-user-involvement">userInvolvement</i> argument set to "<code
data-x="uni-browser-ui">browser UI</code>".</p>
<p>All calls to <span>traverse the history by a delta</span> initiated by the mechanisms mentioned
above must not pass a value for the <i data-x="traverse-sourceDocument">sourceDocument</i>
argument.</p>
<hr>
<p>The above recommendations, and the data structures in this specification, are not meant to
place restrictions on how user agents represent the session history to the user.</p>
<p>For example, although a <span>top-level traversable</span>'s <span
data-x="tn-session-history-entries">session history entries</span> are stored and maintained as a
list, and the user agent is recommended to give an interface for <span data-x="traverse the
history by a delta">traversing that list by a delta</span>, a novel user agent could instead or
in addition present a tree-like view, with each page having multiple "forward" pages that the user
can choose between.</p>
<p>Similarly, although session history for all descendant <span
data-x="navigable">navigables</span> is stored in their <span>traversable navigable</span>, user
agents could present the user with a more nuanced per-<span>navigable</span> view of the session
history.</p>
<hr>
<p>Browser user agents may use a <span>top-level browsing context</span>'s <span>is
popup</span> boolean for the following purposes:
<ul>
<li><p>Deciding whether or not to provide a minimal web browser user interface for the
corresponding <span>top-level traversable</span>.</p></li>
<li><p>Performing the optional steps in <span>set up browsing context features</span>.</p></li>
</ul>
<p>In both cases user agents might additionally incorporate user preferences, or present a choice
as to whether to go down the popup route.</p>
<p>User agents that provides a minimal user interface for such popups are encouraged to not hide
the browser's location bar.</p>
<h2 split-filename="webappapis" id="webappapis">Web application APIs</h2>
<h3 id="scripting">Scripting</h3>
<h4>Introduction</h4>
<p>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:</p>
<ul>
<li>Processing of <code>script</code> elements.</li>
<li>Navigating to <span data-x="javascript protocol"><code>javascript:</code> URLs</span>.</li>
<li>Event handlers, whether registered through the DOM using <code
data-x="">addEventListener()</code>, by explicit <span>event handler content attributes</span>, by
<span>event handler IDL attributes</span>, or otherwise.</li>
<li>Processing of technologies like SVG that have their own scripting features.</li>
</ul>
<h4>Agents and agent clusters</h4>
<h5>Integration with the JavaScript agent formalism</h5>
<p>JavaScript defines the concept of an <span>agent</span>. This section gives the mapping of that
language-level concept on to the web platform.</p>
<div class="note">
<p>Conceptually, the <span>agent</span> concept is an architecture-independent, idealized
"thread" in which JavaScript code runs. Such code can involve multiple globals/<span
data-x="concept-global-object-realm">realms</span> that can synchronously access each other, and
thus needs to run in a single execution thread.</p>
<p w-nodev>Two <code>Window</code> objects having the same <span>agent</span> does not indicate
they can directly access all objects created in each other's realms. They would have to be
<span>same origin-domain</span>; see <span>IsPlatformObjectSameOrigin</span>.</p>
</div>
<p>The following types of agents exist on the web platform:</p>
<dl>
<dt><dfn export>Similar-origin window agent</dfn></dt>
<dd>
<p>Contains various <code>Window</code> objects which can potentially reach each other, either
directly or by using <code data-x="dom-document-domain">document.domain</code>.</p>
<p>If the encompassing <span>agent cluster</span>'s <span>is origin-keyed</span> is true, then
all the <code>Window</code> objects will be <span>same origin</span>, can reach each other
directly, and <code data-x="dom-document-domain">document.domain</code> will no-op.</p>
<p class="note">Two <code>Window</code> objects that are <span>same origin</span> can be in
different <span data-x="similar-origin window agent">similar-origin window agents</span>, for
instance if they are each in their own <span>browsing context group</span>.</p>
</dd>
<dt><dfn export>Dedicated worker agent</dfn></dt>
<dd><p>Contains a single <code>DedicatedWorkerGlobalScope</code>.</p></dd>
<dt><dfn export>Shared worker agent</dfn></dt>
<dd><p>Contains a single <code>SharedWorkerGlobalScope</code>.</p></dd>
<dt><dfn export>Service worker agent</dfn></dt>
<dd><p>Contains a single <code>ServiceWorkerGlobalScope</code>.</p></dd>
<dt><dfn export>Worklet agent</dfn></dt>
<dd>
<p>Contains a single <code>WorkletGlobalScope</code> object.</p>
<p class="note">Although a given worklet can have multiple realms, each such realm needs its own
agent, as each realm can be executing code independently and at the same time as the others.</p>
</dd>
</dl>
<p>Only <span data-x="shared worker agent">shared</span> and <span data-x="dedicated worker
agent">dedicated worker agents</span> allow the use of JavaScript <code>Atomics</code> APIs to
potentially <span data-x="forward progress">block</span>.</p>
<div w-nodev>
<p>To <dfn>create an agent</dfn>, given a boolean <var>canBlock</var>:</p>
<ol>
<li><p>Let <var>signifier</var> be a new unique internal value.</p></li>
<li><p>Let <var>candidateExecution</var> be a new <span>candidate execution</span>.</p></li>
<li><p>Let <var>agent</var> be a new <span>agent</span> whose [[CanBlock]] is
<var>canBlock</var>, [[Signifier]] is <var>signifier</var>, [[CandidateExecution]] is
<var>candidateExecution</var>, and [[IsLockFree1]], [[IsLockFree2]], and [[LittleEndian]] are set
at the implementation's discretion.</p></li>
<li><p>Set <var>agent</var>'s <span data-x="concept-agent-event-loop">event loop</span> to a new
<span>event loop</span>.</p></li>
<li><p>Return <var>agent</var>.</p></li>
</ol>
<p>For a <span>realm</span> <var>realm</var>, the <span>agent</span> whose [[Signifier]] is
<var>realm</var>.[[AgentSignifier]] is <dfn data-x="realm's agent" export data-lt="agent"
for="realm">the realm's agent</dfn>.</p>
<p>The <dfn export>relevant agent</dfn> for a <span>platform object</span>
<var>platformObject</var> is <var>platformObject</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>'s <span data-x="realm's
agent">agent</span>.</p>
<p class="note">The agent equivalent of the <span>current realm</span> is the <span>surrounding
agent</span>.</p>
</div>
<h5>Integration with the JavaScript agent cluster formalism</h5>
<p>JavaScript also defines the concept of an <span>agent cluster</span>, which this standard maps
to the web platform by placing agents appropriately when they are created<span w-nodev> using the
<span data-x="obtain-similar-origin-window-agent">obtain a similar-origin window agent</span> or
<span data-x="obtaining a worker/worklet agent">obtain a worker/worklet agent</span>
algorithms</span>.</p>
<p>The <span>agent cluster</span> concept is crucial for defining the JavaScript memory model, and
in particular among which <span data-x="agent">agents</span> the backing data of
<code>SharedArrayBuffer</code> objects can be shared.</p>
<p class="note">Conceptually, the <span>agent cluster</span> concept is an
architecture-independent, idealized "process boundary" that groups together multiple "threads"
(<span data-x="agent">agents</span>). The <span data-x="agent cluster">agent clusters</span>
defined by the specification are generally more restrictive than the actual process boundaries
implemented in user agents. By enforcing these idealized divisions at the specification level, we
ensure that web developers see interoperable behavior with regard to shared memory, even in the
face of varying and changing user agent process models.</p>
<div w-nodev>
<p>An <span>agent cluster</span> has an associated <dfn
data-x="agent-cluster-cross-origin-isolation">cross-origin isolation mode</dfn>, which is a
<span>cross-origin isolation mode</span>. It is initially "<code
data-x="cross-origin-isolation-none">none</code>".</p>
<p>An <span>agent cluster</span> has an associated <dfn>is origin-keyed</dfn> (a boolean), which
is initially false.</p>
<hr>
<p>The following defines the allocation of the <span data-x="agent cluster">agent clusters</span>
of <span data-x="similar-origin window agent">similar-origin window agents</span>.</p>
<p>An <dfn>agent cluster key</dfn> is a <span>site</span> or <span
data-x="concept-origin-tuple">tuple origin</span>. Without web developer action to achieve <a
href="#origin-keyed-agent-clusters">origin-keyed agent clusters</a>, it will be a
<span>site</span>.</p>
<p class="note">An equivalent formulation is that an <span>agent cluster key</span> can be a
<span>scheme-and-host</span> or an <span>origin</span>.</p>
<p>To <dfn data-x="obtain-similar-origin-window-agent">obtain a similar-origin window agent</dfn>,
given an <span>origin</span> <var>origin</var>, a <span>browsing context group</span>
<var>group</var>, and a boolean <var>requestsOAC</var>, run these steps:</p>
<ol>
<li><p>Let <var>site</var> be the result of <span data-x="obtain a site">obtaining a site</span>
with <var>origin</var>.</p></li>
<li><p>Let <var>key</var> be <var>site</var>.</p></li>
<li><p>If <var>group</var>'s <span data-x="bcg-cross-origin-isolation">cross-origin isolation
mode</span> is not "<code data-x="cross-origin-isolation-none">none</code>", then set
<var>key</var> to <var>origin</var>.</p></li>
<li><p>Otherwise, if <var>group</var>'s <span>historical agent cluster key
map</span>[<var>origin</var>] <span data-x="map exists">exists</span>, then set <var>key</var> to
<var>group</var>'s <span>historical agent cluster key map</span>[<var>origin</var>].</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>If <var>requestsOAC</var> is true, then set <var>key</var> to
<var>origin</var>.</p></li>
<li><p>Set <var>group</var>'s <span>historical agent cluster key map</span>[<var>origin</var>]
to <var>key</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>group</var>'s <span>agent cluster map</span>[<var>key</var>] <span data-x="map
exists">does not exist</span>, then:</p>
<ol>
<li><p>Let <var>agentCluster</var> be a new <span>agent cluster</span>.</p></li>
<li><p>Set <var>agentCluster</var>'s <span
data-x="agent-cluster-cross-origin-isolation">cross-origin isolation mode</span> to
<var>group</var>'s <span data-x="bcg-cross-origin-isolation">cross-origin isolation
mode</span>.</p></li>
<li>
<p>If <var>key</var> is an <span>origin</span>:</p>
<ol>
<li><p><span>Assert</span>: <var>key</var> is <var>origin</var>.</p></li>
<li><p>Set <var>agentCluster</var>'s <span>is origin-keyed</span> to true.</p></li>
</ol>
</li>
<li><p>Add the result of <span data-x="create an agent">creating an agent</span>, given false,
to <var>agentCluster</var>.</p></li>
<li><p>Set <var>group</var>'s <span>agent cluster map</span>[<var>key</var>] to
<var>agentCluster</var>.</p></li>
</ol>
</li>
<li><p>Return the single <span>similar-origin window agent</span> contained in <var>group</var>'s
<span>agent cluster map</span>[<var>key</var>].</p></li>
</ol>
<p class="note">This means that there is only one <span>similar-origin window agent</span> per
browsing context agent cluster. (However, <span data-x="dedicated worker agent">dedicated
worker</span> and <span data-x="worklet agent">worklet agents</span> might be in the same
cluster.)</p>
<hr>
<p>The following defines the allocation of the <span data-x="agent cluster">agent clusters</span>
of all other types of agents.</p>
<p>To <dfn data-x="obtaining a worker/worklet agent">obtain a worker/worklet agent</dfn>, given an
<span>environment settings object</span> or null <var>outside settings</var>, a boolean
<var>isTopLevel</var>, and a boolean <var>canBlock</var>, run these steps:</p>
<ol>
<li><p>Let <var>agentCluster</var> be null.
<li>
<p>If <var>isTopLevel</var> is true, then:</p>
<ol>
<li><p>Set <var>agentCluster</var> to a new <span>agent cluster</span>.</p></li>
<li>
<p>Set <var>agentCluster</var>'s <span>is origin-keyed</span> to true.</p>
<p class="note">These workers can be considered to be origin-keyed. However, this is not
exposed through any APIs (in the way that <code
data-x="dom-originAgentCluster">originAgentCluster</code> exposes the origin-keyedness for
windows).</p>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: <var>outside settings</var> is not null.</p></li>
<li><p>Let <var>ownerAgent</var> be <var>outside settings</var>'s <span data-x="environment
settings object's realm">realm</span>'s <span data-x="realm's agent">agent</span>.</p></li>
<li><p>Set <var>agentCluster</var> to the agent cluster which contains
<var>ownerAgent</var>.</p></li>
</ol>
</li>
<li><p>Let <var>agent</var> be the result of <span data-x="create an agent">creating an
agent</span> given <var>canBlock</var>.</p></li>
<li><p>Add <var>agent</var> to <var>agentCluster</var>.</p></li>
<li><p>Return <var>agent</var>.</p></li>
</ol>
<p>To <dfn>obtain a dedicated/shared worker agent</dfn>, given an <span>environment settings
object</span> <var>outside settings</var> and a boolean <var>isShared</var>, return the result of
<span>obtaining a worker/worklet agent</span> given <var>outside settings</var>,
<var>isShared</var>, and true.</p>
<p>To <dfn>obtain a worklet agent</dfn>, given an <span>environment settings object</span>
<var>outside settings</var>, return the result of <span>obtaining a worker/worklet agent</span>
given <var>outside settings</var>, false, and false.</p>
<p>To <dfn export>obtain a service worker agent</dfn>, return the result of <span>obtaining a
worker/worklet agent</span> given null, true, and false.</p>
<hr>
</div>
<div class="example" id="can-share-memory-with">
<p>The following pairs of global objects are each within the same <span>agent cluster</span>, and
thus can use <code>SharedArrayBuffer</code> instances to share memory with each other:</p>
<ul>
<li><p>A <code>Window</code> object and a dedicated worker that it created.</p></li>
<li><p>A worker (of any type) and a dedicated worker it created.</p></li>
<li><p>A <code>Window</code> object <var>A</var> and the <code>Window</code> object of an
<code>iframe</code> element that <var>A</var> created that could be <span>same
origin-domain</span> with <var>A</var>.</p></li>
<li><p>A <code>Window</code> object and a <span>same origin-domain</span> <code>Window</code>
object that opened it.</p></li>
<li><p>A <code>Window</code> object and a worklet that it created.</p></li>
</ul>
<p>The following pairs of global objects are <em>not</em> within the same <span>agent
cluster</span>, and thus cannot share memory:</p>
<ul>
<li><p>A <code>Window</code> object and a shared worker it created.</p></li>
<li><p>A worker (of any type) and a shared worker it created.</p></li>
<li><p>A <code>Window</code> object and a service worker it created.</p></li>
<li><p>A <code>Window</code> object <var>A</var> and the <code>Window</code> object of an
<code>iframe</code> element that <var>A</var> created that cannot be <span>same
origin-domain</span> with <var>A</var>.</p></li>
<li><p>Any two <code>Window</code> objects with no opener or ancestor relationship. This holds
even if the two <code>Window</code> objects are <span>same origin</span>.</p></li>
</ul>
</div>
<div w-nodev>
<h4>Realms and their counterparts</h4>
<p>The JavaScript specification introduces the <span>realm</span> concept, representing a global
environment in which script is run. Each realm comes with an <span>implementation-defined</span>
<span>global object</span>; much of this specification is devoted to defining that global object
and its properties.</p>
<p>For web specifications, it is often useful to associate values or algorithms with a
realm/global object pair. When the values are specific to a particular type of realm, they are
associated directly with the global object in question, e.g., in the definition of the
<code>Window</code> or <code>WorkerGlobalScope</code> interfaces. When the values have utility
across multiple realms, we use the <span>environment settings object</span> concept.</p>
<p>Finally, in some cases it is necessary to track associated values before a
realm/global object/environment settings object even comes into existence (for example, during
<span data-x="navigate">navigation</span>). These values are tracked in the
<span>environment</span> concept.</p>
<h5>Environments</h5>
<p>An <dfn export>environment</dfn> is an object that identifies the settings of a current or
potential execution environment (i.e., a <span data-x="navigation params">navigation
params</span>'s <span data-x="navigation-params-reserved-environment">reserved environment</span>
or a <span data-x="concept-request">request</span>'s <span
data-x="concept-request-reserved-client">reserved client</span>). An <span>environment</span> has
the following fields:</p>
<dl>
<dt>An <dfn data-x="concept-environment-id" export
for="environment">id</dfn></dt>
<dd><p>An opaque string that uniquely identifies this <span>environment</span>.</p></dd>
<dt>A <dfn data-x="concept-environment-creation-url" export
for="environment">creation URL</dfn></dt>
<dd>
<p>A <span>URL</span> that represents the location of the resource with which this
<span>environment</span> is associated.</p>
<p class="note">In the case of a <code>Window</code> <span>environment settings object</span>,
this URL might be distinct from its <span data-x="concept-settings-object-global">global
object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="concept-document-url">URL</span>, due to
mechanisms such as <code data-x="dom-history-pushstate">history.pushState()</code> which modify
the latter.</p>
</dd>
<dt>A <dfn id="concept-environment-top-level-creation-url" export
for="environment">top-level creation URL</dfn></dt>
<dd><p>Null or a <span>URL</span> that represents the <span
data-x="concept-environment-creation-url">creation URL</span> of the "top-level"
<span>environment</span>. It is null for workers and worklets.</p></dd>
<dt>A <dfn id="concept-environment-top-level-origin" export
for="environment">top-level origin</dfn></dt>
<dd>
<p>A <span class="XXX" data-x="">for now</span> <span>implementation-defined</span> value, null,
or an <span>origin</span>. For a "top-level" potential execution environment it is null (i.e.,
when there is no response yet); otherwise it is the "top-level" <span>environment</span>'s <span
data-x="concept-settings-object-origin">origin</span>. For a dedicated worker or worklet it is
the <span>top-level origin</span> of its creator. For a shared or service worker it is an
<span>implementation-defined</span> value.</p>
<p class="note">This is distinct from the <span>top-level creation URL</span>'s <span
data-x="concept-url-origin">origin</span> when sandboxing, workers, and worklets are
involved.</p>
</dd>
<dt>A <dfn data-x="concept-environment-target-browsing-context" export
for="environment">target browsing context</dfn></dt>
<dd><p>Null or a target <span>browsing context</span> for a <span
data-x="navigation-request">navigation request</span>.</p></dd>
<dt>An <dfn data-x="concept-environment-active-service-worker" export
for="environment">active service worker</dfn></dt>
<dd><p>Null or a <span data-x="dfn-service-worker">service worker</span> that <span
data-x="dfn-control">controls</span> the <span>environment</span>.</p></dd>
<dt>An <dfn data-x="concept-environment-execution-ready-flag" export
for="environment">execution ready flag</dfn></dt>
<dd><p>A flag that indicates whether the environment setup is done. It is initially
unset.</p></dd>
</dl>
<p>Specifications may define <dfn export>environment discarding steps</dfn> for environments. The
steps take an <span>environment</span> as input.</p>
<p class="note">The <span data-x="environment discarding steps">environment discarding
steps</span> are run for only a select few environments: the ones that will
never become execution ready because, for example, they failed to load.</p>
<h5>Environment settings objects</h5>
<p>An <dfn export>environment settings object</dfn> is an <span>environment</span> that
additionally specifies algorithms for:</p>
<dl>
<dt>A <dfn export for="environment settings object">realm execution
context</dfn></dt>
<dd>
<p>A <span>JavaScript execution context</span> shared by all
<span data-x="script">scripts</span> that use this settings object, i.e., all scripts in a given
<span>realm</span>. When we <span>run a classic script</span> or <span>run a module
script</span>, this execution context becomes the top of the <span>JavaScript execution context
stack</span>, on top of which another execution context specific to the script in question is
pushed. (This setup ensures <span>Source Text Module Record</span>'s
<span data-x="js-Evaluate">Evaluate</span> knows which realm to use.)</p>
</dd>
<dt>A <dfn data-x="concept-settings-object-module-map" export for="environment
settings object">module map</dfn></dt>
<dd>
<p>A <span>module map</span> that is used when importing JavaScript modules.</p>
</dd>
<dt>An <dfn export for="environment settings object">API base URL</dfn></dt>
<dd>
<p>A <span>URL</span> used by APIs called by scripts that use this <span>environment settings
object</span> to <span data-x="parse a URL">parse URLs</span>.</p>
</dd>
<dt>An <dfn data-x="concept-settings-object-origin" export for="environment
settings object">origin</dfn></dt>
<dd>
<p>An <span>origin</span> used in security checks.</p>
</dd>
<dt>A <dfn data-x="concept-settings-object-policy-container" export
for="environment settings object">policy container</dfn></dt>
<dd>
<p>A <span>policy container</span> containing policies used for security checks.</p>
</dd>
<dt>A <dfn data-x="concept-settings-object-cross-origin-isolated-capability" export
for="environment settings object">cross-origin isolated capability</dfn></dt>
<dd><p>A boolean representing whether scripts that use this <span>environment settings
object</span> are allowed to use APIs that require cross-origin isolation.</p></dd>
<dt>A <dfn data-x="concept-settings-object-time-origin" export
for="environment settings object">time origin</dfn></dt>
<dd>A number used as the baseline for performance-related timestamps. <ref>HRT</ref></dd>
</dl>
<p>An <span>environment settings object</span>'s <dfn export for="environment settings
object">responsible event loop</dfn> is its <span data-x="concept-settings-object-global">global
object</span>'s <span>relevant agent</span>'s <span data-x="concept-agent-event-loop">event
loop</span>.</p>
<h5 id="realms-settings-objects-global-objects">Realms, settings objects, and global objects</h5>
<p>A <dfn export>global object</dfn> is a JavaScript object that is the [[GlobalObject]] field of
a <span>realm</span>.</p>
<p class="note">In this specification, all <span data-x="realm">realms</span> are <span
data-x="creating a new realm">created</span> with <span data-x="global object">global
objects</span> that are either <code>Window</code>, <code>WorkerGlobalScope</code>, or
<code>WorkletGlobalScope</code> objects.</p>
<p>A <span>global object</span> has an <dfn for="global object">in error reporting mode</dfn>
boolean, which is initially false.</p>
<p>A <span>global object</span> has an <dfn>outstanding rejected promises weak set</dfn>, a
<span>set</span> of <code data-x="idl-Promise">Promise</code> objects, initially empty. This set
must not create strong references to any of its members, and implementations are free to limit
its size in an <span>implementation-defined</span> manner, e.g., by removing old entries from it
when new ones are added.</p>
<p>A <span>global object</span> has an <dfn>about-to-be-notified rejected promises list</dfn>, a
<span>list</span> of <code data-x="idl-Promise">Promise</code> objects, initially empty.</p>
<p>A <span>global object</span> has an <dfn data-x="concept-global-import-map">import map</dfn>,
initially an <span>empty import map</span>.</p>
<p class="note">For now, only <code>Window</code> <span data-x="global object">global
objects</span> have their <span data-x="concept-global-import-map">import map</span> modified
from the initial empty one. The <span data-x="concept-global-import-map">import map</span> is
only accessed for the resolution of a root <span>module script</span>.</p>
<p>A <span>global object</span> has a <dfn>resolved module set</dfn>, a <span>set</span>
of <span data-x="specifier resolution record">specifier resolution records</span>, initially
empty.</p>
<p class="note">The <span>resolved module set</span> ensures that module specifier resolution
returns the same result when called multiple times with the same (referrer, specifier) pair. It
does that by ensuring that <span>import map</span> rules that impact the specifier in its
referrer's scope cannot be defined after its initial resolution. For now, only <code>Window</code>
<span data-x="global object">global objects</span> have their module set data structures modified
from the initial empty one.</p>
<hr>
<p>There is always a 1-to-1-to-1 mapping between <span data-x="realm">realms</span>, <span
data-x="global object">global objects</span>, and <span data-x="environment settings
object">environment settings objects</span>:</p>
<ul>
<li><p>A <span>realm</span> has a [[HostDefined]] field, which contains <dfn
data-x="concept-realm-settings-object" export data-lt="settings object" for="realm">the realm's
settings object</dfn>.</p></li>
<li><p>A <span>realm</span> has a [[GlobalObject]] field, which contains <dfn
data-x="concept-realm-global" export data-lt="global object" for="realm">the realm's global
object</dfn>.</p></li>
<li><p>Each <span>global object</span> in this specification is created during the <span
data-x="creating a new realm">creation</span> of a corresponding <span>realm</span>, known as
<dfn data-x="concept-global-object-realm" export data-lt="realm" for="global object">the global
object's realm</dfn>.</p></li>
<li id="relevant-settings-object-for-a-global-object"><p>Each <span>global object</span> in this
specification is created alongside a corresponding <span>environment settings object</span>,
known as its <span>relevant settings object</span>.</p>
<li><p>An <span>environment settings object</span>'s <span>realm execution context</span>'s
Realm component is <dfn data-x="environment settings object's realm" export data-lt="realm"
for="environment settings object">the environment settings object's realm</dfn>.</p></li>
<li><p>An <span>environment settings object</span>'s <span data-x="environment settings object's
realm">realm</span> then has a [[GlobalObject]] field, which contains <dfn export
data-x="concept-settings-object-global" data-lt="global object" for="environment settings
object">the environment settings object's global object</dfn>.</p></li>
</ul>
<p>To <dfn data-x="creating a new realm" export id="creating-a-new-javascript-realm">create a new
realm</dfn> in an <span>agent</span> <var>agent</var>, optionally with instructions to create a
global object or a global <b>this</b> binding (or both), the following steps are taken:</p>
<ol>
<li><p>Perform <span data-x="js-InitializeHostDefinedRealm">InitializeHostDefinedRealm</span>()
with the provided customizations for creating the global object and the global <b>this</b>
binding.</p></li>
<li>
<p>Let <var>realm execution context</var> be the <span>running JavaScript execution
context</span>.</p>
<p class="note">This is the <span>JavaScript execution context</span> created in the previous
step.</p>
</li>
<li><p>Remove <var>realm execution context</var> from the <span>JavaScript execution context
stack</span>.</p></li>
<li><p>Let <var>realm</var> be <var>realm execution context</var>'s Realm component.</p></li>
<li>
<p>If <var>agent</var>'s <span>agent cluster</span>'s <span
data-x="agent-cluster-cross-origin-isolation">cross-origin isolation mode</span> is "<code
data-x="cross-origin-isolation-none">none</code>", then:</p>
<ol>
<li><p>Let <var>global</var> be <var>realm</var>'s <span data-x="concept-realm-global">global
object</span>.</p></li>
<li><p>Let <var>status</var> be ! <var>global</var>.[[Delete]]("<code
data-x="">SharedArrayBuffer</code>").</p></li>
<li><p><span>Assert</span>: <var>status</var> is true.</p></li>
</ol>
<p class="note">This is done for compatibility with web content and there is some hope that this
can be removed in the future. Web developers can still get at the constructor through
<code class="js" data-x="">new WebAssembly.Memory({ shared:true, initial:0, maximum:0
}).buffer.constructor</code>.</p>
</li>
<li><p>Return <var>realm execution context</var>.</p></li>
</ol>
<hr>
<p>When defining algorithm steps throughout this specification, it is often important to indicate
what <span>realm</span> is to be used—or, equivalently, what <span>global object</span> or
<span>environment settings object</span> is to be used. In general, there are at least four
possibilities:</p>
<dl>
<dt><dfn data-x="concept-entry-everything">Entry</dfn></dt>
<dd>This corresponds to the script that initiated the currently running script action: i.e.,
the function or script that the user agent called into when it called into author code.</dd>
<dt><dfn data-x="concept-incumbent-everything">Incumbent</dfn></dt>
<dd>This corresponds to the most-recently-entered author function or script on the stack, or the
author function or script that originally scheduled the currently-running callback.</dd>
<dt><dfn data-x="concept-current-everything">Current</dfn></dt>
<dd>This corresponds to the currently-running function object, including built-in user-agent
functions which might not be implemented as JavaScript. (It is derived from the <span>current
realm</span>.)</dd>
<dt><dfn data-x="concept-relevant-everything">Relevant</dfn></dt>
<dd>Every <span>platform object</span> has a <span data-x="concept-relevant-realm">relevant
realm</span>, which is roughly the <span>realm</span> in which it was created. When writing
algorithms, the most prominent <span>platform object</span> whose <span
data-x="concept-relevant-realm">relevant realm</span> might be important is the <b>this</b>
value of the currently-running function object. In some cases, there can be other important
<span data-x="concept-relevant-realm">relevant realms</span>, such as those of any
arguments.</dd>
</dl>
<p>Note how the <span data-x="concept-entry-everything">entry</span>, <span
data-x="concept-incumbent-everything">incumbent</span>, and <span
data-x="concept-current-everything">current</span> concepts are usable without qualification,
whereas the <span data-x="concept-relevant-everything">relevant</span> concept must be applied to
a particular <span>platform object</span>.</p>
<p class="warning">The <span data-x="concept-incumbent-everything">incumbent</span> and <span
data-x="concept-entry-everything">entry</span> concepts should not be used by new specifications,
as they are excessively complicated and unintuitive to work with. We are working to remove almost
all existing uses from the platform: see <a
href="https://github.com/whatwg/html/issues/1430">issue #1430</a> for <span
data-x="concept-incumbent-everything">incumbent</span>, and <a
href="https://github.com/whatwg/html/issues/1431">issue #1431</a> for <span
data-x="concept-entry-everything">entry</span>.</p>
<p>In general, web platform specifications should use the <span
data-x="concept-relevant-everything">relevant</span> concept, applied to the object being operated
on (usually the <b>this</b> value of the current method). This mismatches the JavaScript
specification, where <span data-x="concept-current-everything">current</span> is generally used as
the default (e.g., in determining the <span>realm</span> whose <code data-x="">Array</code>
constructor should be used to construct the result in <code data-x="">Array.prototype.map</code>).
But this inconsistency is so embedded in the platform that we have to accept it going forward.</p>
<div class="example">
<p>Consider the following pages, with <code data-x="">a.html</code> being loaded in a browser
window, <code data-x="">b.html</code> being loaded in an <code>iframe</code> as shown, and <code
data-x="">c.html</code> and <code data-x="">d.html</code> omitted (they can simply be empty
documents):</p>
<pre><code class="html"><!-- a.html -->
<!DOCTYPE html>
<html lang="en">
<title>Entry page</title>
<iframe src="b.html"></iframe>
<button onclick="frames[0].hello()">Hello</button>
<!--b.html -->
<!DOCTYPE html>
<html lang="en">
<title>Incumbent page</title>
<iframe src="c.html" id="c"></iframe>
<iframe src="d.html" id="d"></iframe>
<script>
const c = document.querySelector("#c").contentWindow;
const d = document.querySelector("#d").contentWindow;
window.hello = () => {
c.print.call(d);
};
</script></code></pre>
<p>Each page has its own <span>browsing context</span>, and thus its own <span>realm</span>,
<span>global object</span>, and <span>environment settings object</span>.</p>
<p>When the <code data-x="dom-print">print()</code> method is called in response to pressing the
button in <code data-x="">a.html</code>, then:</p>
<ul>
<li><p>The <span data-x="concept-entry-realm">entry realm</span> is that of <code
data-x="">a.html</code>.</p></li>
<li><p>The <span data-x="concept-incumbent-realm">incumbent realm</span> is that of <code
data-x="">b.html</code>.</p></li>
<li><p>The <span>current realm</span> is that of <code data-x="">c.html</code> (since it is the
<code data-x="dom-print">print()</code> method from <code data-x="">c.html</code> whose code is
running).</p></li>
<li><p>The <span data-x="concept-relevant-realm">relevant realm</span> of the object on which
the <code data-x="dom-print">print()</code> method is being called is that of <code
data-x="">d.html</code>.</p></li>
</ul>
</div>
<div class="example">
<p>One reason why the <span data-x="concept-relevant-everything">relevant</span> concept is
generally a better default choice than the <span
data-x="concept-current-everything">current</span> concept is that it is more suitable for
creating an object that is to be persisted and returned multiple times. For example, the <code
data-x="dom-navigator-getBattery">navigator.getBattery()</code> method creates promises in the
<span data-x="concept-relevant-realm">relevant realm</span> for the <code>Navigator</code> object
on which it is invoked. This has the following impact: <ref>BATTERY</ref>
<pre><code class="html"><!-- outer.html -->
<!DOCTYPE html>
<html lang="en">
<title>Relevant realm demo: outer page</title>
<script>
function doTest() {
const promise = navigator.getBattery.call(frames[0].navigator);
console.log(promise instanceof Promise); // logs false
console.log(promise instanceof frames[0].Promise); // logs true
frames[0].hello();
}
</script>
<iframe src="inner.html" onload="doTest()"></iframe>
<!-- inner.html -->
<!DOCTYPE html>
<html lang="en">
<title>Relevant realm demo: inner page</title>
<script>
function hello() {
const promise = navigator.getBattery();
console.log(promise instanceof Promise); // logs true
console.log(promise instanceof parent.Promise); // logs false
}
</script></code></pre>
<p>If the algorithm for the <code data-x="dom-navigator-getBattery">getBattery()</code> method
had instead used the <span>current realm</span>, all the results would be reversed. That is,
after the first call to <code data-x="dom-navigator-getBattery">getBattery()</code> in <code
data-x="">outer.html</code>, the <code>Navigator</code> object in <code
data-x="">inner.html</code> would be permanently storing a <code data-x="">Promise</code> object
created in <code data-x="">outer.html</code>'s <span>realm</span>, and calls like that inside the
<code data-x="">hello()</code> function would thus return a promise from the "wrong" realm. Since
this is undesirable, the algorithm instead uses the <span
data-x="concept-relevant-realm">relevant realm</span>, giving the sensible results indicated in
the comments above.</p>
</div>
<hr>
<p>The rest of this section deals with formally defining the <span
data-x="concept-entry-everything">entry</span>, <span
data-x="concept-incumbent-everything">incumbent</span>, <span
data-x="concept-current-everything">current</span>, and <span
data-x="concept-relevant-everything">relevant</span> concepts.</p>
<h6>Entry</h6>
<p>The process of <a href="#calling-scripts">calling scripts</a> will push or pop <span
data-x="realm execution context">realm execution contexts</span> onto the <span>JavaScript
execution context stack</span>, interspersed with other <span data-x="JavaScript execution
context">execution contexts</span>.</p>
<p>With this in hand, we define the <dfn>entry execution context</dfn> to be the most recently
pushed item in the <span>JavaScript execution context stack</span> that is a <span data-x="realm
execution context">realm execution context</span>. The <dfn data-x="concept-entry-realm">entry
realm</dfn> is the <span>entry execution context</span>'s Realm component.</p>
<p>Then, the <dfn>entry settings object</dfn> is the <span
data-x="concept-realm-settings-object">environment settings object</span> of the <span
data-x="concept-entry-realm">entry realm</span>.</p>
<p>Similarly, the <dfn>entry global object</dfn> is the <span
data-x="concept-realm-global">global object</span> of the <span data-x="concept-entry-realm">entry
realm</span>.</p>
<h6>Incumbent</h6>
<p>All <span data-x="JavaScript execution context">JavaScript execution contexts</span> must
contain, as part of their code evaluation state, a <dfn>skip-when-determining-incumbent
counter</dfn> value, which is initially zero. In the process of <span data-x="prepare to run a
callback">preparing to run a callback</span> and <span data-x="clean up after running a
callback">cleaning up after running a callback</span>, this value will be incremented and
decremented.</p>
<p>Every <span>event loop</span> has an associated <dfn>backup incumbent settings object
stack</dfn>, initially empty. Roughly speaking, it is used to determine the <span>incumbent
settings object</span> when no author code is on the stack, but author code is responsible for the
current algorithm having been run in some way. The process of <span data-x="prepare to run a
callback">preparing to run a callback</span> and <span data-x="clean up after running a
callback">cleaning up after running a callback</span> manipulate this stack. <ref>WEBIDL</ref></p>
<p>When Web IDL is used to <span data-x="es-invoking-callback-functions">invoke</span> author
code, or when <span>HostEnqueuePromiseJob</span> invokes a promise job, they use the following
algorithms to track relevant data for determining the <span>incumbent settings object</span>:</p>
<p>To <dfn export>prepare to run a callback</dfn> with an <span>environment settings object</span>
<var>settings</var>:</p>
<ol>
<li><p>Push <var>settings</var> onto the <span>backup incumbent settings object
stack</span>.</p></li>
<li><p>Let <var>context</var> be the <span>topmost script-having execution
context</span>.</p></li>
<li><p>If <var>context</var> is not null, increment <var>context</var>'s
<span>skip-when-determining-incumbent counter</span>.</p></li>
</ol>
<p>To <dfn export>clean up after running a callback</dfn> with an <span>environment settings
object</span> <var>settings</var>:</p>
<ol>
<li>
<p>Let <var>context</var> be the <span>topmost script-having execution context</span>.</p>
<p class="note">This will be the same as the <span>topmost script-having execution
context</span> inside the corresponding invocation of <span>prepare to run a
callback</span>.</p>
</li>
<li><p>If <var>context</var> is not null, decrement <var>context</var>'s
<span>skip-when-determining-incumbent counter</span>.</p></li>
<li><p><span>Assert</span>: the topmost entry of the <span>backup incumbent settings object
stack</span> is <var>settings</var>.</p></li>
<li><p>Remove <var>settings</var> from the <span>backup incumbent settings object
stack</span>.</p></li>
</ol>
<p>Here, the <dfn>topmost script-having execution context</dfn> is the topmost entry of the
<span>JavaScript execution context stack</span> that has a non-null ScriptOrModule component, or
null if there is no such entry in the <span>JavaScript execution context stack</span>.</p>
<p>With all this in place, the <dfn export>incumbent settings object</dfn> is determined as
follows:</p>
<ol>
<li><p>Let <var>context</var> be the <span>topmost script-having execution
context</span>.</p></li>
<li>
<p>If <var>context</var> is null, or if <var>context</var>'s
<span>skip-when-determining-incumbent counter</span> is greater than zero, then:</p>
<ol>
<li>
<p><span>Assert</span>: the <span>backup incumbent settings object stack</span> is not
empty.</p>
<p class="note">This assert would fail if you try to obtain the <span>incumbent settings
object</span> from inside an algorithm that was triggered neither by <a
href="#calling-scripts">calling scripts</a> nor by Web IDL <span
data-x="es-invoking-callback-functions">invoking</span> a callback. For example, it would
trigger if you tried to obtain the <span>incumbent settings object</span> inside an algorithm
that ran periodically as part of the <span>event loop</span>, with no involvement of author
code. In such cases the <span data-x="concept-incumbent-everything">incumbent</span> concept
cannot be used.</p>
</li>
<li><p>Return the topmost entry of the <span>backup incumbent settings object
stack</span>.</p></li>
</ol>
</li>
<li><p>Return <var>context</var>'s Realm component's <span
data-x="concept-realm-settings-object">settings object</span>.</p></li>
</ol>
<p>Then, the <dfn export data-x="concept-incumbent-realm">incumbent realm</dfn> is the <span
data-x="environment settings object's realm">realm</span> of the <span>incumbent settings
object</span>.</p>
<p>Similarly, the <dfn export data-x="concept-incumbent-global">incumbent global object</dfn> is
the <span data-x="concept-settings-object-global">global object</span> of the <span>incumbent
settings object</span>.</p>
<hr>
<p>The following series of examples is intended to make it clear how all of the different
mechanisms contribute to the definition of the <a href="#incumbent">incumbent</a> concept:</p>
<div class="example" id="example-incumbent-1">
<p>Consider the following starter example:</p>
<pre><code class="html"><!DOCTYPE html>
<iframe></iframe>
<script>
frames[0].postMessage("some data", "*");
</script></code></pre>
<p>There are two interesting <span data-x="environment settings object">environment settings
objects</span> here: that of <code data-x="">window</code>, and that of <code
data-x="">frames[0]</code>. Our concern is: what is the <span>incumbent settings object</span> at
the time that the algorithm for <code data-x="dom-window-postMessage">postMessage()</code>
executes?</p>
<p>It should be that of <code data-x="">window</code>, to capture the intuitive notion that the
author script responsible for causing the algorithm to happen is executing in <code
data-x="">window</code>, not <code data-x="">frames[0]</code>. This makes sense: the <span>window
post message steps</span> use the <span>incumbent settings object</span> to determine the <code
data-x="dom-MessageEvent-source">source</code> property of the resulting
<code>MessageEvent</code>, and in this case <code data-x="">window</code> is definitely the
source of the message.</p>
<p>Let us now explain how the steps given above give us our intuitively-desired result of <code
data-x="">window</code>'s <span>relevant settings object</span>.</p>
<p>When the <span>window post message steps</span> look up the <span>incumbent settings
object</span>, the <span>topmost script-having execution context</span> will be that
corresponding to the <code>script</code> element: it was pushed onto the <span>JavaScript
execution context stack</span> as part of <span
data-x="js-ScriptEvaluation">ScriptEvaluation</span> during the <span>run a classic script</span>
algorithm. Since there are no Web IDL callback invocations involved, the context's
<span>skip-when-determining-incumbent counter</span> is zero, so it is used to determine the
<span>incumbent settings object</span>; the result is the <span>environment settings
object</span> of <code data-x="">window</code>.</p>
<p>(Note how the <span>environment settings object</span> of <code data-x="">frames[0]</code> is
the <span>relevant settings object</span> of <span>this</span> at the time the <code
data-x="dom-window-postMessage">postMessage()</code> method is called, and thus is involved in
determining the <em>target</em> of the message. Whereas the incumbent is used to determine the
<em>source</em>.)
</div>
<div class="example" id="example-incumbent-2">
<p>Consider the following more complicated example:</p>
<pre><code class="html"><!DOCTYPE html>
<iframe></iframe>
<script>
const bound = frames[0].postMessage.bind(frames[0], "some data", "*");
window.setTimeout(bound);
</script></code></pre>
<p>This example is very similar to the previous one, but with an extra indirection through <code
data-x="">Function.prototype.bind</code> as well as <code
data-x="dom-setTimeout">setTimeout()</code>. But, the answer should be the same: invoking
algorithms asynchronously should not change the <span
data-x="concept-incumbent-everything">incumbent</span> concept.</p>
<p>This time, the result involves more complicated mechanisms:</p>
<p>When <code data-x="">bound</code> is <span data-x="concept-idl-convert">converted</span> to a
Web IDL callback type, the <span>incumbent settings object</span> is that corresponding to <code
data-x="">window</code> (in the same manner as in our starter example above). Web IDL stores this
as the resulting callback value's <span>callback context</span>.</p>
<p>When the <span data-x="concept-task">task</span> posted by <code
data-x="dom-setTimeout">setTimeout()</code> executes, the algorithm for that task uses Web IDL to
<span data-x="es-invoking-callback-functions">invoke</span> the stored callback value. Web IDL in
turn calls the above <span>prepare to run a callback</span> algorithm. This pushes the stored
<span>callback context</span> onto the <span>backup incumbent settings object stack</span>. At
this time (inside the timer task) there is no author code on the stack, so the <span>topmost
script-having execution context</span> is null, and nothing gets its
<span>skip-when-determining-incumbent counter</span> incremented.</p>
<p>Invoking the callback then calls <code data-x="">bound</code>, which in turn calls
the <code data-x="dom-window-postMessage">postMessage()</code> method of <code
data-x="">frames[0]</code>. When the <code data-x="dom-window-postMessage">postMessage()</code>
algorithm looks up the <span>incumbent settings object</span>, there is still no author code on
the stack, since the bound function just directly calls the built-in method. So the
<span>topmost script-having execution context</span> will be null: the <span>JavaScript execution
context</span> stack only contains an execution context corresponding to <code
data-x="dom-window-postMessage">postMessage()</code>, with no <span
data-x="js-ScriptEvaluation">ScriptEvaluation</span> context or similar below it.</p>
<p>This is where we fall back to the <span>backup incumbent settings object stack</span>. As
noted above, it will contain as its topmost entry the <span>relevant settings object</span> of
<code data-x="">window</code>. So that is what is used as the <span>incumbent settings
object</span> while executing the <code data-x="dom-window-postMessage">postMessage()</code>
algorithm.</p>
</div>
<div class="example" id="example-incumbent-3">
<p>Consider this final, even more convoluted example:</p>
<pre><code class="html"><!-- a.html -->
<!DOCTYPE html>
<button>click me</button>
<iframe></iframe>
<script>
const bound = frames[0].location.assign.bind(frames[0].location, "https://example.com/");
document.querySelector("button").addEventListener("click", bound);
</script></code></pre>
<pre><code class="html"><!-- b.html -->
<!DOCTYPE html>
<iframe src="a.html"></iframe>
<script>
const iframe = document.querySelector("iframe");
iframe.onload = function onLoad() {
iframe.contentWindow.document.querySelector("button").click();
};
</script></code></pre>
<p>Again there are two interesting <span data-x="environment settings object">environment
settings objects</span> in play: that of <code data-x="">a.html</code>, and that of <code
data-x="">b.html</code>. When the <code data-x="dom-location-assign">location.assign()</code>
method triggers the <span><code>Location</code>-object navigate</span> algorithm, what will be
the <span>incumbent settings object</span>? As before, it should intuitively be that of <code
data-x="">a.html</code>: the <code data-x="event-click">click</code> listener was originally
scheduled by <code data-x="">a.html</code>, so even if something involving <code
data-x="">b.html</code> causes the listener to fire, the <span
data-x="concept-incumbent-everything">incumbent</span> responsible is that of <code
data-x="">a.html</code>.</p>
<p>The callback setup is similar to the previous example: when <code data-x="">bound</code> is
<span data-x="concept-idl-convert">converted</span> to a Web IDL callback type, the
<span>incumbent settings object</span> is that corresponding to <code data-x="">a.html</code>,
which is stored as the callback's <span>callback context</span>.</p>
<p>When the <code data-x="dom-click">click()</code> method is called inside <code
data-x="">b.html</code>, it <span data-x="concept-event-dispatch">dispatches</span> a <code
data-x="event-click">click</code> event on the button that is inside <code
data-x="">a.html</code>. This time, when the <span>prepare to run a callback</span> algorithm
executes as part of event dispatch, there <em>is</em> author code on the stack; the <span>topmost
script-having execution context</span> is that of the <code data-x="">onLoad</code> function,
whose <span>skip-when-determining-incumbent counter</span> gets incremented. Additionally, <code
data-x="">a.html</code>'s <span>environment settings object</span> (stored as the
<code>EventHandler</code>'s <span>callback context</span>) is pushed onto the
<span>backup incumbent settings object stack</span>.</p>
<p>Now, when the <span><code>Location</code>-object navigate</span> algorithm looks up the
<span>incumbent settings object</span>, the <span>topmost script-having execution
context</span> is still that of the <code data-x="">onLoad</code> function (due to the fact we
are using a bound function as the callback). Its <span>skip-when-determining-incumbent
counter</span> value is one, however, so we fall back to the <span>backup incumbent settings
object stack</span>. This gives us the <span>environment settings object</span> of <code
data-x="">a.html</code>, as expected.</p>
<p>Note that this means that even though it is the <code>iframe</code> inside <code
data-x="">a.html</code> that navigates, it is <code data-x="">a.html</code> itself that is used
as the source <code>Document</code>, which determines among other things the <span
data-x="concept-request-client">request client</span>. This is <a
href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=26603#c36">perhaps the only justifiable use
of the incumbent concept on the web platform</a>; in all other cases the consequences of using it
are simply confusing and we hope to one day switch them to use <span
data-x="concept-current-everything">current</span> or <span
data-x="concept-relevant-everything">relevant</span> as appropriate.</p>
</div>
<h6>Current</h6>
<p>The JavaScript specification defines the <span>current realm</span>, also known as the "current
Realm Record". <ref>JAVASCRIPT</ref></p>
<p>Then, the <dfn export>current settings object</dfn> is the <span
data-x="concept-realm-settings-object">environment settings object</span> of the <span>current
realm</span>.</p>
<p>Similarly, the <dfn export>current global object</dfn> is the <span
data-x="concept-realm-global">global object</span> of the <span>current realm</span>.</p>
<h6>Relevant</h6>
<p>The <dfn export data-x="concept-relevant-realm">relevant realm</dfn> for a <span>platform
object</span> is the value of <span data-x="[[Realm]] field of a platform object">its [[Realm]]
field</span>.</p>
<p>Then, the <dfn export>relevant settings object</dfn> for a <span>platform object</span>
<var>o</var> is the <span data-x="concept-realm-settings-object">environment settings
object</span> of the <span data-x="concept-relevant-realm">relevant realm</span> for
<var>o</var>.</p>
<p>Similarly, the <dfn export id="concept-relevant-global">relevant global object</dfn> for a
<span>platform object</span> <var>o</var> is the <span data-x="concept-realm-global">global
object</span> of the <span data-x="concept-relevant-realm">relevant realm</span> for
<var>o</var>.</p>
<h5>Enabling and disabling scripting</h5>
<p id="concept-bc-script"><dfn data-x="concept-environment-script">Scripting is enabled</dfn> for
an <span>environment settings object</span> <var>settings</var> when all of the following
conditions are true:</p>
<ul>
<li>The user agent supports scripting.</li>
<li>
<!--INSERT TRACKING-->
The user has not disabled scripting for <var>settings</var> at this time. (User agents may
provide users with the option to disable scripting globally, or in a finer-grained manner, e.g.,
on a per-origin basis, down to the level of individual <span data-x="environment settings
object">environment settings objects</span>.)</li>
<li id="sandboxScriptBlocked">Either <var>settings</var>'s <span
data-x="concept-settings-object-global">global object</span> is not a <code>Window</code> object,
or <var>settings</var>'s <span data-x="concept-settings-object-global">global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>'s <span>active
sandboxing flag set</span> does not have its <span>sandboxed scripts browsing context flag</span>
set.</li>
</ul>
<p id="concept-bc-noscript"><dfn data-x="concept-environment-noscript">Scripting is disabled</dfn>
for an <span>environment settings object</span> when scripting is not <span
data-x="concept-environment-script">enabled</span> for it, i.e., when any of the above conditions
are false.</p>
<hr>
<p><dfn data-x="concept-n-script">Scripting is enabled</dfn> for a node <var>node</var> if
<var>node</var>'s <span>node document</span>'s <span data-x="concept-document-bc">browsing
context</span> is non-null, and <span data-x="concept-environment-script">scripting is
enabled</span> for <var>node</var>'s <span>relevant settings object</span>.</p>
<p><dfn data-x="concept-n-noscript">Scripting is disabled</dfn> for a node when scripting is not
<span data-x="concept-n-script">enabled</span>, i.e., when its <span>node document</span>'s <span
data-x="concept-document-bc">browsing context</span> is null or when <span
data-x="concept-environment-noscript">scripting is disabled</span> for its <span>relevant settings
object</span>.</p>
<h5>Secure contexts</h5>
<p>An <span>environment</span> <var>environment</var> is a <dfn export data-lt="secure context|Is
an environment settings object contextually secure?">secure context</dfn> if the following
algorithm returns true:</p>
<ol>
<li>
<p>If <var>environment</var> is an <span>environment settings object</span>, then:</p>
<ol>
<li><p>Let <var>global</var> be <var>environment</var>'s <span
data-x="concept-settings-object-global">global object</span>.</p></li>
<li>
<p>If <var>global</var> is a <code>WorkerGlobalScope</code>, then:
<ol>
<li>
<p>If <var>global</var>'s <span>owner set</span>[0]'s <span>relevant settings object</span>
is a <span>secure context</span>, then return true.</p>
<p class="note">We only need to check the 0th item since they will necessarily all be
consistent.</p>
</li>
<li><p>Return false.</p></li>
</ol>
</li>
<li>
<p>If <var>global</var> is a <code>WorkletGlobalScope</code>, then return true.</p>
<p class="note">Worklets can only be created in secure contexts.</p>
</li>
</ol>
</li>
<li><p>If the result of <span>Is url potentially trustworthy?</span> given
<var>environment</var>'s <span>top-level creation URL</span> is "<code data-x="">Potentially
Trustworthy</code>", then return true.</p></li>
<li><p>Return false.</p></li>
</ol>
<p>An <span>environment</span> is a <dfn export>non-secure context</dfn> if it is not a
<span>secure context</span>.</p>
</div>
<h4 id="scripting-processing-model"><span id="processing-model-7"></span>Script processing
model</h4>
<div w-nodev>
<h5 id="script-structs"><span id="definitions-2"></span>Scripts</h5>
<p>A <dfn data-x="concept-script" export>script</dfn> is one of two possible <span
data-x="struct">structs</span> (namely, a <span>classic script</span> or a
<span>module script</span>). All scripts have:</p>
<dl>
<dt>A <dfn for="script" export data-x="concept-script-settings-object"
id="settings-object">settings object</dfn></dt>
<dd><p>An <span>environment settings object</span>, containing various settings that are shared
with other <span data-x="concept-script">scripts</span> in the same context.</p></dd>
<dt>A <dfn for="script" export data-x="concept-script-record">record</dfn></dt>
<dd>
<p>One of the following:</p>
<ul>
<li><p>a <span>script record</span>, for <span data-x="classic script">classic
scripts</span>;</p></li>
<li><p>a <span>Source Text Module Record</span>, for <span data-x="JavaScript module
script">JavaScript module scripts</span>;</p></li>
<li><p>a <span>Synthetic Module Record</span>, for <span data-x="CSS module script">CSS module
scripts</span> and <span data-x="JSON module script">JSON module scripts</span>;</p></li>
<li><p>a <span>WebAssembly Module Record</span>, for <span data-x="WebAssembly module
script">WebAssembly module scripts</span>; or</p></li>
<li><p>null, representing a parsing failure.</p></li>
</ul>
</dd>
<dt>A <dfn for="script" data-x="concept-script-parse-error">parse error</dfn></dt>
<dd>
<p>A JavaScript value, which has meaning only if the <span
data-x="concept-script-record">record</span> is null, indicating that the corresponding script
source text could not be parsed.</p>
<p class="note">This value is used for internal tracking of immediate parse errors when <a
href="#creating-scripts">creating scripts</a>, and is not to be used directly. Instead, consult
the <span data-x="concept-script-error-to-rethrow">error to rethrow</span> when determining
"what went wrong" for this script.</p>
</dd>
<dt>An <dfn for="script" export data-x="concept-script-error-to-rethrow">error
to rethrow</dfn></dt>
<dd>
<p>A JavaScript value representing an error that will prevent evaluation from succeeding. It
will be re-thrown by any attempts to <a href="#calling-scripts">run</a> the script.</p>
<p class="note">This could be the script's <span data-x="concept-script-parse-error">parse
error</span>, but in the case of a <span>module script</span> it could instead be the
<span data-x="concept-script-parse-error">parse error</span> from one of its dependencies, or
an error from <span>resolve a module specifier</span>.</p>
<p class="note">Since this exception value is provided by the JavaScript specification, we know
that it is never null, so we use null to signal that no error has occurred.</p>
</dd>
<dt><dfn for="script" export
data-x="concept-script-script-fetch-options">Fetch options</dfn></dt>
<dd>Null or a <span>script fetch options</span>, containing various options related to fetching
this script or <span data-x="module script">module scripts</span> that it imports.</dd>
<dt>A <dfn for="script" export data-x="concept-script-base-url">base
URL</dfn></dt>
<dd><p>Null or a base <span>URL</span> used for <span data-x="resolve a module
specifier">resolving module specifiers</span>. When non-null, this will either be the URL from
which the script was obtained, for external scripts, or the <span>document base URL</span> of the
containing document, for inline scripts.</p></dd>
</dl>
<p>A <dfn export>classic script</dfn> is a type of <span data-x="concept-script">script</span>
that has the following additional <span data-x="struct item">item</span>:</p>
<dl>
<dt>A <dfn>muted errors</dfn> boolean</dt>
<dd><p>A boolean which, if true, means that error information will not be provided for errors in
this script. This is used to mute errors for cross-origin scripts, since that can leak private
information.</p></dd>
</dl>
<p>A <dfn export>module script</dfn> is another type of <span
data-x="concept-script">script</span>. It has no additional <span data-x="struct
item">items</span>.</p>
<p><span data-x="module script">Module scripts</span> can be classified into four types:</p>
<ul>
<li><p>A <span>module script</span> is a <dfn export>JavaScript module script</dfn> if
its <span data-x="concept-script-record">record</span> is a <span>Source Text Module
Record</span>.</p></li>
<li>
<p>A <span>module script</span> is a <dfn export>CSS module script</dfn> if its <span
data-x="concept-script-record">record</span> is a <span>Synthetic Module Record</span>, and it
was created via the <span data-x="creating a CSS module script">create a CSS module
script</span> algorithm. CSS module scripts represent a parsed CSS stylesheet.</p>
<!--
This definition is not super-rigorous, but it doesn't need to be for now. If we ever start
testing if something is a CSS module script in algorithms, instead of just referring to the
concept, then we should consider adding a type item to the module script struct.
-->
</li>
<li>
<p>A <span>module script</span> is a <dfn export>JSON module script</dfn> if its <span
data-x="concept-script-record">record</span> is a <span>Synthetic Module Record</span>, and it
was created via the <span data-x="creating a JSON module script">create a JSON module
script</span> algorithm. JSON module scripts represent a parsed JSON document.</p>
<!--
This definition is not super-rigorous, but it doesn't need to be for now. If we ever start
testing if something is a JSON module script in algorithms, instead of just referring to the
concept, then we should consider adding a type item to the module script struct.
-->
</li>
<li>
<p>A <span>module script</span> is a <dfn export>WebAssembly module script</dfn> if
its <span data-x="concept-script-record">record</span> is a <span>WebAssembly Module
Record</span>.</p>
</li>
</ul>
<p class="note">As CSS stylesheets and JSON documents do not import dependent modules, and do not
throw exceptions on evaluation, the <span data-x="concept-script-script-fetch-options">fetch
options</span> and <span data-x="concept-script-base-url">base URL</span> of <span data-x="CSS
module script">CSS module scripts</span> and <span data-x="JSON module script">JSON module
scripts</span> and are always null.</p>
<p>The <dfn>active script</dfn> is determined by the following algorithm:</p>
<ol>
<li><p>Let <var>record</var> be <span>GetActiveScriptOrModule</span>().</p></li>
<li><p>If <var>record</var> is null, return null.</p></li>
<li><p>Return <var>record</var>.[[HostDefined]].</p></li>
</ol>
<p class="note">The <span>active script</span> concept is so far only used by the
<code>import()</code> feature, to determine the <span data-x="concept-script-base-url">base
URL</span> to use for resolving relative module specifiers.</p>
<h5 id="fetching-scripts">Fetching scripts</h5>
<p>This section introduces a number of algorithms for fetching scripts, taking various necessary
inputs and resulting in <span data-x="classic script">classic</span> or <span data-x="module
script">module scripts</span>.</p>
<hr>
<p><dfn>Script fetch options</dfn> is a <span>struct</span> with the following <span
data-x="struct item">items</span>:</p>
<dl>
<dt><dfn data-x="concept-script-fetch-options-nonce">cryptographic nonce</dfn></dt>
<dd><p>The <span data-x="concept-request-nonce-metadata">cryptographic nonce metadata</span> used
for the initial fetch and for fetching any imported modules</p></dd>
<dt><dfn data-x="concept-script-fetch-options-integrity">integrity metadata</dfn></dt>
<dd><p>The <span data-x="concept-request-integrity-metadata">integrity metadata</span> used for
the initial fetch</dd>
<dt><dfn data-x="concept-script-fetch-options-parser">parser metadata</dfn></dt>
<dd><p>The <span data-x="concept-request-parser-metadata">parser metadata</span> used for the
initial fetch and for fetching any imported modules</p></dd>
<dt><dfn data-x="concept-script-fetch-options-credentials">credentials mode</dfn></dt>
<dd><p>The <span data-x="concept-request-credentials-mode">credentials mode</span> used for the
initial fetch (for <span data-x="module script">module scripts</span>) and for fetching any
imported modules (for both <span data-x="module script">module scripts</span> and <span
data-x="classic script">classic scripts</span>)</p></dd>
<dt><dfn data-x="concept-script-fetch-options-referrer-policy">referrer policy</dfn></dt>
<dd>
<p>The <span data-x="concept-request-referrer-policy">referrer policy</span> used for the
initial fetch and for fetching any imported modules</p>
<p class="note">This policy can mutate after a <span>module script</span>'s <span
data-x="concept-response">response</span> is received, to be the <span>referrer policy</span>
<span data-x="parse-referrer-policy-header">parsed</span> from the <span
data-x="concept-response">response</span>, and used when fetching any module dependencies.</p>
</dd>
<dt><dfn data-x="concept-script-fetch-options-render-blocking">render-blocking</dfn></dt>
<dd><p>The boolean value of <span data-x="concept-request-render-blocking">render-blocking</span>
used for the initial fetch and for fetching any imported modules. Unless otherwise stated, its
value is false.</p></dd>
<dt><dfn data-x="concept-script-fetch-options-fetch-priority">fetch priority</dfn></dt>
<dd><p>The <span data-x="concept-request-priority">priority</span> used for the
initial fetch</p></dd>
</dl>
<p class="note">Recall that via the <code>import()</code> feature, <span data-x="classic
script">classic scripts</span> can import <span data-x="module script">module scripts</span>.</p>
<p>The <dfn>default script fetch options</dfn> are a <span>script fetch options</span> whose <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is the empty string, <span
data-x="concept-script-fetch-options-integrity">integrity metadata</span> is the empty string,
<span data-x="concept-script-fetch-options-parser">parser metadata</span> is "<code
data-x="">not-parser-inserted</code>", <span
data-x="concept-script-fetch-options-credentials">credentials mode</span> is "<code
data-x="">same-origin</code>", <span
data-x="concept-script-fetch-options-referrer-policy">referrer policy</span> is the empty
string, and <span data-x="concept-script-fetch-options-fetch-priority">fetch priority</span>
is "<code data-x="">auto</code>".</p>
<p>Given a <span data-x="concept-request">request</span> <var>request</var> and a <span>script
fetch options</span> <var>options</var>, we define:</p>
<dl>
<dt><dfn>set up the classic script request</dfn></dt>
<dd><p>Set <var>request</var>'s <span data-x="concept-request-nonce-metadata">cryptographic nonce
metadata</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span>, its <span
data-x="concept-request-integrity-metadata">integrity metadata</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-integrity">integrity metadata</span>, its <span
data-x="concept-request-parser-metadata">parser metadata</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-parser">parser metadata</span>, its <span
data-x="concept-request-referrer-policy">referrer policy</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-referrer-policy">referrer policy</span>, its
<span data-x="concept-request-render-blocking">render-blocking</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-render-blocking">render-blocking</span>, and its
<span data-x="concept-request-priority">priority</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-fetch-priority">fetch priority</span>.</p></dd>
<dt><dfn>set up the module script request</dfn></dt>
<dd><p>Set <var>request</var>'s <span data-x="concept-request-nonce-metadata">cryptographic nonce
metadata</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span>, its <span
data-x="concept-request-integrity-metadata">integrity metadata</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-integrity">integrity metadata</span>, its <span
data-x="concept-request-parser-metadata">parser metadata</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-parser">parser metadata</span>, its <span
data-x="concept-request-credentials-mode">credentials mode</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-credentials">credentials mode</span>, its <span
data-x="concept-request-referrer-policy">referrer policy</span> to <var>options</var>'s <span
data-x="concept-script-fetch-options-referrer-policy">referrer policy</span>, its
<span data-x="concept-request-render-blocking">render-blocking</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-render-blocking">render-blocking</span>, and its
<span data-x="concept-request-priority">priority</span> to <var>options</var>'s
<span data-x="concept-script-fetch-options-fetch-priority">fetch priority</span>.</p></dd>
</dl>
<p>To <dfn>get the descendant script fetch options</dfn> given a <span>script fetch options</span>
<var>originalOptions</var>, a <span>URL</span> <var>url</var>, and an <span>environment settings
object</span> <var>settingsObject</var>:</p>
<ol>
<li><p>Let <var>newOptions</var> be a copy of <var>originalOptions</var>.</p></li>
<li><p>Let <var>integrity</var> be the result of <span>resolving a module integrity
metadata</span> with <var>url</var> and <var>settingsObject</var>.</p></li>
<li><p>Set <var>newOptions</var>'s <span
data-x="concept-script-fetch-options-integrity">integrity metadata</span> to
<var>integrity</var>.</p></li>
<li><p>Set <var>newOptions</var>'s <span
data-x="concept-script-fetch-options-fetch-priority">fetch priority</span> to "<code
data-x="">auto</code>".</p></li>
<li><p>Return <var>newOptions</var>.</p></li>
</ol>
<p>To <dfn data-x="resolving a module integrity metadata">resolve a module integrity
metadata</dfn>, given a <span>URL</span> <var>url</var> and an <span>environment settings
object</span> <var>settingsObject</var>:</p>
<ol>
<li><p>Let <var>map</var> be <var>settingsObject</var>'s <span
data-x="concept-settings-object-global">global object</span>'s <span
data-x="concept-global-import-map">import map</span>.</p></li>
<li><p>If <var>map</var>'s <span
data-x="concept-import-map-integrity">integrity</span>[<var>url</var>] does not <span
data-x="map exists">exist</span>, then return the empty string.</p></li>
<li><p>Return <var>map</var>'s <span
data-x="concept-import-map-integrity">integrity</span>[<var>url</var>].</p></li>
</ol>
<hr>
<p>Several of the below algorithms can be customized with a <dfn
data-x="fetching-scripts-perform-fetch" export for="fetching scripts">perform the fetch
hook</dfn> algorithm, which takes a <span data-x="concept-request">request</span>, a boolean <var
data-x="fetching-scripts-is-top-level">isTopLevel</var>, and a <dfn export for="fetching
scripts"><var
data-x="fetching-scripts-processCustomFetchResponse">processCustomFetchResponse</var></dfn>
algorithm. It runs <var
data-x="fetching-scripts-processCustomFetchResponse">processCustomFetchResponse</var> with a <span
data-x="concept-response">response</span> and either null (on failure) or a <span>byte
sequence</span> containing the response body. <dfn export for="fetching scripts"><var
data-x="fetching-scripts-is-top-level">isTopLevel</var></dfn> will be true for all <span>classic
script</span> fetches, and for the initial fetch when <span data-x="fetch an external module
script graph">fetching an external module script graph</span> or <span data-x="fetch a module
worker script graph">fetching a module worker script graph</span>, but false for the fetches
resulting from <code data-x="">import</code> statements encountered throughout the graph or from
<code data-x="">import()</code> expressions.</p>
<p>By default, not supplying a <span data-x="fetching-scripts-perform-fetch">perform the fetch
hook</span> will cause the below algorithms to simply <span data-x="concept-fetch">fetch</span>
the given <span data-x="concept-request">request</span>, with algorithm-specific customizations
to the <span data-x="concept-request">request</span> and validations of the resulting <span
data-x="concept-response">response</span>.</p>
<p>To layer your own customizations on top of these algorithm-specific ones, supply a <span
data-x="fetching-scripts-perform-fetch">perform the fetch hook</span> that modifies the given
<span data-x="concept-request">request</span>, <span data-x="concept-fetch">fetches</span> it,
and then performs specific validations of the resulting <span
data-x="concept-response">response</span> (completing with a <span>network error</span> if the
validations fail).</p>
<p>The hook can also be used to perform more subtle customizations, such as keeping a cache of
<span data-x="concept-response">responses</span> and avoiding performing a <span
data-x="concept-fetch">fetch</span> at all.</p>
<p class="note"><cite>Service Workers</cite> is an example of a specification that runs these
algorithms with its own options for the hook. <ref>SW</ref></p>
<hr>
<p>Now for the algorithms themselves.</p>
<p>To <dfn export>fetch a classic script</dfn> given a <span>URL</span> <var>url</var>, an
<span>environment settings object</span> <var>settingsObject</var>, a <span>script fetch
options</span> <var>options</var>, a <span data-x="CORS settings attribute">CORS settings
attribute state</span> <var>corsSetting</var>, an <span>encoding</span> <var>encoding</var>, and
an algorithm <var>onComplete</var>, run these steps. <var>onComplete</var> must be an algorithm
accepting null (on failure) or a <span>classic script</span> (on success).</p>
<ol>
<li><p>Let <var>request</var> be the result of <span data-x="create a potential-CORS
request">creating a potential-CORS request</span> given <var>url</var>, "<code
data-x="">script</code>", and <var>corsSetting</var>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to
<var>settingsObject</var>.</p>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to "<code data-x="">script</code>".</p>
<li><p><span>Set up the classic script request</span> given <var>request</var> and
<var>options</var>.</p></li>
<!--FETCH-->
<li>
<p><span data-x="concept-fetch">Fetch</span> <var>request</var> with
the following <i data-x="processResponseConsumeBody">processResponseConsumeBody</i> steps given
<span data-x="concept-response">response</span> <var>response</var> and null, failure, or a
<span>byte sequence</span> <var>bodyBytes</var>:</p>
<p class="note"><var>response</var> can be either <span>CORS-same-origin</span> or
<span>CORS-cross-origin</span>. This only affects how error reporting happens.</p>
<ol>
<li><p>Set <var>response</var> to <var>response</var>'s <span>unsafe response</span>.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>bodyBytes</var> is null or failure; or</p></li>
<li><p><var>response</var>'s <span data-x="concept-response-status">status</span> is not an
<span>ok status</span>,</p></li>
</ul>
<p>then run <var>onComplete</var> given null, and abort these steps.</p>
<p class="note">For historical reasons, this algorithm does not include MIME type checking,
unlike the other script-fetching algorithms in this section.</p>
</li>
<li><p>Let <var>potentialMIMETypeForEncoding</var> be the result of <span data-x="extract a
MIME type">extracting a MIME type</span> given <var>response</var>'s <span
data-x="concept-response-header-list">header list</span>.</p></li>
<li>
<p>Set <var>encoding</var> to the result of <span data-x="legacy extract an encoding">legacy
extracting an encoding</span> given <var>potentialMIMETypeForEncoding</var> and
<var>encoding</var>.</p>
<p class="note">This intentionally ignores the <span>MIME type essence</span>.</p>
</li>
<li>
<p>Let <var>sourceText</var> be the result of <span data-x="decode">decoding</span>
<var>bodyBytes</var> to Unicode, using <var>encoding</var> as the fallback encoding.</p>
<p class="note">The <span>decode</span> algorithm overrides <var>encoding</var> if the file
contains a BOM.</p>
</li>
<li><p>Let <var>mutedErrors</var> be true if <var>response</var> was
<span>CORS-cross-origin</span>, and false otherwise.</p></li>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> given
<var>sourceText</var>, <var>settingsObject</var>, <var>response</var>'s <span
data-x="concept-response-url">URL</span>, <var>options</var>,
<var>mutedErrors</var>, and <var>url</var>.</p></li>
<li>Run <var>onComplete</var> given <var>script</var>.</li>
</ol>
</li>
</ol>
<p>To <dfn export>fetch a classic worker script</dfn> given a <span>URL</span> <var>url</var>, an
<span>environment settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, an
<span>environment settings object</span> <var>settingsObject</var>, an algorithm
<var>onComplete</var>, and an optional <span data-x="fetching-scripts-perform-fetch">perform the
fetch hook</span> <var>performFetch</var>, run these steps. <var>onComplete</var> must be an
algorithm accepting null (on failure) or a <span>classic script</span> (on success).</p>
<ol>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is <var>fetchClient</var>, <span
data-x="concept-request-destination">destination</span> is <var>destination</var>, <span
data-x="concept-request-initiator-type">initiator type</span> is "<code data-x="">other</code>",
<span data-x="concept-request-mode">mode</span> is "<code data-x="">same-origin</code>", <span
data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">same-origin</code>", <span data-x="concept-request-parser-metadata">parser
metadata</span> is "<code data-x="">not parser-inserted</code>", and whose
<span>use-URL-credentials flag</span> is set.</p></li>
<!--FETCH-->
<li>
<p>If <var>performFetch</var> was given, run <var>performFetch</var> with <var>request</var>,
true, and with <var>processResponseConsumeBody</var> as defined below.</p>
<p>Otherwise, <span data-x="concept-fetch">fetch</span> <var>request</var> with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to
<var>processResponseConsumeBody</var> as defined below.</p>
<p>In both cases, let <var>processResponseConsumeBody</var> given <span
data-x="concept-response">response</span> <var>response</var> and null, failure, or a <span>byte
sequence</span> <var>bodyBytes</var> be the following algorithm:</p>
<ol>
<li><p>Set <var>response</var> to <var>response</var>'s <span>unsafe response</span>.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>bodyBytes</var> is null or failure; or</p></li>
<li><p><var>response</var>'s <span data-x="concept-response-status">status</span> is not an
<span>ok status</span>,</p></li>
</ul>
<p>then run <var>onComplete</var> given null, and abort these steps.</p>
</li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>response</var>'s <span data-x="concept-response-url">URL</span>'s <span
data-x="concept-url-scheme">scheme</span> is an <span>HTTP(S) scheme</span>; and</p></li>
<li><p>the result of <span data-x="extract a MIME type">extracting a MIME type</span> from
<var>response</var>'s <span data-x="concept-response-header-list">header list</span> is not
a <span>JavaScript MIME type</span>,</p>
</ul>
<p>then run <var>onComplete</var> given null, and abort these steps.</p>
<p class="note">Other <span data-x="fetch scheme">fetch schemes</span> are exempted from MIME
type checking for historical web-compatibility reasons. We might be able to tighten this in
the future; see <a href="https://github.com/whatwg/html/issues/3255">issue #3255</a>.</p>
</li>
<li><p>Let <var>sourceText</var> be the result of <span data-x="UTF-8 decode">UTF-8
decoding</span> <var>bodyBytes</var>.</p></li>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> using
<var>sourceText</var>, <var>settingsObject</var>, <var>response</var>'s <span
data-x="concept-response-url">URL</span>, and the <span>default script fetch
options</span>.</p></li>
<li><p>Run <var>onComplete</var> given <var>script</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn export>fetch a classic worker-imported script</dfn> given a <span>URL</span>
<var>url</var>, an <span>environment settings object</span> <var>settingsObject</var>, and an
optional <span data-x="fetching-scripts-perform-fetch">perform the fetch hook</span>
<var>performFetch</var>, run these steps. The algorithm will return a <span>classic script</span>
on success, or throw an exception on failure.</p>
<ol>
<li><p>Let <var>response</var> be null.</p></li>
<li><p>Let <var>bodyBytes</var> be null.</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose <span
data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-client">client</span> is <var>settingsObject</var>, <span
data-x="concept-request-destination">destination</span> is "<code data-x="">script</code>",
<span data-x="concept-request-initiator-type">initiator type</span> is "<code
data-x="">other</code>", <span data-x="concept-request-parser-metadata">parser metadata</span>
is "<code data-x="">not parser-inserted</code>", and whose <span>use-URL-credentials flag</span>
is set.</p></li>
<li>
<p>If <var>performFetch</var> was given, run <var>performFetch</var> with <var>request</var>,
<var>isTopLevel</var>, and with <var>processResponseConsumeBody</var> as defined below.</p>
<p>Otherwise, <span data-x="concept-fetch">fetch</span> <var>request</var> with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to
<var>processResponseConsumeBody</var> as defined below.</p>
<p>In both cases, let <var>processResponseConsumeBody</var> given <span
data-x="concept-response">response</span> <var>res</var> and null, failure, or a
<span>byte sequence</span> <var>bb</var> be the following algorithm:</p>
<ol>
<li><p>Set <var>bodyBytes</var> to <var>bb</var>.</p></li>
<li><p>Set <var>response</var> to <var>res</var>.</p></li>
</ol>
</li>
<li>
<p><span>Pause</span> until <var>response</var> is not null.</p>
<p class="note">Unlike other algorithms in this section, the fetching process is synchronous
here.</p>
</li>
<li><p>Set <var>response</var> to <var>response</var>'s <span>unsafe response</span>.</p></li>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>bodyBytes</var> is null or failure;</p></li>
<li><p><var>response</var>'s <span data-x="concept-response-status">status</span> is not an
<span>ok status</span>; or</p></li>
<li><p>the result of <span data-x="extract a MIME type">extracting a MIME type</span> from
<var>response</var>'s <span data-x="concept-response-header-list">header list</span> is not a
<span>JavaScript MIME type</span>,</p>
</ul>
<p>then throw a <span>"<code>NetworkError</code>"</span> <code>DOMException</code>.</p>
</li>
<li><p>Let <var>sourceText</var> be the result of <span data-x="UTF-8 decode">UTF-8
decoding</span> <var>bodyBytes</var>.</p></li>
<li><p>Let <var>mutedErrors</var> be true if <var>response</var> was
<span>CORS-cross-origin</span>, and false otherwise.</p></li>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> given
<var>sourceText</var>, <var>settingsObject</var>, <var>response</var>'s <span
data-x="concept-response-url">URL</span>, the <span>default script fetch options</span>, and
<var>mutedErrors</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p>To <dfn export id="fetch-a-module-script-tree">fetch an external module script graph</dfn>
given a <span>URL</span> <var>url</var>, an <span>environment settings object</span>
<var>settingsObject</var>, a <span>script fetch options</span> <var>options</var>, and an
algorithm <var>onComplete</var>, run these steps. <var>onComplete</var> must be an algorithm
accepting null (on failure) or a <span>module script</span> (on success).</p>
<ol>
<li>
<p><span>Fetch a single module script</span> given <var>url</var>, <var>settingsObject</var>,
"<code data-x="">script</code>", <var>options</var>, <var>settingsObject</var>, "<code
data-x="">client</code>", true, and with the following steps given <var>result</var>:</p>
<ol>
<li><p>If <var>result</var> is null, run <var>onComplete</var> given null, and abort these
steps.</p></li>
<li><p><span data-x="fetch the descendants of and link a module script">Fetch the descendants of
and link</span> <var>result</var> given <var>settingsObject</var>, "<code
data-x="">script</code>", and <var>onComplete</var>.</p></li>
</ol>
</li>
</ol>
<p>To <dfn>fetch a modulepreload module script graph</dfn> given a <span>URL</span> <var>url</var>,
a <span data-x="concept-request-destination">destination</span> <var>destination</var>, an
<span>environment settings object</span> <var>settingsObject</var>, a <span>script fetch
options</span> <var>options</var>, and an algorithm <var>onComplete</var>, run these steps.
<var>onComplete</var> must be an algorithm accepting null (on failure) or a <span>module
script</span> (on success).</p>
<ol>
<li>
<p><span>Fetch a single module script</span> given <var>url</var>, <var>settingsObject</var>,
<var>destination</var>, <var>options</var>, <var>settingsObject</var>, "<code
data-x="">client</code>", true, and with the following steps given <var>result</var>:</p>
<ol>
<li><p>Run <var>onComplete</var> given <var>result</var>.</p></li>
<li><p><span>Assert</span>: <var>settingsObject</var>'s <span
data-x="concept-settings-object-global">global object</span> implements
<code>Window</code>.</p></li>
<li>
<p>If <var>result</var> is not null, optionally <span data-x="fetch the descendants of and
link a module script">fetch the descendants of and link</span> <var>result</var> given
<var>settingsObject</var>, <var>destination</var>, and an empty algorithm.</p>
<p class="note">Generally, performing this step will be beneficial for performance, as it
allows pre-loading the modules that will invariably be requested later, via algorithms such as
<span>fetch an external module script graph</span> that fetch the entire graph. However, user
agents might wish to skip them in bandwidth-constrained situations, or situations where the
relevant fetches are already in flight.</p>
</li>
</ol>
</li>
</ol>
<p>To <dfn>fetch an inline module script graph</dfn> given a <span>string</span>
<var>sourceText</var>, a <span>URL</span> <var>baseURL</var>, an <span>environment settings
object</span> <var>settingsObject</var>, a <span>script fetch options</span> <var>options</var>,
and an algorithm <var>onComplete</var>, run these steps. <var>onComplete</var> must be an
algorithm accepting null (on failure) or a <span>module script</span> (on success).</p>
<ol>
<li><p>Let <var>script</var> be the result of <span>creating a JavaScript module script</span>
using <var>sourceText</var>, <var>settingsObject</var>, <var>baseURL</var>, and
<var>options</var>.</p></li>
<li><p><span data-x="fetch the descendants of and link a module script">Fetch the descendants of
and link</span> <var>script</var>, given <var>settingsObject</var>, "<code
data-x="">script</code>", and <var>onComplete</var>.</p></li>
</ol>
<p>To <dfn export id="fetch-a-module-worker-script-tree">fetch a module worker script graph</dfn>
given a <span>URL</span> <var>url</var>, an <span>environment settings object</span>
<var>fetchClient</var>, a <span data-x="concept-request-destination">destination</span>
<var>destination</var>, a <span data-x="concept-script-fetch-options-credentials">credentials
mode</span> <var>credentialsMode</var>, an <span>environment settings object</span>
<var>settingsObject</var>, and an algorithm <var>onComplete</var>, <span>fetch a worklet/module
worker script graph</span> given <var>url</var>, <var>fetchClient</var>, <var>destination</var>,
<var>credentialsMode</var>, <var>settingsObject</var>, and <var>onComplete</var>.</p>
<p>To <dfn>fetch a worklet script graph</dfn> given a <span>URL</span> <var>url</var>, an
<span>environment settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, a
<span data-x="concept-script-fetch-options-credentials">credentials mode</span>
<var>credentialsMode</var>, an <span>environment settings object</span>
<var>settingsObject</var>, a <span data-x="concept-Worklet-module-responses-map">module responses
map</span> <var>moduleResponsesMap</var>, and an algorithm <var>onComplete</var>, <span>fetch a
worklet/module worker script graph</span> given <var>url</var>, <var>fetchClient</var>,
<var>destination</var>, <var>credentialsMode</var>, <var>settingsObject</var>,
<var>onComplete</var>, and the following <span data-x="fetching-scripts-perform-fetch">perform the
fetch hook</span> given <var>request</var> and <i
data-x="fetching-scripts-processCustomFetchResponse">processCustomFetchResponse</i>:</p>
<ol>
<li><p>Let <var>requestURL</var> be <var>request</var>'s <span
data-x="concept-request-url">URL</span>.</p></li>
<li><p>If <var>moduleResponsesMap</var>[<var>requestURL</var>] is "<code
data-x="">fetching</code>", wait <span>in parallel</span> until that entry's value changes, then
<span>queue a task</span> on the <span>networking task source</span> to proceed with running the
following steps.</p></li>
<li>
<p>If <var>moduleResponsesMap</var>[<var>requestURL</var>] <span data-x="map
exists">exists</span>, then:</p>
<ol>
<li><p>Let <var>cached</var> be <var>moduleResponsesMap</var>[<var>requestURL</var>].</p></li>
<li><p>Run <var>processCustomFetchResponse</var> with <var>cached</var>[0] and
<var>cached</var>[1].</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p><span data-x="map set">Set</span> <var>moduleResponsesMap</var>[<var>requestURL</var>] to
"<code data-x="">fetching</code>".</p></li>
<li>
<p><span data-x="concept-fetch">Fetch</span> <var>request</var>, with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to the following steps
given <span data-x="concept-response">response</span> <var>response</var> and null, failure, or a
<span>byte sequence</span> <var>bodyBytes</var>:</p>
<ol>
<li><p>Set <var>moduleResponsesMap</var>[<var>requestURL</var>] to (<var>response</var>,
<var>bodyBytes</var>).</p></li>
<li><p>Run <var>processCustomFetchResponse</var> with <var>response</var> and
<var>bodyBytes</var>.</p></li>
</ol>
</li>
</ol>
<hr>
<p>The following algorithms are meant for internal use by this specification only as part of <span
data-x="fetch an external module script graph">fetching an external module script graph</span> or
other similar concepts above, and should not be used directly by other specifications.</p>
<p>This diagram illustrates how these algorithms relate to the ones above, as well as to each
other:</p>
<svg id="module-script-fetching-diagram" viewBox="0 0 941 166" role="img" aria-label="Fetch an external module script, fetch a modulepreload module script graph, fetch an inline module script graph, and fetch a module worker script graph all call fetch the descendants of and link a module script.">
<defs>
<marker id="module-script-fetching-diagram-arrow" orient="auto" markerWidth="6" markerHeight="6" refX="5" refY="3">
<path d="M0,0 V6 L5,3 Z" style="fill: var(--text, CanvasText)"/>
</marker>
</defs>
<g transform="translate(0.5,0.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch an external module script graph</span>
</foreignObject>
</g>
<path d="M90.5,50.5 L470.5,140.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(190.5,0.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch a modulepreload module script graph</span>
</foreignObject>
</g>
<path d="M280.5,50.5 L470.5,140.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(380.5,0.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch an inline module script graph</span>
</foreignObject>
</g>
<path d="M470.5,50.5 L470.5,140.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(570.5,0.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch a module worker script graph</span>
</foreignObject>
</g>
<path d="M660.5,50.5 L755.5,70.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(760.5,0.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch a worklet script graph</span>
</foreignObject>
</g>
<path d="M850.5,50.5 L755.5,70.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(665.5,70.5)" class="caller">
<rect width="180" height="50"/>
<foreignObject width="180" height="50">
<span xmlns="http://www.w3.org/1999/xhtml">fetch a worklet/module worker script graph</span>
</foreignObject>
</g>
<path d="M755.5,120.5 L470.5,140.5" marker-end="url(#module-script-fetching-diagram-arrow)"/>
<g transform="translate(260.5,140.5)" class="subalgorithm">
<rect width="420" height="25"/>
<foreignObject width="420" height="25">
<span xmlns="http://www.w3.org/1999/xhtml">fetch the descendants of and link a module script</span>
</foreignObject>
</g>
</svg>
<p>To <dfn>fetch a worklet/module worker script graph</dfn> given a <span>URL</span>
<var>url</var>, an <span>environment settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, a <span
data-x="concept-script-fetch-options-credentials">credentials mode</span>
<var>credentialsMode</var>, an <span>environment settings object</span> <var>settingsObject</var>,
an algorithm <var>onComplete</var>, and an optional <span
data-x="fetching-scripts-perform-fetch">perform the fetch hook</span> <var>performFetch</var>, run
these steps. <var>onComplete</var> must be an algorithm accepting null (on failure) or a
<span>module script</span> (on success).</p>
<ol>
<li><p>Let <var>options</var> be a <span>script fetch options</span> whose <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is the empty string, <span
data-x="concept-script-fetch-options-integrity">integrity metadata</span> is the empty string,
<span data-x="concept-script-fetch-options-parser">parser metadata</span> is "<code
data-x="">not-parser-inserted</code>", <span
data-x="concept-script-fetch-options-credentials">credentials mode</span> is
<var>credentialsMode</var>, <span data-x="concept-script-fetch-options-referrer-policy">referrer
policy</span> is the empty string, and <span
data-x="concept-script-fetch-options-fetch-priority">fetch priority</span> is "<code
data-x="">auto</code>".</p>
<li>
<p><span>Fetch a single module script</span> given <var>url</var>,
<var>fetchClient</var>, <var>destination</var>, <var>options</var>, <var>settingsObject</var>,
"<code data-x="">client</code>", true, and <var>onSingleFetchComplete</var> as defined below. If
<var>performFetch</var> was given, pass it along as well.</p>
<p><var>onSingleFetchComplete</var> given <var>result</var> is the following algorithm:</p>
<ol>
<li><p>If <var>result</var> is null, run <var>onComplete</var> given null, and abort these
steps.</p></li>
<li><p><span data-x="fetch the descendants of and link a module script">Fetch the descendants
of and link</span> <var>result</var> given <var>fetchClient</var>,
<var>destination</var>, and <var>onComplete</var>. If <var>performFetch</var> was given, pass
it along as well.</p></li>
</ol>
</li>
</ol>
<p>To <dfn data-x="fetch the descendants of and link a module script">fetch the descendants of and
link</dfn> a <span>module script</span> <var>moduleScript</var>, given an <span>environment
settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, an algorithm
<var>onComplete</var>, and an optional <span data-x="fetching-scripts-perform-fetch">perform the
fetch hook</span> <var>performFetch</var>, run these steps. <var>onComplete</var> must be an
algorithm accepting null (on failure) or a <span>module script</span> (on success).</p>
<ol>
<li><p>Let <var>record</var> be <var>moduleScript</var>'s <span
data-x="concept-script-record">record</span>.</p></li>
<li>
<p>If <var>record</var> is null, then:</p>
<ol>
<li><p>Set <var>moduleScript</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span> to <var>moduleScript</var>'s <span>parse error</span>.</p></li>
<li><p>Run <var>onComplete</var> given <var>moduleScript</var>.</li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>state</var> be <span>Record</span> { [[ParseError]]: null, [[Destination]]:
<var>destination</var>, [[PerformFetch]]: null, [[FetchClient]]: <var>fetchClient</var>
}.</p></li>
<li><p>If <var>performFetch</var> was given, set <var>state</var>.[[PerformFetch]] to
<var>performFetch</var>.</p></li>
<li>
<p>Let <var>loadingPromise</var> be <var>record</var>.<span
data-x="js-LoadRequestedModules">LoadRequestedModules</span>(<var>state</var>).</p>
<p class="note">This step will recursively load all the module transitive dependencies.</p>
</li>
<li>
<p><span>Upon fulfillment</span> of <var>loadingPromise</var>, run the following steps:</p>
<ol>
<li>
<p>Perform <var>record</var>.<span data-x="js-Link">Link</span>().</p>
<p class="note">This step will recursively call <span data-x="js-Link">Link</span> on all of
the module's unlinked dependencies.</p>
<p>If this throws an exception, catch it, and set <var>moduleScript</var>'s <span
data-x="concept-script-error-to-rethrow">error to rethrow</span> to that exception.</p>
</li>
<li><p>Run <var>onComplete</var> given <var>moduleScript</var>.</p></li>
</ol>
</li>
<li>
<p><span>Upon rejection</span> of <var>loadingPromise</var>, run the
following steps:</p>
<ol>
<li><p>If <var>state</var>.[[ParseError]] is not null, set <var>moduleScript</var>'s <span
data-x="concept-script-error-to-rethrow">error to rethrow</span> to
<var>state</var>.[[ParseError]] and run <var>onComplete</var> given
<var>moduleScript</var>.</p></li>
<li>
<p>Otherwise, run <var>onComplete</var> given null.</p>
<p class="note"><var>state</var>.[[ParseError]] is null when <var>loadingPromise</var> is
rejected due to a loading error.</p>
</li>
</ol>
</li>
</ol>
<p>To <dfn>fetch a single module script</dfn>, given a <span>URL</span> <var>url</var>, an
<span>environment settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, a <span>script
fetch options</span> <var>options</var>, an <span>environment settings object</span>
<var>settingsObject</var>, a <span data-x="concept-request-referrer">referrer</span>
<var>referrer</var>, an optional <span>ModuleRequest Record</span> <var>moduleRequest</var>, a
boolean <var data-x="fetching-scripts-is-top-level">isTopLevel</var>, an algorithm
<var>onComplete</var>, and an optional <span data-x="fetching-scripts-perform-fetch">perform the
fetch hook</span> <var>performFetch</var>, run these steps. <var>onComplete</var> must be an
algorithm accepting null (on failure) or a <span>module script</span> (on success).</p>
<ol>
<li><p>Let <var>moduleType</var> be "<code data-x="">javascript-or-wasm</code>".</p></li>
<li><p>If <var>moduleRequest</var> was given, then set <var>moduleType</var> to the result of
running the <span>module type from module request</span> steps given
<var>moduleRequest</var>.</p></li>
<li><p><span>Assert</span>: the result of running the <span>module type allowed</span> steps
given <var>moduleType</var> and <var>settingsObject</var> is true. Otherwise, we would not have
reached this point because a failure would have been raised when inspecting
<var>moduleRequest</var>.[[Attributes]] in <a href="#validate-requested-module-specifiers">
HostLoadImportedModule</a> or <span>fetch a single imported module script</span>.</p></li>
<li><p>Let <var>moduleMap</var> be <var>settingsObject</var>'s <span
data-x="concept-settings-object-module-map">module map</span>.</p></li>
<li><p>If <var>moduleMap</var>[(<var>url</var>, <var>moduleType</var>)] is
"<code data-x="">fetching</code>", wait <span>in parallel</span> until that entry's value
changes, then <span>queue a task</span> on the <span>networking task source</span> to proceed
with running the following steps.</p></li>
<li><p>If <var>moduleMap</var>[(<var>url</var>, <var>moduleType</var>)] <span
data-x="map exists">exists</span>, run <var>onComplete</var> given
<var>moduleMap</var>[(<var>url</var>, <var>moduleType</var>)], and return.</p></li>
<li><p><span data-x="map set">Set</span> <var>moduleMap</var>[(<var>url</var>,
<var>moduleType</var>)] to "<code data-x="">fetching</code>".</p></li>
<li><p>Let <var>request</var> be a new <span data-x="concept-request">request</span> whose
<span data-x="concept-request-url">URL</span> is <var>url</var>, <span
data-x="concept-request-mode">mode</span> is "<code data-x="">cors</code>", <span
data-x="concept-request-referrer">referrer</span> is <var>referrer</var>, and <span
data-x="concept-request-client">client</span> is <var>fetchClient</var>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-destination">destination</span> to
the result of running the <span>fetch destination from module type</span> steps given
<var>destination</var> and <var>moduleType</var>.</p></li>
<!--
"serviceworker" being included here is not redundant with the Service Worker spec's own
same-origin check, because the request's mode also affects the Origin and Sec-Fetch-Mode
headers.
-->
<li><p>If <var>destination</var> is "<code data-x="">worker</code>", "<code
data-x="">sharedworker</code>", or "<code data-x="">serviceworker</code>", and
<var>isTopLevel</var> is true, then set <var>request</var>'s <span
data-x="concept-request-mode">mode</span> to "<code data-x="">same-origin</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to "<code data-x="">script</code>".</p>
<li><p><span>Set up the module script request</span> given <var>request</var> and
<var>options</var>.</p></li>
<!--FETCH-->
<li>
<p>If <var>performFetch</var> was given, run <var>performFetch</var> with <var>request</var>,
<var>isTopLevel</var>, and with <var>processResponseConsumeBody</var> as defined below.</p>
<p>Otherwise, <span data-x="concept-fetch">fetch</span> <var>request</var> with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to
<var>processResponseConsumeBody</var> as defined below.</p>
<p>In both cases, let <var>processResponseConsumeBody</var> given <span
data-x="concept-response">response</span> <var>response</var> and null, failure, or a
<span>byte sequence</span> <var>bodyBytes</var> be the following algorithm:</p>
<p class="note"><var>response</var> is always <span>CORS-same-origin</span>.</p>
<ol>
<li>
<p>If any of the following are true:</p>
<ul>
<li><p><var>bodyBytes</var> is null or failure; or</p></li>
<li><p><var>response</var>'s <span data-x="concept-response-status">status</span> is not an
<span>ok status</span>,</p></li>
</ul>
<p>then <span data-x="map set">set</span> <var>moduleMap</var>[(<var>url</var>,
<var>moduleType</var>)] to null, run <var>onComplete</var> given null, and abort these
steps.</p>
</li>
<li><p>Let <var>mimeType</var> be the result of <span data-x="extract a MIME type">extracting
a MIME type</span> from <var>response</var>'s <span
data-x="concept-response-header-list">header list</span>.</p></li>
<li><p>Let <var>moduleScript</var> be null.</p></li>
<li><p>Let <var>referrerPolicy</var> be the result of <span
data-x="parse-referrer-policy-header">parsing the `<code>Referrer-Policy</code>` header</span>
given <var>response</var>. <ref>REFERRERPOLICY</ref></p></li>
<li><p>If <var>referrerPolicy</var> is not the empty string, set <var>options</var>'s <span
data-x="concept-script-fetch-options-referrer-policy">referrer policy</span> to
<var>referrerPolicy</var>.</p></li>
<li><p>If <var>mimeType</var>'s <span data-x="MIME type essence">essence</span> is
"<code>application/wasm</code>" and <var>moduleType</var> is "<code
data-x="">javascript-or-wasm</code>", then set <var>moduleScript</var> to the result of
<span>creating a WebAssembly module script</span> given <var>bodyBytes</var>,
<var>settingsObject</var>, <var>response</var>'s <span
data-x="concept-response-url">URL</span>, and <var>options</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>sourceText</var> be the result of <span data-x="UTF-8 decode">UTF-8
decoding</span> <var>bodyBytes</var>.</p></li>
<li><p>If <var>mimeType</var> is a <span>JavaScript MIME type</span> and <var>moduleType</var>
is "<code data-x="">javascript-or-wasm</code>", then set <var>moduleScript</var> to the result of
<span>creating a JavaScript module script</span> given <var>sourceText</var>,
<var>settingsObject</var>, <var>response</var>'s <span
data-x="concept-response-url">URL</span>, and <var>options</var>.</p></li>
<li><p>If the <span>MIME type essence</span> of <var>mimeType</var> is "<code>text/css</code>"
and <var>moduleType</var> is "<code data-x="">css</code>", then set <var>moduleScript</var> to
the result of <span>creating a CSS module script</span> given <var>sourceText</var> and
<var>settingsObject</var>.</p></li>
<li><p>If <var>mimeType</var> is a <span>JSON MIME type</span> and
<var>moduleType</var> is "<code data-x="">json</code>", then set <var>moduleScript</var> to
the result of <span>creating a JSON module script</span> given <var>sourceText</var> and
<var>settingsObject</var>.</p></li>
</ol>
</li>
<li>
<p><span data-x="map set">Set</span> <var>moduleMap</var>[(<var>url</var>,
<var>moduleType</var>)] to <var>moduleScript</var>, and run <var>onComplete</var> given
<var>moduleScript</var>.</p>
<p class="note">It is intentional that the <span>module map</span> is keyed by the <span
data-x="concept-request-url">request URL</span>, whereas the <span
data-x="concept-script-base-url">base URL</span> for the <span>module script</span> is
set to the <span data-x="concept-response-url">response URL</span>. The former is used to
deduplicate fetches, while the latter is used for URL resolution.</p>
</li>
</ol>
</li>
</ol>
<p>To <dfn>fetch a single imported module script</dfn>, given a <span>URL</span> <var>url</var>,
an <span>environment settings object</span> <var>fetchClient</var>, a <span
data-x="concept-request-destination">destination</span> <var>destination</var>, a <span>script
fetch options</span> <var>options</var>, <span>environment settings object</span>
<var>settingsObject</var>, a <span data-x="concept-request-referrer">referrer</span>
<var>referrer</var>, a <span>ModuleRequest Record</span> <var>moduleRequest</var>, an
algorithm <var>onComplete</var>, and an optional <span
data-x="fetching-scripts-perform-fetch">perform the fetch hook</span> <var>performFetch</var>, run
these steps. <var>onComplete</var> must be an algorithm accepting null (on failure) or a
<span>module script</span> (on success).</p>
<ol>
<li><p><span>Assert</span>: <var>moduleRequest</var>.[[Attributes]] does not contain any
<span>Record</span> <var>entry</var> such that <var>entry</var>.[[Key]] is not "<code
data-x="">type</code>", because we only asked for "<code data-x="">type</code>" attributes in
<span>HostGetSupportedImportAttributes</span>.</p></li>
<li><p>Let <var>moduleType</var> be the result of running the <span>module type from module
request</span> steps given <var>moduleRequest</var>.</p></li>
<li><p>If the result of running the <span>module type allowed</span> steps given
<var>moduleType</var> and <var>settingsObject</var> is false, then run <var>onComplete</var>
given null, and return.</p></li>
<li><p><span>Fetch a single module script</span> given <var>url</var>, <var>fetchClient</var>,
<var>destination</var>, <var>options</var>, <var>settingsObject</var>, <var>referrer</var>,
<var>moduleRequest</var>, false, and <var>onComplete</var>. If <var>performFetch</var> was given,
pass it along as well.</p></li>
</ol>
<h5 id="creating-scripts">Creating scripts</h5>
<p>To <dfn data-x="creating a classic script">create a classic script</dfn>, given a
<span>string</span> <var>source</var>, an <span>environment settings object</span>
<var>settings</var>, a <span>URL</span> <var>baseURL</var>, a <span>script fetch options</span>
<var>options</var>, an optional boolean <var>mutedErrors</var> (default false), and an optional
<span>URL</span>-or-null <var>sourceURLForWindowScripts</var> (default null):</p>
<ol>
<li>
<p>If <var>mutedErrors</var> is true, then set <var>baseURL</var> to
<code>about:blank</code>.</p>
<p class="note">When <var>mutedErrors</var> is true, <var>baseURL</var> is the script's
<span>CORS-cross-origin</span> <span data-x="concept-response">response</span>'s <span
data-x="concept-response-url">url</span>, which shouldn't be exposed to JavaScript. Therefore,
<var>baseURL</var> is sanitized here.</p>
</li>
<li><p>If <span data-x="concept-environment-noscript">scripting is disabled</span> for
<var>settings</var>, then set <var>source</var> to the empty string.</p></li>
<li><p>Let <var>script</var> be a new <span>classic script</span> that this algorithm will
subsequently initialize.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span> to <var>settings</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> to
<var>baseURL</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-script-fetch-options">fetch
options</span> to <var>options</var>.</p></li>
<li><p>Set <var>script</var>'s <span>muted errors</span> to <var>mutedErrors</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>
<li><p><span>Record classic script creation time</span> given <var>script</var> and
<var>sourceURLForWindowScripts</var>.</p></li>
<li>
<p>Let <var>result</var> be <span data-x="js-ParseScript">ParseScript</span>(<var>source</var>,
<var>settings</var>'s <span data-x="environment settings object's realm">realm</span>,
<var>script</var>).</p>
<p class="note">Passing <var>script</var> as the last parameter here ensures
<var>result</var>.[[HostDefined]] will be <var>script</var>.</p>
</li>
<li>
<p>If <var>result</var> is a <span>list</span> of errors, then:
<ol>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
its <span data-x="concept-script-error-to-rethrow">error to rethrow</span> to
<var>result</var>[0].</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
</li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>result</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p>To <dfn data-x="creating a JavaScript module script">create a JavaScript module script</dfn>,
given a <span>string</span> <var>source</var>, an <span>environment settings
object</span> <var>settings</var>, a <span>URL</span> <var>baseURL</var>, and a <span>script fetch
options</span> <var>options</var>:</p>
<ol>
<li><p>If <span data-x="concept-environment-noscript">scripting is disabled</span> for
<var>settings</var>, then set <var>source</var> to the empty string.</p></li>
<li><p>Let <var>script</var> be a new <span>module script</span> that this algorithm will
subsequently initialize.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span> to <var>settings</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> to
<var>baseURL</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-script-fetch-options">fetch
options</span> to <var>options</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>
<li>
<p>Let <var>result</var> be <span data-x="js-ParseModule">ParseModule</span>(<var>source</var>,
<var>settings</var>'s <span data-x="environment settings object's realm">realm</span>,
<var>script</var>).</p>
<p class="note">Passing <var>script</var> as the last parameter here ensures
<var>result</var>.[[HostDefined]] will be <var>script</var>.</p>
</li>
<li>
<p>If <var>result</var> is a <span>list</span> of errors, then:</p>
<ol>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> to
<var>result</var>[0].</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
</li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>result</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p>To <dfn data-x="creating a WebAssembly module script">create a WebAssembly module script</dfn>,
given a <span>byte sequence</span> <var>bodyBytes</var>, an <span>environment settings
object</span> <var>settings</var>, a <span>URL</span> <var>baseURL</var>, and a <span>script fetch
options</span> <var>options</var>:</p>
<ol>
<li>
<p>If <span data-x="concept-environment-noscript">scripting is disabled</span> for
<var>settings</var>, then set <var>bodyBytes</var> to the byte sequence 0x00 0x61 0x73 0x6d 0x01
0x00 0x00 0x00.</p>
<p class="note">This byte sequence corresponds to an empty WebAssembly module with only the magic
bytes and version number provided.</p>
</li>
<li><p>Let <var>script</var> be a new <span>module script</span> that this algorithm will
subsequently initialize.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span> to <var>settings</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> to
<var>baseURL</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-script-fetch-options">fetch
options</span> to <var>options</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>
<li>
<p>Let <var>result</var> be the result of <span data-x="parse a WebAssembly module">parsing a
WebAssembly module</span> given <var>bodyBytes</var>,
<var>settings</var>'s <span data-x="environment settings object's realm">realm</span>, and
<var>script</var>.</p>
<p class="note">Passing <var>script</var> as the last parameter here ensures
<var>result</var>.[[HostDefined]] will be <var>script</var>.</p>
</li>
<li>
<p>If the previous step threw an error <var>error</var>, then:</p>
<ol>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> to
<var>error</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
</li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>result</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p class="note"><cite>WebAssembly JavaScript Interface: ESM Integration</cite> specifies the
hooks for the WebAssembly integration with ECMA-262 module loading. This includes support both
for direct dependency imports, as well as for source phase imports, which support virtualization
and multi-instantiation. <ref>WASMESM</ref></p>
<p>To <dfn data-x="creating a CSS module script">create a CSS module script</dfn>, given a
string <var>source</var> and an <span>environment settings object</span> <var>settings</var>:</p>
<ol>
<li><p>Let <var>script</var> be a new <span>module script</span> that this algorithm will
subsequently initialize.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span> to <var>settings</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> and
<span data-x="concept-script-script-fetch-options">fetch options</span> to null.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>
<li><p>Let <var>sheet</var> be the result of running the steps to <span>create a constructed
<code>CSSStyleSheet</code></span> with an empty dictionary as the argument.</p></li>
<li>
<p>Run the steps to <span>synchronously replace the rules of a <code>CSSStyleSheet</code></span>
on <var>sheet</var> given <var>source</var>.</p>
<p>If this throws an exception, catch it, and set <var>script</var>'s <span
data-x="concept-script-parse-error">parse error</span> to that exception, and return
<var>script</var>.</p>
<p class="note">The steps to <span>synchronously replace the rules of a
<code>CSSStyleSheet</code></span> will throw if <var>source</var> contains any <code
data-x="">@import</code> rules. This is by-design for now because there is not yet an
agreement on how to handle these for CSS module scripts; therefore they are blocked altogether
until a consensus is reached.</p>
</li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to the result
of <span>CreateDefaultExportSyntheticModule</span>(<var>sheet</var>).</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p>To <dfn data-x="creating a JSON module script">create a JSON module script</dfn>, given a
string <var>source</var> and an <span>environment settings object</span> <var>settings</var>:</p>
<ol>
<li><p>Let <var>script</var> be a new <span>module script</span> that this algorithm will
subsequently initialize.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span> to <var>settings</var>.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-base-url">base URL</span> and
<span data-x="concept-script-script-fetch-options">fetch options</span> to null.</p></li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-parse-error">parse error</span> and
<span data-x="concept-script-error-to-rethrow">error to rethrow</span> to null.</p></li>
<li>
<p>Let <var>result</var> be <span>ParseJSONModule</span>(<var>source</var>).</p>
<p>If this throws an exception, catch it, and set <var>script</var>'s <span
data-x="concept-script-parse-error">parse error</span> to that exception, and return
<var>script</var>.</p>
</li>
<li><p>Set <var>script</var>'s <span data-x="concept-script-record">record</span> to
<var>result</var>.</p></li>
<li><p>Return <var>script</var>.</p></li>
</ol>
<p>The <dfn>module type from module request</dfn> steps, given a <span>ModuleRequest
Record</span> <var>moduleRequest</var>, are as follows:</p>
<ol>
<li><p>Let <var>moduleType</var> be "<code data-x="">javascript-or-wasm</code>".</p></li>
<li>
<p>If <var>moduleRequest</var>.[[Attributes]] has a <span>Record</span> <var>entry</var> such
that <var>entry</var>.[[Key]] is "<code data-x="">type</code>", then:</p>
<ol>
<li>
<p>If <var>entry</var>.[[Value]] is "<code data-x="">javascript-or-wasm</code>", then set
<var>moduleType</var> to null.</p>
<p class="note">This specification uses the "<code data-x="">javascript-or-wasm</code>" module
type internally for <span data-x="JavaScript module script">JavaScript module scripts</span> or
<span data-x="WebAssembly module script">WebAssembly module scripts</span>, so this step is
needed to prevent modules from being imported using a
"<code data-x="">javascript-or-wasm</code>" type attribute (a null <var>moduleType</var> will
cause the <span>module type allowed</span> check to fail).</p>
</li>
<li><p>Otherwise, set <var>moduleType</var> to <var>entry</var>.[[Value]].</p></li>
</ol>
</li>
<li><p>Return <var>moduleType</var>.</p></li>
</ol>
<p>The <dfn>module type allowed</dfn> steps, given a <span>string</span> <var>moduleType</var>
and an <span>environment settings object</span> <var>settings</var>, are as follows:</p>
<ol>
<li><p>If <var>moduleType</var> is not "<code data-x="">javascript-or-wasm</code>", "<code
data-x="">css</code>", or "<code data-x="">json</code>", then return false.</p></li>
<li><p>If <var>moduleType</var> is "<code data-x="">css</code>" and the
<code>CSSStyleSheet</code> interface is not <span data-x="idl-exposed">exposed</span> in
<var>settings</var>'s <span data-x="environment settings object's realm">realm</span>, then
return false.</p></li>
<li><p>Return true.</p></li>
</ol>
<p>The <dfn>fetch destination from module type</dfn> steps, given a <span
data-x="concept-request-destination">destination</span> <var>defaultDestination</var> and a
<span>string</span> <var>moduleType</var>, are as follows:</p>
<ol>
<li>If <var>moduleType</var> is "<code data-x="">json</code>", then return "<code
data-x="">json</code>".</li>
<li>If <var>moduleType</var> is "<code data-x="">css</code>", then return "<code
data-x="">style</code>".</li>
<li>Return <var>defaultDestination</var>.</li>
</ol>
<h5 id="calling-scripts">Calling scripts</h5>
<p>To <dfn export>run a classic script</dfn> given a <span>classic script</span> <var>script</var>
and an optional boolean <var>rethrow errors</var> (default false):</p>
<ol>
<li><p>Let <var>settings</var> be the <span data-x="concept-script-settings-object">settings
object</span> of <var>script</var>.</p></li>
<li><p><span>Check if we can run script</span> with <var>settings</var>. If this returns "do
not run" then return <span>NormalCompletion</span>(empty).</p></li>
<li><p><span>Record classic script execution start time</span> given <var>script</var>.</p></li>
<li><p><span>Prepare to run script</span> given <var>settings</var>.</p></li>
<li><p>Let <var>evaluationStatus</var> be null.</p></li>
<li><p>If <var>script</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span> is not null, then set <var>evaluationStatus</var> to Completion { [[Type]]: throw,
[[Value]]: <var>script</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span>, [[Target]]: empty }.</p></li>
<li>
<p>Otherwise, set <var>evaluationStatus</var> to <span
data-x="js-ScriptEvaluation">ScriptEvaluation</span>(<var>script</var>'s <span
data-x="concept-script-record">record</span>).</p>
<p>If <span data-x="js-ScriptEvaluation">ScriptEvaluation</span> does not complete because the
user agent has <span data-x="abort a running script">aborted the running script</span>, leave
<var>evaluationStatus</var> as null.</p>
</li>
<li>
<p>If <var>evaluationStatus</var> is an <span data-x="Completion Record">abrupt
completion</span>, then:</p>
<ol>
<li>
<p>If <var>rethrow errors</var> is true and <var>script</var>'s <span>muted
errors</span> is false, then:</p>
<ol>
<li><p><span>Clean up after running script</span> with <var>settings</var>.</p></li>
<li><p>Rethrow <var>evaluationStatus</var>.[[Value]].</p></li>
</ol>
<li>
<p>If <var>rethrow errors</var> is true and <var>script</var>'s <span>muted
errors</span> is true, then:</p>
<ol>
<li><p><span>Clean up after running script</span> with <var>settings</var>.</p></li>
<li><p>Throw a <span>"<code>NetworkError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li>
<p>Otherwise, <var>rethrow errors</var> is false. Perform the following steps:</p>
<ol>
<li><p><span>Report an exception</span> given by <var>evaluationStatus</var>.[[Value]] for
<var>script</var>'s <span data-x="concept-script-settings-object">settings object</span>'s
<span data-x="concept-settings-object-global">global object</span>.</p></li>
<li><p><span>Clean up after running script</span> with <var>settings</var>.</p></li>
<li><p>Return <var>evaluationStatus</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p><span>Clean up after running script</span> with <var>settings</var>.</p></li>
<li><p>If <var>evaluationStatus</var> is a normal completion, then return
<var>evaluationStatus</var>.</p></li>
<li><p>If we've reached this point, <var>evaluationStatus</var> was left as null because the
script was <span data-x="abort a running script">aborted prematurely</span> during evaluation.
Return Completion { [[Type]]: throw, [[Value]]: a new
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code>, [[Target]]: empty }.
</p></li>
</ol>
<p>To <dfn export>run a module script</dfn> given a <span>module script</span> <var>script</var>
and an optional boolean <var>preventErrorReporting</var> (default false):</p>
<ol>
<li><p>Let <var>settings</var> be the <span data-x="concept-script-settings-object">settings
object</span> of <var>script</var>.</p></li>
<li><p><span>Check if we can run script</span> with <var>settings</var>. If this returns "do not
run", then return <span>a promise resolved with</span> undefined.</p></li>
<li><p><span>Record module script execution start time</span> given <var>script</var>.</p></li>
<li><p><span>Prepare to run script</span> given <var>settings</var>.</p></li>
<li><p>Let <var>evaluationPromise</var> be null.</p></li>
<li><p>If <var>script</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span> is not null, then set <var>evaluationPromise</var> to <span>a promise rejected
with</span> <var>script</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>record</var> be <var>script</var>'s <span
data-x="concept-script-record">record</span>.</p>
<li>
<p>Set <var>evaluationPromise</var> to <var>record</var>.<span
data-x="js-Evaluate">Evaluate</span>().</p>
<p class="note">This step will recursively evaluate all of the module's dependencies.</p>
<p>If <span data-x="js-Evaluate">Evaluate</span> fails to complete as a result of the user agent
<span data-x="abort a running script">aborting the running script</span>, then set
<var>evaluationPromise</var> to <span>a promise rejected with</span> a new
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code>.</p>
</li>
</ol>
</li>
<li><p>If <var>preventErrorReporting</var> is false, then <span>upon rejection</span> of
<var>evaluationPromise</var> with <var>reason</var>, <span>report an exception</span> given by
<var>reason</var> for <var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span>'s <span data-x="concept-settings-object-global">global object</span>.</p></li>
<li><p><span>Clean up after running script</span> with <var>settings</var>.</p></li>
<li><p>Return <var>evaluationPromise</var>.</p></li>
</ol>
<p>The steps to <dfn>check if we can run script</dfn> with an <span>environment settings
object</span> <var>settings</var> are as follows. They return either "run" or "do not run".</p>
<ol>
<li><p>If the <span data-x="concept-settings-object-global">global object</span> specified by
<var>settings</var> is a <code>Window</code> object whose <code>Document</code> object is not
<span>fully active</span>, then return "do not run".</p>
<li><p>If <span data-x="concept-environment-noscript">scripting is disabled</span> for
<var>settings</var>, then return "do not run".</p>
<li><p>Return "run".</p></li>
</ol>
<p>The steps to <dfn export>prepare to run script</dfn> with an <span>environment settings
object</span> <var>settings</var> are as follows:</p>
<ol>
<li><p>Push <var>settings</var>'s <span>realm execution context</span> onto the <span>JavaScript
execution context stack</span>; it is now the <span>running JavaScript execution
context</span>.</p></li>
<li><p>Add <var>settings</var> to the <span>surrounding agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>currently running task</span>'s
<span>script evaluation environment settings object set</span>.</p></li>
</ol>
<p>The steps to <dfn export>clean up after running script</dfn> with an <span>environment settings
object</span> <var>settings</var> are as follows:</p>
<ol>
<li><p><span>Assert</span>: <var>settings</var>'s <span>realm execution context</span> is the
<span>running JavaScript execution context</span>.</p></li>
<li><p>Remove <var>settings</var>'s <span>realm execution context</span> from the
<span>JavaScript execution context stack</span>.</p></li>
<li><p>If the <span>JavaScript execution context stack</span> is now empty, <span>perform a
microtask checkpoint</span>. (If this runs scripts, these algorithms will be invoked
reentrantly.)</p></li>
</ol>
<p class="note">These algorithms are not invoked by one script directly calling another, but they
can be invoked reentrantly in an indirect manner, e.g. if a script dispatches an event which has
event listeners registered.</p>
<p>The <dfn>running script</dfn> is the <span data-x="concept-script">script</span> in the
[[HostDefined]] field in the ScriptOrModule component of the <span>running JavaScript execution
context</span>.</p>
<h5>Killing scripts</h5>
<p>Although the JavaScript specification does not account for this possibility, it's sometimes
necessary to <dfn data-lt="abort a running script|abort the running script" export>abort a
running script</dfn>. This causes any <span data-x="js-ScriptEvaluation">ScriptEvaluation</span>
or <span>Source Text Module Record</span> <span data-x="js-Evaluate">Evaluate</span> invocations
to cease immediately, emptying the <span>JavaScript execution context stack</span> without
triggering any of the normal mechanisms like <code data-x="">finally</code> blocks.
<ref>JAVASCRIPT</ref></p>
<p>User agents may impose resource limitations on scripts, for example CPU quotas, memory limits,
total execution time limits, or bandwidth limitations. When a script exceeds a limit, the user
agent may either throw a <span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code>,
<span data-x="abort a running script">abort the script</span> without an exception, prompt the
user, or throttle script execution.</p>
<div class="example">
<p>For example, the following script never terminates. A user agent could, after waiting for a
few seconds, prompt the user to either terminate the script or let it continue.</p>
<pre><code class="html"><script>
while (true) { /* loop */ }
</script></code></pre>
</div>
<p>User agents are encouraged to allow users to disable scripting whenever the user is prompted
either by a script (e.g. using the <code data-x="dom-alert">window.alert()</code> API) or because
of a script's actions (e.g. because it has exceeded a time limit).</p>
<p>If scripting is disabled while a script is executing, the script should be terminated
immediately.</p>
<p>User agents may allow users to specifically disable scripts just for the purposes of closing a
<span>browsing context</span>.</p>
<p class="example">For example, the prompt mentioned in the example above could also offer the
user with a mechanism to just close the page entirely, without running any <code
data-x="event-unload">unload</code> event handlers.</p>
</div>
<h5 id="runtime-script-errors">Runtime script errors</h5>
<dl class="domintro">
<dt><code data-x="">self.<span subdfn data-x="dom-reportError">reportError</span>(<var>e</var>)</code></dt>
<dd><p>Dispatches an <code data-x="event-error">error</code> event at the global object for the
given value <var>e</var>, in the same fashion as an unhandled exception.</p></dd>
</dl>
<p w-dev>In various scenarios, the user agent can report an exception by firing an <code
data-x="event-error">error</code> event at the <code>Window</code>. If this event is not canceled,
then the error is considered not handled, and can be reported to the developer console.</p>
<div w-nodev>
<p>To <dfn data-x="extract-error">extract error information</dfn> from a JavaScript value
<var>exception</var>:</p>
<ol>
<li><p>Let <var>attributes</var> be an empty <span data-x="ordered map">map</span> keyed by IDL
attributes.</p></li>
<li><p>Set <var>attributes</var>[<code data-x="dom-ErrorEvent-error">error</code>] to
<var>exception</var>.</p></li>
<li>
<p>
<!-- INSERT TRACKING-->
Set <var>attributes</var>[<code data-x="dom-ErrorEvent-message">message</code>],
<var>attributes</var>[<code data-x="dom-ErrorEvent-filename">filename</code>],
<var>attributes</var>[<code data-x="dom-ErrorEvent-lineno">lineno</code>], and
<var>attributes</var>[<code data-x="dom-ErrorEvent-colno">colno</code>] to
<span>implementation-defined</span> values derived from <var>exception</var>.
</p>
<p class="note">Browsers implement behavior not specified here or in the JavaScript
specification to gather values which are helpful, including in unusual cases (e.g., <code
data-x="">eval</code>). In the future, this might be specified in greater detail.</p>
</li>
<li><p>Return <var>attributes</var>.</p></li>
</ol>
<p id="runtime-script-errors-in-documents"><span id="report-the-error"></span>To <dfn
export>report an exception</dfn> <var>exception</var> which is a JavaScript value, for a
particular <span>global object</span> <var>global</var> and optional boolean <dfn
data-x="report-exception-omitError"><var>omitError</var></dfn> (default false):</p>
<ol>
<li><p>Let <var>notHandled</var> be true.</p></li>
<li><p>Let <var>errorInfo</var> be the result of <span data-x="extract-error">extracting error
information</span> from <var>exception</var>.</p></li>
<li>
<p>Let <var>script</var> be a <span data-x="concept-script">script</span> found in an
<span>implementation-defined</span> way, or null. This should usually be the <span>running
script</span> (most notably during <span>run a classic script</span>).</p>
<p class="note">Implementations have not yet settled on interoperable behavior for which script
is used to determine whether errors are muted in less common cases.</p>
</li>
<li><p>If <var>script</var> is a <span>classic script</span> and <var>script</var>'s <span>muted
errors</span> is true, then set <var>errorInfo</var>[<code
data-x="dom-ErrorEvent-error">error</code>] to null, <var>errorInfo</var>[<code
data-x="dom-ErrorEvent-message">message</code>] to "<code data-x="">Script error.</code>",
<var>errorInfo</var>[<code data-x="dom-ErrorEvent-filename">filename</code>] to the empty
string, <var>errorInfo</var>[<code data-x="dom-ErrorEvent-lineno">lineno</code>] to 0, and
<var>errorInfo</var>[<code data-x="dom-ErrorEvent-colno">colno</code>] to 0.</p></li>
<li><p>If <var>omitError</var> is true, then set <var>errorInfo</var>[<code
data-x="dom-ErrorEvent-error">error</code>] to null.</p></li>
<li>
<p>If <var>global</var> is not <span>in error reporting mode</span>, then:</p>
<ol>
<li>Set <var>global</var>'s <span>in error reporting mode</span> to true.</li>
<li>
<p>If <var>global</var> implements <code>EventTarget</code>, then set <var>notHandled</var> to
the result of <span data-x="concept-event-fire">firing an event</span> named <code
data-x="event-error">error</code> at <var>global</var>, using <code>ErrorEvent</code>, with
the <code data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true,
and additional attributes initialized according to <var>errorInfo</var>.</p>
<p class="note">Returning true in an event handler cancels the event per <span>the event
handler processing algorithm</span>.</p>
</li>
<li><p>Set <var>global</var>'s <span>in error reporting mode</span> to false.</p></li>
</ol>
</li>
<li>
<p>If <var>notHandled</var> is true, then:</p>
<ol>
<li><p>Set <var>errorInfo</var>[<code data-x="dom-ErrorEvent-error">error</code>] to
null.</p></li>
<li>
<p>If <var>global</var> implements <code>DedicatedWorkerGlobalScope</code>, <span>queue a
global task</span> on the <span>DOM manipulation task source</span> with the
<var>global</var>'s associated <code>Worker</code>'s <span>relevant global object</span> to
run these steps:</p>
<ol>
<li><p>Let <var>workerObject</var> be the <code>Worker</code> object associated with
<var>global</var>.</p></li>
<li><p>Set <var>notHandled</var> be the result of <span data-x="concept-event-fire">firing
an event</span> named <code data-x="event-error">error</code> at <var>workerObject</var>,
using <code>ErrorEvent</code>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true,
and additional attributes initialized according to <var>errorInfo</var>.</p></li>
<li>
<p>If <var>notHandled</var> is true, then <span data-x="report an exception">report</span>
<var>exception</var> for <var>workerObject</var>'s <span>relevant global object</span> with
<span data-x="report-exception-omitError"><var>omitError</var></span> set to true.</p>
<p class="note">The actual <var>exception</var> value will not be available in the owner
realm, but the user agent still carries through enough information to set the message,
filename, and other attributes, as well as potentially report to a developer console.</p>
</li>
</ol>
</li>
<li><p>Otherwise, the user agent may report <var>exception</var> to a developer
console.</p></li>
</ol>
</li>
</ol>
<p>If the implicit port connecting a worker to its <code>Worker</code> object has been
disentangled (i.e. if the parent worker has been terminated), then the user agent must act as if
the <code>Worker</code> object had no <code data-x="event-error">error</code> event handler and as
if that worker's <code data-x="handler-WorkerGlobalScope-onerror">onerror</code> attribute was
null, but must otherwise act as described above.</p>
<p class="note">Thus, error reports propagate up to the chain of dedicated workers up to the
original <code>Document</code>, even if some of the workers along this chain have been terminated
and garbage collected.</p>
<p>Previous revisions of this standard defined an algorithm to <dfn data-x="report the exception"
data-lt="report the exception" export>report the exception</dfn>. As part of <a
href="https://github.com/whatwg/html">issue #958</a>, this has been superseded by <span>report an
exception</span> which behaves differently and takes different inputs. <a
href="https://github.com/whatwg/html/issues/10516">Issue #10516</a> tracks updating the
specification ecosystem.</p>
<hr>
<p>The <dfn method for="WindowOrWorkerGlobalScope"
data-x="dom-reportError"><code>reportError(<var>e</var>)</code></dfn> method steps are to
<span>report an exception</span> <var>e</var> for <span>this</span>.</p>
<p class="XXX">It is unclear whether <span data-x="muted errors">muting</span> is
applicable here. In Chrome and Safari it is muted, but in Firefox it is not. See also <a
href="https://github.com/whatwg/html/issues/958">issue #958</a>.</p>
<hr>
<p id="the-errorevent-interface">The <code>ErrorEvent</code> interface is defined as follows:</p>
<pre><code class="idl">[Exposed=*]
interface <dfn interface>ErrorEvent</dfn> : <span>Event</span> {
<span data-x="dom-Event-constructor">constructor</span>(DOMString type, optional <span>ErrorEventInit</span> eventInitDict = {});
readonly attribute DOMString <span data-x="dom-ErrorEvent-message">message</span>;
readonly attribute USVString <span data-x="dom-ErrorEvent-filename">filename</span>;
readonly attribute unsigned long <span data-x="dom-ErrorEvent-lineno">lineno</span>;
readonly attribute unsigned long <span data-x="dom-ErrorEvent-colno">colno</span>;
readonly attribute any <span data-x="dom-ErrorEvent-error">error</span>;
};
dictionary <dfn dictionary>ErrorEventInit</dfn> : <span>EventInit</span> {
DOMString message = "";
USVString filename = "";
unsigned long lineno = 0;
unsigned long colno = 0;
any error;
};</code></pre>
<p>The <dfn attribute for="ErrorEvent"><code data-x="dom-ErrorEvent-message">message</code></dfn>
attribute must return the value it was initialized to. It represents the error message.</p>
<p>The <dfn attribute for="ErrorEvent"><code
data-x="dom-ErrorEvent-filename">filename</code></dfn> attribute must return the value it was
initialized to. It represents the <span>URL</span> of the script in which the error originally
occurred.</p>
<p>The <dfn attribute for="ErrorEvent"><code data-x="dom-ErrorEvent-lineno">lineno</code></dfn>
attribute must return the value it was initialized to. It represents the line number where the
error occurred in the script.</p>
<p>The <dfn attribute for="ErrorEvent"><code data-x="dom-ErrorEvent-colno">colno</code></dfn>
attribute must return the value it was initialized to. It represents the column number where the
error occurred in the script.</p>
<p>The <dfn attribute for="ErrorEvent"><code data-x="dom-ErrorEvent-error">error</code></dfn>
attribute must return the value it was initialized to. It must initially be initialized to
undefined. Where appropriate, it is set to the object representing the error (e.g., the exception
object in the case of an uncaught exception).</p>
</div>
<h5>Unhandled promise rejections</h5>
<p>In addition to synchronous <a href="#runtime-script-errors">runtime script errors</a>, scripts
may experience asynchronous promise rejections, tracked via the <code
data-x="event-unhandledrejection">unhandledrejection</code> and <code
data-x="event-rejectionhandled">rejectionhandled</code> events.<span w-nodev> Tracking these
rejections is done via the <span>HostPromiseRejectionTracker</span> abstract operation, but
reporting them is defined here.</span></p>
<div w-nodev>
<p>To <dfn>notify about rejected promises</dfn> given a <span>global object</span>
<var>global</var>:</p>
<ol>
<li><p>Let <var>list</var> be a <span data-x="list clone">clone</span> of <var>global</var>'s
<span>about-to-be-notified rejected promises list</span>.</p></li>
<li><p>If <var>list</var> <span data-x="list is empty">is empty</span>, then return.</p></li>
<li><p><span data-x="list empty">Empty</span> <var>global</var>'s <span>about-to-be-notified
rejected promises list</span>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to run the following step:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> promise <var>p</var> of <var>list</var>:</p>
<ol>
<li><p>If <var>p</var>.[[PromiseIsHandled]] is true, then <span>continue</span>.</p></li>
<li><p>Let <var>notCanceled</var> be the result of <span data-x="concept-event-fire">firing
an event</span> named <code data-x="event-unhandledrejection">unhandledrejection</code> at
<var>global</var>, using <code>PromiseRejectionEvent</code>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true, the <code
data-x="dom-PromiseRejectionEvent-promise">promise</code> attribute initialized to
<var>p</var>, and the <code data-x="dom-PromiseRejectionEvent-reason">reason</code>
attribute initialized to <var>p</var>.[[PromiseResult]].</p></li>
<li id="concept-promise-rejection-handled"><p id="concept-promise-rejection-nothandled">If
<var>notCanceled</var> is true, then the user agent may report
<var>p</var>.[[PromiseResult]] to a developer console.</p></li>
<li><p>If <var>p</var>.[[PromiseIsHandled]] is false, then <span data-x="set
append">append</span> <var>p</var> to <var>global</var>'s <span>outstanding rejected
promises weak set</span>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
<p id="the-promiserejectionevent-interface">The <code>PromiseRejectionEvent</code> interface is
defined as follows:</p>
<pre><code class="idl">[Exposed=*]
interface <dfn interface>PromiseRejectionEvent</dfn> : <span>Event</span> {
<span data-x="dom-Event-constructor">constructor</span>(DOMString type, <span>PromiseRejectionEventInit</span> eventInitDict);
readonly attribute <span data-x="idl-object">object</span> <span data-x="dom-PromiseRejectionEvent-promise">promise</span>;
readonly attribute any <span data-x="dom-PromiseRejectionEvent-reason">reason</span>;
};
dictionary <dfn dictionary>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
required <span data-x="idl-object">object</span> promise;
any reason;
};</code></pre>
<p>The <dfn attribute for="PromiseRejectionEvent"><code
data-x="dom-PromiseRejectionEvent-promise">promise</code></dfn> attribute must return the value it
was initialized to. It represents the promise which this notification is about.</p>
<p class="note">Because of how Web IDL conversion rules for <code
data-x=""><span data-x="idl-Promise">Promise</span><<var>T</var>></code> types always wrap the input into a new promise, the
<code data-x="dom-PromiseRejectionEvent-promise">promise</code> attribute is of type <code
data-x="idl-object">object</code> instead, which is more appropriate for representing an opaque
handle to the original promise object.</p>
<p>The <dfn attribute for="PromiseRejectionEvent"><code
data-x="dom-PromiseRejectionEvent-reason">reason</code></dfn> attribute must return the value it
was initialized to. It represents the rejection reason for the promise.</p>
<h5>Import map parse results</h5>
<p>An <dfn>import map parse result</dfn> is a <span>struct</span> that is similar to a <span
data-x="concept-script">script</span>, and also can be stored in a <code>script</code> element's
<span data-x="concept-script-result">result</span>, but is not counted as a <span
data-x="concept-script">script</span> for other purposes. It has the following <span
data-x="struct item">items</span>:</p>
<dl>
<dt>An <dfn data-x="impr-import-map">import map</dfn></dt>
<dd>An <span>import map</span> or null.</dd>
<dt>An <dfn data-x="impr-error-to-rethrow">error to rethrow</dfn></dt>
<dd>A JavaScript value representing an error that will prevent using this import map, when
non-null.</dd>
</dl>
<p>To <dfn>create an import map parse result</dfn> given a <span>string</span> <var>input</var>
and a <span>URL</span> <var>baseURL</var>:</p>
<ol>
<li><p>Let <var>result</var> be an <span>import map parse result</span> whose <span
data-x="impr-import-map">import map</span> is null and whose <span
data-x="impr-error-to-rethrow">error to rethrow</span> is null.</p></li>
<li><p><span>Parse an import map string</span> given <var>input</var> and <var>baseURL</var>,
catching any exceptions. If this threw an exception, then set <var>result</var>'s <span
data-x="impr-error-to-rethrow">error to rethrow</span> to that exception. Otherwise, set
<var>result</var>'s <span data-x="impr-import-map">import map</span> to the return
value.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p>To <dfn>register an import map</dfn> given a <code>Window</code> <var>global</var> and an
<span>import map parse result</span> <var>result</var>:</p>
<ol>
<li><p>If <var>result</var>'s <span data-x="impr-error-to-rethrow">error to rethrow</span> is
not null, then <span>report an exception</span> given by <var>result</var>'s <span
data-x="impr-error-to-rethrow">error to rethrow</span> for <var>global</var> and
return.</p></li>
<li><p><span data-x="merge existing and new import maps">Merge existing and new import
maps</span>, given <var>global</var> and <var>result</var>'s <span
data-x="impr-import-map">import map</span>.</p></li>
</ol>
</div>
<h4>Module specifier resolution</h4>
<h5>The resolution algorithm</h5>
<p>The <span>resolve a module specifier</span> algorithm is the primary entry point for
converting module specifier strings into <span data-x="URL">URLs</span>. When no <span
data-x="import map">import maps</span> are involved, it is relatively straightforward, and
reduces to <span>resolving a URL-like module specifier</span>.</p>
<p>When there is a non-empty <span>import map</span> present, the behavior is more complex. It
checks candidate entries from all applicable <span data-x="module specifier map">module specifier
maps</span>, from most-specific to least-specific <span
data-x="concept-import-map-scopes">scopes</span> (falling back to the top-level unscoped <span
data-x="concept-import-map-imports">imports</span>), and from most-specific to least-specific
prefixes. <span w-nodev>For each candidate, the <span data-x="resolving an imports match">resolve
an imports match</span> algorithm will give on the following results:</span></p>
<ul w-nodev> <li><p>Successful resolution of the specifier to a <span>URL</span>. Then the
<span>resolve a module specifier</span> algorithm will return that URL.</p></li>
<li><p>Throwing an exception. Then the <span>resolve a module specifier</span> algorithm will
rethrow that exception, without any further fallbacks.</p></li>
<li><p>Failing to resolve, without an error. In this case the outer <span>resolve a module
specifier</span> algorithm will move on to the next candidate.</p></li>
</ul>
<p>In the end, if no successful resolution is found via any of the candidate <span data-x="module
specifier map">module specifier maps</span>, <span>resolve a module specifier</span> will throw
an exception. Thus the result is always either a <span>URL</span> or a thrown exception.</p>
<div w-nodev>
<p>To <dfn>resolve a module specifier</dfn> given a <span>script</span>-or-null
<var>referringScript</var> and a <span>string</span> <var>specifier</var>:</p>
<ol>
<li><p>Let <var>settingsObject</var> and <var>baseURL</var> be null.</p></li>
<li>
<p>If <var>referringScript</var> is not null, then:</p>
<ol>
<li><p>Set <var>settingsObject</var> to <var>referringScript</var>'s
<span data-x="concept-script-settings-object">settings object</span>.</p></li>
<li><p>Set <var>baseURL</var> to <var>referringScript</var>'s <span
data-x="concept-script-base-url">base URL</span>.</p></li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p><span>Assert</span>: there is a <span>current settings object</span>.</p></li>
<li><p>Set <var>settingsObject</var> to the <span>current settings object</span>.</p></li>
<li><p>Set <var>baseURL</var> to <var>settingsObject</var>'s <span>API base
URL</span>.</p></li>
</ol>
</li>
<li><p>Let <var>importMap</var> be an <span>empty import map</span>.</p></li>
<li><p>If <var>settingsObject</var>'s <span data-x="concept-settings-object-global">global
object</span> implements <code>Window</code>, then set <var>importMap</var> to
<var>settingsObject</var>'s <span data-x="concept-settings-object-global">global object</span>'s
<span data-x="concept-global-import-map">import map</span>.</p></li>
<li><p>Let <var>serializedBaseURL</var> be <var>baseURL</var>, <span
data-x="concept-url-serializer">serialized</span>.</p></li>
<li><p>Let <var>asURL</var> be the result of <span>resolving a URL-like module specifier</span>
given <var>specifier</var> and <var>baseURL</var>.</p></li>
<li><p>Let <var>normalizedSpecifier</var> be the <span
data-x="concept-url-serializer">serialization</span> of <var>asURL</var>, if <var>asURL</var> is
non-null; otherwise, <var>specifier</var>.</p></li>
<li><p>Let <var>result</var> be a <span>URL</span>-or-null, initially null.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>scopePrefix</var> → <var>scopeImports</var>
of <var>importMap</var>'s <span data-x="concept-import-map-scopes">scopes</span>:</p>
<ol>
<li>
<p>If <var>scopePrefix</var> is <var>serializedBaseURL</var>, or if <var>scopePrefix</var> ends
with U+002F (/) and <var>scopePrefix</var> is a <span>code unit prefix</span> of
<var>serializedBaseURL</var>, then:</p>
<ol>
<li><p>Let <var>scopeImportsMatch</var> be the result of <span>resolving an imports
match</span> given <var>normalizedSpecifier</var>, <var>asURL</var>, and
<var>scopeImports</var>.</p></li>
<li><p>If <var>scopeImportsMatch</var> is not null, then set <var>result</var> to
<var>scopeImportsMatch</var>, and <span>break</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>If <var>result</var> is null, set <var>result</var> be the result of <span>resolving an
imports match</span> given <var>normalizedSpecifier</var>, <var>asURL</var>, and
<var>importMap</var>'s <span data-x="concept-import-map-imports">imports</span>.</p></li>
<li>
<p>If <var>result</var> is null, set it to <var>asURL</var>.</p>
<p class="note">By this point, if <var>result</var> was null, <var>specifier</var> wasn't
remapped to anything by <var>importMap</var>, but it might have been able to be turned into a
URL.</p>
</li>
<li>
<p>If <var>result</var> is not null, then:</p>
<ol>
<li><p><span>Add module to resolved module set</span> given <var>settingsObject</var>,
<var>serializedBaseURL</var>, <var>normalizedSpecifier</var>, and <var>asURL</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
</li>
<li><p>Throw a <code>TypeError</code> indicating that <var>specifier</var> was a bare specifier,
but was not remapped to anything by <var>importMap</var>.</p></li>
</ol>
<p>To <dfn data-x="resolving an imports match">resolve an imports match</dfn>, given a
<span>string</span> <var>normalizedSpecifier</var>, a <span>URL</span>-or-null <var>asURL</var>,
and a <span>module specifier map</span> <var>specifierMap</var>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>specifierKey</var> →
<var>resolutionResult</var> of <var>specifierMap</var>:</p>
<ol>
<li>
<p>If <var>specifierKey</var> is <var>normalizedSpecifier</var>, then:</p>
<ol>
<li>
<p>If <var>resolutionResult</var> is null, then throw a <code>TypeError</code> indicating
that resolution of <var>specifierKey</var> was blocked by a null entry.</p>
<p class="note">This will terminate the entire <span>resolve a module specifier</span>
algorithm, without any further fallbacks.</p>
</li>
<li><p><span>Assert</span>: <var>resolutionResult</var> is a <span>URL</span>.</p></li>
<li><p>Return <var>resolutionResult</var>.</p></li>
</ol>
</li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><p><var>specifierKey</var> ends with U+002F (/);</p></li>
<li><p><var>specifierKey</var> is a <span>code unit prefix</span> of
<var>normalizedSpecifier</var>; and</p></li>
<li><p>either <var>asURL</var> is null, or <var>asURL</var> <span>is special</span>,</p></li>
</ul>
<p>then:</p>
<ol>
<li>
<p>If <var>resolutionResult</var> is null, then throw a <code>TypeError</code> indicating
that the resolution of <var>specifierKey</var> was blocked by a null entry.</p>
<p class="note">This will terminate the entire <span>resolve a module specifier</span>
algorithm, without any further fallbacks.</p>
</li>
<li><p><span>Assert</span>: <var>resolutionResult</var> is a <span>URL</span>.</p></li>
<li><p>Let <var>afterPrefix</var> be the portion of <var>normalizedSpecifier</var> after the
initial <var>specifierKey</var> prefix.</p></li>
<li><p><span>Assert</span>: <var>resolutionResult</var>, <span
data-x="concept-url-serializer">serialized</span>, ends with U+002F (/), as enforced during
<span data-x="parse an import map string">parsing</span>.</p></li>
<li><p>Let <var>url</var> be the result of <span data-x="URL parser">URL parsing</span>
<var>afterPrefix</var> with <var>resolutionResult</var>.</p></li>
<li>
<p>If <var>url</var> is failure, then throw a <code>TypeError</code> indicating that
resolution of <var>normalizedSpecifier</var> was blocked since the <var>afterPrefix</var>
portion could not be URL-parsed relative to the <var>resolutionResult</var> mapped to by
the <var>specifierKey</var> prefix.</p>
<p class="note">This will terminate the entire <span>resolve a module specifier</span>
algorithm, without any further fallbacks.</p>
</li>
<li><p><span>Assert</span>: <var>url</var> is a <span>URL</span>.</p></li>
<li>
<p>If the <span data-x="concept-url-serializer">serialization</span> of
<var>resolutionResult</var> is not a <span>code unit prefix</span> of the <span
data-x="concept-url-serializer">serialization</span> of <var>url</var>, then throw a
<code>TypeError</code> indicating that the resolution of <var>normalizedSpecifier</var> was
blocked due to it backtracking above its prefix <var>specifierKey</var>.</p>
<p class="note">This will terminate the entire <span>resolve a module specifier</span>
algorithm, without any further fallbacks.</p>
</li>
<li><p>Return <var>url</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>Return null.</p>
<p class="note">The <span>resolve a module specifier</span> algorithm will fall back to a
less-specific scope, or to "<code data-x="">imports</code>", if possible.</p>
</li>
</ol>
<p>To <dfn data-x="resolving a URL-like module specifier">resolve a URL-like module
specifier</dfn>, given a <span>string</span> <var>specifier</var> and a <span>URL</span>
<var>baseURL</var>:</p>
<ol>
<li>
<p>If <var>specifier</var> <span>starts with</span> "<code data-x="">/</code>", "<code
data-x="">./</code>", or "<code data-x="">../</code>", then:</p>
<ol>
<li><p>Let <var>url</var> be the result of <span data-x="URL parser">URL parsing</span>
<var>specifier</var> with <var>baseURL</var>.</p></li>
<li>
<p>If <var>url</var> is failure, then return null.</p>
<p class="example">One way this could happen is if <var>specifier</var> is "<code
data-x="">../foo</code>" and <var>baseURL</var> is a <code data-x="data
protocol">data:</code> URL.</p>
</li>
<li><p>Return <var>url</var>.</p></li>
</ol>
<p class="note">This includes cases where <var>specifier</var> <span>starts with</span> "<code
data-x="">//</code>", i.e., scheme-relative URLs. Thus, <var>url</var> might end up with a
different <span data-x="concept-url-host">host</span> than <var>baseURL</var>.</p>
</li>
<li><p>Let <var>url</var> be the result of <span data-x="URL parser">URL parsing</span>
<var>specifier</var> (with no base URL).</p></li>
<li><p>If <var>url</var> is failure, then return null.</p></li>
<li><p>Return <var>url</var>.</p>
</ol>
</div>
<h5>Import maps</h5>
<p>An <span subdfn>import map</span> allows control over module specifier resolution. Import maps
are delivered via inline <code>script</code> elements with their <code
data-x="attr-script-type">type</code> attribute set to "<code data-x="">importmap</code>", and
with their <span>child text content</span> containing a JSON representation of the import
map.</p>
<p>A <code>Document</code> can have multiple import maps processed, which can happen either
before or after any modules have been imported, e.g., via <code>import()</code> expressions or
<code>script</code> elements with their <code data-x="attr-script-type">type</code> attribute set
to "<code data-x="">module</code>". The <span>merge existing and new import maps</span> algorithm
ensures that new import maps cannot define the module resolution for modules that were already
defined by past import maps, or for ones that were already resolved.</p>
<div class="example" id="example-import-map-bare-specifier">
<p>The simplest use of import maps is to globally remap a bare module specifier:</p>
<pre><code class="json" data-x="">{
"imports": {
"moment": "/node_modules/moment/src/moment.js"
}
}</code></pre>
<p>This enables statements like <code class="js" data-x="">import moment from "moment";</code>
to work, fetching and evaluating the JavaScript module at the <code
data-x="">/node_modules/moment/src/moment.js</code> URL.</p>
</div>
<div class="example" id="example-import-map-trailing-slashes">
<p>An import map can remap a class of module specifiers into a class of URLs by using trailing
slashes, like so:</p>
<pre><code class="json" data-x="">{
"imports": {
"moment/": "/node_modules/moment/src/"
}
}</code></pre>
<p>This enables statements like <code class="js" data-x="">import localeData from
"moment/locale/zh-cn.js";</code> to work, fetching and evaluating the JavaScript module at the
<code data-x="">/node_modules/moment/src/locale/zh-cn.js</code> URL. Such trailing-slash
mappings are often combined with bare-specifier mappings, e.g.</p>
<pre><code class="json" data-x="">{
"imports": {
"moment": "/node_modules/moment/src/moment.js",
"moment/": "/node_modules/moment/src/"
}
}</code></pre>
<p>so that both the "main module" specified by "<code data-x="">moment</code>" and the
"submodules" specified by paths such as "<code data-x="">moment/locale/zh-cn.js</code>" are
available.</p>
</div>
<div class="example" id="example-import-map-url-like-specifier">
<p>Bare specifiers are not the only type of module specifiers which import maps can remap.
"URL-like" specifiers, i.e., those that are either parseable as absolute URLs or start with
"<code data-x="">/</code>", "<code data-x="">./</code>", or "<code data-x="">../</code>", can be
remapped as well:</p>
<pre><code class="json" data-x="">{
"imports": {
"https://cdn.example.com/vue/dist/vue.runtime.esm.js": "/node_modules/vue/dist/vue.runtime.esm.js",
"/js/app.mjs": "/js/app-8e0d62a03.mjs",
"../helpers/": "https://cdn.example/helpers/"
}
}</code></pre>
<p>Note how the URL to be remapped, as well as the URL being mapped to, can be specified either
as absolute URLs, or as relative URLs starting with "<code data-x="">/</code>", "<code
data-x="">./</code>", or "<code data-x="">../</code>". (They cannot be specified as relative
URLs without those starting sigils, as those help distinguish from bare module specifiers.) Also
note how the <a href="#example-import-map-trailing-slashes">trailing slash mapping</a> works in
this context as well.</p>
<p>Such remappings operate on the post-canonicalization URL, and do not require a match between
the literal strings supplied in the import map key and the imported module specifier. So for
example, if this import map was included on <code data-x="">https://example.com/app.html</code>,
then not only would <code class="js" data-x="">import "/js/app.mjs"</code> be remapped, but so
would <code class="js" data-x="">import "./js/app.mjs"</code> and <code class="js"
data-x="">import "./foo/../js/app.mjs"</code>.</p>
</div>
<div class="example" id="example-import-map-scopes">
<p>All previous examples have globally remapped module specifiers, by using the top-level "<code
data-x="">imports</code>" key in the import map. The top-level "<code data-x="">scopes</code>"
key can be used to provide localized remappings, which only apply when the referring module
matches a specific URL prefix. For example:</p>
<pre><code class="json" data-x="">{
"scopes": {
"/a/" : {
"moment": "/node_modules/moment/src/moment.js"
},
"/b/" : {
"moment": "https://cdn.example.com/moment/src/moment.js"
}
}
}</code></pre>
<p>With this import map, the statement <code data-x="">import "moment"</code> will have
different meanings depending on which referrer script contains the statement:</p>
<ul>
<li><p>Inside scripts located under <code data-x="">/a/</code>, this will import <code
data-x="">/node_modules/moment/src/moment.js</code>.</p></li>
<li><p>Inside scripts located under <code data-x="">/b/</code>, this will import <code
data-x="">https://cdn.example.com/moment/src/moment.js</code>.</p></li>
<li><p>Inside scripts located under <code data-x="">/c/</code>, this will fail to resolve and
thus throw an exception.</p></li>
</ul>
<p>A typical usage of scopes is to allow multiple versions of the "same" module to exist in a
web application, with some parts of the module graph importing one version, and other parts
importing another version.
</div>
<div class="example" id="example-import-map-scopes-overlapping">
<p>Scopes can overlap each other, and overlap the global "<code data-x="">imports</code>"
specifier map. At resolution time, scopes are consulted in order of most- to least-specific,
where specificity is measured by sorting the scopes using the <span>code unit less than</span>
operation. So, for example, "<code data-x="">/scope2/scope3/</code>" is treated as more specific
than "<code data-x="">/scope2/</code>", which is treated as more specific than the top-level
(unscoped) mappings.</p>
<p>The following import map illustrates this:</p>
<pre><code class="json" data-x="">{
"imports": {
"a": "/a-1.mjs",
"b": "/b-1.mjs",
"c": "/c-1.mjs"
},
"scopes": {
"/scope2/": {
"a": "/a-2.mjs"
},
"/scope2/scope3/": {
"b": "/b-3.mjs"
}
}
}</code></pre>
<p>This results in the following resolutions (using relative URLs for brevity):</p>
<table id="table-import-map-scopes-example">
<thead>
<tr>
<td colspan="2" rowspan="2">
<th colspan="3">Specifier
<tr>
<th>"<code data-x="">a</code>"
<th>"<code data-x="">b</code>"
<th>"<code data-x="">c</code>"
<tbody>
<tr>
<th rowspan="3">Referrer
<th><code data-x="">/scope1/r.mjs</code>
<td><code data-x="">/a-1.mjs</code>
<td><code data-x="">/b-1.mjs</code>
<td><code data-x="">/c-1.mjs</code>
<tr>
<th><code data-x="">/scope2/r.mjs</code>
<td><code data-x="">/a-2.mjs</code>
<td><code data-x="">/b-1.mjs</code>
<td><code data-x="">/c-1.mjs</code>
<tr>
<th><code data-x="">/scope2/scope3/r.mjs</code>
<td><code data-x="">/a-2.mjs</code>
<td><code data-x="">/b-3.mjs</code>
<td><code data-x="">/c-1.mjs</code>
</table>
</div>
<div class="example" id="example-import-map-integrity">
<p>Import maps can also be used to provide modules with integrity metadata to be used in
<cite>Subresource Integrity</cite> checks. <ref>SRI</ref>
</p>
<p>The following import map illustrates this:</p>
<pre><code class="json" data-x="">{
"imports": {
"a": "/a-1.mjs",
"b": "/b-1.mjs",
"c": "/c-1.mjs"
},
"integrity": {
"/a-1.mjs": "sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7",
"/d-1.mjs": "sha384-MBO5IDfYaE6c6Aao94oZrIOiC6CGiSN2n4QUbHNPhzk5Xhm0djZLQqTpL0HzTUxk"
}
}</code></pre>
<p>The above example provides integrity metadata to be enforced on the modules <code
data-x="">/a-1.mjs</code> and <code data-x="">/d-1.mjs</code>, even if the latter is not defined
as an import in the map.</p>
</div>
<hr>
<p>The <span>child text content</span> of a <code>script</code> element representing an
<span>import map</span> must match the following <dfn>import map authoring
requirements</dfn>:</p>
<ul>
<li><p>It must be valid JSON. <ref>JSON</ref></p></li>
<li><p>The JSON must represent a JSON object, with at most the three keys "<code
data-x="">imports</code>", "<code data-x="">scopes</code>", and "<code
data-x="">integrity</code>".</p></li>
<li><p>The values corresponding to the "<code data-x="">imports</code>", "<code
data-x="">scopes</code>", and "<code data-x="">integrity</code>" keys, if present,
must themselves be JSON objects.</p></li>
<li><p>The value corresponding to the "<code data-x="">imports</code>" key, if present, must be
a <span>valid module specifier map</span>.</p></li>
<li><p>The value corresponding to the "<code data-x="">scopes</code>" key, if present, must be a
JSON object, whose keys are <span data-x="valid URL string">valid URL strings</span> and whose
values are <span data-x="valid module specifier map">valid module specifier
maps</span>.</p></li>
<li><p>The value corresponding to the "<code data-x="">integrity</code>" key, if present, must
be a JSON object, whose keys are <span data-x="valid URL string">valid URL strings</span> and
whose values fit <span>the requirements of the integrity attribute</span>.</p></li>
</ul>
<p>A <dfn>valid module specifier map</dfn> is a JSON object that meets the following
requirements:</p>
<ul>
<li><p>All of its keys must be nonempty.</p></li>
<li><p>All of its values must be strings.</p></li>
<li><p>Each value must be either a <span data-x="absolute URL">valid absolute URL</span> or a
<span>valid URL string</span> that <span>starts with</span> "<code data-x="">/</code>", "<code
data-x="">./</code>", or "<code data-x="">../</code>".</p></li>
<li><p>If a given key <span>ends with</span> "<code data-x="">/</code>", then the corresponding
value must also.</p></li>
</ul>
<div w-nodev>
<h5>Import map processing model</h5>
<p>Formally, an <dfn>import map</dfn> is a <span>struct</span> with three <span data-x="struct
item">items</span>:</p>
<ul>
<li><p><dfn data-x="concept-import-map-imports">imports</dfn>, a <span>module specifier
map</span>;</p></li>
<li><p><dfn data-x="concept-import-map-scopes">scopes</dfn>, an <span>ordered map</span> of
<span data-x="URL">URLs</span> to <span data-x="module specifier map">module specifier
maps</span>; and</p></li>
<li><p><dfn data-x="concept-import-map-integrity">integrity</dfn>, a <span>module integrity
map</span>.</p></li>
</ul>
<p>A <dfn>module specifier map</dfn> is an <span>ordered map</span> whose <span data-x="map
key">keys</span> are <span data-x="string">strings</span> and whose <span data-x="map
value">values</span> are either <span data-x="URL">URLs</span> or nulls.</p>
<p>A <dfn>module integrity map</dfn> is an <span>ordered map</span> whose <span data-x="map
key">keys</span> are <span data-x="URL">URLs</span> and whose <span data-x="map
value">values</span> are <span data-x="string">strings</span> that will be used as <span
data-x="concept-request-integrity-metadata">integrity metadata</span>.</p>
<p>An <dfn>empty import map</dfn> is an <span>import map</span> with its <span
data-x="concept-import-map-imports">imports</span> and <span
data-x="concept-import-map-scopes">scopes</span> both being empty maps.</p>
<hr>
<p>A <dfn>specifier resolution record</dfn> is a <span>struct</span>. It has the following <span
data-x="struct item">items</span>:</p>
<dl>
<dt>A <dfn data-x="specifier-resolution-record-serialized-base-url">serialized base
URL</dfn></dt>
<dd>A <span>string</span>-or-null that represents the base URL of the specifier, when one
exists.</dd>
<dt>A <dfn data-x="specifier-resolution-record-specifier">specifier</dfn></dt>
<dd>A <span>string</span> representing the specifier.</dd>
<dt>A <dfn data-x="specifier-resolution-record-as-url">specifier as a URL</dfn></dt>
<dd>A <span>URL</span>-or-null that represents the URL in case of a URL-like module
specifier.</dd>
</dl>
<p class="note">Implementations can replace
<span data-x="specifier-resolution-record-as-url">specifier as a URL</span> with a boolean that
indicates that the specifier is either bare or URL-like that <span>is special</span>.</p>
<p>To <dfn>add module to resolved module set</dfn> given an <span>environment settings
object</span> <var>settingsObject</var>, a <span>string</span> <var>serializedBaseURL</var>, a
<span>string</span> <var>normalizedSpecifier</var>, and a <span>URL</span>-or-null
<var>asURL</var>:</p>
<ol>
<li><p>Let <var>global</var> be <var>settingsObject</var>'s <span
data-x="concept-settings-object-global">global object</span>.</p></li>
<li><p>If <var>global</var> does not implement <code>Window</code>, then return.</p></li>
<li><p>Let <var>record</var> be a new <span>specifier resolution record</span>, with <span
data-x="specifier-resolution-record-serialized-base-url">serialized base URL</span> set to
<var>serializedBaseURL</var>, <span
data-x="specifier-resolution-record-specifier">specifier</span> set to
<var>normalizedSpecifier</var>, and <span
data-x="specifier-resolution-record-as-url">specifier as a URL</span> set to
<var>asURL</var>.</p></li>
<li><p><span data-x="set append">Append</span> <var>record</var> to <var>global</var>'s
<span>resolved module set</span>.</p></li>
</ol>
<hr>
<p>To <dfn>parse an import map string</dfn>, given a <span>string</span> <var>input</var> and a
<span>URL</span> <var>baseURL</var>:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span data-x="parse a JSON string to an Infra
value">parsing a JSON string to an Infra value</span> given <var>input</var>.</p></li>
<li><p>If <var>parsed</var> is not an <span>ordered map</span>, then throw a
<code>TypeError</code> indicating that the top-level value needs to be a JSON object.</p></li>
<li><p>Let <var>sortedAndNormalizedImports</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p>If <var>parsed</var>["<code data-x="">imports</code>"] <span data-x="map
exists">exists</span>, then:</p>
<ol>
<li><p>If <var>parsed</var>["<code data-x="">imports</code>"] is not an <span>ordered
map</span>, then throw a <code>TypeError</code> indicating that the value for the "<code
data-x="">imports</code>" top-level key needs to be a JSON object.</p></li>
<li><p>Set <var>sortedAndNormalizedImports</var> to the result of <span>sorting and
normalizing a module specifier map</span> given <var>parsed</var>["<code
data-x="">imports</code>"] and <var>baseURL</var>.</p></li>
</ol>
</li>
<li><p>Let <var>sortedAndNormalizedScopes</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p>If <var>parsed</var>["<code data-x="">scopes</code>"] <span data-x="map
exists">exists</span>, then:</p>
<ol>
<li><p>If <var>parsed</var>["<code data-x="">scopes</code>"] is not an <span>ordered
map</span>, then throw a <code>TypeError</code> indicating that the value for the "<code
data-x="">scopes</code>" top-level key needs to be a JSON object.</p></li>
<li><p>Set <var>sortedAndNormalizedScopes</var> to the result of <span>sorting and normalizing
scopes</span> given <var>parsed</var>["<code data-x="">scopes</code>"] and
<var>baseURL</var>.</p></li>
</ol>
</li>
<li><p>Let <var>normalizedIntegrity</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p>If <var>parsed</var>["<code data-x="">integrity</code>"] <span data-x="map
exists">exists</span>, then:</p>
<ol>
<li><p>If <var>parsed</var>["<code data-x="">integrity</code>"] is not an <span>ordered
map</span>, then throw a <code>TypeError</code> indicating that the value for the "<code
data-x="">integrity</code>" top-level key needs to be a JSON object.</p></li>
<li><p>Set <var>normalizedIntegrity</var> to the result of <span>normalizing a module
integrity map</span> given <var>parsed</var>["<code data-x="">integrity</code>"] and
<var>baseURL</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>parsed</var>'s <span data-x="map key">keys</span> <span data-x="list
contains">contains</span> any items besides "<code data-x="">imports</code>", "<code
data-x="">scopes</code>", or "<code data-x="">integrity</code>", then the user agent should
<span>report a warning to the console</span> indicating that an invalid top-level key was
present in the import map.</p>
<p class="note">This can help detect typos. It is not an error, because that would prevent any
future extensions from being added backward-compatibly.</p>
</li>
<li><p>Return an <span>import map</span> whose <span
data-x="concept-import-map-imports">imports</span> are <var>sortedAndNormalizedImports</var>,
whose <span data-x="concept-import-map-scopes">scopes</span> are
<var>sortedAndNormalizedScopes</var>, and whose <span
data-x="concept-import-map-integrity">integrity</span> are
<var>normalizedIntegrity</var>.</p></li>
</ol>
<div class="example" id="example-import-map-normalization">
<p>The <span>import map</span> that results from this parsing algorithm is highly normalized.
For example, given a base URL of <code data-x="">https://example.com/base/page.html</code>, the
input</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/helper": "node_modules/helper/index.mjs",
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
<p>will generate an <span>import map</span> with <span
data-x="concept-import-map-imports">imports</span> of</p>
<pre><code data-x="">«[
"https://example.com/app/helper" → https://example.com/base/node_modules/helper/index.mjs
"lodash" → https://example.com/node_modules/lodash-es/lodash.js
]»</code></pre>
<p>and (despite nothing being present in the input string) an empty <span>ordered map</span> for
its <span data-x="concept-import-map-scopes">scopes</span>.</p>
</div>
<hr>
<p>To <dfn>merge module specifier maps</dfn>, given a <span>module specifier map</span>
<var>newMap</var> and a <span>module specifier map</span> <var>oldMap</var>:</p>
<ol>
<li><p>Let <var>mergedMap</var> be a deep copy of <var>oldMap</var>.</p></li>
<!-- XXX "deep copy" ought to be defined. -->
<li>
<p><span data-x="map iterate">For each</span> <var>specifier</var> →
<var>url</var> of <var>newMap</var>:</p>
<ol>
<li>
<p>If <var>specifier</var> <span data-x="map exists">exists</span> in
<var>oldMap</var>, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating the
ignored rule. They may choose to avoid reporting if the rule is identical to an existing
one.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Set <var>mergedMap</var>[<var>specifier</var>] to <var>url</var>.</p></li>
</ol>
</li>
<li><p>Return <var>mergedMap</var>.</p></li>
</ol>
<p>To <dfn data-x="merge existing and new import maps">merge existing and new import maps</dfn>,
given a <span data-x="concept-settings-object-global">global object</span> <var>global</var> and
an <span>import map</span> <var>newImportMap</var>:</p>
<ol>
<li>
<p>Let <var>newImportMapScopes</var> be a deep copy of <var>newImportMap</var>'s <span
data-x="concept-import-map-scopes">scopes</span>.</p>
<p class="note">We're mutating these copies and removing items from them when they are used to
ignore scope-specific rules. This is true for <var>newImportMapScopes</var>, as well as to
<var>newImportMapImports</var> below.</p>
</li>
<li><p>Let <var>oldImportMap</var> be <var>global</var>'s <span
data-x="concept-global-import-map">import map</span>.</p></li>
<li><p>Let <var>newImportMapImports</var> be a deep copy of <var>newImportMap</var>'s <span
data-x="concept-import-map-imports">imports</span>.</p></li>
<!-- XXX "deep copy" ought to be defined. -->
<li>
<p><span data-x="map iterate">For each</span> <var>scopePrefix</var> →
<var>scopeImports</var> of <var>newImportMapScopes</var>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>record</var> of <var>global</var>'s
<span>resolved module set</span>:</p>
<ol>
<li>
<p>If <var>scopePrefix</var> is <var>record</var>'s <span
data-x="specifier-resolution-record-serialized-base-url">serialized base URL</span>, or if
<var>scopePrefix</var> ends with U+002F (/) and <var>scopePrefix</var> is a <span>code unit
prefix</span> of <var>record</var>'s <span
data-x="specifier-resolution-record-serialized-base-url">serialized base URL</span>,
then:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>specifierKey</var> →
<var>resolutionResult</var> of <var>scopeImports</var>:</p>
<ol>
<li>
<p>If <var>specifierKey</var> is <var>record</var>'s <span
data-x="specifier-resolution-record-specifier">specifier</span>, or if all of the
following conditions are true:</p>
<ul>
<li><p><var>specifierKey</var> ends with U+002F (/);</p></li>
<li><p><var>specifierKey</var> is a <span>code unit prefix</span> of
<var>record</var>'s <span
data-x="specifier-resolution-record-specifier">specifier</span>;</p></li>
<li><p>either <var>record</var>'s <span
data-x="specifier-resolution-record-as-url">specifier as a URL</span> is null or
<span>is special</span>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating the
ignored rule. They may choose to avoid reporting if the rule is identical to an existing
one.</p></li>
<li><p>Remove <var>scopeImports</var>[<var>specifierKey</var>].</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
</ol>
<p class="note">Implementers are encouraged to implement a more efficient matching
algorithm when working with the <span>resolved module set</span>. As guidance, the number of
resolved/mapped modules in a large application can be on the order of thousands.</p>
</li>
<li><p>If <var>scopePrefix</var> <span data-x="map exists">exists</span> in
<var>oldImportMap</var>'s <span data-x="concept-import-map-scopes">scopes</span>, then
set <var>oldImportMap</var>'s <span
data-x="concept-import-map-scopes">scopes</span>[<var>scopePrefix</var>] to the result of
<span data-x="merge module specifier maps">merging module specifier maps</span>, given
<var>scopeImports</var> and <var>oldImportMap</var>'s <span
data-x="concept-import-map-scopes">scopes</span>[<var>scopePrefix</var>].</p></li>
<li><p>Otherwise, set <var>oldImportMap</var>'s <span
data-x="concept-import-map-scopes">scopes</span>[<var>scopePrefix</var>] to
<var>scopeImports</var>.</p></li>
</ol>
</li>
<li>
<p><span data-x="map iterate">For each</span> <var>url</var> →
<var>integrity</var> of <var>newImportMap</var>'s <span
data-x="concept-import-map-integrity">integrity</span>:</p>
<ol>
<li>
<p>If <var>url</var> <span data-x="map exists">exists</span> in <var>oldImportMap</var>'s
<span data-x="concept-import-map-integrity">integrity</span>, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating the
ignored rule. They may choose to avoid reporting if the rule is identical to an existing
one.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Set <var>oldImportMap</var>'s <span
data-x="concept-import-map-integrity">integrity</span>[<var>url</var>] to
<var>integrity</var>.</p></li>
</ol>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>record</var> of <var>global</var>'s
<span>resolved module set</span>:</p>
<ol>
<li>
<p><span data-x="list iterate">For each</span> <var>specifier</var> → <var>url</var> of
<var>newImportMapImports</var>:</p>
<ol>
<li>
<p>If <var>specifier</var> <span>starts with</span> <var>record</var>'s <span
data-x="specifier-resolution-record-specifier">specifier</span>, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating the
ignored rule. They may choose to avoid reporting if the rule is identical to an existing
one.</p></li>
<li><p>Remove <var>newImportMapImports</var>[<var>specifier</var>].</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li><p>Set <var>oldImportMap</var>'s <span data-x="concept-import-map-imports">imports</span> to
the result of <span data-x="merge module specifier maps">merge module specifier maps</span>,
given <var>newImportMapImports</var> and <var>oldImportMap</var>'s <span
data-x="concept-import-map-imports">imports</span>.</p></li>
</ol>
<p>The above algorithm merges a new import map into the given <span>environment settings
object</span>'s <span>global object</span>'s <span>import map</span>. Let's examine a few
examples:</p>
<div class="example" id="example-import-map-merge-unrelated">
<p>There are two cases when rules of the new import map don't get merged into the existing
one.</p>
<ol>
<li><p>The new import map rule has the exact same scope and specifier as a rule in the existing
import map. We'll call that "conflicting rule".</p></li>
<li><p>The new import map rule may impact the resolution of an already resolved module. We'll
call that "impacted already resolved module".</p></li>
</ol>
<p>When the new import map has no conflicting rules, and there are no impacted resolved modules,
the resulting map would be a combination of the new and existing maps. Rules that would have
individually impacted similar modules (e.g. "/app/" and "/app/helper") but are not an exact
match are not conflicting, and all make it to the merged map.</p>
<p>So, the following existing and new import maps:</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/": "./original-app/",
}
}</code>
<code class="json" data-x="">{
"imports": {
"/app/helper": "./helper/index.mjs"
},
"scopes": {
"/js": {
"/app/": "./js-app/"
}
}
}</code></pre>
<p>Would be equivalent to the following single import map:</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/": "./original-app/",
"/app/helper": "./helper/index.mjs"
},
"scopes": {
"/js": {
"/app/": "./js-app/"
}
}
}</code></pre>
</div>
<div class="example" id="example-import-map-merge-conflict-imports">
<p>When the new import map impacts an already resolved module, that rule gets dropped from the
import map.</p>
<p>So, if the <span>resolved module set</span> already contains the "<code
data-x="">/app/helper</code>", the following new import map:</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/helper": "./helper/index.mjs",
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
<p>Would be equivalent to the following one:</p>
<pre><code class="json" data-x="">{
"imports": {
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
</div>
<div class="example" id="example-import-map-merge-conflict-scopes">
<p>The same is true for rules that impact already resolved modules defined in specific scopes.
If we already resolved "<code data-x="">/app/helper</code>" from "<code
data-x="">/app/main.mjs</code>" the following new import map:</p>
<pre><code class="json" data-x="">{
"scopes": {
"/app/": {
"/app/helper": "./helper/index.mjs"
}
},
"imports": {
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
<p>Would similarly be equivalent to:</p>
<pre><code class="json" data-x="">{
"imports": {
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
</div>
<div class="example" id="example-import-map-merge-conflict-imports-and-scopes">
<p>We could also have cases where a single already-resolved module specifier has multiple rules
for its resolution, depending on the referring script. In such cases, only the relevant rules
would not be added to the map.</p>
<p>For example, if we already resolved "<code data-x="">/app/helper</code>" from "<code
data-x="">/app/vendor/main.mjs</code>", the following new import map:</p>
<pre><code class="json" data-x="">{
"scopes": {
"/app/": {
"/app/helper": "./helper/index.mjs"
},
"/app/vendor/": {
"/app/": "./vendor_helper/"
},
"/vendor/": {
"/app/helper": "./helper/vendor_index.mjs"
}
},
"imports": {
"lodash": "/node_modules/lodash-es/lodash.js"
"/app/": "./general_app_path/"
"/app/helper": "./other_path/helper/index.mjs"
}
}</code></pre>
<p>Would be equivalent to:</p>
<pre><code class="json" data-x="">{
"scopes": {
"/vendor/": {
"/app/helper": "./helper/vendor_index.mjs"
}
},
"imports": {
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code></pre>
<p>This is achieved by the fact that the merge algorithm tracks already resolved modules
and removes rules affecting them from new import maps before they are merged into the existing
one.</p>
</div>
<div class="example" id="example-import-map-merge-two-map-conflict">
<p>When the new import map has conflicting rules to the existing import map, with no impacted
already resolved modules, the existing import map rules persist.</p>
<p>For example, the following existing and new import maps:</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/helper": "./helper/index.mjs",
"lodash": "/node_modules/lodash-es/lodash.js"
}
}</code>
<code class="json" data-x="">{
"imports": {
"/app/helper": "./main/helper/index.mjs"
}
}</code></pre>
<p>Would be equivalent to the following single import map:</p>
<pre><code class="json" data-x="">{
"imports": {
"/app/helper": "./helper/index.mjs",
"lodash": "/node_modules/lodash-es/lodash.js",
}
}</code></pre>
</div>
<p>To <dfn data-x="sorting and normalizing a module specifier map">sort and normalize a module
specifier map</dfn>, given an <span>ordered map</span> <var>originalMap</var> and a
<span>URL</span> <var>baseURL</var>:</p>
<ol>
<li><p>Let <var>normalized</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>specifierKey</var> → <var>value</var> of
<var>originalMap</var>:</p>
<ol>
<li><p>Let <var>normalizedSpecifierKey</var> be the result of <span>normalizing a specifier
key</span> given <var>specifierKey</var> and <var>baseURL</var>.</p></li>
<li><p>If <var>normalizedSpecifierKey</var> is null, then <span>continue</span>.</p></li>
<li>
<p>If <var>value</var> is not a <span>string</span>, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that
addresses need to be strings.</p></li>
<li><p>Set <var>normalized</var>[<var>normalizedSpecifierKey</var>] to null.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Let <var>addressURL</var> be the result of <span>resolving a URL-like module
specifier</span> given <var>value</var> and <var>baseURL</var>.</p></li>
<li>
<p>If <var>addressURL</var> is null, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that the
address was invalid.</p></li>
<li><p>Set <var>normalized</var>[<var>normalizedSpecifierKey</var>] to null.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li>
<p>If <var>specifierKey</var> ends with U+002F (/), and the <span
data-x="concept-url-serializer">serialization</span> of <var>addressURL</var> does not end
with U+002F (/), then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that an
invalid address was given for the specifier key <var>specifierKey</var>; since
<var>specifierKey</var> ends with a slash, the address needs to as well.</p></li>
<li><p>Set <var>normalized</var>[<var>normalizedSpecifierKey</var>] to null.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Set <var>normalized</var>[<var>normalizedSpecifierKey</var>] to
<var>addressURL</var>.</p></li>
</ol>
</li>
<li><p>Return the result of <span data-x="map sort descending">sorting in descending order</span>
<var>normalized</var>, with an entry <var>a</var> being less than an entry <var>b</var> if
<var>a</var>'s <span data-x="map key">key</span> is <span>code unit less than</span>
<var>b</var>'s <span data-x="map key">key</span>.</p></li>
</ol>
<p>To <dfn data-x="sorting and normalizing scopes">sort and normalize scopes</dfn>, given an
<span>ordered map</span> <var>originalMap</var> and a <span>URL</span> <var>baseURL</var>:</p>
<ol>
<li><p>Let <var>normalized</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>scopePrefix</var> →
<var>potentialSpecifierMap</var> of <var>originalMap</var>:</p>
<ol>
<li><p>If <var>potentialSpecifierMap</var> is not an <span>ordered map</span>, then throw a
<code>TypeError</code> indicating that the value of the scope with prefix
<var>scopePrefix</var> needs to be a JSON object.</p></li>
<li><p>Let <var>scopePrefixURL</var> be the result of <span data-x="URL parser">URL
parsing</span> <var>scopePrefix</var> with <var>baseURL</var>.</p></li>
<li>
<p>If <var>scopePrefixURL</var> is failure, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> that the scope prefix
URL was not parseable.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Let <var>normalizedScopePrefix</var> be the <span
data-x="concept-url-serializer">serialization</span> of <var>scopePrefixURL</var>.</p></li>
<li><p>Set <var>normalized</var>[<var>normalizedScopePrefix</var>] to the result of
<span>sorting and normalizing a module specifier map</span> given
<var>potentialSpecifierMap</var> and <var>baseURL</var>.</p></li>
</ol>
</li>
<li><p>Return the result of <span data-x="map sort descending">sorting in descending
order</span> <var>normalized</var>, with an entry <var>a</var> being less than an entry
<var>b</var> if <var>a</var>'s <span data-x="map key">key</span> is <span>code unit less
than</span> <var>b</var>'s <span data-x="map key">key</span>.</p></li>
</ol>
<p class="note">In the above two algorithms, sorting keys and scopes in descending order has the
effect of putting "<code data-x="">foo/bar/</code>" before "<code data-x="">foo/</code>". This in
turn gives "<code data-x="">foo/bar/</code>" a higher priority than "<code data-x="">foo/</code>"
during <span data-x="resolve a module specifier">module specifier resolution</span>.</p>
<p>To <dfn data-x="normalizing a module integrity map">normalize a module integrity map</dfn>,
given an <span>ordered map</span> <var>originalMap</var>:</p>
<ol>
<li><p>Let <var>normalized</var> be an empty <span>ordered map</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>key</var> → <var>value</var> of
<var>originalMap</var>:</p>
<ol>
<li>
<p>Let <var>resolvedURL</var> be the result of <span>resolving a URL-like module
specifier</span> given <var>key</var> and <var>baseURL</var>.</p>
<p class="note">Unlike "<code data-x="">imports</code>", keys of the integrity map are treated
as URLs, not module specifiers. However, we use the <span data-x="resolving a URL-like module
specifier">resolve a URL-like module specifier</span> algorithm to prohibit "bare" relative
URLs like <code data-x="">foo</code>, which could be mistaken for module specifiers.</p>
</li>
<li>
<p>If <var>resolvedURL</var> is null, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that
the key failed to resolve.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li>
<p>If <var>value</var> is not a <span>string</span>, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that
<span data-x="concept-request-integrity-metadata">integrity metadata</span> values need to
be <span data-x="string">strings</span>.</p></li>
<li><p><span>Continue</span>.</p></li>
</ol>
</li>
<li><p>Set <var>normalized</var>[<var>resolvedURL</var>] to <var>value</var>.</p></li>
</ol>
</li>
<li><p>Return <var>normalized</var>.</p></li>
</ol>
<p>To <dfn data-x="normalizing a specifier key">normalize a specifier key</dfn>, given a <span>string</span> <var>specifierKey</var> and a <span>URL</span> <var>baseURL</var>:</p>
<ol>
<li>
<p>If <var>specifierKey</var> is the empty string, then:</p>
<ol>
<li><p>The user agent may <span>report a warning to the console</span> indicating that specifier keys may not be the empty string.</p></li>
<li><p>Return null.</p></li>
</ol>
</li>
<li><p>Let <var>url</var> be the result of <span>resolving a URL-like module specifier</span>, given <var>specifierKey</var> and <var>baseURL</var>.</p></li>
<li><p>If <var>url</var> is not null, then return the <span data-x="concept-url-serializer">serialization</span> of <var>url</var>.</p></li>
<li><p>Return <var>specifierKey</var>.</p></li>
</ol>
<h4>JavaScript specification host hooks</h4>
<p>The JavaScript specification contains a number of <span>implementation-defined</span> abstract
operations, that vary depending on the host environment. This section defines them for user
agent hosts.</p>
<h5 id="the-hostensurecanaddprivateelement-implementation"><dfn>HostEnsureCanAddPrivateElement</dfn>(<var>O</var>)</h5>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostEnsureCanAddPrivateElement">HostEnsureCanAddPrivateElement</span>(<var>O</var>)
abstract operation. User agents must use the following implementation: <ref>JAVASCRIPT</ref>
<ol>
<li><p>If <var>O</var> is a <code>WindowProxy</code> object, or <span>implements</span>
<code>Location</code>, then return Completion { [[Type]]: throw, [[Value]]: a new
<code>TypeError</code> }.</li>
<li><p>Return <span>NormalCompletion</span>(unused).</p></li>
</ol>
<p class="note">JavaScript private fields can be applied to arbitrary objects. Since this can
dramatically complicate implementation for particularly-exotic host objects, the JavaScript
language specification provides this hook to allow hosts to reject private fields on objects
meeting a host-defined criteria. In the case of HTML, <code>WindowProxy</code> and
<code>Location</code> have complicated semantics — particularly around navigation and
security — that make implementation of private field semantics challenging, so our
implementation simply rejects those objects.</p>
<h5><dfn
data-x="the-hostensurecancompilestrings-implementation">HostEnsureCanCompileStrings</dfn>(<var>realm</var>,
<var>parameterStrings</var>, <var>bodyString</var>, <var>codeString</var>, <var>compilationType</var>,
<var>parameterArgs</var>, <var>bodyArg</var>)</h5>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostEnsureCanCompileStrings">HostEnsureCanCompileStrings</span> abstract operation,
redefined by the <cite>Dynamic Code Brand Checks</cite> proposal. User agents must use
the following implementation: <ref>JAVASCRIPT</ref> <ref>JSDYNAMICCODEBRANDCHECKS</ref>
<ol>
<li><p>Perform ? <span
data-x="csp-EnsureCSPDoesNotBlockStringCompilation">EnsureCSPDoesNotBlockStringCompilation</span>(<var>realm</var>,
<var>parameterStrings</var>, <var>bodyString</var>, <var>codeString</var>,
<var>compilationType</var>, <var>parameterArgs</var>, <var>bodyArg</var>).
<ref>CSP</ref></p></li>
</ol>
<h5><dfn
data-x="the-hostgetcodeforeval-implementation">HostGetCodeForEval</dfn>(<var>argument</var>)</h5>
<p>The <cite>Dynamic Code Brand Checks</cite> proposal contains an
<span>implementation-defined</span> <span
data-x="js-HostGetCodeForEval">HostGetCodeForEval</span>(<var>argument</var>) abstract operation.
User agents must use the following implementation: <ref>JSDYNAMICCODEBRANDCHECKS</ref>
<ol>
<li><p>If <var>argument</var> is a <code data-x="tt-trustedscript">TrustedScript</code> object,
then return <var>argument</var>'s <span data-x="tt-trustedscript-data">data</span>.</p></li>
<li><p>Otherwise, return no-code.</p></li>
</ol>
<h5 id="the-hostpromiserejectiontracker-implementation"><dfn>HostPromiseRejectionTracker</dfn>(<var>promise</var>, <var>operation</var>)</h5>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostPromiseRejectionTracker">HostPromiseRejectionTracker</span>(<var>promise</var>,
<var>operation</var>) abstract operation. User agents must use the following implementation:
<ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>script</var> be the <span>running script</span>.</p></li>
<li><p>If <var>script</var> is a <span>classic script</span> and <var>script</var>'s <span>muted
errors</span> is true, then return.</p></li>
<li><p>Let <var>settingsObject</var> be the <span>current settings object</span>.</p></li>
<li><p>If <var>script</var> is not null, then set <var>settingsObject</var> to
<var>script</var>'s <span data-x="concept-script-settings-object">settings
object</span>.</p></li>
<li><p>Let <var>global</var> be <var>settingsObject</var>'s <span
data-x="concept-settings-object-global">global object</span>.</p></li>
<li>
<p>If <var>operation</var> is "<code data-x="">reject</code>", then:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>promise</var> to <var>global</var>'s
<span>about-to-be-notified rejected promises list</span>.</p></li>
</ol>
</li>
<li>
<p>If <var>operation</var> is "<code data-x="">handle</code>", then:</p>
<ol>
<li><p>If <var>global</var>'s <span>about-to-be-notified rejected promises list</span> <span
data-x="list contains">contains</span> <var>promise</var>, then <span data-x="list
remove">remove</span> <var>promise</var> from that list and return.</p></li>
<li><p>If <var>global</var>'s <span>outstanding rejected promises weak set</span> does not
<span data-x="list contains">contain</span> <var>promise</var>, then return.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>promise</var> from <var>global</var>'s
<span>outstanding rejected promises weak set</span>.</p></li>
<li><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>global</var> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-rejectionhandled">rejectionhandled</code> at <var>global</var>, using
<code>PromiseRejectionEvent</code>, with the <code
data-x="dom-PromiseRejectionEvent-promise">promise</code> attribute initialized to
<var>promise</var>, and the <code data-x="dom-PromiseRejectionEvent-reason">reason</code>
attribute initialized to <var>promise</var>.[[PromiseResult]].</p></li>
</ol>
</li>
</ol>
<h5 id="hostsystemutcepochnanoseconds"><dfn>HostSystemUTCEpochNanoseconds</dfn>(<var>global</var>)</h5>
<p>The Temporal proposal contains an <span>implementation-defined</span> <span
data-x="js-HostSystemUTCEpochNanoseconds">HostSystemUTCEpochNanoseconds</span> abstract operation.
User agents must use the following implementation: <ref>JSTEMPORAL</ref></p>
<ol>
<li><p>Let <var>settingsObject</var> be <var>global</var>'s <span>relevant settings
object</span>.</p></li>
<li><p>Let <var>time</var> be <var>settingsObject</var>'s <span>current wall
time</span>.</p></li>
<li><p>Let <var>ns</var> be the number of nanoseconds from the <span>Unix epoch</span> to
<var>time</var>, rounded to the nearest integer.</p></li>
<li><p>Return the result of <span>clamping</span> <var>ns</var> between
<span>nsMinInstant</span> and <span>nsMaxInstant</span>.</p></li>
</ol>
<h5 id="integration-with-javascript-jobs">Job-related host hooks</h5>
<p>The JavaScript specification defines Jobs to be scheduled and run later by the host, as well as
<span data-x="JobCallback Record">JobCallback Records</span> which encapsulate JavaScript
functions that are called as part of jobs. The JavaScript specification contains a number of
<span>implementation-defined</span> abstract operations that lets the host define how jobs are
scheduled and how JobCallbacks are handled. HTML uses these abstract operations to <span
id="incumbent-settings-object-tracking-in-promises">track the <span>incumbent settings
object</span> in promises and <code>FinalizationRegistry</code> callbacks</span> by saving and
restoring the <span>incumbent settings object</span> and a <span>JavaScript execution
context</span> for the <span>active script</span> in JobCallbacks. This section defines them for
user agent hosts.</p>
<h6 id="hostcalljobcallback"><dfn>HostCallJobCallback</dfn>(<var>callback</var>, <var>V</var>,
<var>argumentsList</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostCallJobCallback">HostCallJobCallback</span>(<var>callback</var>, <var>V</var>,
<var>argumentsList</var>) abstract operation to let hosts restore state when invoking JavaScript
callbacks from inside tasks. User agents must use the following implementation:
<ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>incumbent settings</var> be
<var>callback</var>.[[HostDefined]].[[IncumbentSettings]].</p></li>
<li><p>Let <var>script execution context</var> be
<var>callback</var>.[[HostDefined]].[[ActiveScriptContext]].</li>
<li>
<p><span>Prepare to run a callback</span> with <var>incumbent settings</var>.</p>
<p class="note">This affects the <span data-x="concept-incumbent-everything">incumbent</span>
concept while the callback runs.</p>
</li>
<li>
<p>If <var>script execution context</var> is not null, then <span data-x="stack
push">push</span> <var>script execution context</var> onto the <span>JavaScript execution
context stack</span>.</p>
<p class="note">This affects the <span>active script</span> while the callback runs.</p>
</li>
<li><p>Let <var>result</var> be <span>Call</span>(<var>callback</var>.[[Callback]], <var>V</var>,
<var>argumentsList</var>).</p></li>
<li><p>If <var>script execution context</var> is not null, then <span data-x="stack
pop">pop</span> <var>script execution context</var> from the <span>JavaScript execution context
stack</span>.</p></li>
<li><p><span>Clean up after running a callback</span> with <var>incumbent
settings</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<h6
id="hostenqueuefinalizationregistrycleanupjob"><dfn>HostEnqueueFinalizationRegistryCleanupJob</dfn>(<var>finalizationRegistry</var>)</h6>
<p>JavaScript has the ability to register objects with <code>FinalizationRegistry</code> objects,
in order to schedule a cleanup action if they are found to be garbage collected. The JavaScript
specification contains an <span>implementation-defined</span> <span
data-x="js-HostEnqueueFinalizationRegistryCleanupJob">HostEnqueueFinalizationRegistryCleanupJob</span>(<var>finalizationRegistry</var>)
abstract operation to schedule the cleanup action.</p>
<p class="note">The timing and occurrence of cleanup work is <span>implementation-defined</span>
in the JavaScript specification. User agents might differ in when and whether an object is garbage
collected, affecting both whether the return value of the <code>WeakRef.prototype.deref()</code>
method is undefined, and whether <code>FinalizationRegistry</code> cleanup callbacks occur. There
are well-known cases in popular web browsers where objects are not accessible to JavaScript, but
they remain retained by the garbage collector indefinitely. HTML clears kept-alive
<code>WeakRef</code> objects in the <span>perform a microtask checkpoint</span> algorithm. Authors
would be best off not depending on the timing details of garbage collection implementations.</p>
<p>Cleanup actions do not take place interspersed with synchronous JavaScript execution, but
rather happen in queued <span data-x="concept-task">tasks</span>. User agents must use the
following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>global</var> be <var>finalizationRegistry</var>.[[Realm]]'s <span>global
object</span>.</p></li>
<li>
<p><span>Queue a global task</span> on the <dfn>JavaScript engine task source</dfn> given
<var>global</var> to perform the following steps:</p>
<ol>
<li><p>Let <var>entry</var> be
<var>finalizationRegistry</var>.[[CleanupCallback]].[[Callback]].[[Realm]]'s <span
data-x="concept-realm-settings-object">environment settings object</span>.</p></li>
<li><p><span>Check if we can run script</span> with <var>entry</var>. If this returns "do not
run", then return.</p></li>
<li>
<p><span>Prepare to run script</span> with <var>entry</var>.</p>
<p class="note">This affects the <span data-x="concept-entry-everything">entry</span> concept
while the cleanup callback runs.</p>
</li>
<li><p>Let <var>result</var> be the result of performing
<span>CleanupFinalizationRegistry</span>(<var>finalizationRegistry</var>).</p></li>
<li><p><span>Clean up after running script</span> with <var>entry</var>.</p></li>
<li><p>If <var>result</var> is an <span data-x="Completion Record">abrupt completion</span>,
then <span>report an exception</span> given by <var>result</var>.[[Value]] for
<var>global</var>.</p></li>
</ol>
</li>
</ol>
<h6 id="hostenqueuegenericjob"><dfn>HostEnqueueGenericJob</dfn>(<var>job</var>,
<var>realm</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostEnqueueGenericJob">HostEnqueueGenericJob</span>(<var>job</var>, <var>realm</var>)
abstract operation to perform generic jobs in a particular realm (e.g., resolve promises resulting
from <code>Atomics.waitAsync</code>). User agents must use the following implementation:
<ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>global</var> be <var>realm</var>'s <span data-x="concept-realm-global">global
object</span>.</p></li>
<li><p><span>Queue a global task</span> on the <span>JavaScript engine task source</span> given
<var>global</var> to perform <var>job</var>().</p></li>
</ol>
<span id="integration-with-the-javascript-job-queue"></span>
<span id="enqueuejob(queuename,-job,-arguments)"></span>
<h6 id="hostenqueuepromisejob"><dfn>HostEnqueuePromiseJob</dfn>(<var>job</var>,
<var>realm</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostEnqueuePromiseJob">HostEnqueuePromiseJob</span>(<var>job</var>, <var>realm</var>)
abstract operation to schedule Promise-related operations. HTML schedules these operations in the
microtask queue. User agents must use the following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li>
<p>If <var>realm</var> is not null, then let <var>job settings</var> be the <span
data-x="concept-realm-settings-object">settings object</span> for <var>realm</var>. Otherwise,
let <var>job settings</var> be null.</p>
<div class="note">
<p>If <var>realm</var> is not null, it is the <span>realm</span> of the author code that will
run. When <var>job</var> is returned by <span>NewPromiseReactionJob</span>, it is the realm of
the promise's handler function. When <var>job</var> is returned by
<span>NewPromiseResolveThenableJob</span>, it is the realm of the <code data-x="">then</code>
function.
<p>If <var>realm</var> is null, either no author code will run or author code is guaranteed to
throw. For the former, the author may not have passed in code to run, such as in <code
data-x="">promise.then(null, null)</code>. For the latter, it is because a revoked Proxy was
passed. In both cases, all the steps below that would otherwise use <var>job settings</var>
get skipped.</p>
<p class="XXX"><a
href="https://tc39.es/ecma262/#sec-newpromiseresolvethenablejob">NewPromiseResolveThenableJob</a>
and <a href="https://tc39.es/ecma262/#sec-newpromisereactionjob">NewPromiseReactionJob</a>
both seem to provide non-null realms (the current Realm Record) in the case of a revoked
proxy. The previous text could be updated to reflect that.</p>
</div>
</li>
<li>
<p><span>Queue a microtask</span> to perform the following steps:</p>
<ol>
<li><p>If <var>job settings</var> is not null, then <span>check if we can run script</span>
with <var>job settings</var>. If this returns "do not run" then return.</p></li>
<li>
<p>If <var>job settings</var> is not null, then <span>prepare to run script</span> with
<var>job settings</var>.</p>
<p class="note">This affects the <span data-x="concept-entry-everything">entry</span> concept
while the job runs.</p>
</li>
<li>
<p>Let <var>result</var> be <var>job</var>().</p>
<p class="note"><var>job</var> is an <span>abstract closure</span> returned by
<span>NewPromiseReactionJob</span> or <span>NewPromiseResolveThenableJob</span>. The promise's
handler function when <var>job</var> is returned by <span>NewPromiseReactionJob</span>, and
the <code data-x="">then</code> function when <var>job</var> is returned by
<span>NewPromiseResolveThenableJob</span>, are wrapped in <span data-x="JobCallback
Record">JobCallback Records</span>. HTML saves the <span>incumbent settings object</span> and
a <span>JavaScript execution context</span> for to the <span>active script</span> in
<span>HostMakeJobCallback</span> and restores them in <span>HostCallJobCallback</span>.</p>
</li>
<li><p>If <var>job settings</var> is not null, then <span>clean up after running script</span>
with <var>job settings</var>.</p></li>
<li>
<p>If <var>result</var> is an <span data-x="Completion Record">abrupt completion</span>, then
<span>report an exception</span> given by <var>result</var>.[[Value]] for <var>realm</var>'s
<span data-x="concept-realm-global">global object</span>.</p>
<p class="XXX">There is a very gnarly case where HostEnqueuePromiseJob is called with a null
realm (e.g., because Promise.prototype.then was called with null handlers) but also the job
returns abruptly (because the promise capability's resolve or reject handler threw, possibly
because this is a subclass of Promise that takes the supplied functions and wraps them in
throwing functions before passing them on to the function passed to the Promise superclass
constructor. Which global is to be used then, considering that the current realm could be
different at each of those steps, by using a Promise constructor or Promise.prototype.then
from another realm? See <a href="https://github.com/whatwg/html/issues/10526">issue
#10526</a>.</p>
</li>
</ol>
</li>
</ol>
<h6 id="hostenqueuetimeoutjob"><dfn>HostEnqueueTimeoutJob</dfn>(<var>job</var>, <var>realm</var>,
<var>milliseconds</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostEnqueueTimeoutJob">HostEnqueueTimeoutJob</span>(<var>job</var>,
<var>milliseconds</var>) abstract operation to schedule an operation to be performed after a
timeout. HTML schedules these operations using <span>run steps after a timeout</span>. User agents
must use the following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>global</var> be <var>realm</var>'s <span data-x="concept-realm-global">global
object</span>.</p></li>
<li><p>Let <var>timeoutStep</var> be an algorithm step which <span data-x="queue a global
task">queues a global task</span> on the <span>JavaScript engine task source</span> given
<var>global</var> to perform <var>job</var>().</p></li>
<li><p><span>Run steps after a timeout</span> given <var>global</var>, "<code
data-x="">JavaScript</code>", <var>milliseconds</var>, and <var>timeoutStep</var>.</p></li>
</ol>
<h6 id="hostmakejobcallback"><dfn>HostMakeJobCallback</dfn>(<var>callable</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostMakeJobCallback">HostMakeJobCallback</span>(<var>callable</var>) abstract operation
to let hosts attach state to JavaScript callbacks that are called from inside <span
data-x="concept-task">task</span>s. User agents must use the following implementation:
<ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>incumbent settings</var> be the <span>incumbent settings object</span>.</p></li>
<li><p>Let <var>active script</var> be the <span>active script</span>.</p></li>
<li><p>Let <var>script execution context</var> be null.</p></li>
<li>
<p>If <var>active script</var> is not null, set <var>script execution context</var> to a new
<span>JavaScript execution context</span>, with its Function field set to null, its Realm field
set to <var>active script</var>'s <span data-x="concept-script-settings-object">settings
object</span>'s <span data-x="environment settings object's realm">realm</span>, and its
ScriptOrModule set to <var>active script</var>'s
<span data-x="concept-script-record">record</span>.</p>
<p class="note">As seen below, this is used in order to propagate the current <span>active
script</span> forward to the time when the job callback is invoked.</p>
<div class="example">
<p>A case where <var>active script</var> is non-null, and saving it in this way is useful, is
the following:</p>
<pre><code class="js" data-x="">Promise.resolve('import(`./example.mjs`)').then(eval);</code></pre>
<p>Without this step (and the steps that use it in <span>HostCallJobCallback</span>), there
would be no <span>active script</span> when the <code>import()</code> expression is evaluated,
since <code>eval()</code> is a built-in function that does not originate from any particular
<span data-x="concept-script">script</span>.</p>
<p>With this step in place, the active script is propagated from the above code into the job,
allowing <code>import()</code> to use the original script's <span
data-x="concept-script-base-url">base URL</span> appropriately.</p>
</div>
<div class="example">
<p><var>active script</var> can be null if the user clicks on the following button:</p>
<pre><code class="html" data-x=""><button onclick="Promise.resolve('import(`./example.mjs`)').then(eval)">Click me</button></code></pre>
<p>In this case, the JavaScript function for the <span data-x="event handlers">event
handler</span> will be created by the <span data-x="getting the current value of the event
handler">get the current value of the event handler</span> algorithm, which creates a function
with null [[ScriptOrModule]] value. Thus, when the promise machinery calls
<span>HostMakeJobCallback</span>, there will be no <span>active script</span> to pass
along.</p>
<p>As a consequence, this means that when the <code>import()</code> expression is evaluated,
there will still be no <span>active script</span>. Fortunately that is handled by our
implementation of <span>HostLoadImportedModule</span> by falling back to using the
<span>current settings object</span>'s <span>API base URL</span>.</p>
</div>
</li>
<li><p>Return the <span>JobCallback Record</span> { [[Callback]]: <var>callable</var>,
[[HostDefined]]: { [[IncumbentSettings]]: <var>incumbent settings</var>, [[ActiveScriptContext]]:
<var>script execution context</var> } }.</p></li>
</ol>
</div>
<h5 id="integration-with-the-javascript-module-system">Module-related host hooks</h5>
<p>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 <code>script</code> element with <code
data-x="attr-script-type">type</code> attribute set to "<code data-x="">module</code>", and how
modules are fetched, resolved, and executed. <ref>JAVASCRIPT</ref></p>
<p class="note">Although the JavaScript specification speaks in terms of "scripts" versus
"modules", in general this specification speaks in terms of <span data-x="classic script">classic
scripts</span> versus <span data-x="module script">module scripts</span>, since both of them use
the <code>script</code> element.</p>
<dl class="domintro">
<dt><code data-x=""><var>modulePromise</var> = <span data-x="import()">import(<var>specifier</var>)</span></code></dt>
<dd>
<p>Returns a promise for the module namespace object for the <span>module script</span>
identified by <var>specifier</var>. This allows dynamic importing of module scripts at runtime,
instead of statically using the <code data-x="">import</code> statement form. The specifier will
be <span data-x="resolve a module specifier">resolved</span> relative to the <span>active
script</span>.</p>
<p>The returned promise will be rejected if an invalid specifier is given, or if a failure is
encountered while <span data-x="HostLoadImportedModule">fetching</span> or evaluating the
resulting module graph.</p>
<p>This syntax can be used inside both <span data-x="classic script">classic</span> and <span
data-x="module script">module scripts</span>. It thus provides a bridge into the module-script
world, from the classic-script world.</p>
</dd>
<dt><code data-x=""><var>url</var> = <span data-x="import.meta">import.meta</span>.<span data-x="import-meta-url">url</span></code></dt>
<dd>
<p>Returns the <span data-x="active script">active module script</span>'s <span
data-x="concept-script-base-url">base URL</span>.</p>
<p>This syntax can only be used inside <span data-x="module script">module scripts</span>.</p>
</dd>
<dt><code data-x=""><var>url</var> = <span data-x="import.meta">import.meta</span>.<span data-x="import-meta-resolve">resolve</span>(<var>specifier</var>)</code></dt>
<dd>
<p>Returns <var>specifier</var>, <span data-x="resolve a module specifier">resolved</span>
relative to the <span>active script</span>. That is, this returns the URL that would be imported
by using <code data-x="import()">import(<var>specifier</var>)</code>.</p>
<p>Throws a <code>TypeError</code> exception if an invalid specifier is given.</p>
<p>This syntax can only be used inside <span data-x="module script">module scripts</span>.</p>
</dd>
</dl>
<p><span w-nodev>A <dfn>module map</dfn> is a <span data-x="ordered map">map</span> keyed by <span
data-x="tuple">tuples</span> consisting of a <span>URL record</span> and a <span>string</span>.
The <span>URL record</span> is the <span data-x="concept-request-url">request URL</span> at which
the module was fetched, and the <span>string</span> indicates the type of the module (e.g. "<code
data-x="">javascript-or-wasm</code>"). The <span>module map</span>'s values are either a
<span>module script</span>, null (used to represent failed fetches), or a placeholder value "<code
data-x="">fetching</code>". </span><span data-x="module map">Module maps</span> are used to ensure
that imported module scripts are only fetched, parsed, and evaluated once per
<code>Document</code> or <a href="#workers">worker</a>.</p>
<div class="example">
<p>Since <span data-x="module map">module maps</span> are keyed by (URL, module type), the
following code will create three separate entries in the <span>module map</span>, since it
results in three different (URL, module type) <span data-x="tuple">tuples</span> (all with "<code
data-x="">javascript-or-wasm</code>" type):</p>
<pre><code class="js">import "https://example.com/module.mjs";
import "https://example.com/module.mjs#map-buster";
import "https://example.com/module.mjs?debug=true";</code></pre>
<p>That is, URL <span data-x="concept-url-query">queries</span> and <span
data-x="concept-url-fragment">fragments</span> can be varied to create distinct entries in the
<span>module map</span>; they are not ignored. Thus, three separate fetches and three separate
module evaluations will be performed.</p>
<p>In contrast, the following code would only create a single entry in the <span>module
map</span>, since after applying the <span>URL parser</span> to these inputs, the resulting <span
data-x="URL record">URL records</span> are equal:</p>
<pre><code class="js">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";</code></pre>
<p>So in this second example, only one fetch and one module evaluation will occur.</p>
<p>Note that this behavior is the same as how <span
data-x="SharedWorker">shared workers</span> are keyed by their parsed <span
data-x="concept-SharedWorkerGlobalScope-constructor-url">constructor url</span>.</p>
</div>
<div class="example">
<p>Since module type is also part of the <span>module map</span> key, the following code will
create two separate entries in the <span>module map</span> (the type is "<code
data-x="">javascript-or-wasm</code>" for the first, and "<code data-x="">css</code>" for the
second):</p>
<pre><code class="html" data-x=""><script type=module>
import "https://example.com/module";
</script>
<script type=module>
import "https://example.com/module" with { type: "css" };
</script></code></pre>
<p>This can result in two separate fetches and two separate module evaluations being performed.</p>
<p class="XXX">In practice, due to the as-yet-unspecified memory cache (see issue <a
href="https://github.com/whatwg/html/issues/6110">#6110</a>) the resource may only be fetched
once in WebKit and Blink-based browsers. Additionally, as long as all module types are mutually
exclusive, the module type check in <span>fetch a single module script</span> will fail for at
least one of the imports, so at most one module evaluation will occur.</p>
<p>The purpose of including the type in the <span>module map</span> key is so that an import
with the wrong type attribute does not prevent a different import of the same specifier but with
the correct type from succeeding.</p>
</div>
<div class="example">
<p>JavaScript module scripts are the default import type when importing from another JavaScript
module; that is, when an <code data-x="">import</code> statement lacks a <code
data-x="">type</code> import attribute the imported module script's type will be JavaScript.
Attempting to import a JavaScript resource using an <code data-x="">import</code> statement with
a <code data-x="">type</code> import attribute will fail:</p>
<pre><code class="html"><script type="module">
// All of the following will fail, assuming that the imported .mjs files are served with a
// JavaScript MIME type. JavaScript module scripts are the default and cannot be imported with
// any import type attribute.
import foo from "./foo.mjs" with { type: "javascript" };
import foo2 from "./foo2.mjs" with { type: "js" };
import foo3 from "./foo3.mjs" with { type: "" };
await import("./foo4.mjs", { with: { type: null } });
await import("./foo5.mjs", { with: { type: undefined } });
</script></code></pre>
</div>
<div w-nodev>
<h6
id="hostgetimportmetaproperties"><dfn>HostGetImportMetaProperties</dfn>(<var>moduleRecord</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostGetImportMetaProperties">HostGetImportMetaProperties</span> abstract operation.
User agents must use the following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>moduleScript</var> be <var>moduleRecord</var>.[[HostDefined]].</p></li>
<li><p><span>Assert</span>: <var>moduleScript</var>'s <span data-x="concept-script-base-url">base
URL</span> is not null, as <var>moduleScript</var> is a <span>JavaScript module
script</span>.</p></li>
<li><p>Let <var>urlString</var> be <var>moduleScript</var>'s <span
data-x="concept-script-base-url">base URL</span>, <span
data-x="concept-url-serializer">serialized</span>.</p></li>
<li>
<p>Let <var>steps</var> be the following steps, given the argument <var>specifier</var>:</p>
<ol>
<li><p>Set <var>specifier</var> to ? <span>ToString</span>(<var>specifier</var>).</p></li>
<li><p>Let <var>url</var> be the result of <span data-x="resolve a module specifier">resolving
a module specifier</span> given <var>moduleScript</var> and <var>specifier</var>.</p></li>
<li><p>Return the <span data-x="concept-url-serializer">serialization</span> of
<var>url</var>.</p></li>
</ol>
</li>
<li><p>Let <var>resolveFunction</var> be ! <span>CreateBuiltinFunction</span>(<var>steps</var>,
1, "<code data-x="">resolve</code>", « »).</p></li>
<li><p>Return « <span>Record</span> { [[Key]]: "<dfn><code
data-x="import-meta-url">url</code></dfn>", [[Value]]: <var>urlString</var> },
<span>Record</span> { [[Key]]: "<dfn><code data-x="import-meta-resolve">resolve</code></dfn>",
[[Value]]: <var>resolveFunction</var> } ».</p></li>
</ol>
<h6 id="hostgetsupportedimportattributes"><span
id="hostgetsupportedimportassertions"></span><dfn>HostGetSupportedImportAttributes</dfn>()</h6>
<p>JavaScript contains an an <span>implementation-defined</span> <span
data-x="js-HostGetSupportedImportAttributes">HostGetSupportedImportAttributes</span> abstract
operation. User agents must use the following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Return « "<code data-x="">type</code>" ».</p></li>
</ol>
<h6 id="hostloadimportedmodule"><dfn>HostLoadImportedModule</dfn>(<var>referrer</var>,
<var>moduleRequest</var>, <var>loadState</var>, <var>payload</var>)</h6>
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostLoadImportedModule">HostLoadImportedModule</span> abstract operation. User agents
must use the following implementation: <ref>JAVASCRIPT</ref></p>
<ol>
<li><p>Let <var>settingsObject</var> be the <span>current settings object</span>.</p></li>
<li>
<p>If <var>settingsObject</var>'s <span data-x="concept-settings-object-global">global
object</span> implements <code>WorkletGlobalScope</code> or <code>ServiceWorkerGlobalScope</code>
and <var>loadState</var> is undefined, then:</p>
<p class="note"><var>loadState</var> is undefined when the current fetching process has been
initiated by a dynamic <code>import()</code> call, either directly or when loading the
transitive dependencies of the dynamically imported module.</p>
<ol>
<li><p>Let <var>completion</var> be <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: a new <code>TypeError</code>, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>referencingScript</var> be null.</p></li>
<li><p>Let <var>originalFetchOptions</var> be the <span>default script fetch
options</span>.</p></li>
<li><p>Let <var>fetchReferrer</var> be "<code data-x="">client</code>".</p></li>
<li>
<p>If <var>referrer</var> is a <span>Script Record</span> or a <span>Cyclic Module
Record</span>, then:</p>
<ol>
<li><p>Set <var>referencingScript</var> to <var>referrer</var>.[[HostDefined]].</p>
<li><p>Set <var>settingsObject</var> to <var>referencingScript</var>'s <span
data-x="concept-script-settings-object">settings object</span>.</p></li>
<li><p>Set <var>fetchReferrer</var> to <var>referencingScript</var>'s <span
data-x="concept-script-base-url">base URL</span>.</p></li>
<li><p>Set <var>originalFetchOptions</var> to <var>referencingScript</var>'s <span
data-x="concept-script-script-fetch-options">fetch options</span>.</p></li>
</ol>
<div class="example">
<p><var>referrer</var> is usually a <span>Script Record</span> or a <span>Cyclic Module
Record</span>, but it will not be so for event handlers per the <span data-x="getting the
current value of the event handler">get the current value of the event handler</span>
algorithm. For example, given:</p>
<pre><code class="html"><button onclick="import('./foo.mjs')">Click me</button></code></pre>
<p>If a <code data-x="event-click">click</code> event occurs, then at the time the
<code>import()</code> expression runs, <span>GetActiveScriptOrModule</span> will return null,
and this operation will receive the <span>current realm</span> as a fallback
<var>referrer</var>.</p>
</div>
</li>
<li>
<p>If <var>referrer</var> is a <span>Cyclic Module Record</span> and <var>moduleRequest</var>
is equal to the first element of <var>referrer</var>.[[RequestedModules]], then:</p>
<ol>
<li id="validate-requested-module-specifiers">
<p><span data-x="list iterate">For each</span> <span>ModuleRequest record</span>
<var>requested</var> of <var>referrer</var>.[[RequestedModules]]:</p>
<ol>
<li>
<p>If <var>moduleRequest</var>.[[Attributes]] contains a <span>Record</span> <var>entry</var>
such that <var>entry</var>.[[Key]] is not "<code data-x="">type</code>", then:</p>
<ol>
<li><p>Let <var>completion</var> be <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: a new <code>SyntaxError</code> exception, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
<li><p>Return.</p></li>
</ol>
<p class="note">The JavaScript specification re-performs this validation but it is duplicated
here to avoid unnecessarily loading any of the dependencies on validation failure.</p>
</li>
<li><p><span>Resolve a module specifier</span> given <var>referencingScript</var> and
<var>moduleRequest</var>.[[Specifier]], catching any exceptions. If they throw an exception, let
<var>resolutionError</var> be the thrown exception.</p></li>
<li>
<p>If the previous step threw an exception, then:</p>
<ol>
<li><p>Let <var>completion</var> be <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: <var>resolutionError</var>, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>moduleType</var> be the result of running the <span>module type from module
request</span> steps given <var>moduleRequest</var>.</p></li>
<li>
<p>If the result of running the <span>module type allowed</span> steps given
<var>moduleType</var> and <var>settingsObject</var> is false, then:</p>
<ol>
<li><p>Let <var>completion</var> be <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: a new <code>TypeError</code> exception, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
<li><p>Return.</p></li>
</ol>
</li>
</ol>
<p class="note">This step is essentially validating all of the requested module specifiers and
type attributes when the first call to <span>HostLoadImportedModule</span> for a static module
dependency list is made, to avoid further loading operations in the case any one of the
dependencies has a static error. We treat a module with unresolvable module specifiers or
unsupported type attributes the same as one that cannot be parsed; in both cases, a syntactic
issue makes it impossible to ever contemplate linking the module later.</p>
</li>
</ol>
</li>
<li><p>Let <var>url</var> be the result of <span data-x="resolve a module specifier">resolving a
module specifier</span> given <var>referencingScript</var> and
<var>moduleRequest</var>.[[Specifier]], catching any exceptions. If they throw an exception, let
<var>resolutionError</var> be the thrown exception.</p></li>
<li>
<p>If the previous step threw an exception, then:</p>
<ol>
<li><p>Let <var>completion</var> be <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: <var>resolutionError</var>, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>fetchOptions</var> be the result of <span data-x="get the descendant script
fetch options">getting the descendant script fetch options</span> given
<var>originalFetchOptions</var>, <var>url</var>, and <var>settingsObject</var>.</p></li>
<li><p>Let <var>destination</var> be <code data-x="">"script"</code>.</p></li>
<li><p>Let <var>fetchClient</var> be <var>settingsObject</var>.</p></li>
<li>
<p>If <var>loadState</var> is not undefined, then:</p>
<ol>
<li><p>Set <var>destination</var> to <var>loadState</var>.[[Destination]].</p></li>
<li><p>Set <var>fetchClient</var> to <var>loadState</var>.[[FetchClient]].</p></li>
</ol>
</li>
<li>
<p><span>Fetch a single imported module script</span> given <var>url</var>,
<var>fetchClient</var>, <var>destination</var>, <var>fetchOptions</var>,
<var>settingsObject</var>, <var>fetchReferrer</var>, <var>moduleRequest</var>, and
<var>onSingleFetchComplete</var> as defined below. If <var>loadState</var> is not undefined and
<var>loadState</var>.[[PerformFetch]] is not null, pass <var>loadState</var>.[[PerformFetch]]
along as well.</p>
<p><var>onSingleFetchComplete</var> given <var>moduleScript</var> is the following
algorithm:</p>
<ol>
<li><p>Let <var>completion</var> be null.</p></li>
<li><p>If <var>moduleScript</var> is null, then set <var>completion</var> to <span>Completion
Record</span> { [[Type]]: throw, [[Value]]: a new <code>TypeError</code>, [[Target]]: empty
}.</p></li>
<li>
<p>Otherwise, if <var>moduleScript</var>'s <span data-x="concept-script-parse-error">parse
error</span> is not null, then:</p>
<ol>
<li><p>Let <var>parseError</var> be <var>moduleScript</var>'s <span
data-x="concept-script-parse-error">parse error</span>.</p></li>
<li><p>Set <var>completion</var> to <span>Completion Record</span> { [[Type]]: throw,
[[Value]]: <var>parseError</var>, [[Target]]: empty }.</p></li>
<li><p>If <var>loadState</var> is not undefined and <var>loadState</var>.[[ParseError]] is
null, set <var>loadState</var>.[[ParseError]] to <var>parseError</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>completion</var> to <span>Completion Record</span> { [[Type]]:
normal, [[Value]]: <var>moduleScript</var>'s
<span data-x="concept-script-record">record</span>, [[Target]]: empty }.</p></li>
<li><p>Perform <span>FinishLoadingImportedModule</span>(<var>referrer</var>,
<var>moduleRequest</var>, <var>payload</var>, <var>completion</var>).</p></li>
</ol>
</li>
</ol>
</div>
<h4>Event loops</h4>
<h5 w-nodev>Definitions</h5>
<p>To coordinate events, user interaction, scripts, rendering, networking, and so forth, user
agents must use <dfn data-x="event loop" data-lt="event loop" export>event loops</dfn> as
described in this section. Each <span>agent</span> has an associated <dfn export for="agent"
data-x="concept-agent-event-loop">event loop</dfn>, which is unique to that agent.</p>
<p>The <span data-x="concept-agent-event-loop">event loop</span> of a <span>similar-origin window
agent</span> is known as a <dfn>window event loop</dfn>. The <span
data-x="concept-agent-event-loop">event loop</span> of a <span>dedicated worker agent</span>,
<span>shared worker agent</span>, or <span>service worker agent</span> is known as a <dfn>worker
event loop</dfn>. And the <span data-x="concept-agent-event-loop">event loop</span> of a
<span>worklet agent</span> is known as a <dfn>worklet event loop</dfn>.</p>
<div class="note">
<p><span data-x="event loop">Event loops</span> do not necessarily correspond to implementation
threads. For example, multiple <span data-x="window event loop">window event loops</span> could
be cooperatively scheduled in a single thread.</p>
<p>However, for the various worker <span data-x="agent">agents</span> that are allocated with
[[CanBlock]] set to true, the JavaScript specification does place requirements on them regarding
<span>forward progress</span>, which effectively amount to requiring dedicated per-agent threads
in those cases.</p>
</div>
<div w-nodev>
<hr>
<p>An <span>event loop</span> has one or more <dfn data-x="task queue">task queues</dfn>. A
<span>task queue</span> is a <span>set</span> of <span data-x="concept-task">tasks</span>.</p>
<p class="note"><span data-x="task queue">Task queues</span> are <span data-x="set">sets</span>,
not <span data-x="queue">queues</span>, because the <a href="#event-loop-processing-model">event
loop processing model</a> grabs the first <span
data-x="concept-task-runnable"><em>runnable</em></span> <span data-x="concept-task">task</span>
from the chosen queue, instead of <span data-x="dequeue">dequeuing</span> the first task.</p>
<p class="note">The <span>microtask queue</span> is not a <span>task queue</span>.</p>
<p>Tasks encapsulate algorithms that are responsible for such work as:</p>
<dl>
<dt>Events</dt>
<dd>
<p>Dispatching an <code>Event</code> object at a particular
<code>EventTarget</code> object is often done by a dedicated task.</p>
<p class="note">Not all events are dispatched using the <span>task queue</span>; many are
dispatched during other tasks.</p>
</dd>
<dt>Parsing</dt>
<dd><p>The <span>HTML parser</span> tokenizing one or more bytes, and then processing any
resulting tokens, is typically a task.</p></dd>
<dt>Callbacks</dt>
<dd><p>Calling a callback is often done by a dedicated task.</p></dd>
<dt>Using a resource</dt>
<dd><p>When an algorithm <span data-x="concept-fetch">fetches</span> a resource, if the fetching
occurs in a non-blocking fashion then the processing of the resource once some or all of the
resource is available is performed by a task.</p></dd>
<dt>Reacting to DOM manipulation</dt>
<dd><p>Some elements have tasks that trigger in response to DOM manipulation, e.g. when that
element is <span data-x="node is inserted into a document">inserted into the document</span>.</p>
</dl>
<p>Formally, a <dfn data-x="concept-task" data-lt="task" export>task</dfn> is a
<span>struct</span> which has:</p>
<dl>
<dt><dfn data-x="concept-task-steps">Steps</dfn></dt>
<dd>A series of steps specifying the work to be done by the task.</dd>
<dt>A <dfn data-x="concept-task-source">source</dfn></dt>
<dd>One of the <span data-x="task source">task sources</span>, used to group and serialize
related tasks.</dd>
<dt>A <dfn data-x="concept-task-document">document</dfn></dt>
<dd>A <code>Document</code> associated with the task, or null for tasks that are not in a
<span>window event loop</span>.</dd>
<dt>A <dfn export>script evaluation environment settings object set</dfn></dt>
<dd>A <span>set</span> of <span data-x="environment settings object">environment settings
objects</span> used for tracking script evaluation during the task.</dd>
</dl>
<p>A <span data-x="concept-task">task</span> is <dfn data-x="concept-task-runnable">runnable</dfn>
if its <span data-x="concept-task-document">document</span> is either null or <span>fully
active</span>.</p>
<p>Per its <span data-x="concept-task-source">source</span> field, each <span
data-x="concept-task">task</span> is defined as coming from a specific <dfn export>task
source</dfn>. For each <span>event loop</span>, every <span>task source</span> must be associated
with a specific <span>task queue</span>.</p>
<p class="note">Essentially, <span data-x="task source">task sources</span> are used within
standards to separate logically-different types of tasks, which a user agent might wish to
distinguish between. <span data-x="task queue">Task queues</span> are used by user agents to
coalesce task sources within a given <span>event loop</span>.</p>
<p class="example">For example, a user agent could have one <span>task queue</span> for mouse and
key events (to which the <span>user interaction task source</span> is associated), and another to
which all other <span data-x="task source">task sources</span> are associated. Then, using the
freedom granted in the initial step of the <a href="#event-loop-processing-model">event loop
processing model</a>, it could give keyboard and mouse events preference over other tasks
three-quarters of the time, keeping the interface responsive but not starving other task queues.
Note that in this setup, the processing model still enforces that the user agent would never
process events from any one <span>task source</span> out of order.</p>
<hr>
<p>Each <span>event loop</span> has a <dfn>currently running task</dfn>, which is either a <span
data-x="concept-task">task</span> or null. Initially, this is null. It is used to handle
reentrancy.</p>
<p>Each <span>event loop</span> has a <dfn>microtask queue</dfn>, which is a <span>queue</span> of
<span data-x="microtask">microtasks</span>, initially empty. A <dfn export>microtask</dfn> is a
colloquial way of referring to a <span data-x="concept-task">task</span> that was created via the
<span>queue a microtask</span> algorithm.</p>
<p>Each <span>event loop</span> has a <dfn>performing a microtask checkpoint</dfn> boolean,
which is initially false. It is used to prevent reentrant invocation of the <span>perform a
microtask checkpoint</span> algorithm.</p>
<p>Each <span>window event loop</span> has a <code>DOMHighResTimeStamp</code>
<dfn>last render opportunity time</dfn>, initially set to zero.</p>
<p>Each <span>window event loop</span> has a <code>DOMHighResTimeStamp</code>
<dfn>last idle period start time</dfn>, initially set to zero.</p>
<p>To get the <dfn>same-loop windows</dfn> for a <span>window event loop</span> <var>loop</var>,
return all <code>Window</code> objects whose <span>relevant agent</span>'s
<span data-x="concept-agent-event-loop">event loop</span> is <var>loop</var>.</p>
<h5>Queuing tasks</h5>
<p>To <dfn export>queue a task</dfn> on a <span>task source</span> <var>source</var>, which
performs a series of steps <var>steps</var>, optionally given an event loop <var>event loop</var>
and a document <var>document</var>:</p>
<ol>
<li><p>If <var>event loop</var> was not given, set <var>event loop</var> to the <span>implied
event loop</span>.</p></li>
<li><p>If <var>document</var> was not given, set <var>document</var> to the <span>implied
document</span>.</p></li>
<li><p>Let <var>task</var> be a new <span data-x="concept-task">task</span>.</p></li>
<li><p>Set <var>task</var>'s <span data-x="concept-task-steps">steps</span> to
<var>steps</var>.</p></li>
<li><p>Set <var>task</var>'s <span data-x="concept-task-source">source</span> to
<var>source</var>.</p></li>
<li><p>Set <var>task</var>'s <span data-x="concept-task-document">document</span> to the
<var>document</var>.</p></li>
<li><p>Set <var>task</var>'s <span>script evaluation environment settings object set</span> to an
empty <span>set</span>.</p></li>
<li><p>Let <var>queue</var> be the <span>task queue</span> to which <var>source</var> is
associated on <var>event loop</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>task</var> to <var>queue</var>.</p></li>
</ol>
<p class="warning">Failing to pass an event loop and document to <span>queue a task</span> means
relying on the ambiguous and poorly-specified <span>implied event loop</span> and <span>implied
document</span> concepts. Specification authors should either always pass these values, or use the
wrapper algorithms <span>queue a global task</span> or <span>queue an element task</span>
instead. Using the wrapper algorithms is recommended.</p>
<p>To <dfn export>queue a global task</dfn> on a <span>task source</span> <var>source</var>, with
a <span>global object</span> <var>global</var> and a series of steps <var>steps</var>:</p>
<ol>
<li><p>Let <var>event loop</var> be <var>global</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>Let <var>document</var> be <var>global</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span>, if <var>global</var> is
a <code>Window</code> object; otherwise null.</p>
<li><p><span>Queue a task</span> given <var>source</var>, <var>event loop</var>,
<var>document</var>, and <var>steps</var>.</p></li>
</ol>
<p>To <dfn export>queue an element task</dfn> on a <span>task source</span> <var>source</var>,
with an element <var>element</var> and a series of steps <var>steps</var>:</p>
<ol>
<li><p>Let <var>global</var> be <var>element</var>'s <span>relevant global
object</span>.</p></li>
<li><p><span>Queue a global task</span> given <var>source</var>, <var>global</var>, and
<var>steps</var>.</p></li>
</ol>
<p>To <dfn export>queue a microtask</dfn> which performs a series of steps <var>steps</var>,
optionally given a document <var>document</var>:</p>
<ol>
<li><p><span>Assert</span>: there is a <span>surrounding agent</span>. I.e., this algorithm is
not called while <span>in parallel</span>.</p></li>
<li><p>Let <var>eventLoop</var> be the <span>surrounding agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>If <var>document</var> was not given, set <var>document</var> to the <span>implied
document</span>.</p></li>
<li><p>Let <var>microtask</var> be a new <span data-x="concept-task">task</span>.</p></li>
<li><p>Set <var>microtask</var>'s <span data-x="concept-task-steps">steps</span> to
<var>steps</var>.</p></li>
<li><p>Set <var>microtask</var>'s <span data-x="concept-task-source">source</span> to the
<dfn>microtask task source</dfn>.</p></li>
<li><p>Set <var>microtask</var>'s <span data-x="concept-task-document">document</span> to
<var>document</var>.</p></li>
<li><p>Set <var>microtask</var>'s <span>script evaluation environment settings object set</span>
to an empty <span>set</span>.</p></li>
<li><p><span>Enqueue</span> <var>microtask</var> on <var>eventLoop</var>'s <span>microtask
queue</span>.</p></li>
</ol>
<p class="note">It is possible for a <span>microtask</span> to be moved to a regular <span>task
queue</span>, if, during its initial execution, it <span data-x="spin the event loop">spins the
event loop</span>. This is the only case in which the <span
data-x="concept-task-source">source</span>, <span data-x="concept-task-document">document</span>,
and <span>script evaluation environment settings object set</span> of the microtask are consulted;
they are ignored by the <span>perform a microtask checkpoint</span> algorithm.</p>
<p>The <dfn>implied event loop</dfn> when queuing a task is the one that can deduced from the
context of the calling algorithm. This is generally unambiguous, as most specification algorithms
only ever involve a single <span>agent</span> (and thus a single <span>event loop</span>). The
exception is algorithms involving or specifying cross-agent communication (e.g., between a window
and a worker); for those cases, the <span>implied event loop</span> concept must not be relied
upon and specifications must explicitly provide an <span>event loop</span> when <span
data-x="queue a task">queuing a task</span>.</p>
<p>The <dfn>implied document</dfn> when queuing a task on an <span>event loop</span> <var>event
loop</var> is determined as follows:</p>
<ol>
<li><p>If <var>event loop</var> is not a <span>window event loop</span>, then return
null.</p></li>
<li><p>If the task is being queued in the context of an element, then return the element's
<span>node document</span>.</p></li>
<li><p>If the task is being queued in the context of a <span>browsing context</span>, then return
the browsing context's <span>active document</span>.</p></li>
<li><p>If the task is being queued by or for a <span data-x="concept-script">script</span>, then
return the script's <span data-x="concept-script-settings-object">settings object</span>'s <span
data-x="concept-settings-object-global">global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p><span>Assert</span>: this step is never reached, because one of the previous conditions is
true. <span class="XXX">Really?</span></p></li>
</ol>
<p class="XXX">Both <span>implied event loop</span> and <span>implied
document</span> are vaguely-defined and have a lot of action-at-a-distance. The hope is to remove
these, especially <span>implied document</span>. See <a
href="https://github.com/whatwg/html/issues/4980">issue #4980</a>.</p>
<h5 id="event-loop-processing-model" data-lt="event loop processing model" dfn><span
id="processing-model-8"></span>Processing model</h5>
<!-- EVENT LOOP -->
<p>An <span>event loop</span> must continually run through the following steps for as long as it
exists:</p>
<!-- Don't refer to "step 1" or link to #step1 directly; we need to move steps around too often
for such references to survive. Just link to "event loop processing model". (The id="step1"
is kept for old documents which do not follow this advice.) -->
<ol id="step1">
<li><p>Let <var>oldestTask</var> and <var>taskStartTime</var> be null.</p></li>
<li>
<p>If the <span>event loop</span> has a <span>task queue</span> with at least one <span
data-x="concept-task-runnable">runnable</span> <span data-x="concept-task">task</span>,
then:</p>
<ol>
<li>
<p>Let <var>taskQueue</var> be one such <span>task queue</span>, chosen in an
<span>implementation-defined</span> manner.</p>
<p class="note">Remember that the <span>microtask queue</span> is not a <span>task
queue</span>, so it will not be chosen in this step. However, a <span>task queue</span> to
which the <span>microtask task source</span> is associated might be chosen in this step. In
that case, the <span data-x="concept-task">task</span> chosen in the next step was originally
a <span>microtask</span>, but it got moved as part of <span data-x="spin the event
loop">spinning the event loop</span>.</p>
</li>
<li><p>Set <var>taskStartTime</var> to the <span>unsafe shared current time</span>.</p></li>
<li><p>Set <var>oldestTask</var> to the first <span
data-x="concept-task-runnable">runnable</span> <span data-x="concept-task">task</span> in
<var>taskQueue</var>, and <span data-x="list remove">remove</span> it from
<var>taskQueue</var>.</p></li>
<li><p>If <var>oldestTask</var>'s <span data-x="concept-task-document">document</span> is not
null, then <span>record task start time</span> given <var>taskStartTime</var> and
<var>oldestTask</var>'s <span data-x="concept-task-document">document</span>.</p></li>
<li><p>Set the <span>event loop</span>'s <span>currently running task</span> to
<var>oldestTask</var>.</p></li>
<li><p>Perform <var>oldestTask</var>'s <span data-x="concept-task-steps">steps</span>.</p></li>
<li><p>Set the <span>event loop</span>'s <span>currently running task</span> back to
null.</p></li>
<li><p><span>Perform a microtask checkpoint</span>.</p></li>
</ol>
</li>
<li><p>Let <var>taskEndTime</var> be the <span>unsafe shared current time</span>.
<ref>HRT</ref></p></li>
<li>
<p>If <var>oldestTask</var> is not null, then:</p>
<ol>
<li><p>Let <var>top-level browsing contexts</var> be an empty <span>set</span>.</p></li>
<li>
<p>For each <span>environment settings object</span> <var>settings</var> of
<var>oldestTask</var>'s <span>script evaluation environment settings object set</span>:</p>
<ol>
<li><p>Let <var>global</var> be <var>settings</var>'s <span
data-x="concept-settings-object-global">global object</span>.</p></li>
<li><p>If <var>global</var> is not a <code>Window</code> object, then
<span>continue</span>.</p></li>
<li><p>If <var>global</var>'s <span data-x="window bc">browsing context</span> is null, then
<span>continue</span>.</p></li>
<li><p>Let <var>tlbc</var> be <var>global</var>'s <span data-x="window bc">browsing
context</span>'s <span data-x="bc-tlbc">top-level browsing context</span>.</p></li>
<li><p>If <var>tlbc</var> is not null, then <span data-x="set append">append</span> it to
<var>top-level browsing contexts</var>.</p></li>
</ol>
</li>
<li><p><span>Report long tasks</span>, passing in <var>taskStartTime</var>,
<var>taskEndTime</var>, <var>top-level browsing contexts</var>, and
<var>oldestTask</var>.</p></li>
<li><p>If <var>oldestTask</var>'s <span data-x="concept-task-document">document</span> is not
null, then <span>record task end time</span> given <var>taskEndTime</var> and
<var>oldestTask</var>'s <span data-x="concept-task-document">document</span>.</p></li>
</ol>
</li>
<li id="idle-deadline-computation">
<p>If this is a <span>window event loop</span> that has no <span
data-x="concept-task-runnable"><em>runnable</em></span> <span data-x="concept-task">task</span>
in this <span>event loop</span>'s <span data-x="task queue">task queues</span>, then:</p>
<ol>
<li><p>Set this <span>event loop</span>'s <span>last idle period start time</span> to the
<span>unsafe shared current time</span>.</p></li>
<li>
<p>Let <var>computeDeadline</var> be the following steps:</p>
<ol>
<li>
<p>Let <var>deadline</var> be this <span>event loop</span>'s <span>last idle period start
time</span> plus 50.</p>
<p class="note">The cap of 50ms in the future is to ensure responsiveness to new user input
within the threshold of human perception.</p>
</li>
<li><p>Let <var>hasPendingRenders</var> be false.</p></li>
<li>
<p>For each <var>windowInSameLoop</var> of the <span>same-loop windows</span> for this
<span>event loop</span>:</p>
<ol>
<li><p>If <var>windowInSameLoop</var>'s <span>map of animation frame callbacks</span> is
not <span data-x="map empty">empty</span>, or if the user agent believes that the
<var>windowInSameLoop</var> might have pending rendering updates, set
<var>hasPendingRenders</var> to true.</p></li>
<li><p>Let <var>timerCallbackEstimates</var> be the result of <span data-x="map get the
values">getting the values</span> of <var>windowInSameLoop</var>'s <span>map of active
timers</span>.</p></li>
<li><p>For each <var>timeoutDeadline</var> of <var>timerCallbackEstimates</var>, if
<var>timeoutDeadline</var> is less than <var>deadline</var>, set <var>deadline</var> to
<var>timeoutDeadline</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>hasPendingRenders</var> is true, then:</p>
<ol>
<li>
<p>Let <var>nextRenderDeadline</var> be this <span>event loop</span>'s <span>last render
opportunity time</span> plus (1000 divided by the current refresh rate).</p>
<p>The refresh rate can be hardware- or implementation-specific. For a refresh rate of
60Hz, the <var>nextRenderDeadline</var> would be about 16.67ms after the <span>last
render opportunity time</span>.</p>
</li>
<li><p>If <var>nextRenderDeadline</var> is less than <var>deadline</var>, then return
<var>nextRenderDeadline</var>.</p></li>
</ol>
</li>
<li><p>Return <var>deadline</var>.</p></li>
</ol>
</li>
<li><p>For each <var>win</var> of the <span>same-loop windows</span> for this <span>event
loop</span>, perform the <span>start an idle period algorithm</span> for <var>win</var> with
the following step: return the result of calling <var>computeDeadline</var>, <span
data-x="coarsen time">coarsened</span> given <var>win</var>'s <span>relevant settings
object</span>'s <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>. <ref>REQUESTIDLECALLBACK</ref></p></li>
</ol>
</li>
<li>
<p>If this is a <span>worker event loop</span>, then:</p>
<ol>
<li>
<p>If this <span>event loop</span>'s <span>agent</span>'s single <span>realm</span>'s <span
data-x="concept-realm-global">global object</span> is a <span
data-x="concept-AnimationFrameProvider-supported">supported</span>
<code>DedicatedWorkerGlobalScope</code> and the user agent believes that it would benefit
from having its rendering updated at this time, then:</p>
<!-- TODO: grab the realm from the task. https://github.com/whatwg/html/issues/4342 -->
<ol>
<li><p>Let <var>now</var> be the <span>current high resolution time</span> given the
<code>DedicatedWorkerGlobalScope</code>. <ref>HRT</ref></p></li>
<li><p><span>Run the animation frame callbacks</span> for that
<code>DedicatedWorkerGlobalScope</code>, passing in <var>now</var> as the
timestamp.</p></li>
<li><p>Update the rendering of that dedicated worker to reflect the current state.</p></li>
</ol>
<p class="note">Similar to the notes for <span data-x="update the rendering">updating the
rendering</span> in a <span>window event loop</span>, a user agent can determine the rate of
rendering in the dedicated worker.</p>
</li>
<li><p>If there are no <span data-x="concept-task">tasks</span> in the <span>event
loop</span>'s <span data-x="task queue">task queues</span> and the
<code>WorkerGlobalScope</code> object's <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag is true, then destroy the
<span>event loop</span>, aborting these steps, resuming the <span>run a worker</span> steps
described in the <a href="#workers">Web workers</a> section below.</p></li>
</ol>
</li>
</ol>
<p>A <span>window event loop</span> <var>eventLoop</var> must also run the following <span>in
parallel</span>, as long as it exists:</p>
<ol>
<li><p>Wait until at least one <span>navigable</span> whose <span data-x="nav-document">active
document</span>'s <span>relevant agent</span>'s <span data-x="concept-agent-event-loop">event
loop</span> is <var>eventLoop</var> might have a <span>rendering opportunity</span>.</p></li>
<li><p>Set <var>eventLoop</var>'s <span>last render opportunity time</span> to the <span>unsafe
shared current time</span>.</p></li>
<li>
<p>For each <var>navigable</var> that has a <span>rendering opportunity</span>, <span>queue a
global task</span> on the <span>rendering task source</span> given <var>navigable</var>'s <span
data-x="nav-window">active window</span> to <dfn export>update the rendering</dfn>:</p>
<p class="note">This might cause redundant calls to <span>update the rendering</span>. However,
these calls would have no observable effect because there will be no rendering necessary, as
per the <i>Unnecessary rendering</i> step. Implementations can introduce further optimizations
such as only queuing this task when it is not already queued. However, note that the document
associated with the task might become inactive before the task is processed.</p>
<ol>
<li><p>Let <var>frameTimestamp</var> be <var>eventLoop</var>'s <span>last render opportunity
time</span>.</p></li>
<li>
<p>Let <var>docs</var> be all <span>fully active</span> <code>Document</code> objects whose
<span>relevant agent</span>'s <span data-x="concept-agent-event-loop">event loop</span> is
<var>eventLoop</var>, sorted arbitrarily except that the following conditions must be
met:</p>
<ul>
<li><p>Any <code>Document</code> <var>B</var> whose <span
data-x="doc-container-document">container document</span> is <var>A</var> must be listed
after <var>A</var> in the list.</p></li>
<li><p>If there are two documents <var>A</var> and <var>B</var> that both have the same
non-null <span data-x="doc-container-document">container document</span> <var>C</var>, then
the order of <var>A</var> and <var>B</var> in the list must match the <span>shadow-including
tree order</span> of their respective <span data-x="navigable container">navigable
containers</span> in <var>C</var>'s <span>node tree</span>.</p></li>
</ul>
<p>In the steps below that iterate over <var>docs</var>, each <code>Document</code> must be
processed in the order it is found in the list.</p>
</li>
<li>
<p><i>Filter non-renderable documents</i>: Remove from <var>docs</var> any
<code>Document</code> object <var>doc</var> for which any of the following are true:
<ul>
<li><p><var>doc</var> is <span>render-blocked</span>;</p></li>
<li><p><var>doc</var>'s <span>visibility state</span> is "<code
data-x="">hidden</code>";</p></li>
<li><p><var>doc</var>'s rendering is <span data-x="rendering suppression for view
transitions">suppressed for view transitions</span>; or</p></li>
<li><p><var>doc</var>'s <span>node navigable</span> doesn't currently have a <span>rendering
opportunity</span>.</p></li>
</ul>
<p class="note">We have to check for rendering opportunities here, in addition to checking
that in the <span>in parallel</span> steps, as some documents that share the same <span>event
loop</span> might not have a <span>rendering opportunity</span> at the same time.</p>
</li>
<li>
<p><i>Unnecessary rendering</i>: Remove from <var>docs</var> any <code>Document</code> object
<var>doc</var> for which all of the following are true:</p>
<ul>
<li><p>the user agent believes that updating the rendering of <var>doc</var>'s <span>node
navigable</span> would have no visible effect; and</p></li>
<li><p><var>doc</var>'s <span>map of animation frame callbacks</span> is empty.</p></li>
</ul>
</li>
<li>
<p>Remove from <var>docs</var> all <code>Document</code> objects for which the user agent
believes that it's preferable to skip updating the rendering for other reasons.</p>
<div class="note">
<p>The step labeled <i>Filter non-renderable documents</i> prevents the user agent from
updating the rendering when it is unable to present new content to the user.</p>
<p>The step labeled <i>Unnecessary rendering</i> prevents the user agent from updating the
rendering when there's no new content to draw.</p>
<p>This step enables the user agent to prevent the steps below from running for other
reasons, for example, to ensure certain <span data-x="concept-task">tasks</span> are
executed immediately after each other, with only <span data-x="perform a microtask
checkpoint">microtask checkpoints</span> interleaved (and without, e.g., <span data-x="run
the animation frame callbacks">animation frame callbacks</span> interleaved). Concretely, a
user agent might wish to coalesce timer callbacks together, with no intermediate rendering
updates.</p>
</div>
</li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>reveal</span> <var>doc</var>.</p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>flush autofocus candidates</span> for
<var>doc</var> if its <span>node navigable</span> is a <span>top-level
traversable</span>.</p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>run the resize steps</span> for
<var>doc</var>. <ref>CSSOMVIEW</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>run the scroll steps</span> for
<var>doc</var>. <ref>CSSOMVIEW</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>evaluate media queries and report
changes</span> for <var>doc</var>. <ref>CSSOMVIEW</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>update animations and send
events</span> for <var>doc</var>, passing in <span>relative high resolution time</span> given
<var>frameTimestamp</var> and <var>doc</var>'s <span>relevant global object</span> as the
timestamp <ref>WEBANIMATIONS</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>run the fullscreen steps</span> for
<var>doc</var>. <ref>FULLSCREEN</ref></p></li>
<li>
<p>For each <var>doc</var> of <var>docs</var>, if the user agent detects that the backing
storage associated with a <code>CanvasRenderingContext2D</code> or an
<code>OffscreenCanvasRenderingContext2D</code>, <var>context</var>, has been lost, then it
must run the <dfn>context lost steps</dfn> for each such <var>context</var>:</p>
<ol>
<li><p>Let <var>canvas</var> be the value of <var>context</var>'s <code
data-x="dom-context-2d-canvas">canvas</code> attribute, if <var>context</var> is a
<code>CanvasRenderingContext2D</code>, or the <span>associated <code>OffscreenCanvas</code>
object</span> for <var>context</var> otherwise.</p></li>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-context-lost">context
lost</span> to true.</p></li>
<li><p><span>Reset the rendering context to its default state</span> given
<var>context</var>.</p></li>
<li><p>Let <var>shouldRestore</var> be the result of <span
data-x="concept-event-fire">firing an event</span> named <code
data-x="event-contextlost">contextlost</code> at <var>canvas</var>, with the <code
data-x="dom-Event-cancelable">cancelable</code> attribute initialized to true.</p></li>
<li><p>If <var>shouldRestore</var> is false, then abort these steps.</p></li>
<li><p>Attempt to restore <var>context</var> by creating a backing storage using
<var>context</var>'s attributes and associating them with <var>context</var>. If this fails,
then abort these steps.</p></li>
<li><p>Set <var>context</var>'s <span data-x="concept-canvas-context-lost">context
lost</span> to false.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-contextrestored">contextrestored</code> at <var>canvas</var>.</p></li>
</ol>
</li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>run the animation frame
callbacks</span> for <var>doc</var>, passing in the <span>relative high resolution time</span>
given <var>frameTimestamp</var> and <var>doc</var>'s <span>relevant global object</span> as
the timestamp.</p></li>
<li><p>Let <var>unsafeStyleAndLayoutStartTime</var> be the <span>unsafe shared current
time</span>.</p>
<li>
<p>For each <var>doc</var> of <var>docs</var>:</p>
<ol>
<li><p>Let <var>resizeObserverDepth</var> be 0.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>Recalculate styles and update layout for <var>doc</var>.</p></li>
<li><p>Let <var>hadInitialVisibleContentVisibilityDetermination</var> be false.</p></li>
<li>
<p>For each element <var>element</var> with <span
data-x="content-visibility-auto">'auto'</span> used value of
<span>'content-visibility'</span>:</p>
<ol>
<li><p>Let <var>checkForInitialDetermination</var> be true if <var>element</var>'s
<span>proximity to the viewport</span> is not determined and it is not <span>relevant to
the user</span>. Otherwise, let <var>checkForInitialDetermination</var> be
false.</p></li>
<li><p>Determine <span>proximity to the viewport</span> for <var>element</var>.</p></li>
<li><p>If <var>checkForInitialDetermination</var> is true and <var>element</var> is now
<span>relevant to the user</span>, then set
<var>hadInitialVisibleContentVisibilityDetermination</var> to true.</p></li>
</ol>
</li>
<li>
<p>If <var>hadInitialVisibleContentVisibilityDetermination</var> is true, then
<span>continue</span>.</p>
<p class="note">The intent of this step is for the initial viewport proximity
determination, which takes effect immediately, to be reflected in the style and layout
calculation which is carried out in a previous step of this loop. Proximity
determinations other than the initial one take effect at the next <span>rendering
opportunity</span>. <ref>CSSCONTAIN</ref></p>
</li>
<li><p><span>Gather active resize observations at depth</span>
<var>resizeObserverDepth</var> for <var>doc</var>.</p></li>
<li><p>If <var>doc</var> <span>has active resize observations</span>:</p>
<ol>
<li><p>Set <var>resizeObserverDepth</var> to the result of <span data-x="broadcast
active resize observations">broadcasting active resize observations</span> given
<var>doc</var>.</p></li>
<li><span>Continue</span>.</li>
</ol>
</li>
<li>Otherwise, <span>break</span>.</li>
</ol>
</li>
<li><p>If <var>doc</var> <span>has skipped resize observations</span>, then <span>deliver
resize loop error</span> given <var>doc</var>.</p></li>
</ol>
</li>
<li id="focus-fixup-rule">
<p>For each <var>doc</var> of <var>docs</var>, if the <span data-x="focused area of the
document">focused area</span> of <var>doc</var> is not a <span>focusable area</span>, then
run the <span>focusing steps</span> for <var>doc</var>'s <span>viewport</span>, and set
<var>doc</var>'s <span>relevant global object</span>'s <span
data-x="window-navigation-api">navigation API</span>'s <span>focus changed during ongoing
navigation</span> to false.</p>
<p class="example">For example, this might happen because an element has the <code
data-x="attr-hidden">hidden</code> attribute added, causing it to stop <span>being
rendered</span>. It might also happen to an <code>input</code> element when the element gets
<span data-x="concept-fe-disabled">disabled</span>.</p>
<p class="note">This will <a href="#note-sometimes-no-blur-event">usually</a> fire <code
data-x="event-blur">blur</code> events, and possibly <code
data-x="event-change">change</code> events.</p>
<p class="note">In addition to this asynchronous fixup, if the <span>focused area of the
document</span> is removed, there is a <a href="#node-remove-focus-fixup">synchronous
fixup</a>. That one will <em>not</em> fire <code data-x="event-blur">blur</code> or <code
data-x="event-change">change</code> events.</p>
</li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>perform pending transition
operations</span> for <var>doc</var>. <ref>CSSVIEWTRANSITIONS</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>run the update intersection
observations steps</span> for <var>doc</var>, passing in the <span>relative high resolution
time</span> given <var>now</var> and <var>doc</var>'s <span>relevant global object</span> as
the timestamp. <ref>INTERSECTIONOBSERVER</ref></p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>record rendering time</span> for
<var>doc</var> given <var>unsafeStyleAndLayoutStartTime</var>.</p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>mark paint timing</span> for
<var>doc</var>.</p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, update the rendering or user interface of
<var>doc</var> and its <span>node navigable</span> to reflect the current state.</p></li>
<li><p>For each <var>doc</var> of <var>docs</var>, <span>process top layer removals</span>
given <var>doc</var>.</p></li>
</ol>
</li>
</ol>
<p>A <span>navigable</span> has a <dfn export>rendering opportunity</dfn> if the user agent is
currently able to present the contents of the <span>navigable</span> to the user, accounting for
hardware refresh rate constraints and user agent throttling for performance reasons, but
considering content presentable even if it's outside the viewport.</p>
<p>A <span>navigable</span>'s <span data-x="rendering opportunity">rendering opportunities</span>
are determined based on hardware constraints such as display refresh rates and other factors such
as page performance or whether its <span data-x="nav-document">active document</span>'s
<span>visibility state</span> is "<code data-x="">visible</code>". Rendering opportunities
typically occur at regular intervals.</p>
<p class="note">This specification does not mandate any particular model for selecting rendering
opportunities. But for example, if the browser is attempting to achieve a 60Hz refresh rate, then
rendering opportunities occur at a maximum of every 60th of a second (about 16.7ms). If the
browser finds that a <span>navigable</span> is not able to sustain this rate, it might drop to a
more sustainable 30 rendering opportunities per second for that <span>navigable</span>, rather
than occasionally dropping frames. Similarly, if a <span>navigable</span> is not visible, the
user agent might decide to drop that page to a much slower 4 rendering opportunities per second,
or even less.</p>
<hr>
<p>When a user agent is to <dfn export>perform a microtask checkpoint</dfn>:</p>
<ol>
<li><p>If the <span>event loop</span>'s <span>performing a microtask checkpoint</span> is true,
then return.</p></li>
<li><p>Set the <span>event loop</span>'s <span>performing a microtask checkpoint</span> to
true.</p></li>
<li>
<p>While the <span>event loop</span>'s <span>microtask queue</span> is not <span data-x="list is
empty">empty</span>:</p>
<ol>
<li><p>Let <var>oldestMicrotask</var> be the result of <span data-x="dequeue">dequeuing</span>
from the <span>event loop</span>'s <span>microtask queue</span>.</p></li>
<li><p>Set the <span>event loop</span>'s <span>currently running task</span> to
<var>oldestMicrotask</var>.</p></li>
<li>
<p>Run <var>oldestMicrotask</var>.</p>
<p class="note">This might involve invoking scripted callbacks, which eventually calls the
<span>clean up after running script</span> steps, which call this <span>perform a microtask
checkpoint</span> algorithm again, which is why we use the <span>performing a microtask
checkpoint</span> flag to avoid reentrancy.</p>
</li>
<li><p>Set the <span>event loop</span>'s <span>currently running task</span> back to
null.</p></li>
</ol>
</li>
<li><p>For each <span>environment settings object</span> <var>settingsObject</var> whose
<span>responsible event loop</span> is this <span>event loop</span>, <span>notify about rejected
promises</span> given <var>settingsObject</var>'s <span
data-x="concept-settings-object-global">global object</span>.</p></li>
<li><p><span>Cleanup Indexed Database transactions</span>.</p></li>
<li>
<p>Perform <span>ClearKeptObjects</span>().</p>
<p class="note">When <code>WeakRef.prototype.deref()</code> returns an object, that object is
kept alive until the next invocation of <span>ClearKeptObjects</span>(), after which it is again
subject to garbage collection.</p>
</li>
<li><p>Set the <span>event loop</span>'s <span>performing a microtask checkpoint</span> to
false.</p></li>
<li><p><span>Record timing info for microtask checkpoint</span>.</p></li>
</ol>
<hr>
<p>When an algorithm running <span>in parallel</span> is to <dfn>await a stable state</dfn>, the
user agent must <span>queue a microtask</span> that runs the following steps, and must then stop
executing (execution of the algorithm resumes when the microtask is run, as described in the
following steps):</p>
<ol>
<li><p>Run the algorithm's <dfn>synchronous section</dfn>.</p></li>
<li><p>Resumes execution of the algorithm <span>in parallel</span>, if appropriate, as described
in the algorithm's steps.</p></li>
</ol>
<p class="note">Steps in <span data-x="synchronous section">synchronous sections</span> are marked
with ⌛.</p>
<hr>
<p>Algorithm steps that say to <dfn>spin the event loop</dfn> until a condition <var>goal</var> is
met are equivalent to substituting in the following algorithm steps:</p>
<ol>
<li>
<p>Let <var>task</var> be the <span>event loop</span>'s <span>currently running
task</span>.</p>
<p class="note"><var>task</var> could be a <span>microtask</span>.</p>
</li>
<li><p>Let <var>task source</var> be <var>task</var>'s <span
data-x="concept-task-source">source</span>.</p></li>
<li><p>Let <var>old stack</var> be a copy of the <span>JavaScript execution context
stack</span>.</p></li>
<li><p>Empty the <span>JavaScript execution context stack</span>.</p></li>
<li>
<p><span>Perform a microtask checkpoint</span>.</p>
<p class="note">If <var>task</var> is a <span>microtask</span> this step will be a no-op due to
<span>performing a microtask checkpoint</span> being true.</p>
</li>
<li>
<p><span>In parallel</span>:</p>
<ol>
<li><p>Wait until the condition <var>goal</var> is met.</p></li>
<li>
<p><span>Queue a task</span> on <var>task source</var> to:</p>
<ol>
<li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
stack</var>.</p></li>
<li>
<p>Perform any steps that appear after this <span>spin the event loop</span> instance in the
original algorithm.</p>
<p class="note">This resumes <var>task</var>.</p>
</li>
</ol>
</li>
</ol>
</li>
<li>
<p>Stop <var>task</var>, allowing whatever algorithm that invoked it to resume.</p>
<p class="note">This causes the <span>event loop</span>'s main set of steps or the <span>perform
a microtask checkpoint</span> algorithm to continue.</p>
</li>
</ol>
<p class="note">Unlike other algorithms in this and other specifications, which behave similar to
programming-language function calls, <span>spin the event loop</span> is more like a macro, which
saves typing and indentation at the usage site by expanding into a series of steps and
operations.</p>
<div class="example">
<p>An algorithm whose steps are:</p>
<ol>
<li><p>Do something.</p></li>
<li><p><span>Spin the event loop</span> until awesomeness happens.</p></li>
<li><p>Do something else.</p></li>
</ol>
<p>is a shorthand which, after "macro expansion", becomes</p>
<ol>
<li><p>Do something.</p></li>
<li><p>Let <var>old stack</var> be a copy of the <span>JavaScript execution context
stack</span>.</p></li>
<li><p>Empty the <span>JavaScript execution context stack</span>.</p></li>
<li><p><span>Perform a microtask checkpoint</span>.</p></li>
<li>
<p><span>In parallel</span>:</p>
<ol>
<li><p>Wait until awesomeness happens.</p></li>
<li>
<p><span>Queue a task</span> on the task source in which "do something" was done to:</p>
<ol>
<li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
stack</var>.</p></li>
<li><p>Do something else.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</div>
<div class="example">
<p>Here is a more full example of the substitution, where the event loop is spun from inside a
task that is queued from work in parallel. The version using <span>spin the event loop</span>:</p>
<ol>
<li>
<p><span>In parallel</span>:</p>
<ol>
<li><p>Do parallel thing 1.</p></li>
<li>
<p><span>Queue a task</span> on the <span>DOM manipulation task source</span> to:</p>
<ol>
<li><p>Do task thing 1.</p></li>
<li><p><span>Spin the event loop</span> until awesomeness happens.</p></li>
<li><p>Do task thing 2.</p></li>
</ol>
</li>
<li><p>Do parallel thing 2.</p></li>
</ol>
</li>
</ol>
<p>The fully expanded version:</p>
<ol>
<li>
<p><span>In parallel</span>:</p>
<ol>
<li><p>Do parallel thing 1.</p></li>
<li><p>Let <var>old stack</var> be null.</p></li>
<li>
<p><span>Queue a task</span> on the <span>DOM manipulation task source</span> to:</p>
<ol>
<li><p>Do task thing 1.</p></li>
<li><p>Set <var>old stack</var> to a copy of the <span>JavaScript execution context
stack</span>.</p></li>
<li><p>Empty the <span>JavaScript execution context stack</span>.</p></li>
<li><p><span>Perform a microtask checkpoint</span>.</p></li>
</ol>
</li>
<li><p>Wait until awesomeness happens.</p></li>
<li>
<p><span>Queue a task</span> on the <span>DOM manipulation task source</span> to:</p>
<ol>
<li><p>Replace the <span>JavaScript execution context stack</span> with <var>old
stack</var>.</p></li>
<li><p>Do task thing 2.</p></li>
</ol>
</li>
<li><p>Do parallel thing 2.</p></li>
</ol>
</li>
</ol>
</div>
<hr>
<p>Some of the algorithms in this specification, for historical reasons, require the user agent to
<dfn export>pause</dfn> while running a <span data-x="concept-task">task</span> until a condition
<var>goal</var> is met. This means running the following steps:</p>
<ol>
<li><p>Let <var>global</var> be the <span>current global object</span>.</p></li>
<li><p>Let <var>timeBeforePause</var> be the <span>current high resolution time</span> given
<var>global</var>.</p></li>
<li><p>If necessary, update the rendering or user interface of any <code>Document</code> or
<span>navigable</span> to reflect the current state.</p></li>
<li><p>Wait until the condition <var>goal</var> is met. While a user agent has a paused
<span data-x="concept-task">task</span>, the corresponding <span>event loop</span> must not run
further <span data-x="concept-task">tasks</span>, and any script in the currently running <span
data-x="concept-task">task</span> must block. User agents should remain responsive to user input
while paused, however, albeit in a reduced capacity since the <span>event loop</span> will not be
doing anything.</p></li>
<li><p><span>Record pause duration</span> given the <span>duration from</span>
<var>timeBeforePause</var> to the <span>current high resolution time</span> given
<var>global</var>.</p></li>
</ol>
<div class="warning">
<p><span data-x="pause">Pausing</span> is highly detrimental to the user experience, especially
in scenarios where a single <span>event loop</span> is shared among multiple documents. User
agents are encouraged to experiment with alternatives to <span data-x="pause">pausing</span>,
such as <span data-x="spin the event loop">spinning the event loop</span> or even simply
proceeding without any kind of suspended execution at all, insofar as it is possible to do so
while preserving compatibility with existing content. This specification will happily change if
a less-drastic alternative is discovered to be web-compatible.</p>
<p>In the interim, implementers should be aware that the variety of alternatives that user agents
might experiment with can change subtle aspects of <span>event loop</span> behavior, including
<span data-x="concept-task">task</span> and <span>microtask</span> timing. Implementations should
continue experimenting even if doing so causes them to violate the exact semantics implied by the
<span>pause</span> operation.</p>
</div>
<h5>Generic task sources</h5>
<p>The following <span data-x="task source">task sources</span> are used by a number of mostly
unrelated features in this and other specifications.</p>
<dl>
<dt>The <dfn export>DOM manipulation task source</dfn></dt>
<dd>
<p>This <span>task source</span> is used for features that react to DOM manipulations, such as
things that happen in a non-blocking fashion when an element is <span data-x="node is inserted
into a document">inserted into the document</span>.</p>
</dd>
<dt>The <dfn export>user interaction task source</dfn></dt>
<dd>
<p>This <span>task source</span> is used for features that react to user interaction, for
example keyboard or mouse input.</p>
<p>Events sent in response to user input (e.g. <code
data-x="event-click">click</code> events) must be fired using <span
data-x="concept-task">tasks</span> <span data-x="queue a task">queued</span> with the <span>user
interaction task source</span>. <ref>UIEVENTS</ref></p> <!-- user
interaction events integration point -->
</dd>
<dt>The <dfn export>networking task source</dfn></dt>
<dd>
<p>This <span>task source</span> is used for features that trigger in response to network
activity.</p>
</dd>
<dt id="history-traversal-task-source">The <dfn>navigation and traversal task source</dfn></dt>
<dd>
<p>This <span>task source</span> is used to queue tasks involved in <span
data-x="navigate">navigation</span> and <span data-x="apply the traverse history step">history
traversal</span>.</p>
</dd>
<dt>The <dfn>rendering task source</dfn></dt>
<dd>
<p>This <span>task source</span> is used solely to <span>update the rendering</span>.
</dd>
</dl>
<h5 id="event-loop-for-spec-authors">Dealing with the event loop from other specifications</h5>
<p>Writing specifications that correctly interact with the <span>event loop</span> can be tricky.
This is compounded by how this specification uses concurrency-model-independent terminology, so we
say things like "<span>event loop</span>" and "<span>in parallel</span>" instead of using more
familiar model-specific terms like "main thread" or "on a background thread".</p>
<p>By default, specification text generally runs on the <span>event loop</span>. This falls out
from the formal <a href="#event-loop-processing-model">event loop processing model</a>, in that
you can eventually trace most algorithms back to a <span data-x="concept-task">task</span> <span
data-x="queue a task">queued</span> there.</p>
<p class="example">The algorithm steps for any JavaScript method will be invoked by author code
calling that method. And author code can only be run via queued tasks, usually originating
somewhere in the <a href="#script-processing-model"><code>script</code> processing model</a>.</p>
<p>From this starting point, the overriding guideline is that any work a specification needs to
perform that would otherwise block the <span>event loop</span> must instead be performed <span>in
parallel</span> with it. This includes (but is not limited to):</p>
<ul>
<li><p>performing heavy computation;</p></li>
<li><p>displaying a user-facing prompt;</p></li>
<li><p>performing operations which could require involving outside systems (i.e. "going out of
process").</p></li>
</ul>
<p>The next complication is that, in algorithm sections that are <span>in parallel</span>, you
must not create or manipulate objects associated to a specific <span>realm</span>, <span
data-x="global object">global</span>, or <span>environment settings object</span>. (Stated in more
familiar terms, you must not directly access main-thread artifacts from a background thread.)
Doing so would create data races observable to JavaScript code, since after all, your algorithm
steps are running <em><span>in parallel</span></em> to the JavaScript code.</p>
<p>By extension, you cannot access Web IDL's <span>this</span> value from steps running <span>in
parallel</span>, even if those steps were activated by an algorithm that <em>does</em> have access
to the <span>this</span> value.</p>
<p>You can, however, manipulate specification-level data structures and values from
<cite>Infra</cite>, as those are realm-agnostic. They are never directly exposed to JavaScript without
a specific conversion taking place (often <span data-x="concept-idl-convert">via Web IDL</span>).
<ref>INFRA</ref> <ref>WEBIDL</ref></p>
<p>To affect the world of observable JavaScript objects, then, you must <span>queue a global
task</span> to perform any such manipulations. This ensures your steps are properly interleaved
with respect to other things happening on the <span>event loop</span>. Furthermore, you must
choose a <span>task source</span> when <span data-x="queue a global task">queuing a global
task</span>; this governs the relative order of your steps versus others. If you are unsure which
<span>task source</span> to use, pick one of the <a href="#generic-task-sources">generic task
sources</a> that sounds most applicable. Finally, you must indicate which <span>global
object</span> your queued task is associated with; this ensures that if that global object is
inactive, the task does not run.</p>
<p class="note">The base primitive, on which <span>queue a global task</span> builds, is the
<span>queue a task</span> algorithm. In general, <span>queue a global task</span> is better
because it automatically picks the right <span>event loop</span> and, where appropriate, <span
data-x="concept-task-document">document</span>. Older specifications often use <span>queue a
task</span> combined with the <span>implied event loop</span> and <span>implied document</span>
concepts, but this is discouraged.</p>
<p>Putting this all together, we can provide a template for a typical algorithm that needs to do
work asynchronously:</p>
<ol>
<li><p>Do any synchronous setup work, while still on the <span>event loop</span>. This may
include converting <span>realm</span>-specific JavaScript values into realm-agnostic
specification-level values.</p></li>
<li><p>Perform a set of potentially-expensive steps <span>in parallel</span>, operating entirely
on realm-agnostic values, and producing a realm-agnostic result.</p></li>
<li><p><span>Queue a global task</span>, on a specified <span>task source</span> and given an
appropriate <span>global object</span>, to convert the realm-agnostic result back into observable
effects on the observable world of JavaScript objects on the <span>event loop</span>.</p></li>
</ol>
<div class="example" id="example-event-loop-using-algorithm">
<p>The following is an algorithm that "encrypts" a passed-in <span>list</span> of <span
data-x="scalar value string">scalar value strings</span> <var>input</var>, after parsing them as
URLs:</p>
<ol>
<li><p>Let <var>urls</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>string</var> of <var>input</var>:</p>
<ol>
<li><p>Let <var>parsed</var> be the result of <span>encoding-parsing a URL</span> given
<var>string</var>, relative to the <span>current settings object</span>.</p></li>
<li><p>If <var>parsed</var> is failure, then return <span>a promise rejected with</span> a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>serialized</var> be the result of applying the <span
data-x="concept-url-serializer">URL serializer</span> to <var>parsed</var>.</p></li>
<li><p><span data-x="list append">Append</span> <var>serialized</var> to <var>urls</var>.</p></li>
</ol>
</li>
<li><p>Let <var>realm</var> be the <span>current realm</span>.</p></li>
<li><p>Let <var>p</var> be a new promise.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li><p>Let <var>encryptedURLs</var> be an empty <span>list</span>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>url</var> of <var>urls</var>:</p>
<ol>
<li><p>Wait 100 milliseconds, so that people think we're doing heavy-duty encryption.</p></li>
<li><p>Let <var>encrypted</var> be a new <span>string</span> derived from <var>url</var>,
whose <var>n</var>th <span>code unit</span> is equal to <var>url</var>'s <var>n</var>th
<span>code unit</span> plus 13.</p></li>
<li><p><span data-x="list append">Append</span> <var>encrypted</var> to
<var>encryptedURLs</var>.</p>
</ol>
</li>
<li>
<p><span>Queue a global task</span> on the <span>networking task source</span>, given
<var>realm</var>'s <span data-x="concept-realm-global">global object</span>, to perform the
following steps:</p>
<ol>
<li><p>Let <var>array</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>encryptedURLs</var> to a JavaScript
array, in <var>realm</var>.</p></li>
<li><p>Resolve <var>p</var> with <var>array</var>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>p</var>.</p></li>
</ol>
<p>Here are several things to notice about this algorithm:</p>
<ul>
<li><p>It does its URL parsing up front, on the <span>event loop</span>, before going to the
<span>in parallel</span> steps. This is necessary, since parsing depends on the <span>current
settings object</span>, which would no longer be current after going <span>in
parallel</span>.</p></li>
<li><p>Alternately, it could have saved a reference to the <span>current settings
object</span>'s <span>API base URL</span> and used it during the <span>in parallel</span> steps;
that would have been equivalent. However, we recommend instead doing as much work as possible up
front, as this example does. Attempting to save the correct values can be error prone; for
example, if we'd saved just the <span>current settings object</span>, instead of its <span>API
base URL</span>, there would have been a potential race.</p></li>
<li><p>It implicitly passes a <span>list</span> of <span data-x="string">strings</span> from the
initial steps to the <span>in parallel</span> steps. This is OK, as both <span
data-x="list">lists</span> and <span data-x="string">strings</span> are
<span>realm</span>-agnostic.</p></li>
<li><p>It performs "expensive computation" (waiting for 100 milliseconds per input URL) during
the <span>in parallel</span> steps, thus not blocking the main <span>event loop</span>.</p></li>
<li><p>Promises, as observable JavaScript objects, are never created and manipulated during the
<span>in parallel</span> steps. <var>p</var> is created before entering those steps, and then is
manipulated during a <span data-x="concept-task">task</span> that is <span data-x="queue a
global task">queued</span> specifically for that purpose.</p></li>
<li><p>The creation of a JavaScript array object also happens during the queued task, and is
careful to specify which realm it creates the array in since that is no longer obvious from
context.</p></li>
</ul>
<p>(On these last two points, see also <a
href="https://github.com/whatwg/webidl/issues/135">whatwg/webidl issue #135</a> and <a
href="https://github.com/whatwg/webidl/issues/371">whatwg/webidl issue #371</a>, where we are
still mulling over the subtleties of the above promise-resolution pattern.)</p>
<p>Another thing to note is that, in the event this algorithm was called from a Web IDL-specified
operation taking a <code data-x="">sequence</code><<code
data-x="idl-USVString">USVString</code>>, there was an automatic conversion from
<span>realm</span>-specific JavaScript objects provided by the author as input, into the
realm-agnostic <code data-x="">sequence</code><<code data-x="idl-USVString">USVString</code>>
Web IDL type, which we then treat as a <span>list</span> of <span data-x="scalar value
string">scalar value strings</span>. So depending on how your specification is structured, there
may be other implicit steps happening on the main <span>event loop</span> that play a part in
this whole process of getting you ready to go <span>in parallel</span>.</p>
</div>
</div>
<h4>Events</h4>
<h5 id="event-handler-attributes">Event handlers</h5>
<p>Many objects can have <dfn export data-lt="event handler">event handlers</dfn> specified. These
act as non-capture <span data-x="event listener">event listeners</span> for the object on which
they are specified. <ref>DOM</ref></p>
<div w-nodev>
<p>An <span data-x="event handlers">event handler</span> is a <span>struct</span> with two <span
data-x="struct item">items</span>:</p>
<ul>
<li><p>a <dfn export for="event handler" data-x="event handler value">value</dfn>, which is
either null<span w-nodev>,</span><span w-dev> or</span> a callback object<span w-nodev>, or an
<span>internal raw uncompiled handler</span></span>. The <code>EventHandler</code> callback
function type describes how this is exposed to scripts. <span w-nodev>Initially, an <span
data-x="event handlers">event handler</span>'s <span data-x="event handler value">value</span>
must be set to null.</span></p></li>
<li><p>a <dfn export for="event handler" data-x="event handler listener">listener</dfn>, which
is either null or an <span>event listener</span><span w-nodev> responsible for running <span>the
event handler processing algorithm</span></span>. <span w-nodev>Initially, an <span
data-x="event handlers">event handler</span>'s <span data-x="event handler
listener">listener</span> must be set to null.</span></p></li>
</ul>
</div>
<p>Event handlers are exposed in two ways.</p>
<p>The first way, common to all event handlers, is as an <span data-x="event handler IDL
attributes">event handler IDL attribute</span>.</p>
<p>The second way is as an <span data-x="event handler content attributes">event handler content
attribute</span>. Event handlers on <span>HTML elements</span> and some of the event handlers on
<code>Window</code> objects are exposed in this way.</p>
<p>For both of these two ways, the <span data-x="event handlers">event handler</span> is exposed
through a <dfn data-x="event handler name">name</dfn>, which is a string that always starts with
"<code data-x="">on</code>" and is followed by the name of the event for which the handler is
intended.</p>
<hr>
<p>Most of the time, the object that exposes an <span data-x="event handlers">event handler</span>
is the same as the object on which the corresponding <span>event listener</span> is added.
However, the <code>body</code> and <code>frameset</code> elements expose several <span>event
handlers</span> that act upon the element's <code>Window</code> object, if one exists. In either
case, we call the object an <span data-x="event handlers">event handler</span> acts upon the <dfn
data-x="event handler target">target</dfn> of that <span data-x="event handlers">event
handler</span>.</p>
<div w-nodev>
<p>To <dfn data-x="determining the target of an event handler">determine the target of an event
handler</dfn>, given an <code>EventTarget</code> object <var>eventTarget</var> on which the <span
data-x="event handlers">event handler</span> is exposed, and an <span>event handler name</span>
<var>name</var>, the following steps are taken:</p>
<ol>
<li><p>If <var>eventTarget</var> is not a <code>body</code> element or a <code>frameset</code>
element, then return <var>eventTarget</var>.</p></li>
<li><p>If <var>name</var> is not the name of an attribute member of the
<code>WindowEventHandlers</code> interface mixin and the <span><code>Window</code>-reflecting
body element event handler set</span> does not <span data-x="list contains">contain</span>
<var>name</var>, then return <var>eventTarget</var>.</p></li>
<li>
<p>If <var>eventTarget</var>'s <span>node document</span> is not an <span>active
document</span>, then return null.</p>
<p class="note">This could happen if this object is a <code>body</code> element without
a corresponding <code>Window</code> object, for example.</p>
<p class="note">This check does not necessarily prevent <code>body</code> and
<code>frameset</code> elements that are not <span>the body element</span> of their <span>node
document</span> from reaching the next step. In particular, a <code>body</code> element created
in an <span>active document</span> (perhaps with <code
data-x="dom-Document-createElement">document.createElement()</code>) but not
<span>connected</span> will also have its corresponding <code>Window</code> object as the <span
data-x="event handler target">target</span> of several <span>event handlers</span> exposed
through it.</p>
</li>
<li><p>Return <var>eventTarget</var>'s <span>node document</span>'s <span>relevant global
object</span>.</p></li>
</ol>
<hr>
<p>Each <code>EventTarget</code> object that has one or more <span>event handlers</span> specified
has an associated <dfn export for="EventTarget">event handler map</dfn>, which is a <span
data-x="ordered map">map</span> of strings representing <span data-x="event handler
name">names</span> of <span>event handlers</span> to <span>event handlers</span>.</p>
<p>When an <code>EventTarget</code> object that has one or more <span>event handlers</span>
specified is created, its <span>event handler map</span> must be initialized such that it contains
an <span data-x="map entry">entry</span> for each <span data-x="event handlers">event
handler</span> that has that object as <span data-x="event handler target">target</span>, with
<span data-x="struct item">items</span> in those <span>event handlers</span> set to their initial
values.</p>
<p class="note">The order of the <span data-x="map entry">entries</span> of <span>event handler
map</span> could be arbitrary. It is not observable through any algorithms that operate on the
map.</p>
<p class="note"><span data-x="map entry">Entries</span> are not created in the <span>event handler
map</span> of an object for <span>event handlers</span> that are merely exposed on that object,
but have some other object as their <span data-x="event handler target">targets</span>.</p>
</div>
<hr>
<p>An <dfn data-x="event handler IDL attributes" export>event handler IDL attribute</dfn> is an
IDL attribute for a specific <span data-x="event handlers">event handler</span>. The name of the
IDL attribute is the same as the <span data-x="event handler name">name</span> of the <span
data-x="event handlers">event handler</span>.</p>
<div w-nodev>
<p>The getter of an <span data-x="event handler IDL attributes">event handler IDL attribute</span>
with name <var>name</var>, when called, must run these steps:</p>
<ol>
<li><p>Let <var>eventTarget</var> be the result of <span>determining the target of an event
handler</span> given this object and <var>name</var>.</p></li>
<li><p>If <var>eventTarget</var> is null, then return null.</p></li>
<li><p>Return the result of <span>getting the current value of the event handler</span> given
<var>eventTarget</var> and <var>name</var>.</p>
</ol>
<p>The setter of an <span data-x="event handler IDL attributes">event handler IDL attribute</span>
with name <var>name</var>, when called, must run these steps:</p>
<ol>
<li><p>Let <var>eventTarget</var> be the result of <span>determining the target of an event
handler</span> given this object and <var>name</var>.</p></li>
<li><p>If <var>eventTarget</var> is null, then return.</p></li>
<li><p>If the given value is null, then <span>deactivate an event handler</span> given
<var>eventTarget</var> and <var>name</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>handlerMap</var> be <var>eventTarget</var>'s <span>event handler
map</span>.</p></li>
<li><p>Let <var>eventHandler</var> be <var>handlerMap</var>[<var>name</var>].</p></li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler value">value</span> to the
given value.</p></li>
<li><p><span>Activate an event handler</span> given <var>eventTarget</var> and
<var>name</var>.</p></li>
</ol>
</li>
</ol>
<p class="note">Certain <span>event handler IDL attributes</span> have additional requirements, in
particular the <code data-x="handler-MessageEventTarget-onmessage">onmessage</code> attribute of
<code>MessagePort</code> objects.</p>
</div>
<hr>
<p>An <dfn data-x="event handler content attributes" export>event handler content attribute</dfn>
is a content attribute for a specific <span data-x="event handlers">event handler</span>. The name
of the content attribute is the same as the <span data-x="event handler name">name</span> of the
<span data-x="event handlers">event handler</span>.</p>
<p><span>Event handler content attributes</span>, when specified, must contain valid JavaScript
code which, when parsed, would match the <i data-x="js-prod-FunctionBody">FunctionBody</i>
production after <span>automatic semicolon insertion</span>.</p>
<div w-nodev>
<p>The following <span data-x="concept-element-attributes-change-ext">attribute change
steps</span> are used to synchronize between <span>event handler content attributes</span> and
<span>event handlers</span>: <ref>DOM</ref></p>
<ol>
<li><p>If <var>namespace</var> is not null, or <var>localName</var> is not the name of an <span
data-x="event handler content attributes">event handler content attribute</span> on
<var>element</var>, then return.</p></li>
<li><p>Let <var>eventTarget</var> be the result of <span>determining the target of an event
handler</span> given <var>element</var> and <var>localName</var>.</p></li>
<li><p>If <var>eventTarget</var> is null, then return.</p></li>
<li><p>If <var>value</var> is null, then <span>deactivate an event handler</span> given
<var>eventTarget</var> and <var>localName</var>.</p></li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>If the <span>Should element's inline behavior be blocked by Content Security
Policy?</span> algorithm returns "<code data-x="">Blocked</code>" when executed upon
<var>element</var>, "<code data-x="">script attribute</code>", and <var>value</var>, then
return. <ref>CSP</ref></p></li>
<li><p>Let <var>handlerMap</var> be <var>eventTarget</var>'s <span>event handler
map</span>.</p></li>
<li><p>Let <var>eventHandler</var> be <var>handlerMap</var>[<var>localName</var>].</p></li>
<li><p>Let <var>location</var> be the script location that triggered the execution of these
steps.</p></li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler value">value</span> to the
<span>internal raw uncompiled handler</span> <var>value</var>/<var>location</var>.</p></li>
<li><p><span>Activate an event handler</span> given <var>eventTarget</var> and
<var>localName</var>.</p></li>
</ol>
</li>
</ol>
<p class="note">Per the DOM Standard, these steps are run even if <var>oldValue</var> and
<var>value</var> are identical (setting an attribute to its current value), but <em>not</em> if
<var>oldValue</var> and <var>value</var> are both null (removing an attribute that doesn't
currently exist). <ref>DOM</ref></p>
<hr>
<p>To <dfn>deactivate an event handler</dfn> given an <code>EventTarget</code> object
<var>eventTarget</var> and a string <var>name</var> that is the <span data-x="event handler
name">name</span> of an <span data-x="event handlers">event handler</span>, run these steps:</p>
<ol>
<li><p>Let <var>handlerMap</var> be <var>eventTarget</var>'s <span>event handler
map</span>.</p></li>
<li><p>Let <var>eventHandler</var> be <var>handlerMap</var>[<var>name</var>].</p></li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler value">value</span> to
null.</p></li>
<li><p>Let <var>listener</var> be <var>eventHandler</var>'s <span data-x="event handler
listener">listener</span>.</p></li>
<li><p>If <var>listener</var> is not null, then <span>remove an event listener</span> with
<var>eventTarget</var> and <var>listener</var>.</p></li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler listener">listener</span> to
null.</p></li>
</ol>
<p>To <dfn>erase all event listeners and handlers</dfn> given an <code>EventTarget</code> object
<var>eventTarget</var>, run these steps:</p>
<ol>
<li><p>If <var>eventTarget</var> has an associated <span>event handler map</span>, then for each
<var>name</var> → <var>eventHandler</var> of <var>eventTarget</var>'s associated <span>event
handler map</span>, <span>deactivate an event handler</span> given <var>eventTarget</var> and
<var>name</var>.</p></li>
<li><p><span>Remove all event listeners</span> given <var>eventTarget</var>.</p></li>
</ol>
<p class="note">This algorithm is used to define <code
data-x="dom-document-open">document.open()</code>.</p>
<p>To <dfn>activate an event handler</dfn> given an <code>EventTarget</code> object
<var>eventTarget</var> and a string <var>name</var> that is the <span data-x="event handler
name">name</span> of an <span data-x="event handlers">event handler</span>, run these steps:</p>
<ol>
<li><p>Let <var>handlerMap</var> be <var>eventTarget</var>'s <span>event handler
map</span>.</p></li>
<li><p>Let <var>eventHandler</var> be <var>handlerMap</var>[<var>name</var>].</p></li>
<li><p>If <var>eventHandler</var>'s <span data-x="event handler listener">listener</span> is not
null, then return.</p></li>
<li>
<p>Let <var>callback</var> be the result of creating a Web IDL <code
data-x="dom-EventListener">EventListener</code> instance representing a reference to a function
of one argument that executes the steps of <span>the event handler processing algorithm</span>,
given <var>eventTarget</var>, <var>name</var>, and its argument.</p>
<p>The <code data-x="dom-EventListener">EventListener</code>'s <span>callback context</span> can
be arbitrary; it does not impact the steps of <span>the event handler processing
algorithm</span>. <ref>DOM</ref></p>
<p class="note">The callback is emphatically <em>not</em> the <span data-x="event
handlers">event handler</span> itself. Every event handler ends up registering the same
callback, the algorithm defined below, which takes care of invoking the right code, and
processing the code's return value.</p>
</li>
<li>
<p>Let <var>listener</var> be a new <span>event listener</span> whose <span data-x="event
listener type">type</span> is the <dfn export>event handler event type</dfn> corresponding to
<var>eventHandler</var> and <span data-x="event listener callback">callback</span> is
<var>callback</var>.</p>
<p class="note">To be clear, an <span>event listener</span> is different from an <code
data-x="dom-EventListener">EventListener</code>.</p>
</li>
<li><p><span>Add an event listener</span> with <var>eventTarget</var> and
<var>listener</var>.</p></li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler listener">listener</span> to
<var>listener</var>.</p></li>
</ol>
<div class="note">
<p>The event listener registration happens only if the <span data-x="event handlers">event
handler</span>'s <span data-x="event handler value">value</span> is being set to non-null, and
the <span data-x="event handlers">event handler</span> is not already activated. Since listeners
are called in the order they were registered, assuming no <span data-x="deactivate an event
handler">deactivation</span> occurred, the order of event listeners for a particular event type
will always be:</p>
<ol>
<li><p>the event listeners registered with <code
data-x="dom-EventTarget-addEventListener">addEventListener()</code> before the first time the
<span data-x="event handlers">event handler</span>'s <span data-x="event handler
value">value</span> was set to non-null</p></li>
<li><p>then the callback to which it is currently set, if any</p></li>
<li><p>and finally the event listeners registered with <code
data-x="dom-EventTarget-addEventListener">addEventListener()</code> <em>after</em> the first
time the <span data-x="event handlers">event handler</span>'s <span data-x="event handler
value">value</span> was set to non-null.</p></li>
</ol>
</div>
</div>
<div class="example">
<p>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.</p>
<pre><code class="html"><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></code></pre>
<p>However, in the following example, the event handler is <span data-x="deactivate an event
handler">deactivated</span> 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.</p>
<pre><code class="html"><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></code></pre>
</div>
<div w-nodev>
<p class="note">The interfaces implemented by the event object do not influence whether an <span
data-x="event handlers">event handler</span> is triggered or not.</p>
<p><dfn>The event handler processing algorithm</dfn> for an <code>EventTarget</code> object
<var>eventTarget</var>, a string <var>name</var> representing the <span data-x="event handler
name">name</span> of an <span data-x="event handlers">event handler</span>, and an
<code>Event</code> object <var>event</var> is as follows:</p>
<ol>
<li><p>Let <var>callback</var> be the result of <span>getting the current value of the event
handler</span> given <var>eventTarget</var> and <var>name</var>.</p></li>
<li><p>If <var>callback</var> is null, then return.</p></li>
<li><p>Let <var>special error event handling</var> be true if <var>event</var> is an
<code>ErrorEvent</code> object, <var>event</var>'s <code data-x="dom-Event-type">type</code> is
"<code data-x="event-error">error</code>", and <var>event</var>'s <code
data-x="dom-Event-currentTarget">currentTarget</code> implements the
<code>WindowOrWorkerGlobalScope</code> mixin. Otherwise, let <var>special error event
handling</var> be false.</p></li>
<li>
<p>Process the <code>Event</code> object <var>event</var> as follows:</p>
<dl class="switch">
<dt>If <var>special error event handling</var> is true</dt>
<dd>
<p>Let <var>return value</var> be the result of <span
data-x="es-invoking-callback-functions">invoking</span> <var>callback</var> with «
<var>event</var>'s <code data-x="dom-ErrorEvent-message">message</code>, <var>event</var>'s
<code data-x="dom-ErrorEvent-filename">filename</code>, <var>event</var>'s <code
data-x="dom-ErrorEvent-lineno">lineno</code>, <var>event</var>'s <code
data-x="dom-ErrorEvent-colno">colno</code>, <var>event</var>'s <code
data-x="dom-ErrorEvent-error">error</code> », "<code data-x="">rethrow</code>", and with <i
data-x="dfn-callback-this-value">callback this value</i> set to <var>event</var>'s <code
data-x="dom-Event-currentTarget">currentTarget</code>.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>Let <var>return value</var> be the result of <span
data-x="es-invoking-callback-functions">invoking</span> <var>callback</var> with «
<var>event</var> », "<code data-x="">rethrow</code>", and with <i
data-x="dfn-callback-this-value">callback this value</i> set to <var>event</var>'s <code
data-x="dom-Event-currentTarget">currentTarget</code>.</p>
</dd>
</dl>
<p class="note">If an exception gets thrown by the callback, it will be rethrown, ending these
steps. The exception will propagate to the <span data-x="concept-event-dispatch">DOM event
dispatch logic</span>, which will then <span data-x="report an exception">report</span> it.</p>
</li>
<li>
<p>Process <var>return value</var> as follows:</p>
<dl class="switch">
<dt>If <var>event</var> is a <code>BeforeUnloadEvent</code> object and <var>event</var>'s <code
data-x="dom-Event-type">type</code> is "<code
data-x="event-beforeunload">beforeunload</code>"</dt>
<!-- It is possible to get a BeforeUnloadEvent object whose type is not beforeunload via
document.createEvent("beforeunloadevent") + initEvent. This may be removed; see
https://github.com/whatwg/dom/issues/362. But it's still probably a good idea to check both,
just in case e.g. we end up adding a constructor to BeforeUnloadEvent. -->
<dd>
<p class="note">In this case, the <span data-x="event handler IDL attributes">event handler
IDL attribute</span>'s type will be <code>OnBeforeUnloadEventHandler</code>, so <var>return
value</var> will have been coerced into either null or a <code
data-x="idl-DOMString">DOMString</code>.</p>
<p>If <var>return value</var> is not null, then:</p>
<ol>
<li><p>Set <var>event</var>'s <span>canceled flag</span>.</p></li>
<li><p>If <var>event</var>'s <code
data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code> attribute's value is the empty
string, then set <var>event</var>'s <code
data-x="dom-BeforeUnloadEvent-returnValue">returnValue</code> attribute's value to
<var>return value</var>.</p></li>
</ol>
</dd>
<dt>If <var>special error event handling</var> is true</dt>
<dd><p>If <var>return value</var> is true, then set <var>event</var>'s <span>canceled
flag</span>.</p></dd>
<dt>Otherwise</dt>
<dd>
<p>If <var>return value</var> is false, then set <var>event</var>'s <span>canceled
flag</span>.</p>
<p class="note">If we've gotten to this "Otherwise" clause because <var>event</var>'s <code
data-x="dom-Event-type">type</code> is "<code
data-x="event-beforeunload">beforeunload</code>" but <var>event</var> is <em>not</em> a
<code>BeforeUnloadEvent</code> object, then <var>return value</var> will never be false, since
in such cases <var>return value</var> will have been coerced into either null or a <code
data-x="idl-DOMString">DOMString</code>.</p>
</dd>
</dl>
</li>
</ol>
</div>
<hr>
<p>The <code>EventHandler</code> callback function type represents a callback used for event
handlers.<span w-nodev> It is represented in Web IDL as follows:</span></p>
<pre><code class="idl">[<span>LegacyTreatNonObjectAsNull</span>]
callback <dfn callback>EventHandlerNonNull</dfn> = any (<span>Event</span> event);
typedef <span>EventHandlerNonNull</span>? <dfn typedef>EventHandler</dfn>;</code></pre>
<p class="note">In JavaScript, any <code data-x="idl-Function">Function</code> object implements
this interface.</p>
<div class="example">
<p>For example, the following document fragment:</p>
<pre><code class="html"><body onload="alert(this)" onclick="alert(this)"></code></pre>
<p>...leads to an alert saying "<code data-x="">[object Window]</code>" when the document is
loaded, and an alert saying "<code data-x="">[object HTMLBodyElement]</code>" whenever the
user clicks something in the page.</p>
</div>
<div class="note">
<p>The return value of the function affects whether the event is canceled or not: <span
w-nodev>as described above, </span>if the return value is false, the event is canceled.</p>
<p>There are two exceptions in the platform, for historical reasons:</p>
<ul>
<li><p>The <code data-x="handler-onerror">onerror</code> handlers on global objects, where
returning <em>true</em> cancels the event.</p></li>
<li><p>The <code data-x="handler-window-onbeforeunload">onbeforeunload</code> handler, where
returning any non-null and non-undefined value will cancel the event.</p></li>
</ul>
</div>
<p>For historical reasons, the <code data-x="handler-onerror">onerror</code> handler has different
arguments:</p>
<pre><code class="idl">[<span>LegacyTreatNonObjectAsNull</span>]
callback <dfn callback>OnErrorEventHandlerNonNull</dfn> = any ((<span>Event</span> or DOMString) event, optional DOMString source, optional unsigned long lineno, optional unsigned long colno, optional any error);
typedef <span>OnErrorEventHandlerNonNull</span>? <dfn typedef>OnErrorEventHandler</dfn>;</code></pre>
<div class="example">
<pre><code class="js">window.onerror = (message, source, lineno, colno, error) => { … };</code></pre>
</div>
<p>Similarly, the <code data-x="handler-window-onbeforeunload">onbeforeunload</code> handler has a
different return value:<span w-dev> it will be cast to a string.</span></p>
<pre><code class="idl">[<span>LegacyTreatNonObjectAsNull</span>]
callback <dfn callback>OnBeforeUnloadEventHandlerNonNull</dfn> = DOMString? (<span>Event</span> event);
typedef <span>OnBeforeUnloadEventHandlerNonNull</span>? <dfn typedef>OnBeforeUnloadEventHandler</dfn>;</code></pre>
<!-- onreadystatechange is also defined specially, using [LenientThis]; see IDL -->
<div w-nodev>
<hr>
<p>An <dfn>internal raw uncompiled handler</dfn> is a tuple with the following information:</p>
<ul>
<li><p>An uncompiled script body</p></li>
<li><p>A location where the script body originated, in case an error needs to be
reported</p></li>
</ul>
<p>When the user agent is to <dfn data-x="getting the current value of the event handler">get the
current value of the event handler</dfn> given an <code>EventTarget</code> object
<var>eventTarget</var> and a string <var>name</var> that is the <span data-x="event handler
name">name</span> of an <span data-x="event handlers">event handler</span>, it must run these
steps:</p>
<ol>
<li><p>Let <var>handlerMap</var> be <var>eventTarget</var>'s <span>event handler
map</span>.</p></li>
<li><p>Let <var>eventHandler</var> be <var>handlerMap</var>[<var>name</var>].</p></li>
<li>
<p>If <var>eventHandler</var>'s <span data-x="event handler value">value</span> is an
<span>internal raw uncompiled handler</span>, then:</p>
<ol>
<li><p>If <var>eventTarget</var> is an element, then let <var>element</var> be
<var>eventTarget</var>, and <var>document</var> be <var>element</var>'s <span>node
document</span>. Otherwise, <var>eventTarget</var> is a <code>Window</code> object, let
<var>element</var> be null, and <var>document</var> be <var>eventTarget</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <span data-x="concept-n-noscript">scripting is disabled</span> for
<var>document</var>, then return null.</p></li>
<li><p>Let <var>body</var> be the uncompiled script body in <var>eventHandler</var>'s <span
data-x="event handler value">value</span>.</p></li>
<li><p>Let <var>location</var> be the location where the script body originated, as
given by <var>eventHandler</var>'s <span data-x="event handler value">value</span>.</p></li>
<li><p>If <var>element</var> is not null and <var>element</var> has a
<span>form owner</span>, let <var>form owner</var> be that <span>form owner</span>.
Otherwise, let <var>form owner</var> be null.</p></li>
<li><p>Let <var>settings object</var> be the <span>relevant settings object</span> of
<var>document</var>.</p></li>
<li>
<p>If <var>body</var> is not parsable as <i data-x="js-prod-FunctionBody">FunctionBody</i>
or if parsing detects an <span>early error</span>, then follow these substeps:</p>
<ol>
<li>
<p>Set <var>eventHandler</var>'s <span data-x="event handler value">value</span> to
null.</p>
<p class="note">This does not <span data-x="deactivate an event handler">deactivate</span>
the event handler, which additionally <span data-x="remove an event listener">removes</span>
the event handler's <span data-x="event handler listener">listener</span> (if present).</p>
</li>
<li><p>Let <var>syntaxError</var> be a new <code>SyntaxError</code> exception associated
with <var>settings object</var>'s <span data-x="environment settings object's
realm">realm</span> which describes the error while parsing. It should be based on
<var>location</var>, where the script body originated.</p></li>
<li><p><span>Report an exception</span> with <var>syntaxError</var>
for <var>settings object</var>'s <span data-x="concept-settings-object-global">global
object</span>.</p></li>
<li><p>Return null.</p></li>
</ol>
</li>
<li>
<p>Push <var>settings object</var>'s <span>realm execution context</span> onto the
<span>JavaScript execution context stack</span>; it is now the <span>running JavaScript
execution context</span>.</p>
<p class="note">This is necessary so the subsequent invocation of <span
data-x="js-OrdinaryFunctionCreate">OrdinaryFunctionCreate</span> takes place in the correct
<span>realm</span>.</p>
</li>
<li>
<p>Let <var>function</var> be the result of calling <span
data-x="js-OrdinaryFunctionCreate">OrdinaryFunctionCreate</span>, with arguments:</p>
<dl>
<dt><var>functionPrototype</var></dt>
<dd><span>%Function.prototype%</span></dd>
<dt><var>sourceText</var></dt>
<dd>
<dl class="switch">
<dt>If <var>name</var> is <code data-x="handler-onerror">onerror</code> and
<var>eventTarget</var> is a <code>Window</code> object</dt>
<dd>The string formed by concatenating "<code data-x="">function </code>", <var>name</var>,
"<code data-x="">(event, source, lineno, colno, error) {</code>", U+000A LF,
<var>body</var>, U+000A LF, and "<code data-x="">}</code>".</dd>
<dt>Otherwise</dt>
<dd>The string formed by concatenating "<code data-x="">function </code>", <var>name</var>,
"<code data-x="">(event) {</code>", U+000A LF, <var>body</var>, U+000A LF, and "<code
data-x="">}</code>".</dd>
</dl>
</dd>
<dt><var>ParameterList</var></dt>
<dd>
<dl class="switch">
<dt>If <var>name</var> is <code data-x="handler-onerror">onerror</code> and
<var>eventTarget</var> is a <code>Window</code> object</dt>
<dd>Let the function have five arguments, named <code data-x="">event</code>, <code
data-x="">source</code>, <code data-x="">lineno</code>, <code data-x="">colno</code>, and
<code data-x="">error</code>.</dd>
<dt>Otherwise</dt>
<dd>Let the function have a single argument called <code data-x="">event</code>.</dd>
</dl>
</dd>
<dt><var>body</var></dt>
<dd>The result of parsing <var>body</var> above.</dd>
<dt><var>thisMode</var></dt>
<dd>non-lexical-this</dd>
<dt><var>scope</var></dt>
<dd>
<ol>
<li><p>Let <var>realm</var> be <var>settings object</var>'s <span
data-x="environment settings object's realm">realm</span>.</p></li>
<li><p>Let <var>scope</var> be <var>realm</var>.[[GlobalEnv]].</p></li>
<li>
<p>If <var>eventHandler</var> is an element's <span data-x="event handlers">event
handler</span>, then set <var>scope</var> to <span
data-x="js-NewObjectEnvironment">NewObjectEnvironment</span>(<var>document</var>, true,
<var>scope</var>).</p>
<p>(Otherwise, <var>eventHandler</var> is a <code>Window</code> object's <span
data-x="event handlers">event handler</span>.)</p>
</li>
<li><p>If <var>form owner</var> is not null, then set <var>scope</var> to <span
data-x="js-NewObjectEnvironment">NewObjectEnvironment</span>(<var>form owner</var>, true,
<var>scope</var>).</p></li>
<li><p>If <var>element</var> is not null, then set <var>scope</var> to <span
data-x="js-NewObjectEnvironment">NewObjectEnvironment</span>(<var>element</var>, true,
<var>scope</var>).</p></li>
<li><p>Return <var>scope</var>.</p></li>
</ol>
</dd>
</dl>
</li>
<li><p>Remove <var>settings object</var>'s <span>realm execution context</span> from the
<span>JavaScript execution context stack</span>.</p></li>
<li>
<p>Set <var>function</var>.[[ScriptOrModule]] to null.</p>
<div class="note">
<p>This is done because the default behavior, of associating the created function
with the nearest <span data-x="concept-script">script</span> on the stack, can lead to
path-dependent results. For example, an event handler which is first invoked by user
interaction would end up with null [[ScriptOrModule]] (since then this algorithm would be
first invoked when the <span>active script</span> is null), whereas one that is first invoked
by dispatching an event from script would have its [[ScriptOrModule]] set to that script.</p>
<p>Instead, we just always set [[ScriptOrModule]] to null. This is more intuitive anyway; the
idea that the first script which dispatches an event is somehow responsible for the event
handler code is dubious.</p>
<p>In practice, this only affects the resolution of relative URLs via <code>import()</code>,
which consult the <span data-x="concept-script-base-url">base URL</span> of the associated
script. Nulling out [[ScriptOrModule]] means that <span>HostLoadImportedModule</span> will
fall back to the <span>current settings object</span>'s <span>API base URL</span>.</p>
</div>
</li>
<li><p>Set <var>eventHandler</var>'s <span data-x="event handler value">value</span> to the
result of creating a Web IDL <code>EventHandler</code> callback function object whose object
reference is <var>function</var> and whose <span>callback context</span> is <var>settings
object</var>.</p></li>
</ol>
</li>
<li><p>Return <var>eventHandler</var>'s <span data-x="event handler value">value</span>.</p></li>
</ol>
</div>
<h5>Event handlers on elements, <code>Document</code> objects, and <code>Window</code> objects</h5>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span>
supported by all <span>HTML elements</span>, as both <span>event handler content attributes</span>
and <span>event handler IDL attributes</span>; and <span w-nodev>that must be</span>
supported by all <code>Document</code> and <code>Window</code> objects, as <span>event handler IDL
attributes</span>:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onabort">onabort</code></dfn> <td> <code data-x="">abort</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onauxclick">onauxclick</code></dfn> <td> <code data-x="event-auxclick">auxclick</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onbeforeinput">onbeforeinput</code></dfn> <td> <code data-x="event-beforeinput">beforeinput</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onbeforematch">onbeforematch</code></dfn> <td> <code data-x="event-beforematch">beforematch</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onbeforetoggle">onbeforetoggle</code></dfn> <td> <code data-x="event-beforetoggle">beforetoggle</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncancel">oncancel</code></dfn> <td> <code data-x="event-cancel">cancel</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncanplay">oncanplay</code></dfn> <td> <code data-x="event-media-canplay">canplay</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncanplaythrough">oncanplaythrough</code></dfn> <td> <code data-x="event-media-canplaythrough">canplaythrough</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onchange">onchange</code></dfn> <td> <code data-x="event-change">change</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onclick">onclick</code></dfn> <td> <code data-x="event-click">click</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onclose">onclose</code></dfn> <td> <code data-x="event-close">close</code> <!-- new for <dialog> -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncommand">oncommand</code></dfn> <td> <code data-x="event-command">command</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncontextlost">oncontextlost</code></dfn> <td> <code data-x="event-contextlost">contextlost</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncontextmenu">oncontextmenu</code></dfn> <td> <code data-x="event-contextmenu">contextmenu</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncontextrestored">oncontextrestored</code></dfn> <td> <code data-x="event-contextrestored">contextrestored</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncopy">oncopy</code></dfn> <td> <code data-x="event-copy">copy</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncuechange">oncuechange</code></dfn> <td> <code data-x="event-media-cuechange">cuechange</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncut">oncut</code></dfn> <td> <code data-x="event-cut">cut</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondblclick">ondblclick</code></dfn> <td> <code data-x="event-dblclick">dblclick</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondrag">ondrag</code></dfn> <td> <code data-x="event-dnd-drag">drag</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondragend">ondragend</code></dfn> <td> <code data-x="event-dnd-dragend">dragend</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondragenter">ondragenter</code></dfn> <td> <code data-x="event-dnd-dragenter">dragenter</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondragleave">ondragleave</code></dfn> <td> <code data-x="event-dnd-dragleave">dragleave</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondragover">ondragover</code></dfn> <td> <code data-x="event-dnd-dragover">dragover</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondragstart">ondragstart</code></dfn> <td> <code data-x="event-dnd-dragstart">dragstart</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondrop">ondrop</code></dfn> <td> <code data-x="event-dnd-drop">drop</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ondurationchange">ondurationchange</code></dfn> <td> <code data-x="event-media-durationchange">durationchange</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onemptied">onemptied</code></dfn> <td> <code data-x="event-media-emptied">emptied</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onended">onended</code></dfn> <td> <code data-x="event-media-ended">ended</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onformdata">onformdata</code></dfn> <td> <code data-x="event-formdata">formdata</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oninput">oninput</code></dfn> <td> <code data-x="event-input">input</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oninvalid">oninvalid</code></dfn> <td> <code data-x="event-invalid">invalid</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onkeydown">onkeydown</code></dfn> <td> <code data-x="event-keydown">keydown</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onkeypress">onkeypress</code></dfn> <td> <code data-x="event-keypress">keypress</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onkeyup">onkeyup</code></dfn> <td> <code data-x="event-keyup">keyup</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onloadeddata">onloadeddata</code></dfn> <td> <code data-x="event-media-loadeddata">loadeddata</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onloadedmetadata">onloadedmetadata</code></dfn> <td> <code data-x="event-media-loadedmetadata">loadedmetadata</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onloadstart">onloadstart</code></dfn> <td> <code data-x="event-media-loadstart">loadstart</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmousedown">onmousedown</code></dfn> <td> <code data-x="event-mousedown">mousedown</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmouseenter">onmouseenter</code></dfn> <td> <code data-x="event-mouseenter">mouseenter</code> <!-- compat -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmouseleave">onmouseleave</code></dfn> <td> <code data-x="event-mouseleave">mouseleave</code> <!-- compat -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmousemove">onmousemove</code></dfn> <td> <code data-x="event-mousemove">mousemove</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmouseout">onmouseout</code></dfn> <td> <code data-x="event-mouseout">mouseout</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmouseover">onmouseover</code></dfn> <td> <code data-x="event-mouseover">mouseover</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onmouseup">onmouseup</code></dfn> <td> <code data-x="event-mouseup">mouseup</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onpaste">onpaste</code></dfn> <td> <code data-x="event-paste">paste</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onpause">onpause</code></dfn> <td> <code data-x="event-media-pause">pause</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onplay">onplay</code></dfn> <td> <code data-x="event-media-play">play</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onplaying">onplaying</code></dfn> <td> <code data-x="event-media-playing">playing</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onprogress">onprogress</code></dfn> <td> <code data-x="event-media-progress">progress</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onratechange">onratechange</code></dfn> <td> <code data-x="event-media-ratechange">ratechange</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onreset">onreset</code></dfn> <td> <code data-x="event-reset">reset</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onscrollend">onscrollend</code></dfn> <td> <code data-x="event-scrollend">scrollend</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onsecuritypolicyviolation">onsecuritypolicyviolation</code></dfn> <td> <code data-x="event-securitypolicyviolation">securitypolicyviolation</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onseeked">onseeked</code></dfn> <td> <code data-x="event-media-seeked">seeked</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onseeking">onseeking</code></dfn> <td> <code data-x="event-media-seeking">seeking</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onselect">onselect</code></dfn> <td> <code data-x="event-select">select</code> <!-- widely used --> <!-- [CSSOM] -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onslotchange">onslotchange</code></dfn> <td> <code data-x="event-slotchange">slotchange</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onstalled">onstalled</code></dfn> <td> <code data-x="event-media-stalled">stalled</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onsubmit">onsubmit</code></dfn> <td> <code data-x="event-submit">submit</code> <!-- widely used -->
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onsuspend">onsuspend</code></dfn> <td> <code data-x="event-media-suspend">suspend</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ontimeupdate">ontimeupdate</code></dfn> <td> <code data-x="event-media-timeupdate">timeupdate</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-ontoggle">ontoggle</code></dfn> <td> <code data-x="event-toggle">toggle</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onvolumechange">onvolumechange</code></dfn> <td> <code data-x="event-media-volumechange">volumechange</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwaiting">onwaiting</code></dfn> <td> <code data-x="event-media-waiting">waiting</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwebkitanimationend">onwebkitanimationend</code></dfn> <td> <code data-x="">webkitAnimationEnd</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwebkitanimationiteration">onwebkitanimationiteration</code></dfn> <td> <code data-x="">webkitAnimationIteration</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwebkitanimationstart">onwebkitanimationstart</code></dfn> <td> <code data-x="">webkitAnimationStart</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwebkittransitionend">onwebkittransitionend</code></dfn> <td> <code data-x="">webkitTransitionEnd</code>
<tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onwheel">onwheel</code></dfn> <td> <code data-x="event-wheel">wheel</code> <!-- widely used -->
<!-- not supported, use dnd: -->
<!--<tr><td><dfn><code data-x="handler-onbeforecopy">onbeforecopy</code></dfn> <td> <code data-x="event-cp-beforecopy">beforecopy</code>--> <!-- widely used -->
<!-- not supported yet (v2?): -->
<!--<tr><td><dfn><code data-x="handler-onselectstart">onselectstart</code></dfn> <td> <code data-x="event-selectstart">selectstart</code>--> <!-- widely used -->
</table>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span>
supported by all <span>HTML elements</span> other than <code>body</code> and <code>frameset</code>
elements, as both <span>event handler content attributes</span> and <span>event handler IDL
attributes</span>; <span w-nodev>that must be</span> supported by all <code>Document</code>
objects, as <span>event handler IDL attributes</span>; and <span w-nodev>that must be</span>
supported by all <code>Window</code> objects, as <span>event handler IDL attributes</span> on the
<code>Window</code> objects themselves, and with corresponding <span>event handler content
attributes</span> and <span>event handler IDL attributes</span> exposed on all <code>body</code>
and <code>frameset</code> elements that are owned by that <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span>:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onblur">onblur</code></dfn> <td> <code data-x="event-blur">blur</code> <!-- widely used -->
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onerror">onerror</code></dfn> <td> <code data-x="event-error">error</code>
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onfocus">onfocus</code></dfn> <td> <code data-x="event-focus">focus</code> <!-- widely used -->
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onload">onload</code></dfn> <td> <code data-x="event-load">load</code>
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onresize">onresize</code></dfn> <td> <code data-x="event-resize">resize</code>
<tr><td><dfn attribute for="GlobalEventHandlers"><code data-x="handler-onscroll">onscroll</code></dfn> <td> <code data-x="event-scroll">scroll</code>
</table>
<p>We call the <span>set</span> of the <span data-x="event handler name">names</span> of the
<span>event handlers</span> listed in the first column of this table the
<dfn><code>Window</code>-reflecting body element event handler set</dfn>.</p>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span>
supported by <code>Window</code> objects, as <span>event handler IDL attributes</span> on the
<code>Window</code> objects themselves, and with corresponding <span>event handler content
attributes</span> and <span>event handler IDL attributes</span> exposed on all <code>body</code>
and <code>frameset</code> elements that are owned by that <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span>:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onafterprint">onafterprint</code></dfn> <td> <code data-x="event-afterprint">afterprint</code>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onbeforeprint">onbeforeprint</code></dfn> <td> <code data-x="event-beforeprint">beforeprint</code>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onbeforeunload">onbeforeunload</code></dfn> <td> <code data-x="event-beforeunload">beforeunload</code>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onhashchange">onhashchange</code></dfn> <td> <code data-x="event-hashchange">hashchange</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onlanguagechange">onlanguagechange</code></dfn> <td> <code data-x="event-languagechange">languagechange</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onmessage">onmessage</code></dfn> <td> <code data-x="event-message">message</code> <!-- new for postMessage -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onmessageerror">onmessageerror</code></dfn> <td> <code data-x="event-messageerror">messageerror</code> <!-- new for SAB -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onoffline">onoffline</code></dfn> <td> <code data-x="event-offline">offline</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-ononline">ononline</code></dfn> <td> <code data-x="event-online">online</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onpageswap">onpageswap</code></dfn> <td> <code data-x="event-pageswap">pageswap</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onpagehide">onpagehide</code></dfn> <td> <code data-x="event-pagehide">pagehide</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onpagereveal">onpagereveal</code></dfn> <td> <code data-x="event-pagereveal">pagereveal</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onpageshow">onpageshow</code></dfn> <td> <code data-x="event-pageshow">pageshow</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onpopstate">onpopstate</code></dfn> <td> <code data-x="event-popstate">popstate</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onrejectionhandled">onrejectionhandled</code></dfn> <td> <code data-x="event-rejectionhandled">rejectionhandled</code>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onstorage">onstorage</code></dfn> <td> <code data-x="event-storage">storage</code> <!-- new -->
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onunhandledrejection">onunhandledrejection</code></dfn> <td> <code data-x="event-unhandledrejection">unhandledrejection</code>
<tr><td><dfn attribute for="WindowEventHandlers"><code data-x="handler-window-onunload">onunload</code></dfn> <td> <code data-x="event-unload">unload</code> <!-- widely used -->
</table>
<p w-nodev>This list of <span>event handlers</span> is reified as <span>event handler IDL
attributes</span> through the <code>WindowEventHandlers</code> interface mixin.</p>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span>
supported on <code>Document</code> objects as <span>event handler IDL attributes</span>:</p>
<!-- This is only on Document and not on HTMLElement because otherwise HTMLScriptElement would
have it and that causes compatibility issues since IE fires readystatechange events on <script>,
not load events, and we can't fire both, and some sites try to decide which to look for based on
the presence of script.onreadystatechange on HTMLScriptElement.
https://www.w3.org/Bugs/Public/show_bug.cgi?id=13965
https://lists.w3.org/Archives/Public/public-whatwg-archive/2011Sep/0074.html
-->
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="Document"><code data-x="handler-onreadystatechange">onreadystatechange</code></dfn> <td> <code data-x="event-readystatechange">readystatechange</code>
<tr><td><dfn attribute for="Document"><code data-x="handler-onvisibilitychange">onvisibilitychange</code></dfn> <td> <code data-x="event-visibilitychange">visibilitychange</code>
</table>
<div w-nodev>
<h6>IDL definitions</h6>
<pre><code class="idl">interface mixin <dfn interface>GlobalEventHandlers</dfn> {
attribute <span>EventHandler</span> <span data-x="handler-onabort">onabort</span>;
attribute <span>EventHandler</span> <span data-x="handler-onauxclick">onauxclick</span>;
attribute <span>EventHandler</span> <span data-x="handler-onbeforeinput">onbeforeinput</span>;
attribute <span>EventHandler</span> <span data-x="handler-onbeforematch">onbeforematch</span>;
attribute <span>EventHandler</span> <span data-x="handler-onbeforetoggle">onbeforetoggle</span>;
attribute <span>EventHandler</span> <span data-x="handler-onblur">onblur</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncancel">oncancel</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncanplay">oncanplay</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncanplaythrough">oncanplaythrough</span>;
attribute <span>EventHandler</span> <span data-x="handler-onchange">onchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onclick">onclick</span>;
attribute <span>EventHandler</span> <span data-x="handler-onclose">onclose</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncommand">oncommand</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncontextlost">oncontextlost</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncontextmenu">oncontextmenu</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncontextrestored">oncontextrestored</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncopy">oncopy</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncuechange">oncuechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-oncut">oncut</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondblclick">ondblclick</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondrag">ondrag</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondragend">ondragend</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondragenter">ondragenter</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondragleave">ondragleave</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondragover">ondragover</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondragstart">ondragstart</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondrop">ondrop</span>;
attribute <span>EventHandler</span> <span data-x="handler-ondurationchange">ondurationchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onemptied">onemptied</span>;
attribute <span>EventHandler</span> <span data-x="handler-onended">onended</span>;
attribute <span>OnErrorEventHandler</span> <span data-x="handler-onerror">onerror</span>;
attribute <span>EventHandler</span> <span data-x="handler-onfocus">onfocus</span>;
attribute <span>EventHandler</span> <span data-x="handler-onformdata">onformdata</span>;
attribute <span>EventHandler</span> <span data-x="handler-oninput">oninput</span>;
attribute <span>EventHandler</span> <span data-x="handler-oninvalid">oninvalid</span>;
attribute <span>EventHandler</span> <span data-x="handler-onkeydown">onkeydown</span>;
attribute <span>EventHandler</span> <span data-x="handler-onkeypress">onkeypress</span>;
attribute <span>EventHandler</span> <span data-x="handler-onkeyup">onkeyup</span>;
attribute <span>EventHandler</span> <span data-x="handler-onload">onload</span>;
attribute <span>EventHandler</span> <span data-x="handler-onloadeddata">onloadeddata</span>;
attribute <span>EventHandler</span> <span data-x="handler-onloadedmetadata">onloadedmetadata</span>;
attribute <span>EventHandler</span> <span data-x="handler-onloadstart">onloadstart</span>;
attribute <span>EventHandler</span> <span data-x="handler-onmousedown">onmousedown</span>;
[<span>LegacyLenientThis</span>] attribute <span>EventHandler</span> <span data-x="handler-onmouseenter">onmouseenter</span>;
[<span>LegacyLenientThis</span>] attribute <span>EventHandler</span> <span data-x="handler-onmouseleave">onmouseleave</span>;
attribute <span>EventHandler</span> <span data-x="handler-onmousemove">onmousemove</span>;
attribute <span>EventHandler</span> <span data-x="handler-onmouseout">onmouseout</span>;
attribute <span>EventHandler</span> <span data-x="handler-onmouseover">onmouseover</span>;
attribute <span>EventHandler</span> <span data-x="handler-onmouseup">onmouseup</span>;
attribute <span>EventHandler</span> <span data-x="handler-onpaste">onpaste</span>;
attribute <span>EventHandler</span> <span data-x="handler-onpause">onpause</span>;
attribute <span>EventHandler</span> <span data-x="handler-onplay">onplay</span>;
attribute <span>EventHandler</span> <span data-x="handler-onplaying">onplaying</span>;
attribute <span>EventHandler</span> <span data-x="handler-onprogress">onprogress</span>;
attribute <span>EventHandler</span> <span data-x="handler-onratechange">onratechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onreset">onreset</span>;
attribute <span>EventHandler</span> <span data-x="handler-onresize">onresize</span>;
attribute <span>EventHandler</span> <span data-x="handler-onscroll">onscroll</span>;
attribute <span>EventHandler</span> <span data-x="handler-onscrollend">onscrollend</span>;
attribute <span>EventHandler</span> <span data-x="handler-onsecuritypolicyviolation">onsecuritypolicyviolation</span>;
attribute <span>EventHandler</span> <span data-x="handler-onseeked">onseeked</span>;
attribute <span>EventHandler</span> <span data-x="handler-onseeking">onseeking</span>;
attribute <span>EventHandler</span> <span data-x="handler-onselect">onselect</span>;
attribute <span>EventHandler</span> <span data-x="handler-onslotchange">onslotchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onstalled">onstalled</span>;
attribute <span>EventHandler</span> <span data-x="handler-onsubmit">onsubmit</span>;
attribute <span>EventHandler</span> <span data-x="handler-onsuspend">onsuspend</span>;
attribute <span>EventHandler</span> <span data-x="handler-ontimeupdate">ontimeupdate</span>;
attribute <span>EventHandler</span> <span data-x="handler-ontoggle">ontoggle</span>;
attribute <span>EventHandler</span> <span data-x="handler-onvolumechange">onvolumechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwaiting">onwaiting</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwebkitanimationend">onwebkitanimationend</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwebkitanimationiteration">onwebkitanimationiteration</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwebkitanimationstart">onwebkitanimationstart</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwebkittransitionend">onwebkittransitionend</span>;
attribute <span>EventHandler</span> <span data-x="handler-onwheel">onwheel</span>;
};
interface mixin <dfn interface>WindowEventHandlers</dfn> {
attribute <span>EventHandler</span> <span data-x="handler-window-onafterprint">onafterprint</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onbeforeprint">onbeforeprint</span>;
attribute <span>OnBeforeUnloadEventHandler</span> <span data-x="handler-window-onbeforeunload">onbeforeunload</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onhashchange">onhashchange</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onlanguagechange">onlanguagechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onmessageerror">onmessageerror</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onoffline">onoffline</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-ononline">ononline</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onpagehide">onpagehide</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onpagereveal">onpagereveal</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onpageshow">onpageshow</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onpageswap">onpageswap</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onpopstate">onpopstate</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onrejectionhandled">onrejectionhandled</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onstorage">onstorage</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onunhandledrejection">onunhandledrejection</span>;
attribute <span>EventHandler</span> <span data-x="handler-window-onunload">onunload</span>;
};</code></pre>
<h5>Event firing</h5>
<p>Certain operations and methods are defined as firing events on elements. For example, the <code
data-x="dom-click">click()</code> method on the <code>HTMLElement</code> interface is defined as
firing a <code data-x="event-click">click</code> event on the element. <ref>UIEVENTS</ref></p>
<p><dfn data-x="fire a synthetic pointer event">Firing a synthetic pointer event named
<var>e</var></dfn> at <var>target</var>, with an optional <var>not trusted flag</var>, means
running these steps:</p>
<ol>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> using
<code>PointerEvent</code>.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-Event-type">type</code> attribute to
<var>e</var>.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-Event-bubbles">bubbles</code> and <code
data-x="dom-Event-cancelable">cancelable</code> attributes to true.</p></li>
<li><p>Set <var>event</var>'s <span>composed flag</span>.</p></li>
<li><p>If the <var>not trusted flag</var> is set, initialize <var>event</var>'s <code
data-x="dom-Event-isTrusted">isTrusted</code> attribute to false.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="">ctrlKey</code>, <code
data-x="">shiftKey</code>, <code data-x="">altKey</code>, and <code data-x="">metaKey</code>
attributes according to the current state of the key input device, if any (false for any keys
that are not available).</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-UIEvent-view">view</code> attribute to
<var>target</var>'s <span>node document</span>'s <code>Window</code> object, if any, and null
otherwise.</p></li>
<li><p><var>event</var>'s <code data-x="">getModifierState()</code> method is to return values
appropriately describing the current state of the key input device.</p></li>
<li><p>Return the result of <span data-x="concept-event-dispatch">dispatching</span>
<var>event</var> at <var>target</var>.</p></li>
</ol>
<p><dfn data-x="fire a click event">Firing a <code data-x="event-click">click</code> event</dfn>
at <var>target</var> means <span data-x="fire a synthetic pointer event">firing a synthetic
pointer event named <code data-x="event-click">click</code></span> at <var>target</var>.</p>
</div>
<h3 id="windoworworkerglobalscope-mixin">The <code>WindowOrWorkerGlobalScope</code> mixin</h3>
<p>The <code>WindowOrWorkerGlobalScope</code> mixin is for use of APIs that are to be exposed on
<code>Window</code> and <code>WorkerGlobalScope</code> objects.</p>
<p class="note">Other standards are encouraged to further extend it using <code data-x="">partial
interface mixin <span>WindowOrWorkerGlobalScope</span> { … };</code> along with an
appropriate reference.</p>
<pre><code class="idl">typedef (DOMString or <span data-x="idl-Function">Function</span> or <span data-x="tt-trustedscript">TrustedScript</span>) <dfn typedef>TimerHandler</dfn>;
interface mixin <dfn interface>WindowOrWorkerGlobalScope</dfn> {
[Replaceable] readonly attribute USVString <span data-x="dom-origin">origin</span>;
readonly attribute boolean <span data-x="dom-isSecureContext">isSecureContext</span>;
readonly attribute boolean <span data-x="dom-crossOriginIsolated">crossOriginIsolated</span>;
undefined <span data-x="dom-reportError">reportError</span>(any e);
// base64 utility methods
DOMString <span data-x="dom-btoa">btoa</span>(DOMString data);
ByteString <span data-x="dom-atob">atob</span>(DOMString data);
// timers
long <span data-x="dom-setTimeout">setTimeout</span>(<span>TimerHandler</span> handler, optional long timeout = 0, any... arguments);
undefined <span data-x="dom-clearTimeout">clearTimeout</span>(optional long id = 0);
long <span data-x="dom-setInterval">setInterval</span>(<span>TimerHandler</span> handler, optional long timeout = 0, any... arguments);
undefined <span data-x="dom-clearInterval">clearInterval</span>(optional long id = 0);
// microtask queuing
undefined <span data-x="dom-queueMicrotask">queueMicrotask</span>(<span data-x="idl-VoidFunction">VoidFunction</span> callback);
// ImageBitmap
<span data-x="idl-Promise">Promise</span><<span>ImageBitmap</span>> <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, optional <span>ImageBitmapOptions</span> options = {});
<span data-x="idl-Promise">Promise</span><<span>ImageBitmap</span>> <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, long sx, long sy, long sw, long sh, optional <span>ImageBitmapOptions</span> options = {});
// structured cloning
any <span data-x="dom-structuredClone">structuredClone</span>(any value, optional <span>StructuredSerializeOptions</span> options = {});
};
<span>Window</span> includes <span>WindowOrWorkerGlobalScope</span>;
<span>WorkerGlobalScope</span> includes <span>WindowOrWorkerGlobalScope</span>;</code></pre>
<dl class="domintro">
<dt><code data-x="">self.<span subdfn data-x="dom-isSecureContext">isSecureContext</span></code></dt>
<dd><p>Returns whether or not this global object represents a <span>secure context</span>.
<ref>SECURE-CONTEXTS</ref></p></dd>
<dt><code data-x="">self.<span subdfn data-x="dom-origin">origin</span></code></dt>
<dd><p>Returns the global object's <span>origin</span>, serialized as string.</p></dd>
<dt><code data-x="">self.<span subdfn data-x="dom-crossOriginIsolated">crossOriginIsolated</span></code></dt>
<dd><p>Returns whether scripts running in this global are allowed to use APIs that require
cross-origin isolation. This depends on the `<code>Cross-Origin-Opener-Policy</code>` and
`<code>Cross-Origin-Embedder-Policy</code>` HTTP response headers and the "<code
data-x="cross-origin-isolated-feature">cross-origin-isolated</code>" feature.</p></dd>
</dl>
<div class="example">
<p>Developers are strongly encouraged to use <code data-x="">self.origin</code> over <code
data-x="">location.origin</code>. The former returns the <span>origin</span> of the environment,
the latter of the URL of the environment. Imagine the following script executing in a document on
<code data-x="">https://stargate.example/</code>:</p>
<pre><code class="js">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)</code></pre>
<p><code data-x="">self.origin</code> is a more reliable security indicator.</p>
</div>
<div w-nodev>
<p>The <dfn attribute for="WindowOrWorkerGlobalScope"
data-x="dom-isSecureContext"><code>isSecureContext</code></dfn> getter steps are to return true if
<span>this</span>'s <span>relevant settings object</span> is a <span>secure context</span>, or
false otherwise.</p>
<p>The <dfn attribute for="WindowOrWorkerGlobalScope"
data-x="dom-origin"><code>origin</code></dfn> getter steps are to return <span>this</span>'s
<span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span>, <span data-x="serialization of an
origin">serialized</span>.</p>
<p>The <dfn attribute for="WindowOrWorkerGlobalScope"
data-x="dom-crossOriginIsolated"><code>crossOriginIsolated</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p>
</div>
<h3 id="atob">Base64 utility methods</h3>
<p>The <code data-x="dom-atob">atob()</code> and <code data-x="dom-btoa">btoa()</code> methods
allow developers to transform content to and from the base64 encoding.</p>
<p class="note">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.</p>
<dl class="domintro">
<dt><code data-x=""><var>result</var> = self.<span subdfn data-x="dom-btoa">btoa</span>(<var>data</var>)</code></dt>
<dd>
<p>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.</p>
<p>Throws an <span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code>
exception if the input string contains any out-of-range characters.</p>
</dd>
<dt><code data-x=""><var>result</var> = self.<span subdfn data-x="dom-atob">atob</span>(<var>data</var>)</code></dt>
<dd>
<p>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.</p>
<p>Throws an <span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code> if the
input string is not valid base64 data.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-btoa"><code
id="dom-windowbase64-btoa">btoa(<var>data</var>)</code></dfn> method must throw an
<span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code> if <var>data</var>
contains any character whose code point is greater than U+00FF. Otherwise, the user agent must
convert <var>data</var> to a byte sequence whose <var>n</var>th byte is the eight-bit
representation of the <var>n</var>th code point of <var>data</var>, and then must apply
<span>forgiving-base64 encode</span> to that byte sequence and return the result.</p>
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-atob"><code
id="dom-windowbase64-atob">atob(<var>data</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>decodedData</var> be the result of running <span>forgiving-base64 decode</span>
on <var>data</var>.</p></li>
<li><p>If <var>decodedData</var> is failure, then throw an
<span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Return <var>decodedData</var>.</p></li>
</ol>
</div>
<h3 split-filename="dynamic-markup-insertion"><dfn>Dynamic markup insertion</dfn></h3>
<p class="note">APIs for dynamically inserting markup into the document interact with the parser,
and thus their behavior varies depending on whether they are used with <span>HTML
documents</span> (and the <span>HTML parser</span>) or <span>XML documents</span> (and the
<span>XML parser</span>).</p>
<div w-nodev>
<p><code>Document</code> objects have a <dfn>throw-on-dynamic-markup-insertion counter</dfn>,
which is used in conjunction with the <span>create an element for the token</span> algorithm to
prevent <span data-x="custom element constructor">custom element constructors</span> from being
able to use <code data-x="dom-document-open">document.open()</code>, <code
data-x="dom-document-close">document.close()</code>, and <code
data-x="dom-document-write">document.write()</code> when they are invoked by the parser.
Initially, the counter must be set to zero.</p>
</div>
<h4>Opening the input stream</h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var> = <var>document</var>.<span subdfn data-x="dom-document-open">open</span>()</code></dt>
<dd>
<p>Causes the <code>Document</code> to be replaced in-place, as if it was a new
<code>Document</code> object, but reusing the previous object, which is then returned.</p>
<p>The resulting <code>Document</code> has an HTML parser associated with it, which can be given
data to parse using <code data-x="dom-document-write">document.write()</code>.</p>
<p>The method has no effect if the <code>Document</code> is still being parsed.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
<code>Document</code> is an <span data-x="XML documents">XML document</span>.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
parser is currently executing a <span>custom element constructor</span>.</p>
</dd>
<dt><code data-x=""><var>window</var> = <var>document</var>.<span data-x="dom-document-open-window">open</span>(<var>url</var>, <var>name</var>, <var>features</var>)</code></dt>
<dd><p>Works like the <code data-x="dom-open">window.open()</code> method.</p></dd>
</dl>
<div w-nodev>
<p><code>Document</code> objects have an <dfn>active parser was aborted</dfn> boolean, which is
used to prevent scripts from invoking the <code data-x="dom-document-open">document.open()</code>
and <code data-x="dom-document-write">document.write()</code> methods (directly or indirectly)
after the document's <span>active parser</span> has been aborted. It is initially false.</p>
<p>The <dfn>document open steps</dfn>, given a <var>document</var>, are as follows:</p>
<ol>
<li><p>If <var>document</var> is an <span data-x="XML documents">XML document</span>, then throw
an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> exception.</p></li>
<li><p>If <var>document</var>'s <span>throw-on-dynamic-markup-insertion counter</span> is greater
than 0, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>entryDocument</var> be the <span>entry global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var>'s <span data-x="concept-document-origin">origin</span> is not
<span>same origin</span> to <var>entryDocument</var>'s <span
data-x="concept-document-origin">origin</span>, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>If <var>document</var> has an <span>active parser</span> whose <span>script nesting
level</span> is greater than 0, then return <var>document</var>.</p>
<p class="note">This basically causes <code data-x="dom-document-open">document.open()</code> to
be ignored when it's called in an inline script found during parsing, while still letting it
have an effect when called from a non-parser task such as a timer callback or event handler.</p>
</li>
<li>
<p>Similarly, if <var>document</var>'s <span>unload counter</span> is greater than 0, then
return <var>document</var>.</p>
<p class="note">This basically causes <code data-x="dom-document-open">document.open()</code> to
be ignored when it's called from a <code data-x="event-beforeunload">beforeunload</code>, <code
data-x="event-pagehide">pagehide</code>, or <code data-x="event-unload">unload</code> event
handler while the <code>Document</code> is being unloaded.</p>
</li>
<li>
<p>If <var>document</var>'s <span>active parser was aborted</span> is true, then return
<var>document</var>.</p>
<p class="note">This notably causes <code data-x="dom-document-open">document.open()</code> to
be ignored if it is called after a <span data-x="navigate">navigation</span> has started, but
only during the initial parse. See <a href="https://github.com/whatwg/html/issues/4723">issue
#4723</a> for more background.</p>
</li>
<li><p>If <var>document</var>'s <span>node navigable</span> is non-null and
<var>document</var>'s <span>node navigable</span>'s <span>ongoing navigation</span> is a
<span>navigation ID</span>, then <span data-x="nav-stop">stop loading</span>
<var>document</var>'s <span>node navigable</span>.</p></li>
<li><p>For each <span>shadow-including inclusive descendant</span> <var>node</var> of
<var>document</var>, <span>erase all event listeners and handlers</span> given
<var>node</var>.</p></li>
<li><p>If <var>document</var> is the <span data-x="concept-document-window">associated
<code>Document</code></span> of <var>document</var>'s <span>relevant global object</span>, then
<span>erase all event listeners and handlers</span> given <var>document</var>'s <span>relevant
global object</span>.</p></li>
<li><p><span data-x="concept-node-replace-all">Replace all</span> with null within
<var>document</var>.</p></li>
<li>
<p>If <var>document</var> is <span>fully active</span>, then:</p>
<ol>
<li><p>Let <var>newURL</var> be a copy of <var>entryDocument</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>If <var>entryDocument</var> is not <var>document</var>, then set <var>newURL</var>'s
<span data-x="concept-url-fragment">fragment</span> to null.</p></li>
<li><p>Run the <span>URL and history update steps</span> with <var>document</var> and
<var>newURL</var>.</p></li>
</ol>
</li>
<!-- <span>the document's referrer</span> stays the same -->
<li><p>Set <var>document</var>'s <span>is initial <code>about:blank</code></span> to
false.</p></li>
<li><p>If <var>document</var>'s <span>iframe load in progress</span> flag is set, then set
<var>document</var>'s <span>mute iframe load</span> flag.</p></li>
<li><p>Set <var>document</var> to <span>no-quirks mode</span>.</p></li>
<li><p>Create a new <span>HTML parser</span> and associate it with <var>document</var>. This is a
<dfn>script-created parser</dfn> (meaning that it can be closed by the <code
data-x="dom-document-open">document.open()</code> and <code
data-x="dom-document-close">document.close()</code> methods, and that the tokenizer will wait for
an explicit call to <code data-x="dom-document-close">document.close()</code> before emitting an
end-of-file token). The encoding <span data-x="concept-encoding-confidence">confidence</span> is
<i>irrelevant</i>.</p></li>
<li><p>Set the <span>insertion point</span> to point at just before the end of the <span>input
stream</span> (which at this point will be empty).</p></li>
<li>
<p><span>Update the current document readiness</span> of <var>document</var> to "<code
data-x="">loading</code>".</p>
<p class="note">This causes a <code data-x="event-readystatechange">readystatechange</code>
event to fire, but the event is actually unobservable to author code, because of the previous
step which <span data-x="erase all event listeners and handlers">erased all event listeners and
handlers</span> that could observe it.</p>
</li>
<li><p>Return <var>document</var>.</p></li>
</ol>
<p class="note">The <span>document open steps</span> do not affect whether a <code>Document</code>
is <span>ready for post-load tasks</span> or <span>completely loaded</span>.</p>
<p>The <dfn method for="Document" data-x="dom-document-open"><code>open(<var>unused1</var>,
<var>unused2</var>)</code></dfn> method must return the result of running the <span>document open
steps</span> with <span>this</span>.</p>
<p class="note" id="dom-document-open-unused-arguments">The <var>unused1</var> and
<var>unused2</var> arguments are ignored, but kept in the IDL to allow code that calls the
function with one or two arguments to continue working. They are necessary due to Web IDL
<span>overload resolution algorithm</span> rules, which would throw a <code>TypeError</code>
exception for such calls had the arguments not been there. <a
href="https://github.com/whatwg/webidl/issues/581">whatwg/webidl issue #581</a> investigates
changing the algorithm to allow for their removal. <ref>WEBIDL</ref></p>
<p>The <dfn method for="Document" data-x="dom-document-open-window"><code>open(<var>url</var>,
<var>name</var>, <var>features</var>)</code></dfn> method must run these steps:</p>
<ol>
<li><p>If <span>this</span> is not <span>fully active</span>, then throw an
<span>"<code>InvalidAccessError</code>"</span> <code>DOMException</code> exception.</p></li>
<li><p>Return the result of running the <span>window open steps</span> with <var>url</var>,
<var>name</var>, and <var>features</var>.</p></li>
</ol>
</div>
<h4>Closing the input stream</h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-close">close</span>()</code></dt>
<dd>
<p>Closes the input stream that was opened by the <code
data-x="dom-document-open">document.open()</code> method.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
<code>Document</code> is an <span data-x="XML documents">XML document</span>.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
parser is currently executing a <span>custom element constructor</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="Document"><code data-x="dom-document-close">close()</code></dfn> method must run the following
steps:</p>
<ol>
<li><p>If <span>this</span> is an <span data-x="XML documents">XML document</span>, then throw
an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <span>this</span>'s <span>throw-on-dynamic-markup-insertion counter</span> is greater
than zero, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If there is no <span>script-created parser</span> associated with <span>this</span>, then
return.</p></li>
<li><p>Insert an <span>explicit "EOF" character</span> at the end of the parser's <span>input
stream</span>.</p></li>
<li><p>If <span>this</span>'s <span>pending parsing-blocking script</span> is not null, then
return.</p></li>
<li><p>Run the tokenizer, processing resulting tokens as they are emitted, and stopping when the
tokenizer reaches the <span>explicit "EOF" character</span> or <span data-x="spin the event
loop">spins the event loop</span>.</p></li>
</ol>
</div>
<h4><code data-x="dom-document-write">document.write()</code></h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-write">write</span>(...<var>text</var>)</code></dt>
<dd>
<p>In general, adds the given string(s) to the <code>Document</code>'s input stream.</p>
<p class="warning">This method has very idiosyncratic behavior. In some cases, this method can
affect the state of the <span>HTML parser</span> while the parser is running, resulting in a DOM
that does not correspond to the source of the document (e.g. if the string written is the string
"<code data-x=""><plaintext></code>" or "<code data-x=""><!--</code>"). In other cases,
the call can clear the current page first, as if <code data-x="dom-document-open">document.open()</code> had been called. In yet more cases, the method
is simply ignored, or throws an exception. Users agents are <a href="#document-written-scripts-intervention">explicitly allowed to avoid executing
<code>script</code> elements inserted via this method</a>. And to make matters even worse, the
exact behavior of this method can in some cases be dependent on network latency<!--
Namely, in the following case:
<script>
document.write('<link rel=stylesheet href=foo.css><script></script>x');
// at this point, whether the DOM contains an "x" or not depends on how quickly the foo.css file could be processed
</script>
-->, which can lead to failures that are very hard to debug. <strong>For all these reasons, use
of this method is strongly discouraged.</strong></p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> when
invoked on <span>XML documents</span>.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
parser is currently executing a <span>custom element constructor</span>.</p>
</dd>
</dl>
<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<div w-nodev>
<p><code>Document</code> objects have an <dfn>ignore-destructive-writes counter</dfn>, which is
used in conjunction with the processing of <code>script</code> elements to prevent external
scripts from being able to use <code data-x="dom-document-write">document.write()</code> to blow
away the document by implicitly calling <code data-x="dom-document-open">document.open()</code>.
Initially, the counter must be set to zero.</p>
<p>The <dfn>document write steps</dfn>, given a <code>Document</code> object <var>document</var>,
a list <var>text</var>, a boolean <var>lineFeed</var>, and a string <var>sink</var>, are as
follows:</p>
<ol>
<li><p>Let <var>string</var> be the empty string.</p></li>
<li><p>Let <var>isTrusted</var> be false if <var>text</var> <span data-x="list
contains">contains</span> a string; otherwise true.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>value</var> of <var>text</var>:</p>
<ol>
<li><p>If <var>value</var> is a <code data-x="tt-trustedhtml">TrustedHTML</code> object, then
append <var>value</var>'s associated <span data-x="tt-trustedhtml-data">data</span> to
<var>string</var>.</p></li>
<li><p>Otherwise, append <var>value</var> to <var>string</var>.</p></li>
</ol>
</li>
<li><p>If <var>isTrusted</var> is false, set <var>string</var> to the result of invoking the
<span data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with
<code data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>string</var>, <var>sink</var>, and "<code data-x="">script</code>".</p></li>
<li><p>If <var>lineFeed</var> is true, append U+000A LINE FEED to <var>string</var>.</p></li>
<li><p>If <var>document</var> is an <span data-x="XML documents">XML document</span>, then throw
an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.</p></li>
<!-- Where would document.write() insert?
Consider: data:text/xml,<script xmlns="http://www.w3.org/1999/xhtml"><![CDATA[ document.write('<foo>Test</foo>'); ]]></script>
-->
<li><p>If <var>document</var>'s <span>throw-on-dynamic-markup-insertion counter</span> is greater
than 0, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <var>document</var>'s <span>active parser was aborted</span> is true, then
return.</p></li>
<li>
<p>If the <span>insertion point</span> is undefined, then:
<ol>
<li><p>If <var>document</var>'s <span>unload counter</span> is greater than 0 or
<var>document</var>'s <span>ignore-destructive-writes counter</span> is greater than 0, then
return.</p></li>
<li><p>Run the <span>document open steps</span> with <var>document</var>.</p></li>
</ol>
</li>
<li><p>Insert <var>string</var> into the <span>input stream</span> just before the <span>insertion
point</span>.</p></li>
<li>
<p>If <var>document</var>'s <span>pending parsing-blocking script</span> is null, then have the
<span>HTML parser</span> process <var>string</var>, one code point at a time, processing
resulting tokens as they are emitted, and stopping when the tokenizer reaches the insertion
point or when the processing of the tokenizer is aborted by the tree construction stage (this
can happen if a <code>script</code> end tag token is emitted by the tokenizer).
<p class="note">If the <code data-x="dom-document-write">document.write()</code> method was
called from script executing inline (i.e. executing because the parser parsed a set of
<code>script</code> tags), then this is a <a href="#nestedParsing">reentrant invocation of the
parser</a>. If the <span>parser pause flag</span> is set, the tokenizer will abort immediately
and no HTML will be parsed, per the tokenizer's <a href="#check-parser-pause-flag">parser pause
flag check</a>.</p>
</li>
</ol>
<p>The <dfn method for="Document"><code
data-x="dom-document-write">document.write(...<var>text</var>)</code></dfn> method steps are
to run the <span>document write steps</span> with <span>this</span>, <var>text</var>, false, and
"<code data-x="">Document write</code>".</p>
</div>
<h4><code data-x="dom-document-writeln">document.writeln()</code></h4>
<dl class="domintro">
<dt><code data-x=""><var>document</var>.<span subdfn data-x="dom-document-writeln">writeln</span>(...<var>text</var>)</code></dt>
<dd>
<p>Adds the given string(s) to the <code>Document</code>'s input stream, followed by a newline
character. If necessary, calls the <code data-x="dom-document-open">open()</code> method
implicitly first.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> when
invoked on <span>XML documents</span>.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
parser is currently executing a <span>custom element constructor</span>.</p>
</dd>
</dl>
<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<div w-nodev>
<p>The <dfn method for="Document"><code
data-x="dom-document-writeln">document.writeln(...<var>text</var>)</code></dfn> method steps are
to run the <span>document write steps</span> with <span>this</span>, <var>text</var>, true, and
"<code data-x="">Document writeln</code>".</p>
</div>
<h3 id="dom-parsing-and-serialization">DOM parsing and serialization APIs</h3>
<pre><code class="idl">partial interface <span id="Element-partial">Element</span> {
[<span>CEReactions</span>] undefined <span data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
DOMString <span data-x="dom-Element-getHTML">getHTML</span>(optional <span>GetHTMLOptions</span> options = {});
[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or [<span>LegacyNullToEmptyString</span>] DOMString) <span data-x="dom-Element-innerHTML">innerHTML</span>;
[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or [<span>LegacyNullToEmptyString</span>] DOMString) <span data-x="dom-Element-outerHTML">outerHTML</span>;
[<span>CEReactions</span>] undefined <span data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML</span>(DOMString position, (<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) string);
};
partial interface <span id="ShadowRoot-partial">ShadowRoot</span> {
[<span>CEReactions</span>] undefined <span data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
DOMString <span data-x="dom-ShadowRoot-getHTML">getHTML</span>(optional <span>GetHTMLOptions</span> options = {});
[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or [<span>LegacyNullToEmptyString</span>] DOMString) <span data-x="dom-ShadowRoot-innerHTML">innerHTML</span>;
};
dictionary <dfn dictionary>GetHTMLOptions</dfn> {
boolean <dfn dict-member for="GetHTMLOptions" data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</dfn> = false;
sequence<ShadowRoot> <dfn dict-member for="GetHTMLOptions" data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</dfn> = [];
};</code></pre>
<h4>The <code>DOMParser</code> interface</h4>
<p>The <code>DOMParser</code> interface allows authors to create new <code>Document</code> objects
by parsing strings, as either HTML or XML.</p>
<dl class="domintro">
<dt><code data-x=""><var>parser</var> = new <span subdfn data-x="dom-DOMParser-constructor">DOMParser</span>()</code></dt>
<dd><p>Constructs a new <code>DOMParser</code> object.</p></dd>
<dt><code data-x=""><var>document</var> = <var>parser</var>.<span subdfn data-x="dom-DOMParser-parseFromString">parseFromString</span>(<var>string</var>, <var>type</var>)</code></dt>
<dd>
<p>Parses <var>string</var> using either the HTML or XML parser, according to <var>type</var>,
and returns the resulting <code>Document</code>. <var>type</var> can be "<code>text/html</code>"
(which will invoke the HTML parser), or any of "<code>text/xml</code>",
"<code>application/xml</code>", "<code>application/xhtml+xml</code>", or
"<code>image/svg+xml</code>" (which will invoke the XML parser).</p>
<p>For the XML parser, if <var>string</var> cannot be parsed, then the returned
<code>Document</code> will contain elements describing the resulting error.</p>
<p>Note that <code>script</code> elements are not evaluated during parsing, and the resulting
document's <span data-x="document's character encoding">encoding</span> will always be
<span>UTF-8</span>. The document's <span data-x="concept-document-url">URL</span> will be
inherited from <var>parser</var>'s <span>relevant global object</span>.</p>
<p>Values other than the above for <var>type</var> will cause a <code>TypeError</code> exception
to be thrown.</p>
</dd>
</dl>
<p class="note">The design of <code>DOMParser</code>, as a class that needs to be constructed and
then have its <code data-x="dom-DOMParser-parseFromString">parseFromString()</code> method
called, is an unfortunate historical artifact. If we were designing this functionality today it
would be a standalone function. For parsing HTML, the modern alternative is <code
data-x="dom-parseHTMLUnsafe">Document.parseHTMLUnsafe()</code>.</p>
<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>DOMParser</dfn> {
<span data-x="dom-DOMParser-constructor">constructor</span>();
[NewObject] <code>Document</code> <span data-x="dom-DOMParser-parseFromString">parseFromString</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) string, <span>DOMParserSupportedType</span> type);
};
enum <dfn enum>DOMParserSupportedType</dfn> {
"<span data-x="dom-DOMParserSupportedType-texthtml">text/html</span>",
"<span data-x="dom-DOMParserSupportedType-otherwise">text/xml</span>",
"<span data-x="dom-DOMParserSupportedType-otherwise">application/xml</span>",
"<span data-x="dom-DOMParserSupportedType-otherwise">application/xhtml+xml</span>",
"<span data-x="dom-DOMParserSupportedType-otherwise">image/svg+xml</span>"
};</code></pre>
<div w-nodev>
<p>The <dfn data-x="dom-DOMParser-constructor"><code>new DOMParser()</code></dfn> constructor
steps are to do nothing.</p>
<p>The <dfn method for="DOMParser"
data-x="dom-DOMParser-parseFromString"><code>parseFromString(<var>string</var>,
<var>type</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>string</var>, "<code data-x="">DOMParser parseFromString</code>", and "<code
data-x="">script</code>".</p></li>
<li>
<p>Let <var>document</var> be a new <code>Document</code>, whose <span
data-x="concept-document-content-type">content type</span> is <var>type</var> and <span
data-x="concept-document-URL">URL</span> is <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>'s <span
data-x="concept-document-URL">URL</span>.</p>
<!-- When https://github.com/whatwg/html/issues/4792 gets fixed we need to investigate which of
HTMLDocument vs. XMLDocument gets returned, and when, with tests. In particular we'll want
to check the application/xhtml+xml case as even for navigation it seems like browsers
diverge there: https://github.com/whatwg/html/issues/5157#issuecomment-573052638. -->
<p class="note">The document's <span data-x="document's character encoding">encoding</span> will
be left as its default, of <span>UTF-8</span>. In particular, any XML declarations or
<code>meta</code> elements found while parsing <var>compliantString</var> will have no effect.</p>
</li>
<li>
<p>Switch on <var>type</var>:</p>
<dl class="switch">
<dt>"<dfn enum-value for="DOMParserSupportedType"
data-x="dom-DOMParserSupportedType-texthtml"><code>text/html</code></dfn>"</dt>
<dd>
<ol>
<li><p><span>Parse HTML from a string</span> given <var>document</var> and
<var>compliantString</var>.</p></li>
</ol>
<p class="note">Since <var>document</var> does not have a <span
data-x="concept-document-bc">browsing context</span>, <span
data-x="concept-n-script">scripting is disabled</span>.</p>
</dd>
<dt><dfn data-x="dom-DOMParserSupportedType-otherwise">Otherwise</dfn></dt>
<dd>
<ol>
<li><p>Create an <span>XML parser</span> <var>parser</var>, associated with
<var>document</var>, and with <span>XML scripting support disabled</span>.</p></li>
<li><p>Parse <var>compliantString</var> using <var>parser</var>.</p>
<li>
<p>If the previous step resulted in an XML well-formedness or XML namespace well-formedness
error, then:</p>
<ol>
<li><p><span>Assert</span>: <var>document</var> has no child nodes.</p></li>
<li><p>Let <var>root</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">parsererror</code>", and "<code
data-x="">http://www.mozilla.org/newlayout/xml/parsererror.xml</code>".</p></li>
<li><p>Optionally, add attributes or children to <var>root</var> to describe the nature of
the parsing error.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>root</var> to
<var>document</var>.</p></li>
</ol>
</li>
</ol>
</dd>
</dl>
</li>
<li><p>Return <var>document</var>.</p>
</ol>
<p>To <dfn>parse HTML from a string</dfn>, given a <code>Document</code> <var>document</var> and a
<span>string</span> <var>html</var>:</p>
<ol>
<li><p>Set <var>document</var>'s <span data-x="concept-document-type">type</span> to "<code
data-x="">html</code>".</p></li>
<li><p>Create an <span>HTML parser</span> <var>parser</var>, associated with
<var>document</var>.</p></li>
<li><p>Place <var>html</var> into the <span>input stream</span> for <var>parser</var>. The
encoding <span data-x="concept-encoding-confidence">confidence</span> is
<i>irrelevant</i>.</p></li>
<li>
<p>Start <var>parser</var> and let it run until it has consumed all the characters just
inserted into the input stream.</p>
<p class="note">This might mutate the document's <span
data-x="concept-document-mode">mode</span>.</p>
</li>
</ol>
</div>
<h4>Unsafe HTML parsing methods</h4>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>)</code></dt>
<dd>
<p>Parses <var>html</var> using the HTML parser, and replaces the children of <var>element</var>
with the result. <var>element</var> provides context for the HTML parser.</p>
</dd>
<dt><code data-x=""><var>shadowRoot</var>.<span subdfn
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>)</code></dt>
<dd>
<p>Parses <var>html</var> using the HTML parser, and replaces the children of
<var>shadowRoot</var> with the result. <var>shadowRoot</var>'s <span
data-x="concept-DocumentFragment-host">host</span> provides context for the HTML parser.</p>
</dd>
<dt><code data-x=""><var>doc</var> = Document.<span
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>(<var>html</var>)</code></dt>
<dd>
<p>Parses <var>html</var> using the HTML parser, and returns the resulting
<code>Document</code>.</p>
<p>Note that <code>script</code> elements are not evaluated during parsing, and the resulting
document's <span data-x="document's character encoding">encoding</span> will always be
<span>UTF-8</span>. The document's <span data-x="concept-document-url">URL</span> will be
<code>about:blank</code>.</p>
</dd>
</dl>
<p class="warning">These methods perform no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<div w-nodev>
<p><code>Element</code>'s <dfn method for="Element"><code
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>Let <var>compliantHTML</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>html</var>, "<code data-x="">Element setHTMLUnsafe</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>target</var> be <span>this</span>'s <span>template contents</span> if
<span>this</span> is a <code>template</code> element; otherwise <span>this</span>.</p></li>
<li><p><span>Unsafely set HTML</span> given <var>target</var>, <span>this</span>, and
<var>compliantHTML</var>.</p></li>
</ol>
<p><code>ShadowRoot</code>'s <dfn method for="ShadowRoot"><code
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>Let <var>compliantHTML</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>html</var>, "<code data-x="">ShadowRoot setHTMLUnsafe</code>", and "<code
data-x="">script</code>".</p></li>
<li><p><span>Unsafely set HTML</span> given <span>this</span>, <span>this</span>'s <span
data-x="concept-DocumentFragment-host">shadow host</span>, and <var>compliantHTML</var>.</p></li>
</ol>
<p>To <dfn>unsafely set HTML</dfn>, given an <code>Element</code> or <code>DocumentFragment</code>
<var>target</var>, an <code>Element</code> <var>contextElement</var>, and a <span>string</span>
<var>html</var>:</p>
<ol>
<li><p>Let <var>newChildren</var> be the result of the <span>HTML fragment parsing
algorithm</span> given <var>contextElement</var>, <var>html</var>, and true.</p></li>
<li><p>Let <var>fragment</var> be a new <code>DocumentFragment</code> whose <span>node
document</span> is <var>contextElement</var>'s <span>node document</span>.</p></li>
<li><p>For each <var>node</var> in <var>newChildren</var>, <span
data-x="concept-node-append">append</span> <var>node</var> to <var>fragment</var>.</p></li>
<li><p><span data-x="concept-node-replace-all">Replace all</span> with <var>fragment</var> within
<var>target</var>.</p></li>
</ol>
<hr>
<p>The static <dfn method for="Document"><code
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe(<var>html</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>compliantHTML</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>html</var>, "<code data-x="">Document parseHTMLUnsafe</code>", and "<code
data-x="">script</code>".</p></li>
<li>
<p>Let <var>document</var> be a new <code>Document</code>, whose <span
data-x="concept-document-content-type">content type</span> is "<code
data-x="">text/html</code>".</p>
<p class="note">Since <var>document</var> does not have a <span
data-x="concept-document-bc">browsing context</span>, <span data-x="concept-n-script">scripting
is disabled</span>.</p>
</li>
<li><p>Set <var>document</var>'s <span
data-x="concept-document-allow-declarative-shadow-roots">allow declarative shadow roots</span> to
true.</p></li>
<li><p><span>Parse HTML from a string</span> given <var>document</var> and
<var>compliantHTML</var>.</p></li>
<li><p>Return <var>document</var>.</p></li>
</ol>
</div>
<h4>HTML serialization methods</h4>
<dl class="domintro">
<dt><code data-x=""><var>html</var> = <var>element</var>.<span subdfn data-x="dom-Element-getHTML">getHTML</span>({ <span data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</span>, <span data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</span> })</code></dt>
<dd>
<p>Returns the result of serializing <var>element</var> to HTML. <span data-x="shadow root">Shadow roots</span> within <var>element</var> are serialized according to the provided options:</p>
<ul>
<li><p>If <code data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</code> is true, then all shadow roots marked as <span data-x="shadow-serializable">serializable</span> are serialized.</p></li>
<li><p>If the <code data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</code> array is provided, then all shadow roots specified in the array are serialized, regardless of whether or not they are marked as serializable.</p></li>
</ul>
<p>If neither option is provided, then no shadow roots are serialized.</p>
</dd>
<dt><code data-x=""><var>html</var> = <var>shadowRoot</var>.<span subdfn data-x="dom-ShadowRoot-getHTML">getHTML</span>({ <span data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</span>, <span data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</span> })</code></dt>
<dd>
<p>Returns the result of serializing <var>shadowRoot</var> to HTML, using its <span data-x="concept-DocumentFragment-host">shadow host</span> as the context element. <span data-x="shadow root">Shadow roots</span> within <var>shadowRoot</var> are serialized according to the provided options, as above.</p>
</dd>
</dl>
<div w-nodev>
<p><code>Element</code>'s <dfn method for="Element"><code
data-x="dom-Element-getHTML">getHTML(<var>options</var>)</code></dfn> method steps
are to return the result of <span>HTML fragment serialization algorithm</span> with
<span>this</span>, <var>options</var>["<code
data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</code>"],
and <var>options</var>["<code data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</code>"].</p>
<p><code>ShadowRoot</code>'s <dfn method for="ShadowRoot"><code
data-x="dom-ShadowRoot-getHTML">getHTML(<var>options</var>)</code></dfn> method steps
are to return the result of <span>HTML fragment serialization algorithm</span> with
<span>this</span>, <var>options</var>["<code
data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</code>"],
and <var>options</var>["<code data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</code>"].</p>
</div>
<h4>The <code data-x="dom-element-innerHTML">innerHTML</code> property</h4>
<p class="XXX">The <code data-x="dom-element-innerHTML">innerHTML</code> property has a number of outstanding issues
in the <cite>DOM Parsing and Serialization</cite> <a href="https://github.com/w3c/DOM-Parsing/issues">issue
tracker</a>, documenting various problems with its specification.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-Element-innerHTML">innerHTML</span></code></dt>
<dd>
<p>Returns a fragment of HTML or XML that represents the element's contents.</p>
<p>In the case of an XML document, throws a <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code> if the element cannot be serialized to XML.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-Element-innerHTML">innerHTML</span> = <var>value</var></code></dt>
<dd>
<p>Replaces the contents of the element with nodes parsed from the given string.</p>
<p>In the case of an XML document, throws a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code> if the given string is not well-formed.</p>
</dd>
<dt><code data-x=""><var>shadowRoot</var>.<span subdfn data-x="dom-ShadowRoot-innerHTML">innerHTML</span></code></dt>
<dd>
<p>Returns a fragment of HTML that represents the shadow roots's contents.</p>
</dd>
<dt><code data-x=""><var>shadowRoot</var>.<span data-x="dom-ShadowRoot-innerHTML">innerHTML</span> = <var>value</var></code></dt>
<dd>
<p>Replaces the contents of the shadow root with nodes parsed from the given string.</p>
</dd>
</dl>
<p class="warning">These properties' setters perform no sanitization to remove
potentially-dangerous elements and attributes like <code>script</code> or <span>event handler
content attributes</span>.</p>
<div w-nodev>
<p>The <dfn export>fragment serializing algorithm steps</dfn>, given an <code>Element</code>,
<code>Document</code>, or <code>DocumentFragment</code> <var>node</var> and a boolean <var>require
well-formed</var>, are:</p>
<ol>
<li><p>Let <var>context document</var> be <var>node</var>'s <span>node document</span>.</p></li>
<li><p>If <var>context document</var> is an <span data-x="HTML documents">HTML document</span>,
return the result of <span>HTML fragment serialization algorithm</span> with <var>node</var>,
false, and « ».</p></li>
<li><p>Return the <span data-x="xml-serialization">XML serialization</span> of <var>node</var>
given <var>require well-formed</var>.</p></li>
</ol>
<p>The <dfn export>fragment parsing algorithm steps</dfn>, given an <code>Element</code>
<var>context</var> and a string <var>markup</var>, are:</p>
<ol>
<li><p>Let <var>algorithm</var> be the <span>HTML fragment parsing algorithm</span>.</p></li>
<li><p>If <var>context</var>'s <span>node document</span> is an <span data-x="XML documents">XML
document</span>, then set <var>algorithm</var> to the <span>XML fragment parsing
algorithm</span>.</p></li>
<li><p>Let <var>newChildren</var> be the result of invoking <var>algorithm</var> given
<var>context</var> and <var>markup</var>.</p></li>
<li><p>Let <var>fragment</var> be a new <code>DocumentFragment</code> whose <span>node
document</span> is <var>context</var>'s <span>node document</span>.</p></li>
<li>
<p>For each <var>node</var> of <var>newChildren</var>, in <span>tree order</span>: <span
data-x="concept-node-append">append</span> <var>node</var> to <var>fragment</var>.</p>
<p class=note>This ensures the <span>node document</span> for the new <span
data-x="node">nodes</span> is correct.</p>
</li>
<li><p>Return <var>fragment</var>.</p></li>
</ol>
<p><code>Element</code>'s <dfn attribute for="Element"><code
data-x="dom-Element-innerHTML">innerHTML</code></dfn> getter steps are to return the result of
running <span>fragment serializing algorithm steps</span> with <span>this</span> and true.</p>
<p><code>ShadowRoot</code>'s <dfn attribute for="ShadowRoot"><code
data-x="dom-ShadowRoot-innerHTML">innerHTML</code></dfn> getter steps are to return the result of
running <span>fragment serializing algorithm steps</span> with <span>this</span> and true.</p>
<p><code>Element</code>'s <code data-x="dom-Element-innerHTML">innerHTML</code> setter steps
are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, the given value, "<code data-x="">Element innerHTML</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>context</var> be <span>this</span>.</p></li>
<li><p>Let <var>fragment</var> be the result of invoking the <span>fragment parsing algorithm
steps</span> with <var>context</var> and <var>compliantString</var>.</p></li>
<li>
<p>If <var>context</var> is a <code>template</code> element, then set <var>context</var> to
the <code>template</code> element's <span>template contents</span> (a
<code>DocumentFragment</code>).</p>
<p class=note>Setting <code data-x="dom-Element-innerHTML">innerHTML</code> on a
<code>template</code> element will replace all the nodes in its <span>template contents</span>
rather than its <span data-x="concept-tree-child">children</span>.</p>
</li>
<li><p><span data-x="concept-node-replace-all">Replace all</span> with <var>fragment</var>
within <var>context</var>.</p></li>
</ol>
<p><code>ShadowRoot</code>'s <code data-x="dom-ShadowRoot-innerHTML">innerHTML</code> setter
steps are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, the given value, "<code data-x="">ShadowRoot innerHTML</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>context</var> be <span>this</span>'s <span
data-x="concept-DocumentFragment-host">host</span>.</p></li>
<li><p>Let <var>fragment</var> be the result of invoking the <span>fragment parsing algorithm
steps</span> with <var>context</var> and <var>compliantString</var>.</p></li>
<li><p><span data-x="concept-node-replace-all">Replace all</span> with <var>fragment</var>
within <span>this</span>.</p></li>
</ol>
</div>
<h4>The <code data-x="dom-element-outerHTML">outerHTML</code> property</h4>
<p class="XXX">The <code data-x="dom-element-outerHTML">outerHTML</code> property has a number of outstanding issues
in the <cite>DOM Parsing and Serialization</cite> <a href="https://github.com/w3c/DOM-Parsing/issues">issue
tracker</a>, documenting various problems with its specification.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-Element-outerHTML">outerHTML</span></code></dt>
<dd>
<p>Returns a fragment of HTML or XML that represents the element and its contents.</p>
<p>In the case of an XML document, throws a <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code> if the element cannot be serialized to XML.</p>
</dd>
<dt><code data-x=""><var>element</var>.<span data-x="dom-Element-outerHTML">outerHTML</span> = <var>value</var></code></dt>
<dd>
<p>Replaces the element with nodes parsed from the given string.</p>
<p>In the case of an XML document, throws a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code> if the given string is not well-formed.</p>
<p>Throws a <span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code> if
the parent of the element is a <span><code>Document</code></span>.</p>
</dd>
</dl>
<p class="warning">This property's setter performs no sanitization to remove potentially-dangerous
elements and attributes like <code>script</code> or <span>event handler content
attributes</span>.</p>
<div w-nodev>
<p><code>Element</code>'s <dfn attribute for="Element"><code
data-x="dom-Element-outerHTML">outerHTML</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>element</var> be a fictional node whose only child is <span>this</span>.</p></li>
<li><p>Return the result of running <span>fragment serializing algorithm steps</span> with
<var>element</var> and true.
</ol>
<p><code>Element</code>'s <code data-x="dom-Element-outerHTML">outerHTML</code> setter steps
are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, the given value, "<code data-x="">Element outerHTML</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>parent</var> be <span>this</span>'s <span>parent</span>.</p></li>
<li><p>If <var>parent</var> is null, return. There would be no way to obtain a
reference to the nodes created even if the remaining steps were run.</p></li>
<li><p>If <var>parent</var> is a <code>Document</code>, throw a
<span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>parent</var> is a <code>DocumentFragment</code>, set <var>parent</var> to the
result of <span data-x="create an element">creating an element</span> given <span>this</span>'s
<span>node document</span>, "<code data-x="">body</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p>Let <var>fragment</var> be the result of invoking the <span>fragment parsing algorithm
steps</span> given <var>parent</var> and <var>compliantString</var>.</p></li>
<li><p><span data-x="concept-node-replace">Replace</span> <span>this</span> with
<var>fragment</var> within <span>this</span>'s <span>parent</span>.</p></li>
</ol>
</div>
<h4>The <code data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code> method</h4>
<p class="XXX">The <code data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code>
method has a number of outstanding issues in the <cite>DOM Parsing and Serialization</cite> <a
href="https://github.com/w3c/DOM-Parsing/issues">issue tracker</a>, documenting various problems
with its specification.</p>
<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML</span>(<var>position</var>, <var>string</var>)</code></dt>
<dd>
<p>Parses <var>string</var> as HTML or XML and inserts the resulting nodes into the tree in
the position given by the <var>position</var> argument, as follows:</p>
<dl>
<dt>"<code data-x="">beforebegin</code>"</dt>
<dd>Before the element itself (i.e., after <var>element</var>'s previous sibling)</dd>
<dt>"<code data-x="">afterbegin</code>"</dt>
<dd>Just inside the element, before its first child.</dd>
<dt>"<code data-x="">beforeend</code>"</dt>
<dd>Just inside the element, after its last child.</dd>
<dt>"<code data-x="">afterend</code>"</dt>
<dd>After the element itself (i.e., before <var>element</var>'s next sibling)</dd>
</dl>
<p>Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if the arguments
have invalid values (e.g., in the case of an <span data-x="XML documents">XML document</span>,
if the given string is not well-formed).</p>
<p>Throws a <span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>
if the given position isn't possible (e.g. inserting elements after the root element of a
<code>Document</code>).</p>
</dd>
</dl>
<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<div w-nodev>
<p><code>Element</code>'s <dfn method for="Element"><code
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML(<var>position</var>,
<var>string</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>string</var>, "<code data-x="">Element insertAdjacentHTML</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>context</var> be null.</p></li>
<li><p>Use the first matching item from this list:</p>
<dl class=switch>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforebegin</code>"</dt>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterend</code>"</dt>
<dd>
<ol>
<li><p>Set <var>context</var> to <span>this</span>'s <span
data-x="dom-parent">parent</span>.</p></li>
<li><p>If <var>context</var> is null or a <code>Document</code>, throw a
<span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</dd>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterbegin</code>"</dt>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforeend</code>"</dt>
<dd>Set <var>context</var> to <span>this</span>.</dd>
<dt>Otherwise</dt>
<dd><p>Throw a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></dd>
</dl>
</li>
<li>
<p>If <var>context</var> is not an <code>Element</code> or all of the following are true:</p>
<ul>
<li><p><var>context</var>'s <span>node document</span> is an HTML document;</p></li>
<li><p><var>context</var>'s <span data-x="concept-element-local-name">local name</span> is
"<code>html</code>"; and</p></li>
<li><p><var>context</var>'s <span data-x="concept-element-namespace">namespace</span> is the
<span>HTML namespace</span>,</p></li>
</ul>
<p>set <var>context</var> to the result of <span data-x="create an element">creating an
element</span> given <span>this</span>'s <span>node document</span>, "<code
data-x="">body</code>", and the <span>HTML namespace</span>.</p>
</li>
<li>
<p>Let <var>fragment</var> be the result of invoking the <span>fragment parsing algorithm
steps</span> with <var>context</var> and <var>compliantString</var>.</p>
</li>
<li>Use the first matching item from this list:
<dl class=switch>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforebegin</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
<span>this</span>'s <span data-x="dom-parent">parent</span> before <span>this</span>.</p>
</dd>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterbegin</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
<span>this</span> before its <span>first child</span>.</p>
</dd>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforeend</code>"</dt>
<dd>
<p><span data-x="concept-node-append">Append</span> <var>fragment</var> to
<span>this</span>.</p>
</dd>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterend</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
<span>this</span>'s <span data-x="dom-parent">parent</span> before <span>this</span>'s
<span>next sibling</span>.</p>
</dd>
</dl>
</li>
</ol>
<p class=note>As with other direct <code>Node</code>-manipulation APIs (and unlike <code
data-x="dom-Element-innerHTML">innerHTML</code>), <code
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code> does not include any special
handling for <code>template</code> elements. In most cases you will want to use <code
data-x="">templateEl.<span data-x="dom-template-content">content</span>.<span
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</span></code> instead of directly
manipulating the child nodes of a <code>template</code> element.</p>
</div>
<h4>The <code data-x="dom-Range-createContextualFragment">createContextualFragment()</code>
method</h4>
<p class="XXX">The <code
data-x="dom-Range-createContextualFragment">createContextualFragment()</code> method has a number
of outstanding issues in the <cite>DOM Parsing and Serialization</cite> <a
href="https://github.com/w3c/DOM-Parsing/issues">issue tracker</a>, documenting various problems
with its specification.</p>
<dl class="domintro">
<dt><code data-x=""><var>docFragment</var> = <var>range</var>.<span subdfn data-x="dom-Range-createContextualFragment">createContextualFragment</span>(<var>string</var>)</code></dt>
<dd>
<p>Returns a <code>DocumentFragment</code> created from the markup string <var>string</var> using
<var>range</var>'s <span data-x="concept-range-start-node">start node</span> as the context in
which <var>fragment</var> is parsed.</p>
</dd>
</dl>
<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>
<pre><code class="idl">partial interface <span id="Range-partial">Range</span> {
[<span>CEReactions</span>, NewObject] <code>DocumentFragment</code> <span data-x="dom-Range-createContextualFragment">createContextualFragment</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) string);
};</code></pre>
<div w-nodev>
<p><code>Range</code>'s <dfn method for="Range"><code
data-x="dom-Range-createContextualFragment">createContextualFragment(<var>string</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>Let <var>compliantString</var> be the result of invoking the <span data-x="tt-getcompliantstring">Get
Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedhtml">TrustedHTML</code>, <span>this</span>'s <span>relevant global
object</span>, <var>string</var>, "<code data-x="">Range createContextualFragment</code>", and
"<code data-x="">script</code>".</p></li>
<li><p>Let <var>node</var> be <span>this</span>'s <span data-x="concept-range-start-node">start
node</span>.</p></li>
<li><p>Let <var>element</var> be null.</p></li>
<li><p>If <var>node</var> <span>implements</span> <code>Element</code>, set <var>element</var>
to <var>node</var>.</p></li>
<li><p>Otherwise, if <var>node</var> <span>implements</span> <code>Text</code> or
<code>Comment</code>, set <var>element</var> to <var>node</var>'s <span>parent
element</span>.</p></li>
<li>
<p>If <var>element</var> is null or all of the following are true:</p>
<ul>
<li><p><var>element</var>'s <span>node document</span> is an HTML document;</p></li>
<li><p><var>element</var>'s <span data-x="concept-element-local-name">local name</span> is
"<code>html</code>"; and</p></li>
<li><p><var>element</var>'s <span data-x="concept-element-namespace">namespace</span> is the
<span>HTML namespace</span>,</p></li>
</ul>
<p>then set <var>element</var> to the result of <span data-x="create an element">creating an
element</span> given <span>this</span>'s <span>node document</span>, "<code
data-x="">body</code>", and the <span>HTML namespace</span>.</p>
</li>
<li><p>Let <var>fragment node</var> be the result of invoking the <span>fragment parsing
algorithm steps</span> with <var>element</var> and <var>compliantString</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>script</var> of <var>fragment node</var>'s
<code data-x="script">script</code> element <span
data-x="concept-tree-descendant">descendants</span>:</p>
<ol>
<li><p>Set <var>script</var>'s <span>already started</span> to false.</p></li>
<li><p>Set <var>script</var>'s <span>parser document</span> to null.</p></li>
</ol>
</li>
<li><p>Return <var>fragment node</var>.</p></li>
</ol>
</div>
<h4>The <code>XMLSerializer</code> interface</h4>
<p class="XXX">The <code>XMLSerializer</code> interface has a number of outstanding issues in the
<cite>DOM Parsing and Serialization</cite> <a
href="https://github.com/w3c/DOM-Parsing/issues">issue tracker</a>, documenting various problems
with its specification. The remainder of <cite>DOM Parsing and Serialization</cite> will be
gradually upstreamed to this specification.</p>
<dl class="domintro">
<dt><code data-x=""><var>xmlSerializer</var> = new <span subdfn data-x="dom-XMLSerializer-constructor">XMLSerializer</span>()</code></dt>
<dd><p>Constructs a new <code>XMLSerializer</code> object.</p></dd>
<dt><code data-x=""><var>string</var> = <var>xmlSerializer</var>.<span subdfn data-x="dom-XMLSerializer-serializeToString">serializeToString</span>(<var>root</var>)</code></dt>
<dd>
<p>Returns the result of serializing <var>root</var> to XML.</p>
<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if
<var>root</var> cannot be serialized to XML.</p>
</dd>
</dl>
<p class="note">The design of <code>XMLSerializer</code>, as a class that needs to be constructed
and then have its <code data-x="dom-XMLSerializer-serializeToString">serializeToString()</code>
method called, is an unfortunate historical artifact. If we were designing this functionality
today it would be a standalone function.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>XMLSerializer</dfn> {
<span data-x="dom-XMLSerializer-constructor">constructor</span>();
DOMString <span data-x="dom-XMLSerializer-serializeToString">serializeToString</span>(<code>Node</code> root);
};</code></pre>
<div w-nodev>
<p>The <dfn data-x="dom-XMLSerializer-constructor"><code>new XMLSerializer()</code></dfn>
constructor steps are to do nothing.</p>
<p>The <dfn method for="XMLSerializer"
data-x="dom-XMLSerializer-serializeToString"><code>serializeToString(<var>root</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>Return the <span data-x="xml-serialization">XML serialization</span> of <var>root</var>
given false.</p></li>
</ol>
</div>
<h3 split-filename="timers-and-user-prompts" id="timers">Timers</h3>
<p>The <code data-x="dom-setTimeout">setTimeout()</code> and <code
data-x="dom-setInterval">setInterval()</code> methods allow authors to schedule timer-based
callbacks.</p>
<dl class="domintro">
<dt><code data-x=""><var>id</var> = self.<span subdfn data-x="dom-setTimeout">setTimeout</span>(<var>handler</var> [, <var>timeout</var> [, ...<var>arguments</var> ] ])</code></dt>
<dd>
<p>Schedules a timeout to run <var>handler</var> after <var>timeout</var> milliseconds. Any
<var>arguments</var> are passed straight through to the <var>handler</var>.</p>
</dd>
<dt><code data-x=""><var>id</var> = self.<span data-x="dom-setTimeout">setTimeout</span>(<var>code</var> [, <var>timeout</var> ])</code></dt>
<dd>
<p>Schedules a timeout to compile and run <var>code</var> after <var>timeout</var>
milliseconds.</p>
</dd>
<dt><code data-x="">self.<span subdfn data-x="dom-clearTimeout">clearTimeout</span>(<var>id</var>)</code></dt>
<!-- don't mention that the id is optional, since if omitted, the method does nothing -->
<dd><p>Cancels the timeout set with <code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code> identified by <var>id</var>.</p></dd>
<dt><code data-x=""><var>id</var> = self.<span subdfn data-x="dom-setInterval">setInterval</span>(<var>handler</var> [, <var>timeout</var> [, ...<var>arguments</var> ] ])</code></dt>
<dd>
<p>Schedules a timeout to run <var>handler</var> every <var>timeout</var> milliseconds. Any
<var>arguments</var> are passed straight through to the <var>handler</var>.</p>
</dd>
<dt><code data-x=""><var>id</var> = self.<span data-x="dom-setInterval">setInterval</span>(<var>code</var> [, <var>timeout</var> ])</code></dt>
<dd>
<p>Schedules a timeout to compile and run <var>code</var> every <var>timeout</var>
milliseconds.</p>
</dd>
<dt><code data-x="">self.<span subdfn data-x="dom-clearInterval">clearInterval</span>(<var>id</var>)</code></dt>
<!-- don't mention that the id is optional, since if omitted, the method does nothing -->
<dd><p>Cancels the timeout set with <code data-x="dom-setInterval">setInterval()</code> or <code
data-x="dom-setTimeout">setTimeout()</code> identified by <var>id</var>.</p></dd>
</dl>
<p class="note">Timers can be nested; after five such nested timers, however, the interval is
forced to be at least four milliseconds.</p>
<p class="note">This API does not guarantee that timers will run exactly on schedule. Delays due
to CPU load, other tasks, etc, are to be expected.</p>
<div w-nodev>
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a
<dfn export for="WindowOrWorkerGlobalScope">map of setTimeout and setInterval IDs</dfn>, which is
an <span>ordered map</span>, initially empty. Each <span data-x="map key">key</span> in this map
is a positive integer, corresponding to the return value of a <code data-x="dom-setTimeout"
>setTimeout()</code> or <code data-x="dom-setInterval">setInterval()</code> call.
Each <span data-x="map value">value</span> is a <span>unique internal value</span>, corresponding
to a key in the object's <span>map of active timers</span>.</p>
<hr>
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-setTimeout"><code
id="dom-windowtimers-setTimeout">setTimeout(<var>handler</var>, <var>timeout</var>,
...<var>arguments</var>)</code></dfn> method steps are to return the result of running the
<span>timer initialization steps</span> given <span>this</span>, <var>handler</var>,
<var>timeout</var>, <var>arguments</var>, and false.</p>
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-setInterval"><code
id="dom-windowtimers-setInterval">setInterval(<var>handler</var>, <var>timeout</var>,
...<var>arguments</var>)</code></dfn> method steps are to return the result of running the
<span>timer initialization steps</span> given <span>this</span>, <var>handler</var>,
<var>timeout</var>, <var>arguments</var>, and true.</p>
<p>The <dfn method for="WindowOrWorkerGlobalScope" data-x="dom-clearTimeout"><code
id="dom-windowtimers-clearTimeout">clearTimeout(<var>id</var>)</code></dfn> and <dfn method
for="WindowOrWorkerGlobalScope" data-x="dom-clearInterval"><code
id="dom-windowtimers-clearInterval">clearInterval(<var>id</var>)</code></dfn> method steps
are to <span data-x="map remove">remove</span> <span>this</span>'s <span>map of setTimeout and
setInterval IDs</span>[<var>id</var>].</p>
<p class="note">Because <code data-x="dom-clearTimeout">clearTimeout()</code> and <code
data-x="dom-clearInterval">clearInterval()</code> clear entries from the same map, either method
can be used to clear timers created by <code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code>.</p>
<hr>
<p>To perform the <!--en-GB--><dfn id="timer-initialisation-steps">timer initialization
steps</dfn>, given a <code>WindowOrWorkerGlobalScope</code> <var>global</var>, a string or <code
data-x="idl-Function">Function</code> or <code data-x="tt-trustedscript">TrustedScript</code>
<var>handler</var>, a number <var>timeout</var>, a list <var>arguments</var>, a boolean
<var>repeat</var>, and optionally (and only if <var>repeat</var> is true) a number
<var>previousId</var>, perform the following steps. They return a number.</p>
<ol>
<li><p>Let <var>thisArg</var> be <var>global</var> if that is a <code>WorkerGlobalScope</code>
object; otherwise let <var>thisArg</var> be the <code>WindowProxy</code> that corresponds to
<var>global</var>.</p></li>
<li><p>If <var>previousId</var> was given, let <var>id</var> be <var>previousId</var>;
otherwise, let <var>id</var> be an <span>implementation-defined</span> integer that is greater
than zero and does not already <span data-x="map exists">exist</span> in <var>global</var>'s
<span>map of setTimeout and setInterval IDs</span>.</p></li>
<li>
<p>If the <span>surrounding agent</span>'s <span data-x="concept-agent-event-loop">event
loop</span>'s <span>currently running task</span> is a task that was created by this algorithm,
then let <var>nesting level</var> be the <span data-x="concept-task">task</span>'s <span>timer
nesting level</span>. Otherwise, let <var>nesting level</var> be zero.</p>
<p class="note">The task's <span>timer nesting level</span> is used both for nested calls to
<code data-x="dom-setTimeout">setTimeout()</code>, and for the repeating timers created by
<code data-x="dom-setInterval">setInterval()</code>. (Or, indeed, for any combination of the
two.) In other words, it represents nested invocations of this algorithm, not of a particular
method.</p>
</li>
<li><p>If <var>timeout</var> is less than 0, then set <var>timeout</var> to 0.</p></li>
<li><p>If <var>nesting level</var> is greater than 5, and <var>timeout</var> is less than 4,
then set <var>timeout</var> to 4.</p></li>
<li><p>Let <var>realm</var> be <var>global</var>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p>Let <var>initiating script</var> be the <span>active script</span>.</p></li>
<li><p>Let <var>uniqueHandle</var> be null.</p></li>
<li>
<p>Let <var>task</var> be a <span data-x="concept-task">task</span> that runs the following
substeps:</p>
<ol>
<li><p><span>Assert</span>: <var>uniqueHandle</var> is a <span>unique internal value</span>,
not null.</p></li>
<li><p>If <var>id</var> does not <span data-x="map exists">exist</span> in <var>global</var>'s
<span>map of setTimeout and setInterval IDs</span>, then abort these steps.</p></li>
<li>
<p>If <var>global</var>'s <span>map of setTimeout and setInterval IDs</span>[<var>id</var>]
does not equal <var>uniqueHandle</var>, then abort these steps.</p>
<p class="note">This accommodates for the ID having been cleared by a <code
data-x="dom-clearTimeout">clearTimeout()</code> or <code
data-x="dom-clearInterval">clearInterval()</code> call, and being reused by a subsequent
<code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code> call.</p>
</li>
<li><p><span>Record timing info for timer handler</span> given <var>handler</var>,
<var>global</var>'s <span>relevant settings object</span>, and <var>repeat</var>.</p></li>
<li><p>If <var>handler</var> is a <code data-x="idl-Function">Function</code>, then <span
data-x="es-invoking-callback-functions">invoke</span> <var>handler</var> given
<var>arguments</var> and "<code data-x="">report</code>", and with <i
data-x="dfn-callback-this-value">callback this value</i> set to <var>thisArg</var>.</p>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li>
<p>If <var>previousId</var> was not given:</p>
<ol>
<li><p>Let <var>globalName</var> be "<code data-x="">Window</code>" if <var>global</var> is
a <code>Window</code> object; "<code data-x="">WorkerGlobalScope</code>"
otherwise.</p></li>
<li><p>Let <var>methodName</var> be "<code data-x="">setInterval</code>" if
<var>repeat</var> is true; "<code data-x="">setTimeout</code>" otherwise.</p></li>
<li><p>Let <var>sink</var> be a concatenation of <var>globalName</var>, U+0020 SPACE, and
<var>methodName</var>.</p></li>
<li><p>Set <var>handler</var> to the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with
<code data-x="tt-trustedscript">TrustedScript</code>, <var>global</var>,
<var>handler</var>, <var>sink</var>, and "<code data-x="">script</code>".</p></li>
</ol>
</li>
<li><p><span>Assert</span>: <var>handler</var> is a string.</p></li>
<li><p>Perform <span
data-x="csp-EnsureCSPDoesNotBlockStringCompilation">EnsureCSPDoesNotBlockStringCompilation</span>(<var>realm</var>,
« », <var>handler</var>, <var>handler</var>, timer, « », <var>handler</var>). If this throws
an exception, catch it, <span data-x="report an exception">report</span> it for
<var>global</var>, and abort these steps.</p></li>
<!-- timer is an enum value. -->
<li><p>Let <var>settings object</var> be <var>global</var>'s <span>relevant settings
object</span>.</p></li>
<li><p>Let <var>fetch options</var> be the <span>default script fetch
options</span>.</p></li>
<li><p>Let <var>base URL</var> be <var>settings object</var>'s <span>API base
URL</span>.</p></li>
<li>
<p>If <var>initiating script</var> is not null, then:</p>
<ol>
<li><p>Set <var>fetch options</var> to a <span>script fetch options</span> whose <span
data-x="concept-script-fetch-options-nonce">cryptographic nonce</span> is <var>initiating
script</var>'s <span data-x="concept-script-script-fetch-options">fetch options</span>'s
<span data-x="concept-script-fetch-options-nonce">cryptographic nonce</span>, <span
data-x="concept-script-fetch-options-integrity">integrity metadata</span> is the empty
string, <span data-x="concept-script-fetch-options-parser">parser metadata</span> is
"<code data-x="">not-parser-inserted</code>", <span
data-x="concept-script-fetch-options-credentials">credentials mode</span> is
<var>initiating script</var>'s <span data-x="concept-script-script-fetch-options">fetch
options</span>'s <span data-x="concept-script-fetch-options-credentials">credentials
mode</span>, <span data-x="concept-script-fetch-options-referrer-policy">referrer
policy</span> is <var>initiating script</var>'s <span
data-x="concept-script-script-fetch-options">fetch options</span>'s <span
data-x="concept-script-fetch-options-referrer-policy">referrer policy</span>, and <span
data-x="concept-script-fetch-options-fetch-priority">fetch priority</span> is "<code
data-x="">auto</code>".</p></li>
<li><p>Set <var>base URL</var> to <var>initiating script</var>'s <span
data-x="concept-script-base-url">base URL</span>.</p></li>
</ol>
<p class="note">The effect of these steps ensures that the string compilation done by <code
data-x="dom-setTimeout">setTimeout()</code> and <code
data-x="dom-setInterval">setInterval()</code> behaves equivalently to that done by
<code>eval()</code>. That is, <span>module script</span> fetches via <code>import()</code>
will behave the same in both contexts.</p>
</li>
<li><p>Let <var>script</var> be the result of <span>creating a classic script</span> given
<var>handler</var>, <var>settings object</var>, <var>base URL</var>, and <var>fetch
options</var>.</p></li>
<li><p><span data-x="run a classic script">Run the classic script</span>
<var>script</var>.</p></li>
</ol>
</li>
<li><p>If <var>id</var> does not <span data-x="map exists">exist</span> in <var>global</var>'s
<span>map of setTimeout and setInterval IDs</span>, then abort these steps.</p></li>
<li>
<p>If <var>global</var>'s <span>map of setTimeout and setInterval IDs</span>[<var>id</var>]
does not equal <var>uniqueHandle</var>, then abort these steps.</p>
<p class="note">The ID might have been removed via the author code in <var>handler</var>
calling <code data-x="dom-clearTimeout">clearTimeout()</code> or <code
data-x="dom-clearInterval">clearInterval()</code>. Checking that uniqueHandle isn't different
accounts for the possibility of the ID, after having been cleared, being reused by a
subsequent <code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code> call.</p>
</li>
<li><p>If <var>repeat</var> is true, then perform the <span>timer initialization
steps</span> again, given <var>global</var>, <var>handler</var>, <var>timeout</var>,
<var>arguments</var>, true, and <var>id</var>.</p></li>
<li><p>Otherwise, <span data-x="map remove">remove</span> <var>global</var>'s <span>map of
setTimeout and setInterval IDs</span>[<var>id</var>].</p></li>
</ol>
</li>
<li><p>Increment <var>nesting level</var> by one.</p></li>
<li><p>Set <var>task</var>'s <dfn>timer nesting level</dfn> to <var>nesting level</var>.</p></li>
<li><p>Let <var>completionStep</var> be an algorithm step which <span data-x="queue a global
task">queues a global task</span> on the <dfn export>timer task source</dfn> given
<var>global</var> to run <var>task</var>.</p></li>
<li><p>Set <var>uniqueHandle</var> to the result of <span data-x="run steps after a
timeout">running steps after a timeout</span> given <var>global</var>, "<code
data-x="">setTimeout/setInterval</code>", <var>timeout</var>,
<var>completionStep</var>.</p></li>
<li><p><span data-x="map set">Set</span> <var>global</var>'s <span>map of setTimeout and
setInterval IDs</span>[<var>id</var>] to <var>uniqueHandle</var>.</p></li>
<li><p>Return <var>id</var>.</p></li>
</ol>
<p class="note">Argument conversion as defined by Web IDL (for example, invoking <code
data-x="">toString()</code> methods on objects passed as the first argument) happens in the
algorithms defined in Web IDL, before this algorithm is invoked.</p>
<div class="example">
<p>So for example, the following rather silly code will result in the log containing "<code
data-x="">ONE TWO </code>":</p>
<pre><code class="js">var log = '';
function logger(s) { log += s + ' '; }
setTimeout({ toString: function () {
setTimeout("logger('ONE')", 100);
return "logger('TWO')";
} }, 100);</code></pre>
</div>
</div>
<div class="example">
<p>To run tasks of several milliseconds back to back without any delay, while still yielding back
to the browser to avoid starving the user interface (and to avoid the browser killing the script
for hogging the CPU), simply queue the next timer before performing work:</p>
<pre><code class="js">function doExpensiveWork() {
var done = false;
// ...
// this part of the function takes up to five milliseconds
// set done to true if we're done
// ...
return done;
}
function rescheduleWork() {
var id = setTimeout(rescheduleWork, 0); // preschedule next iteration
if (doExpensiveWork())
clearTimeout(id); // clear the timeout if we don't need it
}
function scheduleWork() {
setTimeout(rescheduleWork, 0);
}
scheduleWork(); // queues a task to do lots of work</code></pre>
</div>
<div w-nodev>
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn export
for="WindowOrWorkerGlobalScope">map of active timers</dfn>, which is an <span>ordered map</span>,
initially empty. Each <span data-x="map key">key</span> in this map is a <span>unique internal
value</span> that represents a timer, and each <span data-x="map value">value</span> is a
<code>DOMHighResTimeStamp</code>, representing the expiry time for that timer.</p>
<p>To <dfn export>run steps after a timeout</dfn>, given a <code>WindowOrWorkerGlobalScope</code>
<var>global</var>, a string <var>orderingIdentifier</var>, a number <var>milliseconds</var>, and a
set of steps <var>completionSteps</var>, perform the following steps. They return a <span>unique
internal value</span>.</p>
<ol>
<li><p>Let <var>timerKey</var> be a new <span>unique internal value</span>.</p></li>
<li><p>Let <var>startTime</var> be the <span>current high resolution time</span> given
<var>global</var>.</p></li>
<li><p><span data-x="map set">Set</span> <var>global</var>'s <span>map of active
timers</span>[<var>timerKey</var>] to <var>startTime</var> plus
<var>milliseconds</var>.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li>
<p>If <var>global</var> is a <code>Window</code> object, wait until <var>global</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> has been <span>fully
active</span> for a further <var>milliseconds</var> milliseconds (not necessarily
consecutively).</p>
<p>Otherwise, <var>global</var> is a <code>WorkerGlobalScope</code> object; wait until
<var>milliseconds</var> milliseconds have passed with the worker not suspended (not
necessarily consecutively).</p>
</li>
<li><p>Wait until any invocations of this algorithm that had the same <var>global</var> and
<var>orderingIdentifier</var>, that started before this one, and whose <var>milliseconds</var>
is less than or equal to this one's, have completed.</p></li>
<li>
<p>Optionally, wait a further <span>implementation-defined</span> length of time.</p>
<p class="note">This is intended to allow user agents to pad timeouts as needed to optimize
the power usage of the device. For example, some processors have a low-power mode where the
granularity of timers is reduced; on such platforms, user agents can slow timers down to fit
this schedule instead of requiring the processor to use the more accurate mode with its
associated higher power usage.</p>
</li>
<li><p>Perform <var>completionSteps</var>.</p></li>
<li><p><span data-x="map remove">Remove</span> <var>global</var>'s
<span>map of active timers</span>[<var>timerKey</var>].</p></li>
</ol>
</li>
<li><p>Return <var>timerKey</var>.</p></li>
</ol>
<p class="note"><span>Run steps after a timeout</span> is meant to be used by other
specifications that want to execute developer-supplied code after a developer-supplied timeout,
in a similar manner to <code data-x="dom-setTimeout">setTimeout()</code>. (Note, however, it does
not have the nesting and clamping behavior of <code data-x="dom-setTimeout">setTimeout()</code>.)
Such specifications can choose an <var>orderingIdentifier</var> to ensure ordering within their
specification's timeouts, while not constraining ordering with respect to other specification's
timeouts.</p>
</div>
<h3>Microtask queuing</h3>
<dl class="domintro">
<dt><code data-x=""><var>self</var>.<span subdfn data-x="dom-queueMicrotask">queueMicrotask</span>(<var>callback</var>)</code></dt>
<dd><p><span data-x="queue a microtask">Queues</span> a <span>microtask</span> to run the given
<var>callback</var>.</p></dd>
</dl>
<p w-nodev>The <dfn method for="WindowOrWorkerGlobalScope"><code
data-x="dom-queueMicrotask">queueMicrotask(<var>callback</var>)</code></dfn> method must
<span>queue a microtask</span> to <span data-x="es-invoking-callback-functions">invoke</span>
<var>callback</var> with « » and "<code data-x="">report</code>".</p>
<p>The <code data-x="dom-queueMicrotask">queueMicrotask()</code> method allows authors to schedule
a callback on the <span>microtask queue</span>. This allows their code to run once the
<span>JavaScript execution context stack</span> is next empty, which happens once all currently
executing synchronous JavaScript has run to completion. This doesn't yield control back to the
<span>event loop</span>, as would be the case when using, for example, <code
data-x="dom-setTimeout">setTimeout(<var>f</var>, 0)</code>.</p>
<p>Authors ought to be aware that scheduling a lot of microtasks has the same performance
downsides as running a lot of synchronous code. Both will prevent the browser from doing its own
work, such as rendering. In many cases, <code
data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame()</code> or
<code>requestIdleCallback()</code> is a better choice. In particular, if the goal is to run code
before the next rendering cycle, that is the purpose of <code
data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame()</code>.</p>
<p>As can be seen from the following examples, the best way of thinking about <code
data-x="dom-queueMicrotask">queueMicrotask()</code> is as a mechanism for rearranging synchronous
code, effectively placing the queued code immediately after the currently executing synchronous
JavaScript has run to completion.</p>
<div class="example">
<p>The most common reason for using <code data-x="dom-queueMicrotask">queueMicrotask()</code> is
to create consistent ordering, even in the cases where information is available synchronously,
without introducing undue delay.</p>
<p>For example, consider a custom element firing a <code data-x="">load</code> event, that also
maintains an internal cache of previously-loaded data. A naïve implementation might look
like:</p>
<pre><code class="js">MyElement.prototype.loadData = function (url) {
if (this._cache[url]) {
this._setData(this._cache[url]);
this.dispatchEvent(new Event("load"));
} else {
fetch(url).then(res => res.arrayBuffer()).then(data => {
this._cache[url] = data;
this._setData(data);
this.dispatchEvent(new Event("load"));
});
}
};</code></pre>
<p>This naïve implementation is problematic, however, in that it causes its users to
experience inconsistent behavior. For example, code such as</p>
<pre><code class="js">element.addEventListener("load", () => console.log("loaded"));
console.log("1");
element.loadData();
console.log("2");</code></pre>
<p>will sometimes log "1, 2, loaded" (if the data needs to be fetched), and sometimes log "1,
loaded, 2" (if the data is already cached). Similarly, after the call to <code
data-x="">loadData()</code>, it will be inconsistent whether or not the data is set on the
element.</p>
<p>To get a consistent ordering, <code data-x="dom-queueMicrotask">queueMicrotask()</code> can be
used:</p>
<pre><code class="js">MyElement.prototype.loadData = function (url) {
if (this._cache[url]) {<strong>
queueMicrotask(() => {
this._setData(this._cache[url]);
this.dispatchEvent(new Event("load"));
});</strong>
} else {
fetch(url).then(res => res.arrayBuffer()).then(data => {
this._cache[url] = data;
this._setData(data);
this.dispatchEvent(new Event("load"));
});
}
};</code></pre>
<p>By essentially rearranging the queued code to be after the <span>JavaScript execution context
stack</span> empties, this ensures a consistent ordering and update of the element's state.</p>
</div>
<div class="example">
<p>Another interesting use of <code data-x="dom-queueMicrotask">queueMicrotask()</code> is to
allow uncoordinated "batching" of work by multiple callers. For example, consider a library
function that wants to send data somewhere as soon as possible, but doesn't want to make multiple
network requests if doing so is easily avoidable. One way to balance this would be like so:</p>
<pre><code class="js">const queuedToSend = [];
function sendData(data) {
queuedToSend.push(data);
if (queuedToSend.length === 1) {
queueMicrotask(() => {
const stringToSend = JSON.stringify(queuedToSend);
queuedToSend.length = 0;
fetch("/endpoint", stringToSend);
});
}
}</code></pre>
<p>With this architecture, multiple subsequent calls to <code data-x="">sendData()</code> within
the currently executing synchronous JavaScript will be batched together into one
<code>fetch()</code> call, but with no intervening event loop tasks preempting the fetch (as
would have happened with similar code that instead used <code
data-x="dom-setTimeout">setTimeout()</code>).</p>
</div>
<h3>User prompts</h3>
<!--
v2 ideas:
* in-window modal dialogs
- escape/enter handling
- dragging the window out of the tab
* in-window non-modal palettes
- with a solution for the mobile space
-->
<h4>Simple dialogs</h4>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-alert">alert</span>(<var>message</var>)</code></dt>
<dd><p>Displays a modal alert with the given message, and waits for the user to dismiss
it.</p></dd>
<dt><code data-x=""><var>result</var> = <var>window</var>.<span subdfn data-x="dom-confirm">confirm</span>(<var>message</var>)</code></dt>
<dd>
<p>Displays a modal OK/Cancel prompt with the given message, waits for the user to dismiss it,
and returns true if the user clicks OK and false if the user clicks Cancel.</p>
</dd>
<dt><code data-x=""><var>result</var> = <var>window</var>.<span subdfn data-x="dom-prompt">prompt</span>(<var>message</var> [, <var>default</var>])</code></dt>
<dd>
<p>Displays a modal text control prompt with the given message, waits for the user to dismiss
it, and returns the value that the user entered. If the user cancels the prompt, then returns
null instead. If the second argument is present, then the given value is used as a default.</p>
</dd>
</dl>
<p class="note">Logic that depends on <span data-x="concept-task">tasks</span> or <span
data-x="microtask">microtasks</span>, such as <span data-x="media element">media elements</span>
loading their <span>media data</span>, are stalled when these methods are invoked.</p>
<div w-nodev>
<p>The <dfn method for="Window"><code data-x="dom-alert-noargs">alert()</code></dfn> and <dfn
method for="Window"><code data-x="dom-alert">alert(<var>message</var>)</code></dfn> method steps
are:</p>
<ol>
<li><p>If we <span>cannot show simple dialogs</span> for <span>this</span>, then return.</p></li>
<li><p>If the method was invoked with no arguments, then let <var>message</var> be the
empty string; otherwise, let <var>message</var> be the method's first
argument.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>message</var>.</p></li>
<li><p>Let <var>userPromptHandler</var> be <span>WebDriver BiDi user prompt opened</span> with
<span>this</span>, "<code data-x="">alert</code>", and <var>message</var>.</p></li>
<li>
<p>If <var>userPromptHandler</var> is "<code data-x="">none</code>", then:</p>
<ol>
<li><p>Show <var>message</var> to the user, treating U+000A LF as a line break.</p></li>
<li><p>Optionally, <span>pause</span> while waiting for the user to acknowledge the
message.</p></li>
</ol>
</li>
<li><p>Invoke <span>WebDriver BiDi user prompt closed</span> with <span>this</span>,
"<code data-x="">alert</code>", and true.</p></li>
</ol>
<p class="note">This method is defined using two overloads, instead of using an
<!--non-normative-->optional argument, for historical reasons. The practical impact of this is
that <code data-x="" class="js">alert(undefined)</code> is treated as <code data-x=""
class="js">alert("undefined")</code>, but <code data-x="" class="js">alert()</code> is treated as
<code data-x="" class="js">alert("")</code>.</p>
<p>The <dfn method for="Window"><code
data-x="dom-confirm">confirm(<var>message</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If we <span>cannot show simple dialogs</span> for <span>this</span>, then return
false.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>message</var>.</p></li>
<li><p>Show <var>message</var> to the user, treating U+000A LF as a line break, and ask the user
to respond with a positive or negative response.</p></li>
<li><p>Let <var>userPromptHandler</var> be <span>WebDriver BiDi user prompt opened</span> with
<span>this</span>, "<code data-x="">confirm</code>", and <var>message</var>.</p></li>
<li><p>Let <var>accepted</var> be false.</p></li>
<li>
<p>If <var>userPromptHandler</var> is "<code data-x="">none</code>", then:</p>
<ol>
<li><p><span>Pause</span> until the user responds either positively or negatively.</p></li>
<li><p>If the user responded positively, then set <var>accepted</var> to true.</p></li>
</ol>
</li>
<li><p>If <var>userPromptHandler</var> is "<code data-x="">accept</code>", then set
<var>accepted</var> to true.</p></li>
<li><p>Invoke <span>WebDriver BiDi user prompt closed</span> with <span>this</span>,
"<code data-x="">confirm</code>", and <var>accepted</var>.</p></li>
<li><p>Return <var>accepted</var>.</p></li>
</ol>
<p>The <dfn method for="Window"><code data-x="dom-prompt">prompt(<var>message</var>,
<var>default</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If we <span>cannot show simple dialogs</span> for <span>this</span>, then return
null.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>message</var>.</p></li>
<li><p>Set <var>default</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>default</var>.</p></li>
<li><p>Show <var>message</var> to the user, treating U+000A LF as a line break, and ask the user
to either respond with a string value or abort. The response must be defaulted to the value given
by <var>default</var>.</p></li>
<li><p>Let <var>userPromptHandler</var> be <span>WebDriver BiDi user prompt opened</span> with
<span>this</span>, "<code data-x="">prompt</code>", and <var>message</var>.</p></li>
<li><p>Let <var>result</var> be null.</p></li>
<li>
<p>If <var>userPromptHandler</var> is "<code data-x="">none</code>", then:</p>
<ol>
<li><p><span>Pause</span> while waiting for the user's response.</p></li>
<li><p>If the user did not abort, then set <var>result</var> to the string that the user
responded with.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>userPromptHandler</var> is "<code data-x="">accept</code>", then set
<var>result</var> to the empty string.</p></li>
<li><p>Invoke <span>WebDriver BiDi user prompt closed</span> with <span>this</span>,
"<code data-x="">prompt</code>", false if <var>result</var> is null or true otherwise,
and <var>result</var>.</p></li>
<li><p>Return <var>result</var>.</p></li>
</ol>
<p>To <dfn>optionally truncate a simple dialog string</dfn> <var>s</var>, return either
<var>s</var> itself or some string derived from <var>s</var> that is shorter. User agents should
not provide UI for displaying the elided portion of <var>s</var>, as this makes it too easy for
abusers to create dialogs of the form "Important security alert! Click 'Show More' for full
details!".</p>
<p class="note">For example, a user agent might want to only display the first 100 characters of a
message. Or, a user agent might replace the middle of the string with "…". These types of
modifications can be useful in limiting the abuse potential of unnaturally large,
trustworthy-looking system dialogs.</p>
<p>We <dfn>cannot show simple dialogs</dfn> for a <code>Window</code> <var>window</var> when the
following algorithm returns true:</p>
<ol>
<li><p>If the <span>active sandboxing flag set</span> of <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
modals flag</span> set, then return true.</p></li>
<li><p>If <var>window</var>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span> and <var>window</var>'s <span>relevant
settings object</span>'s <span>top-level origin</span> are not <span>same origin-domain</span>,
then return true.</p></li>
<li>If <var>window</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>termination nesting level</span> is
nonzero, then optionally return true.</li>
<li><p>Optionally, return true. (For example, the user agent might give the
user the option to ignore all modal dialogs, and would thus abort at this step whenever the method was
invoked.)</p></li>
<li><p>Return false.</p></li>
</ol>
</div>
<h4>Printing</h4>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-print">print</span>()</code></dt>
<dd><p>Prompts the user to print the page.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn method for="Window"><code data-x="dom-print">print()</code></dfn> method steps
are:</p>
<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>document</var> is not <span>fully active</span>, then return.</p></li>
<li><p>If <var>document</var>'s <span>unload counter</span> is greater than 0, then
return.</p></li>
<li><p>If <var>document</var> is <span>ready for post-load tasks</span>, then run the
<span>printing steps</span> for <var>document</var>.</p></li>
<li><p>Otherwise, set <var>document</var>'s <dfn>print when loaded</dfn> flag.</p></li>
</ol>
<p>User agents should also run the <span>printing steps</span> whenever the user asks for the
opportunity to <span>obtain a physical form</span> (e.g. printed copy), or the representation of a
physical form (e.g. PDF copy), of a document.</p>
<p>The <dfn>printing steps</dfn> for a <code>Document</code> <var>document</var> are:</p>
<ol>
<li>
<p>The user agent may display a message to the user or return (or both).</p>
<p class="example">For instance, a kiosk browser could silently ignore any invocations of the
<code data-x="dom-print">print()</code> method.</p>
<p class="example">For instance, a browser on a mobile device could detect that there are no
printers in the vicinity and display a message saying so before continuing to offer a "save to
PDF" option.</p>
</li>
<li>
<p>If the <span>active sandboxing flag set</span> of <var>document</var> has the <span>sandboxed
modals flag</span> set, then return.</p>
<p class="note">If the printing dialog is blocked by a <code>Document</code>'s sandbox,
then neither the <code data-x="event-beforeprint">beforeprint</code> nor <code
data-x="event-afterprint">afterprint</code> events will be fired.</p>
</li>
<li>
<p>The user agent must <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-beforeprint">beforeprint</code> at the <span>relevant global object</span> of
<var>document</var>, as well as any <span data-x="child navigable">child navigable</span> in
it.</p>
<p class="XXX">Firing in children only doesn't seem right here, and some tasks likely need to
be queued. See <a href="https://github.com/whatwg/html/issues/5096">issue #5096</a>.</p>
<p class="example">The <code data-x="event-beforeprint">beforeprint</code> event can be used to
annotate the printed copy, for instance adding the time at which the document was printed.</p>
</li>
<li><p>The user agent should offer the user the opportunity to <span>obtain a physical
form</span> (or the representation of a physical form) of <var>document</var>. The user agent may
wait for the user to either accept or decline before returning; if so, the user agent must
<span>pause</span> while the method is waiting. Even if the user agent doesn't wait at this
point, the user agent must use the state of the relevant documents as they are at this point in
the algorithm if and when it eventually creates the alternate form.</p></li>
<li>
<p>The user agent must <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-afterprint">afterprint</code> at the <span>relevant global object</span> of
<var>document</var>, as well as any <span data-x="child navigable">child navigables</span> in
it.</p>
<p class="XXX">Firing in children only doesn't seem right here, and some tasks likely need to
be queued. See <a href="https://github.com/whatwg/html/issues/5096">issue #5096</a>.</p>
<p class="example">The <code data-x="event-afterprint">afterprint</code> event can be used to
revert annotations added in the earlier event, as well as showing post-printing UI. For
instance, if a page is walking the user through the steps of applying for a home loan, the
script could automatically advance to the next step after having printed a form or other.</p>
</li>
</ol>
</div>
<h3 split-filename="system-state">System state and capabilities</h3>
<h4>The <code>Navigator</code> object</h4>
<p>Instances of <code>Navigator</code> represent the identity and state of the user agent (the
client). It has also been used as a generic global under which various APIs are located, but this
is not precedent to build upon. Instead use the <code>WindowOrWorkerGlobalScope</code> mixin or
equivalent.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>Navigator</dfn> {
// objects implementing this interface also implement the interfaces given below
};
<span>Navigator</span> includes <span>NavigatorID</span>;
<span>Navigator</span> includes <span>NavigatorLanguage</span>;
<span>Navigator</span> includes <span>NavigatorOnLine</span>;
<span>Navigator</span> includes <span>NavigatorContentUtils</span>;
<span>Navigator</span> includes <span>NavigatorCookies</span>;
<span>Navigator</span> includes <span>NavigatorPlugins</span>;
<span>Navigator</span> includes <span>NavigatorConcurrentHardware</span>;</code></pre>
<div w-nodev>
<p class="note">These interface mixins are defined separately so that <code>WorkerNavigator</code> can reuse parts of
the <code>Navigator</code> interface.</p>
<p>Each <code>Window</code> has an <dfn>associated <code>Navigator</code></dfn>, which is a <code>Navigator</code>
object. Upon creation of the <code>Window</code> object, its <span>associated <code>Navigator</code></span> must be
set to a <span>new</span> <code>Navigator</code> object created in the <code>Window</code> object's <span
data-x="concept-relevant-realm">relevant realm</span>.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-navigator">navigator</code></dfn> and <dfn attribute
for="Window"><code data-x="dom-clientInformation">clientInformation</code></dfn> getter steps are to return
<span>this</span>'s <span>associated <code>Navigator</code></span>.
</div>
<h5>Client identification</h5>
<pre><code class="idl">interface mixin <dfn interface>NavigatorID</dfn> {
readonly attribute DOMString <span data-x="dom-navigator-appCodeName">appCodeName</span>; // constant "Mozilla"
readonly attribute DOMString <span data-x="dom-navigator-appName">appName</span>; // constant "Netscape"
readonly attribute DOMString <span data-x="dom-navigator-appVersion">appVersion</span>;
readonly attribute DOMString <span data-x="dom-navigator-platform">platform</span>;
readonly attribute DOMString <span data-x="dom-navigator-product">product</span>; // constant "Gecko"
[Exposed=Window] readonly attribute DOMString <span data-x="dom-navigator-productSub">productSub</span>;
readonly attribute DOMString <span data-x="dom-navigator-userAgent">userAgent</span>;
[Exposed=Window] readonly attribute DOMString <span data-x="dom-navigator-vendor">vendor</span>;
[Exposed=Window] readonly attribute DOMString <span data-x="dom-navigator-vendorSub">vendorSub</span>; // constant ""
};</code></pre>
<p>In certain cases, despite the best efforts of the entire industry, web browsers have bugs and
limitations that web authors are forced to work around.</p>
<p>This section defines a collection of attributes that can be used to determine, from script, the
kind of user agent in use, in order to work around these issues.</p>
<div w-nodev>
<p>The user agent has a <dfn data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</dfn>, which is either <i>Chrome</i>, <i>Gecko</i>, or <i>WebKit</i>.</p>
<p class="note">The <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> constrains the <code>NavigatorID</code> mixin to the combinations of attribute
values and presence of <code data-x="dom-navigator-taintEnabled">taintEnabled()</code> and <code
data-x="dom-navigator-oscpu">oscpu</code> that are known to be compatible with existing web
content.</p>
</div>
<p>Client detection should always be limited to detecting known current versions; future versions
and unknown versions should always be assumed to be fully compliant.</p>
<dl class="domintro">
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-appCodeName">appCodeName</span></code></dt>
<dd><p>Returns the string "<code data-x="">Mozilla</code>".</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-appName">appName</span></code></dt>
<dd><p>Returns the string "<code data-x="">Netscape</code>".</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-appVersion">appVersion</span></code></dt>
<dd><p>Returns the version of the browser.</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-platform">platform</span></code></dt>
<dd><p>Returns the name of the platform.</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-product">product</span></code></dt>
<dd><p>Returns the string "<code data-x="">Gecko</code>".</p></dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-productSub">productSub</span></code></dt>
<dd><p>Returns either the string "<code data-x="">20030107</code>", or the string "<code
data-x="">20100101</code>".</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-userAgent">userAgent</span></code></dt>
<dd><p>Returns the complete `<code data-x="">User-Agent</code>` header.</p></dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-vendor">vendor</span></code></dt>
<dd><p>Returns either the empty string, the string "<code data-x="">Apple Computer, Inc.</code>",
or the string "<code data-x="">Google Inc.</code>".</p></dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-vendorSub">vendorSub</span></code></dt>
<dd><p>Returns the empty string.</p></dd>
</dl>
<div w-nodev>
<dl>
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-appCodeName">appCodeName</code></dfn></dt>
<dd><p>Must return the string "<code data-x="">Mozilla</code>".</p></dd>
<!-- appMinorVersion: IE only. In IE8b1, returns " Beta" (with the space) -->
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-appName">appName</code></dfn></dt>
<dd><p>Must return the string "<code data-x="">Netscape</code>".</p></dd>
<dt><dfn attribute for="NavigatorID"><code
data-x="dom-navigator-appVersion">appVersion</code></dfn></dt>
<dd>
<p>Must return the appropriate string that starts with "<code data-x="">5.0 (</code>", as
follows:</p>
<p>Let <var>trail</var> be the substring of <span data-x="default-user-agent-value">default
`<code>User-Agent</code>` value</span> that follows the "<code data-x="">Mozilla/</code>"
prefix.</p>
<!-- Fetch doesn't actually require the value to start with "Mozilla/5.0 (". -->
<dl class="switch"> <dt>If the <span data-x="concept-navigator-compatibility-mode">navigator
compatibility mode</span> is <i>Chrome</i> or <i>WebKit</i></dt>
<dd><p>Return <var>trail</var>.</p></dd>
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>Gecko</i></dt>
<dd>
<p>If <var>trail</var> starts with "<code data-x="">5.0 (Windows</code>", then return "<code
data-x="">5.0 (Windows)</code>".</p>
<p>Otherwise, return the prefix of <var>trail</var> up to but not including the first U+003B
(;), concatenated with the character U+0029 RIGHT PARENTHESIS. For example, "<code
data-x="">5.0 (Macintosh)</code>", "<code data-x="">5.0 (Android 10)</code>", or "<code
data-x="">5.0 (X11)</code>".</p> <!-- Unclear if Gecko mode returning a shorter string that
doesn't contain the whole trail is needed for Web compat. -->
</dd>
</dl>
</dd>
<!-- buildID: Mozilla only -->
<!-- oscpu: Mozilla only -->
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-platform">platform</code></dfn></dt>
<dd><p>Must return a string representing the platform on which the
browser is executing (e.g. "<code data-x="">MacIntel</code>", "<code data-x="">Win32</code>",
"<code data-x="">Linux x86_64</code>", "<code data-x="">Linux armv81</code>") or, for privacy and
compatibility, a string that is commonly returned on another platform.</p></dd>
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-product">product</code></dfn></dt>
<dd><p>Must return the string "<code data-x="">Gecko</code>".</p></dd>
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-productSub">productSub</code></dfn></dt>
<dd>
<p>Must return the appropriate string from the following list:</p>
<dl class="switch">
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>Chrome</i> or <i>WebKit</i></dt>
<dd><p>The string "<code data-x="">20030107</code>".</p></dd>
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>Gecko</i></dt>
<dd><p>The string "<code data-x="">20100101</code>".</p></dd>
</dl>
</dd>
<!-- securityPolicy: Mozilla only; always returns "" -->
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-userAgent">userAgent</code></dfn></dt>
<dd><p>Must return the <span data-x="default-user-agent-value">default `<code>User-Agent</code>`
value</span>.</p></dd>
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-vendor">vendor</code></dfn></dt>
<dd>
<p>Must return the appropriate string from the following list:</p>
<dl class="switch">
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>Chrome</i></dt>
<dd><p>The string "<code data-x="">Google Inc.</code>".</p></dd>
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>Gecko</i></dt>
<dd><p>The empty string.</p></dd>
<dt>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility
mode</span> is <i>WebKit</i></dt>
<dd><p>The string "<code data-x="">Apple Computer, Inc.</code>".</p></dd>
</dl>
</dd>
<dt><dfn attribute for="NavigatorID"><code data-x="dom-navigator-vendorSub">vendorSub</code></dfn></dt>
<dd><p>Must return the empty string.</p></dd>
</dl>
<p>If the <span data-x="concept-navigator-compatibility-mode">navigator compatibility mode</span>
is <i>Gecko</i>, then the user agent must also support the following partial interface:</p>
<pre><code class="idl">partial interface mixin <span id="NavigatorID-partial">NavigatorID</span> {
[Exposed=Window] boolean <span data-x="dom-navigator-taintEnabled">taintEnabled</span>(); // constant false
[Exposed=Window] readonly attribute DOMString <span data-x="dom-navigator-oscpu">oscpu</span>;
};</code></pre>
<p>The <dfn method for="NavigatorID"><code
data-x="dom-navigator-taintEnabled">taintEnabled()</code></dfn> method must return false.</p>
<p>The <dfn attribute for="NavigatorID"><code data-x="dom-navigator-oscpu">oscpu</code></dfn> attribute's getter must return
either the empty string or a string representing the platform on which the browser is executing,
e.g. "<code data-x="">Windows NT 10.0; Win64; x64</code>", "<code data-x="">Linux
x86_64</code>".</p>
<!-- similar paragraph in next section -->
<p class="warning">
<!--INSERT TRACKING-->
Any information in this API that varies from user to user can be used to profile the user. In
fact, if enough such information is available, a user can actually be uniquely identified. For
this reason, user agent implementers are strongly urged to include as little information in this
API as possible.</p>
</div>
<!-- next section refers to previous section as "previous section" -->
<h5>Language preferences</h5>
<pre><code class="idl">interface mixin <dfn interface>NavigatorLanguage</dfn> {
readonly attribute DOMString <span data-x="dom-navigator-language">language</span>;
readonly attribute FrozenArray<DOMString> <span data-x="dom-navigator-languages">languages</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-language">language</span></code></dt>
<dd><p>Returns a language tag representing the user's preferred language.</p></dd>
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-languages">languages</span></code></dt>
<dd>
<p>Returns an array of language tags representing the user's preferred languages, with the most
preferred language first.</p>
<p>The most preferred language is the one returned by <code
data-x="dom-navigator-language">navigator.language</code>.</p>
</dd>
</dl>
<p class="note">A <code data-x="event-languagechange">languagechange</code> event is fired at the
<code>Window</code> or <code>WorkerGlobalScope</code> object when the user agent's understanding
of what the user's preferred languages are changes.</p>
<div w-nodev>
<dl>
<!--
<dt><dfn><code data-x="dom-navigator-browserLanguage">browserLanguage</code></dfn></dt> <!- - Opera and IE only - ->
<dd><p>Must return a language tag representing either <span>a plausible language</span> or the
language the browser uses in its interface.</p></dd>
<dt><dfn><code data-x="dom-navigator-userLanguage">userLanguage</code></dfn></dt> <!- - Opera and IE only - ->
-->
<!-- at time of testing, this was supported by Opera, Safari, and Mozilla only -->
<dt><dfn attribute for="NavigatorLanguage"><code
data-x="dom-navigator-language">language</code></dfn></dt> <dd><p>Must return a valid BCP 47
language tag representing either <span>a plausible language</span> or the user's most preferred
language. <ref>BCP47</ref></p></dd>
<dt><dfn attribute for="NavigatorLanguage"><code data-x="dom-navigator-languages">languages</code></dfn></dt>
<dd>
<p>Must return a <span>frozen array</span> of valid BCP 47 language tags representing either one
or more <span data-x="a plausible language">plausible languages</span>, or the user's preferred
languages, ordered by preference with the most preferred language first. The same object must be
returned until the user agent needs to return different values, or values in a different order.
<ref>BCP47</ref></p>
<p>Whenever the user agent needs to make the <code
data-x="dom-navigator-languages">navigator.languages</code> attribute of a <code>Window</code>
or <code>WorkerGlobalScope</code> object <var>global</var> return a new set of language tags,
the user agent must <span>queue a global task</span> on the <span>DOM manipulation task
source</span> given <var>global</var> to <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-languagechange">languagechange</code> at <var>global</var>, and wait
until that task begins to be executed before actually returning a new value.</p>
</dd>
</dl>
<p>To determine <dfn>a plausible language</dfn>, the user agent should bear in mind the following:</p>
<ul>
<li>
<!--INSERT TRACKING-->
Any information in this API that varies from user to user can be used to profile or identify the
user.</li>
<li>If the user is not using a service that obfuscates the user's point of origin (e.g. the Tor
anonymity network), then the value that is least likely to distinguish the user from other users
with similar origins (e.g. from the same IP address block) is the language used by the majority
of such users. <ref>TOR</ref></li>
<li>If the user is using an anonymizing service, then the value "<code data-x="">en-US</code>" is
suggested; if all users of the service use that same value, that reduces the possibility of
distinguishing the users from each other.</li>
</ul>
<p>
<!--INSERT TRACKING-->
To avoid introducing any more fingerprinting vectors, user agents should use the same list for the
APIs defined in this function as for the HTTP `<code
data-x="http-accept-language">Accept-Language</code>` header.</p>
</div>
<h5 id="navigator.online"><span id="browser-state"></span>Browser state</h5>
<pre><code class="idl">interface mixin <dfn interface>NavigatorOnLine</dfn> {
readonly attribute boolean <span data-x="dom-navigator-onLine">onLine</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-onLine">onLine</span></code></dt>
<dd>
<p>Returns false if the user agent is definitely offline (disconnected from the network).
Returns true if the user agent might be online.</p>
<p>The events <code data-x="event-online">online</code> and <code
data-x="event-offline">offline</code> are fired when the value of this attribute changes.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="NavigatorOnLine"><code
data-x="dom-navigator-onLine">onLine</code></dfn> attribute must return false if the user agent
will not contact the network when the user follows links or when a script requests a remote page
(or knows that such an attempt would fail), and must return true otherwise.</p>
<p>When the value that would be returned by the <code
data-x="dom-navigator-onLine">navigator.onLine</code> attribute of a <code>Window</code> or
<code>WorkerGlobalScope</code> <var>global</var> changes from true to false, the user agent must
<span>queue a global task</span> on the <span>networking task source</span> given
<var>global</var> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-offline">offline</code> at <var>global</var>.</p>
<p>On the other hand, when the value that would be returned by the <code
data-x="dom-navigator-onLine">navigator.onLine</code> attribute of a <code>Window</code> or
<code>WorkerGlobalScope</code> <var>global</var> changes from false to true, the user agent must
<span>queue a global task</span> on the <span>networking task source</span> given
<var>global</var> to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-online">online</code> at the <code>Window</code> or <code>WorkerGlobalScope</code>
object.</p>
</div>
<p class="note">This attribute is inherently unreliable. A computer can be connected to a network
without having Internet access.</p>
<div class="example">
<p>In this example, an indicator is updated as the browser goes online and offline.</p>
<pre><code class="html"><!DOCTYPE HTML>
<html lang="en">
<head>
<title>Online status</title>
<script>
function updateIndicator() {
document.getElementById('indicator').textContent = navigator.onLine ? 'online' : 'offline';
}
</script>
</head>
<body onload="updateIndicator()" ononline="updateIndicator()" onoffline="updateIndicator()">
<p>The network is: <span id="indicator">(state unknown)</span>
</body>
</html></code></pre>
</div>
<h5 id="custom-handlers">Custom scheme handlers: the <code data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler()</code> method</h5>
<pre><code class="idl">interface mixin <dfn interface>NavigatorContentUtils</dfn> {
[SecureContext] undefined <span data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler</span>(DOMString scheme, USVString url);
[SecureContext] undefined <span data-x="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler</span>(DOMString scheme, USVString url);
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler</span>(<var>scheme</var>, <var>url</var>)</code></dt>
<dd>
<p>Registers a handler for <var>scheme</var> at <var>url</var>. For example, an online telephone
messaging service could register itself as a handler of the <code data-x="sms
protocol">sms:</code> scheme, so that if the user clicks on such a link, they are given the
opportunity to use that web site. <ref>SMS</ref></p>
<p>The string "<code data-x="">%s</code>" in <var>url</var> is used as a placeholder for where
to put the URL of the content to be handled.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the user
agent blocks the registration (this might happen if trying to register as a handler for "<code
data-x="">http</code>", for instance).</p>
<p>Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if the "<code
data-x="">%s</code>" string is missing in <var>url</var>.</p>
</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler</span>(<var>scheme</var>, <var>url</var>)</code></dt>
<dd>
<p>Unregisters the handler given by the arguments.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the user
agent blocks the deregistration (this might happen if with invalid schemes, for instance).</p>
<p>Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if the "<code
data-x="">%s</code>" string is missing in <var>url</var>.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn method for="NavigatorContentUtils"><code
data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler(<var>scheme</var>,
<var>url</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let (<var>normalizedScheme</var>, <var>normalizedURLString</var>) be the result of running
<span>normalize protocol handler parameters</span> with <var>scheme</var>, <var>url</var>, and
<span>this</span>'s <span>relevant settings object</span>.</p></li>
<li>
<p><span>In parallel</span>: <dfn data-x="protocol-handler-registration" export>register a
protocol handler</dfn> for <var>normalizedScheme</var> and <var>normalizedURLString</var>. User
agents may, within the constraints described, do whatever they like. A user agent could, for
instance, prompt the user and offer the user the opportunity to add the site to a shortlist of
handlers, or make the handlers their default, or cancel the request. User agents could also
silently collect the information, providing it only when relevant to the user.</p>
<p>User agents should keep track of which sites have registered handlers (even if the user has
declined such registrations) so that the user is not repeatedly prompted with the same
request.</p>
<p>If the <span><code
data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler()</code> automation
mode</span> of <span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span> is not "<dfn><code
data-x="rph-automation-mode-none">none</code></dfn>", the user agent should first verify that it
is in an automation context (see <span>WebDriver's security considerations</span>). The user
agent should then bypass the above communication of information and gathering of user consent,
and instead do the following based on the value of the <span><code
data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler()</code> automation
mode</span>:</p>
<dl>
<dt>"<dfn data-x="rph-automation-mode-auto-accept"><code>autoAccept</code></dfn>"</dt>
<dd><p>Act as if the user has seen the registration details and accepted the request.</p></dd>
<dt>"<dfn data-x="rph-automation-mode-auto-reject"><code>autoReject</code></dfn>"</dt>
<dd><p>Act as if the user has seen the registration details and rejected the request.</p></dd>
</dl>
<p>When the <dfn export data-x="protocol-handler-invocation" data-lt="invoke a protocol
handler">user agent uses this handler</dfn> for a <span>URL</span> <var>inputURL</var>:</p>
<ol>
<li><p><span>Assert</span>: <var>inputURL</var>'s <span
data-x="concept-url-scheme">scheme</span> is <var>normalizedScheme</var>.</p></li>
<li><p><span data-x="set the username">Set the username</span> given <var>inputURL</var> and
the empty string.</p></li>
<li><p><span data-x="set the password">Set the password</span> given <var>inputURL</var> and
the empty string.</p></li>
<li><p>Let <var>inputURLString</var> be the <span
data-x="concept-url-serializer">serialization</span> of <var>inputURL</var>.</p></li>
<li><p>Let <var>encodedURL</var> be the result of running <span>UTF-8 percent-encode</span> on
<var>inputURLString</var> using the <span>component percent-encode set</span>.</p></li>
<li><p>Let <var>handlerURLString</var> be <var>normalizedURLString</var>.</p></li>
<li><p>Replace the first instance of "<code data-x="">%s</code>" in <var>handlerURLString</var>
with <var>encodedURL</var>.</p></li>
<li><p>Let <var>resultURL</var> be the result of <span data-x="URL parser">parsing</span>
<var>handlerURLString</var>.</p></li>
<li><p><span>Navigate</span><!--DONAV user--> an appropriate <span>navigable</span> to
<var>resultURL</var>.</p></li>
</ol>
<div class="example">
<p>If the user had visited a site at <code data-x="">https://example.com/</code> that made the
following call:</p>
<pre><code class="js">navigator.registerProtocolHandler('web+soup', 'soup?url=%s')</code></pre>
<p>...and then, much later, while visiting <code data-x="">https://www.example.net/</code>,
clicked on a link such as:</p>
<pre><code class="html"><a href="web+soup:chicken-kïwi">Download our Chicken Kïwi soup!</a></code></pre>
<p>...then the UA might navigate to the following URL:</p>
<pre>https://example.com/soup?url=web+soup:chicken-k%C3%AFwi</pre>
<p>This site could then do whatever it is that it does with soup (synthesize it and ship it to
the user, or whatever).</p>
</div>
<p>This does not define when the handler is used. To some extent, the <span
data-x="navigate">processing model for navigating across documents</span> defines some cases
where it is relevant, but in general user agents may use this information wherever they would
otherwise consider handing schemes to native plugins or helper applications.</p>
</li>
</ol>
<p>The <dfn method for="NavigatorContentUtils"><code
data-x="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler(<var>scheme</var>,
<var>url</var>)</code></dfn> method steps are:
<ol>
<li><p>Let (<var>normalizedScheme</var>, <var>normalizedURLString</var>) be the result of running
<span>normalize protocol handler parameters</span> with <var>scheme</var>, <var>url</var>, and
<span>this</span>'s <span>relevant settings object</span>.</p></li>
<li><p><span>In parallel</span>: unregister the handler described by <var>normalizedScheme</var>
and <var>normalizedURLString</var>.</p></li>
</ol>
<hr>
<p>To <dfn export>normalize protocol handler parameters</dfn>, given a string <var>scheme</var>, a
string <var>url</var>, and an <span>environment settings object</span> <var>environment</var>, run
these steps:</p>
<ol>
<li><p>Set <var>scheme</var> to <var>scheme</var>, <span>converted to ASCII
lowercase</span>.</p></li>
<li>
<p>If <var>scheme</var> is neither a <span>safelisted scheme</span> nor a string starting with
"<code data-x="">web+</code>" followed by one or more <span data-x="ASCII lower alpha">ASCII
lower alphas</span>, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p>
<p class="note">This means that including a colon in <var>scheme</var> (as in "<code
data-x="">mailto:</code>") will throw.</p>
<p>The following schemes are the <dfn data-x="safelisted scheme" export>safelisted
schemes</dfn>:</p>
<ul class="brief">
<li><code data-x="">bitcoin</code></li> <!-- https://en.bitcoin.it/wiki/BIP_0021 -->
<li><code data-x="">ftp</code></li>
<li><code data-x="">ftps</code></li>
<li><code data-x="">geo</code></li>
<li><code data-x="">im</code></li>
<li><code data-x="">irc</code></li>
<li><code data-x="">ircs</code></li>
<li><code data-x="">magnet</code></li>
<li><code data-x="">mailto</code></li>
<li><code data-x="">matrix</code></li>
<li><code data-x="">mms</code></li>
<li><code data-x="">news</code></li>
<li><code data-x="">nntp</code></li>
<li><code data-x="">openpgp4fpr</code></li>
<li><code data-x="">sftp</code></li>
<li><code data-x="">sip</code></li>
<li><code data-x="">sms</code></li>
<li><code data-x="">smsto</code></li>
<li><code data-x="">ssh</code></li>
<li><code data-x="">tel</code></li>
<li><code data-x="">urn</code></li>
<li><code data-x="">webcal</code></li>
<li><code data-x="">wtai</code></li>
<li><code data-x="">xmpp</code></li>
</ul>
<p class="note">This list can be changed. If there are schemes that ought to be added, please
send feedback.</p>
</li>
<li><p>If <var>url</var> does not contain "<code data-x="">%s</code>", then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to <var>environment</var>.</p></li>
<li>
<p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p>
<p class="note">This is forcibly the case if the <code data-x="">%s</code> placeholder is in the
host or port of the URL.</p>
</li>
<li><p>If <var>urlRecord</var>'s <span data-x="concept-url-scheme">scheme</span> is not an
<span>HTTP(S) scheme</span> or <var>urlRecord</var>'s <span
data-x="concept-url-origin">origin</span> is not <span>same origin</span> with
<var>environment</var>'s <span data-x="concept-settings-object-origin">origin</span>, then throw
a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p><span>Assert</span>: the result of <span>Is url potentially trustworthy?</span> given
<var>urlRecord</var> is "<code data-x="">Potentially Trustworthy</code>".</p>
<p class="note">Because <span>normalize protocol handler parameters</span> is run within a
<span>secure context</span>, this is implied by the <span>same origin</span> condition.</p>
</li>
<li>
<p>Return (<var>scheme</var>, <var>urlRecord</var>).</p>
<p class="note">The <span data-x="concept-url-serializer">serialization</span> of
<var>urlRecord</var> will by definition not be a <span>valid URL string</span> as it includes
the string "<code data-x="">%s</code>" which is not a valid component in a URL.</p>
</li>
</ol>
<h6>Security and privacy</h6>
<p>Custom scheme handlers can introduce a number of concerns, in particular privacy concerns.</p>
<p><strong>Hijacking all web usage.</strong> User agents should not allow schemes that are key to
its normal operation, such as an <span>HTTP(S) scheme</span>, to be rerouted through third-party
sites. This would allow a user's activities to be trivially tracked, and would allow user
information, even in secure connections, to be collected.</p>
<p><strong>Hijacking defaults.</strong> User agents are strongly urged to not automatically change
any defaults, as this could lead the user to send data to remote hosts that the user is not
expecting. New handlers registering themselves should never automatically cause those sites to be
used.</p>
<p><strong>Registration spamming.</strong> User agents should consider the possibility that a site
will attempt to register a large number of handlers, possibly from multiple domains (e.g., by
redirecting through a series of pages each on a different domain, and each registering a handler
for <code data-x="">web+spam:</code> — analogous practices abusing other web browser
features have been used by pornography web sites for many years). User agents should gracefully
handle such hostile attempts, protecting the user.</p>
<p><strong>Hostile handler metadata.</strong> User agents should protect against typical attacks
against strings embedded in their interface, for example ensuring that markup or escape characters
in such strings are not executed, that null bytes are properly handled, that over-long strings do
not cause crashes or buffer overruns, and so forth.</p>
<p><strong>Leaking private data.</strong> Web page authors may reference a custom scheme
handler using URL data considered private. They might do so with the expectation that the user's
choice of handler points to a page inside the organization, ensuring that sensitive data will not
be exposed to third parties. However, a user may have registered a handler pointing to an
external site, resulting in a data leak to that third party. Implementers might wish to consider
allowing administrators to disable custom handlers on certain subdomains, content types, or
schemes.</p>
<p><strong>Interface interference.</strong> User agents should be prepared to handle intentionally
long arguments to the methods. For example, if the user interface exposed consists of an "accept"
button and a "deny" button, with the "accept" binding containing the name of the handler, it's
important that a long name not cause the "deny" button to be pushed off the screen.</p>
<h6><dfn id="rph-user-agent-automation">User agent automation</dfn></h6>
<p>Each <code>Document</code> has a <dfn><code
data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler()</code> automation
mode</dfn>. It defaults to "<code data-x="rph-automation-mode-none">none</code>", but it also can
be either "<code data-x="rph-automation-mode-auto-accept">autoAccept</code>" or "<code
data-x="rph-automation-mode-auto-reject">autoReject</code>".</p>
<p>For the purposes of user agent automation and website testing, this standard defines <dfn
data-x="set-rph-registration-mode">Set RPH Registration Mode</dfn> WebDriver <span>extension
command</span>. It instructs the user agent to place a <code>Document</code> into a mode where it
will automatically simulate a user either accepting or rejecting and registration confirmation
prompt dialog.</p>
<table class="data">
<thead>
<tr>
<th>HTTP Method
<th>URI Template
<tbody>
<tr>
<td>`<code data-x="">POST</code>`
<td><code data-x="">/session/{session id}/custom-handlers/set-mode</code>
</table>
<p>The <span>remote end steps</span> are:</p>
<ol>
<li><p>If <var>parameters</var> is not a JSON Object, return a <span>WebDriver error</span> with
<span>WebDriver error code</span> <span>invalid argument</span>.</p></li>
<li><p>Let <var>mode</var> be the result of <span>getting a property</span> named "<code
data-x="">mode</code>" from <var>parameters</var>.</p></li>
<li><p>If <var>mode</var> is not "<code
data-x="rph-automation-mode-auto-accept">autoAccept</code>", "<code
data-x="rph-automation-mode-auto-reject">autoReject</code>", or "<code
data-x="rph-automation-mode-none">none</code>", return a <span>WebDriver error</span> with
<span>WebDriver error code</span> <span>invalid argument</span>.</p></li>
<li><p>Let <var>document</var> be the <span data-x="webdriver-current-browsing-context">current
browsing context</span>'s <span>active document</span>.</p></li>
<li><p>Set <var>document</var>'s <span><code
data-x="dom-navigator-registerProtocolHandler">registerProtocolHandler()</code> automation
mode</span> to <var>mode</var>.</p></li>
<li><p>Return <span data-x="success-value">success</span> with data null.</p></li>
</ol>
</div>
<h5>Cookies</h5>
<pre><code class="idl">interface mixin <dfn interface>NavigatorCookies</dfn> {
readonly attribute boolean <span data-x="dom-navigator-cookieEnabled">cookieEnabled</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-cookieEnabled">cookieEnabled</span></code></dt>
<dd><p>Returns false if setting a cookie will be ignored, and true otherwise.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="NavigatorCookies"><code
data-x="dom-navigator-cookieEnabled">cookieEnabled</code></dfn> attribute must return true if the
user agent attempts to handle cookies according to <cite>HTTP State Management Mechanism</cite>,
and false if it ignores cookie change requests. <ref>COOKIES</ref></p>
</div>
<h5>PDF viewing support</h5>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-pdfViewerEnabled">pdfViewerEnabled</span></code></dt>
<dd><p>Returns true if the user agent supports inline viewing of PDF files when <span
data-x="navigate">navigating</span> to them, or false otherwise. In the latter case, PDF files
will be handled by <span data-x="hand-off to external software">external
software</span>.</p></dd>
</dl>
<pre><code class="idl">interface mixin <dfn interface>NavigatorPlugins</dfn> {
[SameObject] readonly attribute <span>PluginArray</span> <span data-x="dom-navigator-plugins">plugins</span>;
[SameObject] readonly attribute <span>MimeTypeArray</span> <span data-x="dom-navigator-mimeTypes">mimeTypes</span>;
boolean <span data-x="dom-navigator-javaEnabled">javaEnabled</span>();
readonly attribute boolean <span data-x="dom-navigator-pdfViewerEnabled">pdfViewerEnabled</span>;
};
[Exposed=Window,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface>PluginArray</dfn> {
undefined <span data-x="dom-PluginArray-refresh">refresh</span>();
readonly attribute unsigned long <span data-x="dom-PluginArray-length">length</span>;
getter <span>Plugin</span>? <span data-x="dom-PluginArray-item">item</span>(unsigned long index);
getter <span>Plugin</span>? <span data-x="dom-PluginArray-namedItem">namedItem</span>(DOMString name);
};
[Exposed=Window,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface>MimeTypeArray</dfn> {
readonly attribute unsigned long <span data-x="dom-MimeTypeArray-length">length</span>;
getter <span>MimeType</span>? <span data-x="dom-MimeTypeArray-item">item</span>(unsigned long index);
getter <span>MimeType</span>? <span data-x="dom-MimeTypeArray-namedItem">namedItem</span>(DOMString name);
};
[Exposed=Window,
<span>LegacyUnenumerableNamedProperties</span>]
interface <dfn interface data-x="dom-Plugin">Plugin</dfn> {
readonly attribute DOMString <span data-x="dom-Plugin-name">name</span>;
readonly attribute DOMString <span data-x="dom-Plugin-description">description</span>;
readonly attribute DOMString <span data-x="dom-Plugin-filename">filename</span>;
readonly attribute unsigned long <span data-x="dom-Plugin-length">length</span>;
getter <span>MimeType</span>? <span data-x="dom-Plugin-item">item</span>(unsigned long index);
getter <span>MimeType</span>? <span data-x="dom-Plugin-namedItem">namedItem</span>(DOMString name);
};
[Exposed=Window]
interface <dfn interface>MimeType</dfn> {
readonly attribute DOMString <span data-x="dom-MimeType-type">type</span>;
readonly attribute DOMString <span data-x="dom-MimeType-description">description</span>;
readonly attribute DOMString <span data-x="dom-MimeType-suffixes">suffixes</span>;
readonly attribute <span>Plugin</span> <span data-x="dom-MimeType-enabledPlugin">enabledPlugin</span>;
};</code></pre>
<div w-nodev>
<p>Although these days detecting PDF viewer support can be done via <code
data-x="dom-navigator-pdfViewerEnabled">navigator.pdfViewerEnabled</code>, for historical reasons,
there are a number of complex and intertwined interfaces that provide the same capability, which
legacy code relies on. This section specifies both the simple modern variant and the complicated
historical one.</p>
<!-- INSERT TRACKING -->
<p>Each user agent has a <dfn>PDF viewer supported</dfn> boolean, whose value is
<span>implementation-defined</span> (and might vary according to user preferences).</p>
<p class="note">This value also impacts the <span data-x="navigate">navigation</span> processing
model.</p>
<hr>
<p>Each <code>Window</code> object has a <dfn>PDF viewer plugin objects</dfn> list. If the user
agent's <span>PDF viewer supported</span> is false, then it is the empty list. Otherwise, it is a
list containing five <code data-x="dom-Plugin">Plugin</code> objects, whose <span
data-x="concept-Plugin-name">names</span> are, respectively:</p>
<ol class="brief" start="0">
<li>"<code data-x="">PDF Viewer</code>"</li>
<li>"<code data-x="">Chrome PDF Viewer</code>"</li>
<li>"<code data-x="">Chromium PDF Viewer</code>"</li>
<li>"<code data-x="">Microsoft Edge PDF Viewer</code>"</li>
<li>"<code data-x="">WebKit built-in PDF</code>"</li>
</ol>
<p>The values of the above list form the <dfn>PDF viewer plugin names</dfn> list.</p>
<p class="note">These names were chosen based on evidence of what websites historically search
for, and thus what is necessary for user agents to expose in order to maintain compatibility with
existing content. They are ordered alphabetically. The "<code data-x="">PDF Viewer</code>" name
was then inserted in the 0th position so that the <code
data-x="dom-MimeType-enabledPlugin">enabledPlugin</code> getter could point to a generic plugin
name.</p>
<p>Each <code>Window</code> object has a <dfn>PDF viewer mime type objects</dfn> list. If the user
agent's <span>PDF viewer supported</span> is false, then it is the empty list. Otherwise, it is a
list containing two <code>MimeType</code> objects, whose <span
data-x="concept-MimeType-type">types</span> are, respectively:</p>
<ol class="brief" start="0">
<li>"<code data-x="">application/pdf</code>"</li>
<li>"<code data-x="">text/pdf</code>"</li>
</ol>
<p>The values of the above list form the <dfn>PDF viewer mime types</dfn> list.</p>
<hr>
<p>Each <code>NavigatorPlugins</code> object has a <dfn>plugins array</dfn>, which is a new
<code>PluginArray</code>, and a <dfn>mime types array</dfn>, which is a new
<code>MimeTypeArray</code>.</p>
<p>The <code>NavigatorPlugins</code> mixin's <dfn attribute for="NavigatorPlugins"><code
data-x="dom-navigator-plugins">plugins</code></dfn> getter steps are to return <span>this</span>'s
<span>plugins array</span>.</p>
<p>The <code>NavigatorPlugins</code> mixin's <dfn attribute for="NavigatorPlugins"><code
data-x="dom-navigator-mimeTypes">mimeTypes</code></dfn> getter steps are to return
<span>this</span>'s <span>mime types array</span>.</p>
<p>The <code>NavigatorPlugins</code> mixin's <dfn method for="NavigatorPlugins"><code
data-x="dom-navigator-javaEnabled">javaEnabled()</code></dfn> method steps are to return false.</p>
<p>The <code>NavigatorPlugins</code> mixin's <dfn attribute for="NavigatorPlugins"><code
data-x="dom-navigator-pdfViewerEnabled">pdfViewerEnabled</code></dfn> getter steps are to return
the user agent's <span>PDF viewer supported</span>.</p>
<hr>
<p>The <code>PluginArray</code> interface <span data-x="support named properties">supports named
properties</span>. If the user agent's <span>PDF viewer supported</span> is true, then they are
the <span>PDF viewer plugin names</span>. Otherwise, they are the empty list.</p>
<p>The <code>PluginArray</code> interface's <dfn method for="PluginArray"><code
data-x="dom-PluginArray-namedItem">namedItem(<var>name</var>)</code></dfn> method steps are:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <code data-x="dom-Plugin">Plugin</code>
<var>plugin</var> of <span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer
plugin objects</span>: if <var>plugin</var>'s <span data-x="concept-Plugin-name">name</span> is
<var>name</var>, then return <var>plugin</var>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code>PluginArray</code> interface <span>supports indexed properties</span>. The
<span>supported property indices</span> are the <span>indices</span> of <span>this</span>'s
<span>relevant global object</span>'s <span>PDF viewer plugin objects</span>.</p>
<p>The <code>PluginArray</code> interface's <dfn method for="PluginArray"><code
data-x="dom-PluginArray-item">item(<var>index</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>plugins</var> be <span>this</span>'s <span>relevant global object</span>'s
<span>PDF viewer plugin objects</span>.</p></li>
<li><p>If <var>index</var> < <var>plugins</var>'s <span data-x="list size">size</span>, then
return <var>plugins</var>[<var>index</var>].</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code>PluginArray</code> interface's <dfn attribute for="PluginArray"><code
data-x="dom-PluginArray-length">length</code></dfn> getter steps are to return <span>this</span>'s
<span>relevant global object</span>'s <span>PDF viewer plugin objects</span>'s <span
data-x="list size">size</span>.</p>
<p>The <code>PluginArray</code> interface's <dfn method for="PluginArray"><code
data-x="dom-PluginArray-refresh">refresh()</code></dfn> method steps are to do nothing.</p>
<hr>
<p>The <code>MimeTypeArray</code> interface <span data-x="support named properties">supports named
properties</span>. If the user agent's <span>PDF viewer supported</span> is true, then they are
the <span>PDF viewer mime types</span>. Otherwise, they are the empty list.</p>
<p>The <code>MimeTypeArray</code> interface's <dfn method for="MimeTypeArray"><code
data-x="dom-MimeTypeArray-namedItem">namedItem(<var>name</var>)</code></dfn> method steps are:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <code>MimeType</code> <var>mimeType</var> of
<span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer mime type
objects</span>: if <var>mimeType</var>'s <span data-x="concept-MimeType-type">type</span> is
<var>name</var>, then return <var>mimeType</var>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code>MimeTypeArray</code> interface <span>supports indexed properties</span>. The
<span>supported property indices</span> are the <span>indices</span> of <span>this</span>'s
<span>relevant global object</span>'s <span>PDF viewer mime type objects</span>.</p>
<p>The <code>MimeTypeArray</code> interface's <dfn method for="MimeTypeArray"><code
data-x="dom-MimeTypeArray-item">item(<var>index</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>mimeTypes</var> be <span>this</span>'s <span>relevant global object</span>'s
<span>PDF viewer mime type objects</span>.</p></li>
<li><p>If <var>index</var> < <var>mimeTypes</var>'s <span data-x="list size">size</span>, then
return <var>mimeTypes</var>[<var>index</var>].</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code>MimeTypeArray</code> interface's <dfn attribute for="MimeTypeArray"><code
data-x="dom-MimeTypeArray-length">length</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer mime type
objects</span>'s <span data-x="list size">size</span>.</p>
<hr>
<p>Each <code data-x="dom-Plugin">Plugin</code> object has a <dfn
data-x="concept-Plugin-name">name</dfn>, which is set when the object is created.</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn attribute for="Plugin"><code
data-x="dom-Plugin-name">name</code></dfn> getter steps are to return <span>this</span>'s <span
data-x="concept-Plugin-name">name</span>.</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn attribute for="Plugin"><code
data-x="dom-Plugin-description">description</code></dfn> getter steps are to return "<code
data-x="">Portable Document Format</code>".</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn attribute for="Plugin"><code
data-x="dom-Plugin-filename">filename</code></dfn> getter steps are to return "<code
data-x="">internal-pdf-viewer</code>".</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface <span data-x="support named
properties">supports named properties</span>. If the user agent's <span>PDF viewer
supported</span> is true, then they are the <span>PDF viewer mime types</span>. Otherwise, they
are the empty list.</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn method for="Plugin"><code
data-x="dom-Plugin-namedItem">namedItem(<var>name</var>)</code></dfn> method steps are:</p>
<ol>
<li><p><span data-x="list iterate">For each</span> <code>MimeType</code> <var>mimeType</var> of
<span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer mime type
objects</span>: if <var>mimeType</var>'s <span data-x="concept-MimeType-type">type</span> is
<var>name</var>, then return <var>mimeType</var>.</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code data-x="dom-Plugin">Plugin</code> interface <span>supports indexed properties</span>.
The <span>supported property indices</span> are the <span>indices</span> of <span>this</span>'s
<span>relevant global object</span>'s <span>PDF viewer mime type objects</span>.</p>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn method for="Plugin"><code
data-x="dom-Plugin-item">item(<var>index</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>mimeTypes</var> be <span>this</span>'s <span>relevant global object</span>'s
<span>PDF viewer mime type objects</span>.</p></li>
<li><p>If <var>index</var> < <var>mimeTypes</var>'s <span data-x="list size">size</span>, then
return <var>mimeTypes</var>[<var>index</var>].</p></li>
<li><p>Return null.</p></li>
</ol>
<p>The <code data-x="dom-Plugin">Plugin</code> interface's <dfn attribute for="Plugin"><code
data-x="dom-Plugin-length">length</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer mime type
objects</span>'s <span data-x="list size">size</span>.</p>
<hr>
<p>Each <code>MimeType</code> object has a <dfn data-x="concept-MimeType-type">type</dfn>, which
is set when the object is created.</p>
<p>The <code>MimeType</code> interface's <dfn attribute for="MimeType"><code
data-x="dom-MimeType-type">type</code></dfn> getter steps are to return <span>this</span>'s <span
data-x="concept-MimeType-type">type</span>.</p>
<p>The <code>MimeType</code> interface's <dfn attribute for="MimeType"><code
data-x="dom-MimeType-description">description</code></dfn> getter steps are to return "<code
data-x="">Portable Document Format</code>".</p>
<p>The <code>MimeType</code> interface's <dfn attribute for="MimeType"><code
data-x="dom-MimeType-suffixes">suffixes</code></dfn> getter steps are to return "<code
data-x="">pdf</code>".</p>
<p>The <code>MimeType</code> interface's <dfn attribute for="MimeType"><code
data-x="dom-MimeType-enabledPlugin">enabledPlugin</code></dfn> getter steps are to return
<span>this</span>'s <span>relevant global object</span>'s <span>PDF viewer plugin
objects</span>[0] (i.e., the generic "<code data-x="">PDF Viewer</code>" one).</p>
</div>
<h3 split-filename="imagebitmap-and-animations">Images</h3>
<pre><code class="idl">[Exposed=(Window,Worker), <span>Serializable</span>, <span>Transferable</span>]
interface <dfn interface>ImageBitmap</dfn> {
readonly attribute unsigned long <span data-x="dom-ImageBitmap-width">width</span>;
readonly attribute unsigned long <span data-x="dom-ImageBitmap-height">height</span>;
undefined <span data-x="dom-ImageBitmap-close">close</span>();
};
typedef (<span>CanvasImageSource</span> or
<span>Blob</span> or
<span>ImageData</span>) <dfn typedef>ImageBitmapSource</dfn>;
enum <dfn enum>ImageOrientation</dfn> { "<span data-x="dom-ImageOrientation-from-image">from-image</span>", "<span data-x="dom-ImageOrientation-flipY">flipY</span>" };
enum <dfn enum>PremultiplyAlpha</dfn> { "<span data-x="dom-PremultiplyAlpha-none">none</span>", "<span data-x="dom-PremultiplyAlpha-premultiply">premultiply</span>", "<span data-x="dom-PremultiplyAlpha-default">default</span>" };
enum <dfn enum>ColorSpaceConversion</dfn> { "<span data-x="dom-ColorSpaceConversion-none">none</span>", "<span data-x="dom-ColorSpaceConversion-default">default</span>" };
enum <dfn enum>ResizeQuality</dfn> { "<span data-x="dom-ResizeQuality-pixelated">pixelated</span>", "<span data-x="dom-ResizeQuality-low">low</span>", "<span data-x="dom-ResizeQuality-medium">medium</span>", "<span data-x="dom-ResizeQuality-high">high</span>" };
dictionary <dfn dictionary>ImageBitmapOptions</dfn> {
<span>ImageOrientation</span> <span data-x="dom-ImageBitmapOptions-imageOrientation">imageOrientation</span> = "<span data-x="dom-ImageOrientation-from-image">from-image</span>";
<span>PremultiplyAlpha</span> <span data-x="dom-ImageBitmapOptions-premultiplyAlpha">premultiplyAlpha</span> = "<span data-x="dom-PremultiplyAlpha-default">default</span>";
<span>ColorSpaceConversion</span> <span data-x="dom-ImageBitmapOptions-colorSpaceConversion">colorSpaceConversion</span> = "<span data-x="dom-ColorSpaceConversion-default">default</span>";
[EnforceRange] unsigned long <span data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</span>;
[EnforceRange] unsigned long <span data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</span>;
<span>ResizeQuality</span> <span data-x="dom-ImageBitmapOptions-resizeQuality">resizeQuality</span> = "<span data-x="dom-ResizeQuality-low">low</span>";
};</code></pre>
<p>An <code>ImageBitmap</code> object represents a bitmap image that can be painted to a canvas
without undue latency.</p>
<p class="note">The exact judgement of what is undue latency of this is left up to the
implementer, but in general if making use of the bitmap requires network I/O, or even local disk
I/O, then the latency is probably undue; whereas if it only requires a blocking read from a GPU or
system RAM, the latency is probably acceptable.</p>
<dl class="domintro">
<dt><code data-x=""><var>promise</var> = self.<span subdfn data-x="dom-createImageBitmap">createImageBitmap</span>(<var>image</var> [, <var>options</var> ])</code></dt>
<dt><code data-x=""><var>promise</var> = self.<span data-x="dom-createImageBitmap">createImageBitmap</span>(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>options</var> ])</code></dt>
<dd>
<p>Takes <var>image</var>, which can be an <code>img</code> element, an <span>SVG
<code>image</code></span> element, a <code>video</code> element, a <code>canvas</code> element,
a <code>Blob</code> object, an <code>ImageData</code> object, or another
<code>ImageBitmap</code> object, and returns a promise that is resolved when a new
<code>ImageBitmap</code> is created.</p>
<p>If no <code>ImageBitmap</code> object can be constructed, for example because the provided
<var>image</var> data is not actually an image, then the promise is rejected instead.</p>
<p>If <var>sx</var>, <var>sy</var>, <var>sw</var>, and <var>sh</var> arguments are provided, the
source image is cropped to the given pixels, with any pixels missing in the original replaced by
<span>transparent black</span>. These coordinates are in the source image's pixel coordinate
space, <em>not</em> in <span data-x="'px'">CSS pixels</span>.</p>
<p>If <var>options</var> is provided, the <code>ImageBitmap</code> object's bitmap data is
modified according to <var>options</var>. For example, if the <code
data-x="dom-ImageBitmapOptions-premultiplyAlpha">premultiplyAlpha</code> option is set to "<code
data-x="dom-PremultiplyAlpha-premultiply">premultiply</code>", the <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>'s non-alpha color components are
<span data-x="concept-premultiplied-alpha">premultiplied by the alpha component</span>.</p>
<p>Rejects the promise with an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code> if the source image is not in a valid state (e.g., an <code>img</code>
element that hasn't loaded successfully, an <code>ImageBitmap</code> object whose
<span>[[Detached]]</span> internal slot value is true, an <code>ImageData</code> object whose
<code data-x="dom-imagedata-data">data</code> attribute value's [[ViewedArrayBuffer]] internal
slot is detached, or a <code>Blob</code> whose data cannot be interpreted as a bitmap
image).</p>
<p>Rejects the promise with a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code> if the script is not allowed to access the image data of the source
image (e.g. a <code>video</code> that is <span>CORS-cross-origin</span>, or a
<code>canvas</code> being drawn on by a script in a worker from another
<span>origin</span>).</p>
</dd>
<dt><code data-x=""><var>imageBitmap</var>.<span subdfn data-x="dom-ImageBitmap-close">close</span>()</code></dt>
<dd><p>Releases <var>imageBitmap</var>'s underlying <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>.</p></dd>
<dt><code data-x=""><var>imageBitmap</var>.<span subdfn data-x="dom-ImageBitmap-width">width</span></code></dt>
<dd>
<p>Returns the <span>natural width</span> of the image, in <span data-x="'px'">CSS
pixels</span>.</p>
</dd>
<dt><code data-x=""><var>imageBitmap</var>.<span subdfn data-x="dom-ImageBitmap-height">height</span></code></dt>
<dd>
<p>Returns the <span>natural height</span> of the image, in <span data-x="'px'">CSS
pixels</span>.</p>
</dd>
</dl>
<div w-nodev>
<p>An <code>ImageBitmap</code> object whose <span>[[Detached]]</span> internal slot value
is false always has associated <dfn data-x="concept-ImageBitmap-bitmap-data">bitmap data</dfn>,
with a width and a height. However, it is possible for this data to be corrupted. If an
<code>ImageBitmap</code> object's media data can be decoded without errors, it is said to be <dfn
data-x="concept-ImageBitmap-good">fully decodable</dfn>.</p>
<p>An <code>ImageBitmap</code> object's bitmap has an <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag, which indicates whether the
bitmap is tainted by content from a different <span>origin</span>. The flag is initially set to
true and may be changed to false by the steps of <code
data-x="dom-createImageBitmap">createImageBitmap()</code>.</p>
<hr>
<p><code>ImageBitmap</code> objects are <span>serializable objects</span> and <span>transferable
objects</span>.</p>
<p>Their <span>serialization steps</span>, given <var>value</var> and <var>serialized</var>,
are:</p>
<ol>
<li><p>If <var>value</var>'s <span data-x="concept-canvas-origin-clean">origin-clean</span>
flag is not set, then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.
<li><p>Set <var>serialized</var>.[[BitmapData]] to a copy of <var>value</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>.</p></li>
</ol>
<p>Their <span>deserialization steps</span>, given <var>serialized</var>, <var>value</var>,
and <var>targetRealm</var>, are:</p>
<ol>
<li><p>Set <var>value</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>
to <var>serialized</var>.[[BitmapData]].</p></li>
</ol>
<p>Their <span>transfer steps</span>, given <var>value</var> and <var>dataHolder</var>, are:</p>
<ol>
<li><p>If <var>value</var>'s <span data-x="concept-canvas-origin-clean">origin-clean</span>
flag is not set, then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.
<li><p>Set <var>dataHolder</var>.[[BitmapData]] to <var>value</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>.</p></li>
<li><p>Unset <var>value</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span>.</p></li>
</ol>
<p>Their <span>transfer-receiving steps</span>, given <var>dataHolder</var> and <var>value</var>,
are:</p>
<ol>
<li><p>Set <var>value</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>
to <var>dataHolder</var>.[[BitmapData]].</p></li>
</ol>
<hr>
<p>The <dfn method for="WindowOrWorkerGlobalScope"><code
data-x="dom-createImageBitmap">createImageBitmap(<var>image</var>,
<var>options</var>)</code></dfn> and <code data-x="">createImageBitmap(<var>image</var>,
<var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>, <var>options</var>)</code> methods,
when invoked, must run these steps:</p>
<ol>
<li><p>If either <var>sw</var> or <var>sh</var> is given and is 0, then return <span>a promise
rejected with</span> a <code data-x="js-RangeError">RangeError</code>.</p></li>
<li><p>If either <var>options</var>'s <dfn dict-member for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code></dfn> or <var>options</var>'s
<dfn dict-member for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code></dfn> is present and is 0, then
return <span>a promise rejected with</span> an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span>Check the usability of the <var>image</var> argument</span>. If this throws an
exception or returns <i>bad</i>, then return <span>a promise rejected with</span> an
<span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>.
<li><p>Let <var>p</var> be a new promise.</p></li>
<li><p>Let <var>imageBitmap</var> be a new <code>ImageBitmap</code> object.</p></li>
<li>
<p>Switch on <var>image</var>:</p>
<dl class="switch">
<dt><code>img</code>
<dt><span>SVG <code>image</code></span>
<dd>
<ol>
<li><p>If <var>image</var>'s media data has no <span>natural dimensions</span> (e.g., it's
a vector graphic with no specified content size) and either <var>options</var>'s <code
data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> or <var>options</var>'s <code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> is not present, then return
<span>a promise rejected with</span> an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>If <var>image</var>'s media data has no <span>natural dimensions</span> (e.g., it's
a vector graphic with no specified content size), it should be rendered to a bitmap of the
size specified by the <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code>
and the <code data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code>
options.</p></li>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to a copy of <var>image</var>'s media data, <span>cropped to the source rectangle
with formatting</span>. If this is an animated image, <var>imageBitmap</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span> must only be taken from the
default image of the animation (the one that the format defines is to be used when animation
is not supported or is disabled), or, if there is no such image, the first frame of the
animation.</p></li>
<li><p>If <var>image</var> <span>is not origin-clean</span>, then set the <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag of <var>imageBitmap</var>'s
bitmap to false.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt><code>video</code>
<dd>
<ol>
<li><p>If <var>image</var>'s <code data-x="dom-media-networkState">networkState</code>
attribute is <code data-x="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, then return
<span>a promise rejected with</span> an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to a copy of the frame at the <span>current playback position</span>, at the
<span>media resource</span>'s <span data-x="concept-video-natural-width">natural
width</span> and <span data-x="concept-video-natural-height">natural height</span> (i.e.,
after any aspect-ratio correction has been applied), <span>cropped to the source rectangle
with formatting</span>.</p>
<li><p>If <var>image</var> <span>is not origin-clean</span>, then set the <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag of <var>imageBitmap</var>'s
bitmap to false.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt><code>canvas</code>
<dd>
<ol>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to a copy of <var>image</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>, <span>cropped to the source
rectangle with formatting</span>.</p></li>
<li><p>Set the <span data-x="concept-canvas-origin-clean">origin-clean</span> flag of the
<var>imageBitmap</var>'s bitmap to the same value as the <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag of <var>image</var>'s
bitmap.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt><code>Blob</code>
<dd>
<p>Run these steps <span>in parallel</span>:</p>
<ol>
<li><p>Let <var>imageData</var> be the result of reading <var>image</var>'s data. If an <span
data-x="file-error-read">error occurs during reading of the object</span>, then reject
<var>p</var> with an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>
and abort these steps.</p></li>
<li><p>Apply the <span data-x="Content-Type sniffing: image">image sniffing rules</span> to
determine the file format of <var>imageData</var>, with MIME type of <var>image</var> (as
given by <var>image</var>'s <code data-x="dom-Blob-type">type</code> attribute) giving the
official type.</p></li>
<li><p>If <var>imageData</var> is not in a supported image file format (e.g., it's not an
image at all), or if <var>imageData</var> is corrupted in some fatal way such that the image
dimensions cannot be obtained (e.g., a vector graphic with no natural size), then reject
<var>p</var> with an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>
and abort these steps.</p></li>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to <var>imageData</var>, <span>cropped to the source rectangle with
formatting</span>. If this is an animated image, <var>imageBitmap</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span> must only be taken from the
default image of the animation (the one that the format defines is to be used when animation
is not supported or is disabled), or, if there is no such image, the first frame of the
animation.</p></li>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</dd>
<dt><code>ImageData</code>
<dd>
<ol>
<li><p>Let <var>buffer</var> be <var>image</var>'s <code
data-x="dom-imagedata-data">data</code> attribute value's [[ViewedArrayBuffer]] internal
slot.</p></li>
<li><p>If <span>IsDetachedBuffer</span>(<var>buffer</var>) is true, then return <span>a
promise rejected with</span> an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to <var>image</var>'s image data, <span>cropped to the source rectangle with
formatting</span>.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt><code>ImageBitmap</code>
<dd>
<ol>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to a copy of <var>image</var>'s <span
data-x="concept-ImageBitmap-bitmap-data">bitmap data</span>, <span>cropped to the source
rectangle with formatting</span>.</p></li>
<li><p>Set the <span data-x="concept-canvas-origin-clean">origin-clean</span> flag of
<var>imageBitmap</var>'s bitmap to the same value as the <span
data-x="concept-canvas-origin-clean">origin-clean</span> flag of <var>image</var>'s
bitmap.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
<dt><code>VideoFrame</code>
<dd>
<ol>
<li><p>Set <var>imageBitmap</var>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> to a copy of <var>image</var>'s visible pixel data, <span>cropped to the source
rectangle with formatting</span>.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p>Resolve <var>p</var> with <var>imageBitmap</var>.</p></li>
</ol>
</li>
</ol>
</dd>
</dl>
</li>
<li><p>Return <var>p</var>.</p></li>
</ol>
<p>When the steps above require that the user agent <dfn data-x="cropped to the source
rectangle with formatting">crop bitmap data to the source rectangle with formatting</dfn>,
the user agent must run the following steps:</p>
<ol>
<li><p>Let <var>input</var> be the <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span> being transformed.</p></li>
<li>
<p>If <var>sx</var>, <var>sy</var>, <var>sw</var> and <var>sh</var> are specified, let
<var>sourceRectangle</var> be a rectangle whose corners are the four points (<var>sx</var>,
<var>sy</var>), (<var>sx</var>+<var>sw</var>, <var>sy</var>), (<var>sx</var>+<var>sw</var>,
<var>sy</var>+<var>sh</var>), (<var>sx</var>, <var>sy</var>+<var>sh</var>). Otherwise, let
<var>sourceRectangle</var> be a rectangle whose corners are the four points (0, 0), (width of
<var>input</var>, 0), (width of <var>input</var>, height of <var>input</var>), (0, height of
<var>input</var>).</p>
<p class="note">If either <var>sw</var> or <var>sh</var> are negative, then
the top-left corner of this rectangle will be to the left or above the (<var>sx</var>,
<var>sy</var>) point.</p>
</li>
<li>
<p>Let <var>outputWidth</var> be determined as follows:</p>
<dl class="switch">
<dt>If the <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> member of
<var>options</var> is specified</dt>
<dd>the value of the <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code>
member of <var>options</var></dd>
<dt>If the <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> member of
<var>options</var> is not specified, but the <code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> member is specified</dt>
<dd>the width of <var>sourceRectangle</var>, times the value of the <code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> member of <var>options</var>,
divided by the height of <var>sourceRectangle</var>, rounded up to the nearest integer</dd>
<dt>If neither <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> nor <code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> are specified</dt>
<dd>the width of <var>sourceRectangle</var></dd>
</dl>
</li>
<li>
<p>Let <var>outputHeight</var> be determined as follows:</p>
<dl class="switch">
<dt>If the <code data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> member of
<var>options</var> is specified</dt>
<dd>the value of the <code data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code>
member of <var>options</var></dd>
<dt>If the <code data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> member of
<var>options</var> is not specified, but the <code
data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> member is specified</dt>
<dd>the height of <var>sourceRectangle</var>, times the value of the <code
data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> member of <var>options</var>,
divided by the width of <var>sourceRectangle</var>, rounded up to the nearest integer</dd>
<dt>If neither <code data-x="dom-ImageBitmapOptions-resizeWidth">resizeWidth</code> nor <code
data-x="dom-ImageBitmapOptions-resizeHeight">resizeHeight</code> are specified</dt>
<dd>the height of <var>sourceRectangle</var></dd>
</dl>
</li>
<li><p>Place <var>input</var> on an infinite <span>transparent black</span> grid plane,
positioned so that its top left corner is at the origin of the plane, with the
<var>x</var>-coordinate increasing to the right, and the <var>y</var>-coordinate increasing down,
and with each pixel in the <var>input</var> image data occupying a cell on the plane's
grid.</p></li>
<li><p>Let <var>output</var> be the rectangle on the plane denoted by
<var>sourceRectangle</var>.</p></li>
<li><p>Scale <var>output</var> to the size specified by <var>outputWidth</var> and
<var>outputHeight</var>. The user agent should use the value of the <dfn dict-member
for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-resizeQuality">resizeQuality</code></dfn> option to guide the
choice of scaling algorithm.</p></li>
<li>
<p>If the value of the <dfn dict-member for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-imageOrientation">imageOrientation</code></dfn> member of
<var>options</var> is "<dfn enum-value for="ImageOrientation"><code
data-x="dom-ImageOrientation-flipY">flipY</code></dfn>", <var>output</var> must be flipped
vertically, disregarding any image orientation metadata of the source (such as EXIF metadata),
if any. <ref>EXIF</ref></p>
<p class="note">If the value is "<dfn enum-value for="ImageOrientation"><code
data-x="dom-ImageOrientation-from-image">from-image</code></dfn>", no extra step is needed.</p>
<p class="note">There used to be a "<dfn><code
data-x="dom-ImageBitmapOptions-imageOrientation-none">none</code></dfn>" enum value. It was
renamed to "<code data-x="dom-ImageOrientation-from-image">from-image</code>". In the future,
"<code data-x="dom-ImageBitmapOptions-imageOrientation-none">none</code>" will be added back
with a different meaning.</p>
</li>
<li>
<p>If <var>image</var> is an <code>img</code> element or a <code>Blob</code> object, let
<var>val</var> be the value of the <dfn dict-member for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-colorSpaceConversion">colorSpaceConversion</code></dfn> member
of <var>options</var>, and then run these substeps:</p>
<ol>
<li><p>If <var>val</var> is "<dfn enum-value for="ColorSpaceConversion"><code
data-x="dom-ColorSpaceConversion-default">default</code></dfn>",
the color space conversion behavior is implementation-specific, and should be chosen according
to the default color space that the implementation uses for drawing images onto the canvas.</p>
</li>
<li><p>If <var>val</var> is "<dfn enum-value for="ColorSpaceConversion"><code
data-x="dom-ColorSpaceConversion-none">none</code></dfn>", <var>output</var> must be decoded
without performing any color space conversions. This means that the image decoding algorithm
must ignore color profile metadata embedded in the source data as well as the display device
color profile.</p></li>
</ol>
</li>
<li>
<p>Let <var>val</var> be the value of <dfn dict-member for="ImageBitmapOptions"><code
data-x="dom-ImageBitmapOptions-premultiplyAlpha">premultiplyAlpha</code></dfn> member of
<var>options</var>, and then run these substeps:</p>
<ol>
<li><p>If <var>val</var> is "<dfn enum-value for="PremultiplyAlpha"><code
data-x="dom-PremultiplyAlpha-default">default</code></dfn>", the alpha premultiplication
behavior is implementation-specific, and should be chosen according to implementation deems
optimal for drawing images onto the canvas.</p></li>
<li><p>If <var>val</var> is "<dfn enum-value for="PremultiplyAlpha"><code
data-x="dom-PremultiplyAlpha-premultiply">premultiply</code></dfn>", the <var>output</var> that
is not premultiplied by alpha must have its color components <span
data-x="convert-to-premultiplied">multiplied by alpha</span> and that is premultiplied by alpha
must be left untouched.</p></li>
<li><p>If <var>val</var> is "<dfn enum-value for="PremultiplyAlpha"><code
data-x="dom-PremultiplyAlpha-none">none</code></dfn>", the <var>output</var> that is not
premultiplied by alpha must be left untouched and that is premultiplied by alpha must have its
color components <span data-x="convert-from-premultiplied">divided by alpha</span>.</p></li>
</ol>
</li>
<li><p>Return <var>output</var>.</p></li>
</ol>
<p>The <dfn method for="ImageBitmap"><code data-x="dom-ImageBitmap-close">close()</code></dfn>
method steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <span>[[Detached]]</span> internal slot value to true.</p></li>
<li><p>Unset <span>this</span>'s <span data-x="concept-ImageBitmap-bitmap-data">bitmap
data</span>.</p></li>
</ol>
<p>The <dfn attribute for="ImageBitmap"><code data-x="dom-ImageBitmap-width">width</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>[[Detached]]</span> internal slot's value is true, then
return 0.</p></li>
<li><p>Return <span>this</span>'s width, in <span data-x="'px'">CSS pixels</span>.</p></li>
</ol>
<p>The <dfn attribute for="ImageBitmap"><code data-x="dom-ImageBitmap-height">height</code></dfn>
getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span>[[Detached]]</span> internal slot's value is true, then
return 0.</p></li>
<li><p>Return <span>this</span>'s height, in <span data-x="'px'">CSS pixels</span>.</p></li>
</ol>
<p>The <code>ResizeQuality</code> enumeration is used to express a preference for the
interpolation quality to use when scaling images.</p>
<p>The "<dfn enum-value for="ResizeQuality"><code
data-x="dom-ResizeQuality-pixelated">pixelated</code></dfn>" value indicates a preference for
scaling the image to preserve the pixelation of the original as much as possible, with minor
smoothing as necessary to avoid distorting the image when the target size is not a clean multiple
of the original.</p>
<p>To implement "<code data-x="dom-ResizeQuality-pixelated">pixelated</code>", for each axis
independently, first determine the integer multiple of its natural size that puts it closest to
the target size and is greater than zero. Scale it to this integer-multiple-size using nearest
neighbor, then scale it the rest of the way to the target size using bilinear interpolation.</p>
<p>The "<dfn enum-value for="ResizeQuality"><code data-x="dom-ResizeQuality-low">low</code></dfn>"
value indicates a preference for a low level of image interpolation quality. Low-quality image
interpolation may be more computationally efficient than higher settings.</p>
<p>The "<dfn enum-value for="ResizeQuality"><code
data-x="dom-ResizeQuality-medium">medium</code></dfn>" value indicates a preference for a medium
level of image interpolation quality.</p>
<p>The "<dfn enum-value for="ResizeQuality"><code
data-x="dom-ResizeQuality-high">high</code></dfn>" value indicates a preference for a high level
of image interpolation quality. High-quality image interpolation may be more computationally
expensive than lower settings.</p>
<p class="note">Bilinear scaling is an example of a relatively fast, lower-quality image-smoothing
algorithm. Bicubic or Lanczos scaling are examples of image-scaling algorithms that produce
higher-quality output. This specification does not mandate that specific interpolation algorithms
be used, except for "<code data-x="dom-ResizeQuality-pixelated">pixelated</code>" as described
above.</p>
</div>
<div class="example">
<p>Using this API, a sprite sheet can be precut and prepared:</p>
<pre><code class="js">var sprites = {};
function loadMySprites() {
var image = new Image();
image.src = 'mysprites.png';
var resolver;
var promise = new Promise(function (arg) { resolver = arg });
image.onload = function () {
resolver(Promise.all([
createImageBitmap(image, 0, 0, 40, 40).then(function (image) { sprites.person = image }),
createImageBitmap(image, 40, 0, 40, 40).then(function (image) { sprites.grass = image }),
createImageBitmap(image, 80, 0, 40, 40).then(function (image) { sprites.tree = image }),
createImageBitmap(image, 0, 40, 40, 40).then(function (image) { sprites.hut = image }),
createImageBitmap(image, 40, 40, 40, 40).then(function (image) { sprites.apple = image }),
createImageBitmap(image, 80, 40, 40, 40).then(function (image) { sprites.snake = image })
]));
};
return promise;
}
function runDemo() {
var canvas = document.querySelector('canvas#demo');
var context = canvas.getContext('2d');
context.drawImage(sprites.tree, 30, 10);
context.drawImage(sprites.snake, 70, 10);
}
loadMySprites().then(runDemo);</code></pre>
</div>
<h3>Animation frames</h3>
<p>Some objects include the <code>AnimationFrameProvider</code> interface mixin.</p>
<pre><code class="idl">callback <dfn callback>FrameRequestCallback</dfn> = undefined (<span>DOMHighResTimeStamp</span> time);
interface mixin <dfn interface>AnimationFrameProvider</dfn> {
unsigned long <span data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame</span>(<span>FrameRequestCallback</span> callback);
undefined <span data-x="AnimationFrameProvider-cancelAnimationFrame">cancelAnimationFrame</span>(unsigned long handle);
};
<span>Window</span> includes <span>AnimationFrameProvider</span>;
<span>DedicatedWorkerGlobalScope</span> includes <span>AnimationFrameProvider</span>;</code></pre>
<p>Each <code>AnimationFrameProvider</code> object also has a <dfn
data-x="concept-AnimationFrameProvider-target-object">target object</dfn> that stores the
provider's internal state. It is defined as follows:</p>
<dl>
<dt>If the <code>AnimationFrameProvider</code> is a <code>Window</code></dt>
<dd>The <code>Window</code>'s <span data-x="concept-document-window">associated
<code>Document</code></span></dd>
<dt>If the <code>AnimationFrameProvider</code> is a <code>DedicatedWorkerGlobalScope</code></dt>
<dd>The <code>DedicatedWorkerGlobalScope</code></dd>
</dl>
<p>Each <span data-x="concept-AnimationFrameProvider-target-object">target object</span> has a
<dfn id="list-of-animation-frame-callbacks">map of animation frame callbacks</dfn>, which is an
<span>ordered map</span> that must be initially empty, and an <dfn>animation frame callback
identifier</dfn>, which is a number that must initially be zero.</p>
<p>An <code>AnimationFrameProvider</code> <var>provider</var> is considered <dfn
data-x="concept-AnimationFrameProvider-supported">supported</dfn> if any of the following are
true:</p>
<ul>
<li><p><var>provider</var> is a <code>Window</code>.</p></li>
<li><p><var>provider</var>'s <span>owner set</span> <span data-x="list contains">contains</span>
a <code>Document</code> object.</p></li>
<li><p>Any of the <code>DedicatedWorkerGlobalScope</code> objects in <var>provider</var>'s
<span>owner set</span> are <span
data-x="concept-AnimationFrameProvider-supported">supported</span>.</p></li>
</ul>
<hr>
<p>The <dfn method for="AnimationFrameProvider"><code
data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame(<var>callback</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span> is not <span
data-x="concept-AnimationFrameProvider-supported">supported</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>target</var> be <span>this</span>'s <span
data-x="concept-AnimationFrameProvider-target-object">target object</span>.</p></li>
<li><p>Increment <var>target</var>'s <span>animation frame callback identifier</span> by one,
and let <var>handle</var> be the result.</p></li>
<li><p>Let <var>callbacks</var> be <var>target</var>'s <span>map of animation frame
callbacks</span>.</p></li>
<li><p><span data-x="map set">Set</span> <var>callbacks</var>[<var>handle</var>] to
<var>callback</var>.</p></li>
<li><p>Return <var>handle</var>.</p></li>
</ol>
<p>The <dfn method for="AnimationFrameProvider"><code
data-x="AnimationFrameProvider-cancelAnimationFrame">cancelAnimationFrame(<var>handle</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>If <span>this</span> is not <span
data-x="concept-AnimationFrameProvider-supported">supported</span>, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>callbacks</var> be <span>this</span>'s <span
data-x="concept-AnimationFrameProvider-target-object">target object</span>'s <span>map of
animation frame callbacks</span>.</p></li>
<li><p><span data-x="map remove">Remove</span> <var>callbacks</var>[<var>handle</var>].</p></li>
</ol>
<p>To <dfn>run the animation frame callbacks</dfn> for a <span
data-x="concept-AnimationFrameProvider-target-object">target object</span> <var>target</var> with
a timestamp <var>now</var>:</p>
<ol>
<li><p>Let <var>callbacks</var> be <var>target</var>'s <span>map of animation frame
callbacks</span>.</p></li>
<li><p>Let <var>callbackHandles</var> be the result of <span data-x="map get the keys">getting
the keys</span> of <var>callbacks</var>.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>handle</var> in
<var>callbackHandles</var>, if <var>handle</var> <span data-x="map exists">exists</span> in
<var>callbacks</var>:</p>
<ol>
<li><p>Let <var>callback</var> be <var>callbacks</var>[<var>handle</var>].</p></li>
<li><p><span data-x="map remove">Remove</span>
<var>callbacks</var>[<var>handle</var>].</p></li>
<li><p><span data-x="es-invoking-callback-functions">Invoke</span> <var>callback</var> with «
<var>now</var> » and "<code data-x="">report</code>".</p></li>
</ol>
</li>
</ol>
<div class="example">
<p>Inside workers, <code
data-x="dom-AnimationFrameProvider-requestAnimationFrame">requestAnimationFrame()</code> can be
used together with an <code>OffscreenCanvas</code> transferred from a <code>canvas</code>
element. First, in the document, transfer control to the worker:</p>
<pre><code class="js">const offscreenCanvas = document.getElementById("c").transferControlToOffscreen();
worker.postMessage(offscreenCanvas, [offscreenCanvas]);</code></pre>
<p>Then, in the worker, the following code will draw a rectangle moving from left to right:</p>
<pre><code class="js">let ctx, pos = 0;
function draw(dt) {
ctx.clearRect(0, 0, 100, 100);
ctx.fillRect(pos, 0, 10, 10);
pos += 10 * dt;
requestAnimationFrame(draw);
}
self.onmessage = function(ev) {
const transferredCanvas = ev.data;
ctx = transferredCanvas.getContext("2d");
draw();
};</code></pre>
</div>
<h2 split-filename="comms" id="comms">Communication</h2>
<p class="note" id="network"><span id="network-intro"></span><span
id="the-websocket-interface"></span><span id="feedback-from-the-protocol"></span><span
id="ping-and-pong-frames"></span><span id="the-closeevent-interface"></span><span
id="garbage-collection-2"></span><span id="websocket"></span><span id="binarytype"></span><span
id="closeevent"></span><span id="closeeventinit"></span>The <code>WebSocket</code> interface used
to be defined here. It is now defined in <cite>WebSockets</cite>. <ref>WEBSOCKETS</ref></p>
<h3>The <code>MessageEvent</code> interface</h3>
<p>Messages in <span>server-sent events</span>, <span>cross-document messaging</span>,
<span>channel messaging</span>, <span>broadcast channels</span>, and <cite>WebSockets</cite> use
the <code>MessageEvent</code> interface for their <code data-x="event-message">message</code>
events: <ref>WEBSOCKETS</ref></p>
<pre><code class="idl">[Exposed=(Window,Worker,AudioWorklet)]
interface <dfn interface>MessageEvent</dfn> : <span>Event</span> {
<span data-x="dom-Event-constructor">constructor</span>(DOMString type, optional <span>MessageEventInit</span> eventInitDict = {});
readonly attribute any <span data-x="dom-MessageEvent-data">data</span>;
readonly attribute USVString <span data-x="dom-MessageEvent-origin">origin</span>;
readonly attribute DOMString <span data-x="dom-MessageEvent-lastEventId">lastEventId</span>;
readonly attribute <span>MessageEventSource</span>? <span data-x="dom-MessageEvent-source">source</span>;
readonly attribute FrozenArray<<span>MessagePort</span>> <span data-x="dom-MessageEvent-ports">ports</span>;
undefined <span data-x="dom-MessageEvent-initMessageEvent">initMessageEvent</span>(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional any data = null, optional USVString origin = "", optional DOMString lastEventId = "", optional <span>MessageEventSource</span>? source = null, optional sequence<<span>MessagePort</span>> ports = []);
};
dictionary <dfn dictionary>MessageEventInit</dfn> : <span>EventInit</span> {
any <dfn dict-member for="MessageEventInit" data-x="dom-MessageEventInit-data">data</dfn> = null;
USVString <dfn dict-member for="MessageEventInit" data-x="dom-MessageEventInit-origin">origin</dfn> = "";
DOMString <dfn dict-member for="MessageEventInit" data-x="dom-MessageEventInit-lastEventId">lastEventId</dfn> = "";
<span>MessageEventSource</span>? <dfn dict-member for="MessageEventInit" data-x="dom-MessageEventInit-source">source</dfn> = null;
sequence<<span>MessagePort</span>> <dfn dict-member for="MessageEventInit" data-x="dom-MessageEventInit-ports">ports</dfn> = [];
};
typedef (<span>WindowProxy</span> or <span>MessagePort</span> or <span>ServiceWorker</span>) <dfn typedef>MessageEventSource</dfn>;</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-MessageEvent-data">data</span></code></dt>
<dd><p>Returns the data of the message.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-MessageEvent-origin">origin</span></code></dt>
<dd>
<p>Returns the origin of the message, for <span>server-sent events</span> and
<span>cross-document messaging</span>.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-MessageEvent-lastEventId">lastEventId</span></code></dt>
<dd>
<p>Returns the <span data-x="concept-event-stream-last-event-id">last event ID string</span>,
for <span>server-sent events</span>.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-MessageEvent-source">source</span></code></dt>
<dd>
<p>Returns the <code>WindowProxy</code> of the source window, for <span>cross-document
messaging</span>, and the <code>MessagePort</code> being attached, in the <code
data-x="event-WorkerGlobalScope-connect">connect</code> event fired at
<code>SharedWorkerGlobalScope</code> objects.</p>
</dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-MessageEvent-ports">ports</span></code></dt>
<dd>
<p>Returns the <code>MessagePort</code> array sent with the message, for <span>cross-document
messaging</span> and <span>channel messaging</span>.</p>
</dd>
<!-- initMessageEvent is deprecated -->
</dl>
<div w-nodev>
<p>The <dfn attribute for="MessageEvent"><code data-x="dom-MessageEvent-data">data</code></dfn>
attribute must return the value it was initialized to. It represents the message being sent.</p>
<p>The <dfn attribute for="MessageEvent"><code
data-x="dom-MessageEvent-origin">origin</code></dfn> attribute must return the value it was
initialized to. It represents, in <span>server-sent events</span> and <span>cross-document
messaging</span>, the <span data-x="concept-document-origin">origin</span> of the document that
sent the message (typically the scheme, hostname, and port of the document, but not its path or
<span data-x="concept-url-fragment">fragment</span>).</p>
<p>The <dfn attribute for="MessageEvent"><code
data-x="dom-MessageEvent-lastEventId">lastEventId</code></dfn> attribute must return the value it
was initialized to. It represents, in <span>server-sent events</span>, the <span
data-x="concept-event-stream-last-event-id">last event ID string</span> of the event source.</p>
<p>The <dfn attribute for="MessageEvent"><code
data-x="dom-MessageEvent-source">source</code></dfn> attribute must return the value it was
initialized to. It represents, in <span>cross-document messaging</span>, the
<code>WindowProxy</code> of the <span>browsing context</span> of the <code>Window</code> object
from which the message came; and in the <code
data-x="event-WorkerGlobalScope-connect">connect</code> events used by <span
data-x="SharedWorkerGlobalScope">shared workers</span>, the newly connecting
<code>MessagePort</code>.</p>
<p>The <dfn attribute for="MessageEvent"><code data-x="dom-MessageEvent-ports">ports</code></dfn>
attribute must return the value it was initialized to. It represents, in <span>cross-document
messaging</span> and <span>channel messaging</span>, the <code>MessagePort</code> array being
sent.</p>
<!-- handwavy, file bugs if there are interop issues -->
<p>The <dfn method for="MessageEvent"><code
data-x="dom-MessageEvent-initMessageEvent">initMessageEvent(<var>type</var>, <var>bubbles</var>,
<var>cancelable</var>, <var>data</var>, <var>origin</var>, <var>lastEventId</var>,
<var>source</var>, <var>ports</var>)</code></dfn> method must initialize the event in a manner
analogous to the similarly-named <code data-x="dom-Event-initEvent">initEvent()</code> method.
<ref>DOM</ref></p>
</div>
<p class="note">Various APIs (e.g., <code>WebSocket</code>, <code>EventSource</code>) use the
<code>MessageEvent</code> interface for their <code data-x="event-message">message</code> event
without using the <code>MessagePort</code> API.</p>
<h3 split-filename="server-sent-events" id="server-sent-events"><dfn>Server-sent events</dfn></h3>
<h4 id="server-sent-events-intro">Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>To enable servers to push data to web pages over HTTP or using dedicated server-push protocols,
this specification introduces the <code>EventSource</code> interface.</p>
<p>Using this API consists of creating an <code>EventSource</code> object and registering an event
listener.</p>
<pre><code class="js">var source = new EventSource('updates.cgi');
source.onmessage = function (event) {
alert(event.data);
};</code></pre>
<p>On the server-side, the script ("<code data-x="">updates.cgi</code>" in this case) sends
messages in the following form, with the <code>text/event-stream</code> MIME type:</p>
<pre>data: This is the first message.
data: This is the second message, it
data: has two lines.
data: This is the third message.</pre>
<hr>
<p>Authors can separate events by using different event types. Here is a stream that has two event
types, "add" and "remove":</p>
<pre>event: add
data: 73857293
event: remove
data: 2153
event: add
data: 113411</pre>
<p>The script to handle such a stream would look like this (where <code data-x="">addHandler</code>
and <code data-x="">removeHandler</code> are functions that take one argument, the event):</p>
<pre><code class="js">var source = new EventSource('updates.cgi');
source.addEventListener('add', addHandler, false);
source.addEventListener('remove', removeHandler, false);</code></pre>
<p>The default event type is "message".</p>
<p>Event streams are always decoded as UTF-8. There is no way to specify another character
encoding.</p>
<hr>
<p>Event stream requests can be redirected using HTTP 301 and 307 redirects as with normal HTTP
requests. Clients will reconnect if the connection is closed; a client can be told to stop
reconnecting using the HTTP 204 No Content response code.</p>
<p>Using this API rather than emulating it using <code>XMLHttpRequest</code> or an
<code>iframe</code> allows the user agent to make better use of network resources in cases where
the user agent implementer and the network operator are able to coordinate in advance. Amongst
other benefits, this can result in significant savings in battery life on portable devices. This
is discussed further in the section below on <a href="#eventsource-push">connectionless
push</a>.</p>
<h4>The <code>EventSource</code> interface</h4>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>EventSource</dfn> : <span>EventTarget</span> {
<span data-x="dom-EventSource">constructor</span>(USVString url, optional <span>EventSourceInit</span> eventSourceInitDict = {});
readonly attribute USVString <span data-x="dom-EventSource-url">url</span>;
readonly attribute boolean <span data-x="dom-EventSource-withCredentials">withCredentials</span>;
// ready state
const unsigned short <span data-x="dom-EventSource-CONNECTING">CONNECTING</span> = 0;
const unsigned short <span data-x="dom-EventSource-OPEN">OPEN</span> = 1;
const unsigned short <span data-x="dom-EventSource-CLOSED">CLOSED</span> = 2;
readonly attribute unsigned short <span data-x="dom-EventSource-readyState">readyState</span>;
// networking
attribute <span>EventHandler</span> <span data-x="handler-EventSource-onopen">onopen</span>;
attribute <span>EventHandler</span> <span data-x="handler-EventSource-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-EventSource-onerror">onerror</span>;
undefined <span data-x="dom-EventSource-close">close</span>();
};
dictionary <dfn dictionary>EventSourceInit</dfn> {
boolean <dfn dict-member for="EventSourceInit" data-x="dom-EventSourceInit-withCredentials">withCredentials</dfn> = false;
};</code></pre>
<div w-nodev>
<p>Each <code>EventSource</code> object has the following associated with it:</p>
<ul>
<li><p>A <dfn data-x="concept-EventSource-url" for="EventSource">url</dfn> (a <span>URL
record</span>). Set during construction.</p></li>
<li><p>A <dfn data-x="concept-event-stream-request">request</dfn>. This must initially be
null.</p></li>
<li><p>A <dfn data-x="concept-event-stream-reconnection-time">reconnection time</dfn>, in
milliseconds. This must initially be an <span>implementation-defined</span> value, probably in
the region of a few seconds.</p></li>
<li><p>A <dfn data-x="concept-event-stream-last-event-id">last event ID string</dfn>. This must
initially be the empty string.</p></li>
</ul>
<p>Apart from <span data-x="concept-EventSource-url">url</span> these are not currently exposed on
the <code>EventSource</code> object.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>source</var> = new <span subdfn data-x="dom-EventSource">EventSource</span>(
<var>url</var> [, { <span data-x="dom-EventSourceInit-withCredentials">withCredentials</span>:
true } ])</code></dt>
<dd>
<p>Creates a new <code>EventSource</code> object.</p>
<p><var>url</var> is a string giving the <span>URL</span> that will provide the event
stream.</p>
<p>Setting <code data-x="dom-EventSourceInit-withCredentials">withCredentials</code> to true
will set the <span data-x="concept-request-credentials-mode">credentials mode</span> for
connection requests to <var>url</var> to "<code data-x="">include</code>".</p>
</dd>
<dt><code data-x=""><var>source</var>.<span subdfn data-x="dom-EventSource-close">close</span>()</code></dt>
<dd>
<p>Aborts any instances of the <span data-x="concept-fetch">fetch</span> algorithm started for
this <code>EventSource</code> object, and sets the <code
data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-CLOSED">CLOSED</code>.</p>
</dd>
<dt><code data-x=""><var>source</var>.<span subdfn data-x="dom-EventSource-url">url</span></code></dt>
<dd><p>Returns the <span data-x="concept-EventSource-url">URL providing the event
stream</span>.</p></dd>
<dt><code data-x=""><var>source</var>.<span subdfn data-x="dom-EventSource-withCredentials">withCredentials</span></code></dt>
<dd>
<p>Returns true if the <span data-x="concept-request-credentials-mode">credentials mode</span>
for connection requests to the <span data-x="concept-EventSource-url">URL providing the event
stream</span> is set to "<code data-x="">include</code>", and false otherwise.</p>
</dd>
<dt><code data-x=""><var>source</var>.<span subdfn data-x="dom-EventSource-readyState">readyState</span></code></dt>
<dd>
<p>Returns the state of this <code>EventSource</code> object's connection. It can have the
values described below.</p>
</dd>
</dl>
<div w-nodev>
<p>The <dfn constructor for="EventSource"><code
data-x="dom-EventSource">EventSource(<var>url</var>, <var>eventSourceInitDict</var>)</code></dfn>
constructor, when invoked, must run these steps:</p>
<ol>
<li><p>Let <var>ev</var> be a new <code>EventSource</code> object.</p></li>
<li><p>Let <var>settings</var> be <var>ev</var>'s <span>relevant settings object</span>.
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to <var>settings</var>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>ev</var>'s <span data-x="concept-EventSource-url">url</span> to
<var>urlRecord</var>.</p>
<li><p>Let <var>corsAttributeState</var> be <span
data-x="attr-crossorigin-anonymous">Anonymous</span>.</p></li>
<li><p>If the value of <var>eventSourceInitDict</var>'s <code
data-x="dom-EventSourceInit-withCredentials">withCredentials</code> member is true, then set
<var>corsAttributeState</var> to <span data-x="attr-crossorigin-use-credentials">Use
Credentials</span> and set <var>ev</var>'s <code
data-x="dom-EventSource-withCredentials">withCredentials</code> attribute to true.</p></li>
<li><p>Let <var>request</var> be the result of <span
data-x="create a potential-CORS request">creating a potential-CORS request</span> given
<var>urlRecord</var>, the empty string, and <var>corsAttributeState</var>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-client">client</span> to
<var>settings</var>.</p></li>
<li><p>User agents may <span data-x="concept-header-list-set">set</span> (`<code
data-x="http-accept">Accept</code>`, `<code>text/event-stream</code>`) in <var>request</var>'s
<span data-x="concept-request-header-list">header list</span>.</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-cache-mode">cache mode</span> to
"<code data-x="">no-store</code>".</p></li>
<li><p>Set <var>request</var>'s <span data-x="concept-request-initiator-type">initiator
type</span> to "<code data-x="">other</code>".</p></li>
<li><p>Set <var>ev</var>'s <span data-x="concept-event-stream-request">request</span> to
<var>request</var>.</p></li>
<li><p>Let <var>processEventSourceEndOfBody</var> given <span
data-x="concept-response">response</span> <var>res</var> be the following step: if
<var>res</var> is not a <span>network error</span>, then <span>reestablish the
connection</span>.</p></li>
<li>
<p><span data-x="concept-fetch">Fetch</span> <var>request</var>, with <i
data-x="processResponseEndOfBody">processResponseEndOfBody</i> set to
<var>processEventSourceEndOfBody</var> and <i data-x="processResponse">processResponse</i> set
to the following steps given <span data-x="concept-response">response</span>
<var>res</var>:</p>
<ol>
<li><p>If <var>res</var> is an <span>aborted network error</span>, then <span>fail the
connection</span>.</p></li>
<li><p>Otherwise, if <var>res</var> is a <span>network error</span>, then <span>reestablish
the connection</span>, unless the user agent knows that to be futile, in which case the user
agent may <span>fail the connection</span>.</p></li>
<li><p>Otherwise, if <var>res</var>'s <span data-x="concept-response-status">status</span> is
not 200, or if <var>res</var>'s `<code>Content-Type</code>` is not
`<code>text/event-stream</code>`, then <span>fail the connection</span>.</p>
<li><p>Otherwise, <span>announce the connection</span> and <a
href="#event-stream-interpretation">interpret</a> <var>res</var>'s <span
data-x="concept-response-body">body</span> line by line.</p></li>
</ol>
</li>
<li><p>Return <var>ev</var>.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="EventSource"><code data-x="dom-EventSource-url">url</code></dfn>
attribute's getter must return the <span data-x="concept-url-serializer">serialization</span> of
this <code>EventSource</code> object's <span data-x="concept-EventSource-url">url</span>.</p>
<p>The <dfn attribute for="EventSource"><code
data-x="dom-EventSource-withCredentials">withCredentials</code></dfn> attribute must return the
value to which it was last initialized. When the object is created, it must be initialized to
false.</p>
<p>The <dfn attribute for="EventSource"><code
data-x="dom-EventSource-readyState">readyState</code></dfn> attribute represents the state of the
connection. It can have the following values:</p>
</div>
<dl>
<dt><dfn const for="EventSource"><code data-x="dom-EventSource-CONNECTING">CONNECTING</code></dfn> (numeric value 0)</dt>
<dd>The connection has not yet been established, or it was closed and the user agent is
reconnecting.</dd>
<dt><dfn const for="EventSource"><code data-x="dom-EventSource-OPEN">OPEN</code></dfn> (numeric value 1)</dt>
<dd>The user agent has an open connection and is dispatching events as it receives them.</dd>
<dt><dfn const for="EventSource"><code data-x="dom-EventSource-CLOSED">CLOSED</code></dfn> (numeric value 2)</dt>
<dd>The connection is not open, and the user agent is not trying to reconnect. Either there was a
fatal error or the <code data-x="dom-EventSource-close">close()</code> method was invoked.</dd>
</dl>
<div w-nodev>
<p>When the object is created its <code data-x="dom-EventSource-readyState">readyState</code> must
be set to <code data-x="dom-EventSource-CONNECTING">CONNECTING</code> (0). The rules given below
for handling the connection define when the value changes.</p>
<p>The <dfn method for="EventSource"><code data-x="dom-EventSource-close">close()</code></dfn>
method must abort any instances of the <span data-x="concept-fetch">fetch</span> algorithm started
for this <code>EventSource</code> object, and must set the <code
data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-CLOSED">CLOSED</code>.</p> <!-- this also causes all the message events to
stop firing, even if they were queued before close() was called -->
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>EventSource</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="EventSource"><code data-x="handler-EventSource-onopen">onopen</code></dfn> <td> <code data-x="event-open">open</code>
<tr><td><dfn attribute for="EventSource"><code data-x="handler-EventSource-onmessage">onmessage</code></dfn> <td> <code data-x="event-message">message</code>
<tr><td><dfn attribute for="EventSource"><code data-x="handler-EventSource-onerror">onerror</code></dfn> <td> <code data-x="event-error">error</code>
</table>
<hr>
<div w-nodev>
<h4 id="sse-processing-model"><span id="processing-model-9"></span>Processing model</h4>
<p>When a user agent is to <dfn>announce the connection</dfn>, the user agent must <span>queue a
task</span> which, if the <code data-x="dom-EventSource-readyState">readyState</code> attribute is
set to a value other than <code data-x="dom-EventSource-CLOSED">CLOSED</code>, sets the <code
data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-OPEN">OPEN</code> and <span data-x="concept-event-fire">fires an
event</span> named <code data-x="event-open">open</code> at the <code>EventSource</code>
object.</p>
<p>When a user agent is to <dfn>reestablish the connection</dfn>, the user agent must run the
following steps. These steps are run <span>in parallel</span>, not as part of a <span
data-x="concept-task">task</span>. (The tasks that it queues, of course, are run like normal tasks
and not themselves <span>in parallel</span>.)</p>
<ol>
<li>
<p><span>Queue a task</span> to run the following steps:</p>
<ol>
<li><p>If the <code data-x="dom-EventSource-readyState">readyState</code> attribute is set to
<code data-x="dom-EventSource-CLOSED">CLOSED</code>, abort the task.</p></li>
<li><p>Set the <code data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-CONNECTING">CONNECTING</code>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-error">error</code> at the <code>EventSource</code> object.</p></li>
</ol>
</li>
<li><p>Wait a delay equal to the reconnection time of the event source.</li>
<li><p>Optionally, wait some more. In particular, if the previous attempt failed, then user
agents might introduce an exponential backoff delay to avoid overloading a potentially already
overloaded server. Alternatively, if the operating system has reported that there is no network
connectivity, user agents might wait for the operating system to announce that the network
connection has returned before retrying.</li>
<li><p>Wait until the aforementioned task has run, if it has not yet run.</p></li>
<li>
<p><span>Queue a task</span> to run the following steps:</p>
<ol>
<li><p>If the <code>EventSource</code> object's <code
data-x="dom-EventSource-readyState">readyState</code> attribute is not set to <code
data-x="dom-EventSource-CONNECTING">CONNECTING</code>, then return.</p></li>
<li><p>Let <var>request</var> be the <code>EventSource</code> object's <span
data-x="concept-event-stream-request">request</span>.
<li>
<p>If the <code>EventSource</code> object's <span
data-x="concept-event-stream-last-event-id">last event ID string</span> is not the empty
string, then:</p>
<ol>
<li><p>Let <var>lastEventIDValue</var> be the <code>EventSource</code> object's <span
data-x="concept-event-stream-last-event-id">last event ID string</span>, <span data-x="UTF-8
encode">encoded as UTF-8</span>.</p></li>
<li><p><span data-x="concept-header-list-set">Set</span> (`<code>Last-Event-ID</code>`,
<var>lastEventIDValue</var>) in <var>request</var>'s <span
data-x="concept-request-header-list">header list</span>.</p></li>
</ol>
</li>
<!--FETCH--><li><p><span data-x="concept-fetch">Fetch</span> <var>request</var> and process the
response obtained in this fashion, if any, as described earlier in this section.</p></li>
</ol>
</li>
</ol>
<p>When a user agent is to <dfn>fail the connection</dfn>, the user agent must <span>queue a
task</span> which, if the <code data-x="dom-EventSource-readyState">readyState</code> attribute is
set to a value other than <code data-x="dom-EventSource-CLOSED">CLOSED</code>, sets the <code
data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-CLOSED">CLOSED</code> and <span data-x="concept-event-fire">fires an
event</span> named <code data-x="event-error">error</code> at the <code>EventSource</code> object.
<strong>Once the user agent has <span data-x="fail the connection">failed the connection</span>,
it does <em>not</em> attempt to reconnect.</strong></p>
<hr>
<p>The <span>task source</span> for any <span data-x="concept-task">tasks</span> that are <span
data-x="queue a task">queued</span> by <code>EventSource</code> objects is the <dfn>remote event
task source</dfn>.</p>
</div>
<h4>The `<code>Last-Event-ID</code>` header</h4>
<p>The <dfn http-header><code>Last-Event-ID</code></dfn>` HTTP request header reports an
<code>EventSource</code> object's <span data-x="concept-event-stream-last-event-id">last event ID
string</span> to the server when the user agent is to <span>reestablish the connection</span>.
<p class="XXX">See <a href="https://github.com/whatwg/html/issues/7363">whatwg/html issue
#7363</a> to define the value space better. It is essentially any UTF-8 encoded string, that does
not contain U+0000 NULL, U+000A LF, or U+000D CR.</p>
<h4 w-nodev>Parsing an event stream</h4>
<h4 w-dev>The event stream format</h4>
<p>This event stream format's <span>MIME type</span> is <code>text/event-stream</code>.</p>
<p>The event stream format is as described by the <code data-x="">stream</code> production of the
following ABNF, the character set for which is Unicode. <ref>ABNF</ref></p>
<pre><code data-x="" class="abnf">stream = [ bom ] *event
event = *( comment / field ) end-of-line
comment = colon *any-char end-of-line
field = 1*name-char [ colon [ space ] *any-char ] end-of-line
end-of-line = ( cr lf / cr / lf )
; characters
lf = %x000A ; U+000A LINE FEED (LF)
cr = %x000D ; U+000D CARRIAGE RETURN (CR)
space = %x0020 ; U+0020 SPACE
colon = %x003A ; U+003A COLON (:)
bom = %xFEFF ; U+FEFF BYTE ORDER MARK
name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
; a <span>scalar value</span> other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
; a <span>scalar value</span> other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)</code></pre>
<p>Event streams in this format must always be encoded as UTF-8. <ref>ENCODING</ref></p>
<p>Lines must be separated by either a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character
pair, a single U+000A LINE FEED (LF) character, or a single U+000D CARRIAGE RETURN (CR)
character.</p>
<p w-nodev>Since connections established to remote servers for such resources are expected to be
long-lived, UAs should ensure that appropriate buffering is used. In particular, while line
buffering with lines are defined to end with a single U+000A LINE FEED (LF) character is safe,
block buffering or line buffering with different expected line endings can cause delays in event
dispatch.</p>
<div w-nodev>
<h4 id="event-stream-interpretation">Interpreting an event stream</h4>
<p>Streams must be decoded using the <span>UTF-8 decode</span> algorithm.</p>
<p class="note">The <span>UTF-8 decode</span> algorithm strips one leading UTF-8 Byte Order Mark
(BOM), if any.</p>
<p>The stream must then be parsed by reading everything line by line, with a U+000D CARRIAGE
RETURN U+000A LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF) character not
preceded by a U+000D CARRIAGE RETURN (CR) character, and a single U+000D CARRIAGE RETURN (CR)
character not followed by a U+000A LINE FEED (LF) character being the ways in which a line can
end.</p>
<p>When a stream is parsed, a <var>data</var> buffer, an <var>event type</var>
buffer, and a <var>last event ID</var> buffer must be associated with it. They must be
initialized to the empty string.</p>
<p>Lines must be processed, in the order they are received, as follows:</p>
<dl class="switch">
<dt>If the line is empty (a blank line)</dt>
<dd><p><span>Dispatch the event</span>, as defined below.</p></dd>
<dt>If the line starts with a U+003A COLON character (:)</dt>
<dd><p>Ignore the line.</p></dd>
<dt>If the line contains a U+003A COLON character (:)</dt>
<dd>
<p>Collect the characters on the line before the first U+003A COLON character (:), and let <var>field</var> be that string.</p>
<p>Collect the characters on the line after the first U+003A COLON character (:), and let <var>value</var> be that string. If <var>value</var> starts with a U+0020 SPACE
character, remove it from <var>value</var>.</p>
<p><a href="#processField">Process the field</a> using the steps described below, using <var>field</var> as the field name and <var>value</var> as the field value.</p>
</dd>
<dt>Otherwise, the string is not empty but does not contain a U+003A COLON character (:)</dt>
<dd>
<p><a href="#processField">Process the field</a> using the steps described below, using the
whole line as the field name, and the empty string as the field value.</p>
</dd>
</dl>
<p>Once the end of the file is reached, any pending data must be discarded. (If the file ends in
the middle of an event, before the final empty line, the incomplete event is not dispatched.)</p>
<hr>
<p id="processField">The steps to <dfn data-x="">process the field</dfn> given a field name and a
field value depend on the field name, as given in the following list. Field names must be compared
literally, with no case folding performed.</p>
<dl class="switch">
<dt>If the field name is "event"</dt>
<dd><p>Set the <var>event type</var> buffer to field value.</p></dd>
<dt>If the field name is "data"</dt>
<dd><p>Append the field value to the <var>data</var> buffer, then append a single U+000A
LINE FEED (LF) character to the <var>data</var> buffer.</p></dd>
<dt>If the field name is "id"</dt>
<dd><p>If the field value does not contain U+0000 NULL, then set the <var>last event ID</var>
buffer to the field value. Otherwise, ignore the field.</p></dd>
<dt>If the field name is "retry"</dt>
<dd><p>If the field value consists of only <span>ASCII digits</span>, then interpret the field
value as an integer in base ten, and set the event stream's <span
data-x="concept-event-stream-reconnection-time">reconnection time</span> to that integer.
Otherwise, ignore the field.</p></dd>
<!-- v2 feature request from Per-Erik Brodin:
> > > Finally, it could be useful to be able to reset the reconnection
> > > time to the user agent default value by sending the retry field only
> > > and leave out the value similar to how you reset the last event id.
> >
> > What's the use case?
>
> Take the stock ticker as an example. When the stock market closes the
> server logic knows that there won't be any new events for a number of
> hours and so it can send the corresponding reconnection time and close
> the connection. If the client is still running by the time the market
> opens, it will reconnect, and the server can now reset the reconnection
> time to a time that is convenient for the user agent (which is the user
> agent default value, unknown to the server).
-->
<!-- v2 feature request from John Fallows - https://lists.w3.org/Archives/Public/public-html-comments/2008Oct/0009.html
<dt>If the field name is "reconnect"</dt>
<dd><p>If the field value is the empty string, then: <span>dispatch the
event</span> as defined below, and then drop the connection and immediately reconnect as if the
<span data-x="concept-event-stream-reconnection-time">reconnection time</span> was zero for this
one time.</p></dd>
-->
<dt>Otherwise</dt>
<dd><p>The field is ignored.</p></dd>
</dl>
<p>When the user agent is required to <dfn id="dispatchMessage">dispatch the
event</dfn>, the user agent must process the <var>data</var> buffer, the <var>event type</var> buffer, and the <var>last event ID</var> buffer using steps
appropriate for the user agent.</p>
<p>For web browsers, the appropriate steps to <span>dispatch the event</span> are as follows:</p>
<ol>
<li><p>Set the <span data-x="concept-event-stream-last-event-id">last event ID string</span> of
the event source to the value of the <var>last event ID</var> buffer. The buffer does
not get reset, so the <span data-x="concept-event-stream-last-event-id">last event ID
string</span> of the event source remains set to this value until the next time it is set by the
server.</p></li>
<li><p>If the <var>data</var> buffer is an empty string, set the <var>data</var> buffer and the <var>event type</var> buffer to the empty string and
return.</p></li>
<li><p>If the <var>data</var> buffer's last character is a U+000A LINE FEED (LF)
character, then remove the last character from the <var>data</var> buffer.</p></li>
<li><p>Let <var>event</var> be the result of <span>creating an event</span> using
<code>MessageEvent</code>, in the <span data-x="concept-relevant-realm">relevant realm</span> of
the <code>EventSource</code> object.</p></li>
<li><p>Initialize <var>event</var>'s <code data-x="dom-Event-type">type</code> attribute to
"<code data-x="event-message">message</code>", its <code
data-x="dom-MessageEvent-data">data</code> attribute to <var>data</var>, its <code
data-x="dom-MessageEvent-origin">origin</code> attribute to the <span data-x="serialization of
an origin">serialization</span> of the <span data-x="concept-url-origin">origin</span> of the
event stream's final URL (i.e., the URL after redirects), and its <code
data-x="dom-MessageEvent-lastEventId">lastEventId</code> attribute to the <span
data-x="concept-event-stream-last-event-id">last event ID string</span> of the event
source.</p></li>
<li><p>If the <var>event type</var> buffer has a value other than the empty string, change the
<span data-x="concept-event-type">type</span> of the newly created event to equal the value of
the <var>event type</var> buffer.</p></li>
<li><p>Set the <var>data</var> buffer and the <var>event type</var> buffer to
the empty string.</p></li>
<li><p><span>Queue a task</span> which, if the <code
data-x="dom-EventSource-readyState">readyState</code> attribute is set to a value other than <code
data-x="dom-EventSource-CLOSED">CLOSED</code>, <span
data-x="concept-event-dispatch">dispatches</span> the newly created event at the
<code>EventSource</code> object.</p></li> <!-- so calling close() drops the messages immediately.
The connection dying doesn't interfere with already-sent messages since it sets us to CLOSED via
a task, not immediately -->
</ol>
<p class="note">If an event doesn't have an "id" field, but an earlier event did set the event
source's <span data-x="concept-event-stream-last-event-id">last event ID string</span>, then the
event's <code data-x="dom-MessageEvent-lastEventId">lastEventId</code> field will be set to the
value of whatever the last seen "id" field was.</p>
<p>For other user agents, the appropriate steps to <span>dispatch the event</span> are
implementation dependent, but at a minimum they must set the <var>data</var> and <var>event type</var> buffers to the empty string before returning.</p>
</div>
<div class="example">
<p>The following event stream, once followed by a blank line:</p>
<pre>data: YHOO
data: +2
data: 10</pre>
<p>...would cause an event <code data-x="event-message">message</code> with the interface
<code>MessageEvent</code> to be dispatched on the <code>EventSource</code> object. The event's
<code data-x="dom-MessageEvent-data">data</code> attribute would contain the string "<code
data-x="">YHOO\n+2\n10</code>" (where "<code data-x="">\n</code>" represents a newline).</p>
<p>This could be used as follows:
<pre><code class="js">var stocks = new EventSource("https://stocks.example.com/ticker.php");
stocks.onmessage = function (event) {
var data = event.data.split('\n');
updateStocks(data[0], data[1], data[2]);
};</code></pre>
<p>...where <code data-x="">updateStocks()</code> is a function defined as:</p>
<pre><code class="js">function updateStocks(symbol, delta, value) { ... }</code></pre>
<p>...or some such.</p>
</div>
<div class="example">
<p>The following stream contains four blocks. The first block has just a comment, and will fire
nothing. The second block has two fields with names "data" and "id" respectively; an event will
be fired for this block, with the data "first event", and will then set the last event ID to "1"
so that if the connection died between this block and the next, the server would be sent a
`<code>Last-Event-ID</code>` header with the value `<code data-x="">1</code>`. The third block
fires an event with data "second event", and also has an "id" field, this time with no value,
which resets the last event ID to the empty string (meaning no `<code>Last-Event-ID</code>`
header will now be sent in the event of a reconnection being attempted). Finally, the last block
just fires an event with the data " third event" (with a single leading space
character). Note that the last still has to end with a blank line, the end of the stream is not
enough to trigger the dispatch of the last event.</p>
<pre>: test stream
data: first event
id: 1
data:second event
id
data: third event
</pre>
</div>
<div class="example">
<p>The following stream fires two events:</p>
<pre>data
data
data
data:</pre>
<p>The first block fires events with the data set to the empty string, as would the last block if
it was followed by a blank line. The middle block fires an event with the data set to a single
newline character. The last block is discarded because it is not followed by a blank line.</p>
</div>
<div class="example">
<p>The following stream fires two identical events:</p>
<pre>data:test
data: test
</pre>
<p>This is because the space after the colon is ignored if present.</p>
</div>
<h4>Authoring notes</h4>
<p>Legacy proxy servers are known to, in certain cases, drop HTTP connections after a short
timeout. To protect against such proxy servers, authors can include a comment line (one starting
with a ':' character) every 15 seconds or so.</p>
<p>Authors wishing to relate event source connections to each other or to specific documents
previously served might find that relying on IP addresses doesn't work, as individual clients can
have multiple IP addresses (due to having multiple proxy servers) and individual IP addresses can
have multiple clients (due to sharing a proxy server). It is better to include a unique identifier
in the document when it is served and then pass that identifier as part of the URL when the
connection is established.</p>
<p>Authors are also cautioned that HTTP chunking can have unexpected negative effects on the
reliability of this protocol, in particular if the chunking is done by a different layer unaware
of the timing requirements. If this is a problem, chunking can be disabled for serving event
streams.</p> <!-- v2 can we get a better solution? -->
<p>Clients that support HTTP's per-server connection limitation might run into trouble when
opening multiple pages from a site if each page has an <code>EventSource</code> to the same
domain. Authors can avoid this using the relatively complex mechanism of using unique domain names
per connection, or by allowing the user to enable or disable the <code>EventSource</code>
functionality on a per-page basis, or by sharing a single <code>EventSource</code> object using a
<span data-x="SharedWorkerGlobalScope">shared worker</span>.</p>
<div w-nodev>
<h4 id="eventsource-push">Connectionless push and other features</h4>
<p>User agents running in controlled environments, e.g. browsers on mobile handsets tied to
specific carriers, may offload the management of the connection to a proxy on the network. In such
a situation, the user agent for the purposes of conformance is considered to include both the
handset software and the network proxy.</p>
<div class="example">
<p>For example, a browser on a mobile device, after having established a connection, might detect
that it is on a supporting network and request that a proxy server on the network take over the
management of the connection. The timeline for such a situation might be as follows:</p>
<ol>
<li>Browser connects to a remote HTTP server and requests the resource specified by the author
in the <code data-x="dom-EventSource">EventSource</code> constructor.</li>
<li>The server sends occasional messages.</li>
<li>In between two messages, the browser detects that it is idle except for the network activity
involved in keeping the TCP connection alive, and decides to switch to sleep mode to save
power.</li>
<li>The browser disconnects from the server.</li>
<li>The browser contacts a service on the network, and requests that the service, a "push
proxy", maintain the connection instead.</li>
<li>The "push proxy" service contacts the remote HTTP server and requests the resource specified
by the author in the <code data-x="dom-EventSource">EventSource</code> constructor (possibly
including a `<code>Last-Event-ID</code>` HTTP header, etc.).</li>
<li>The browser allows the mobile device to go to sleep.</li>
<li>The server sends another message.</li>
<li>The "push proxy" service uses a technology such as OMA push to convey the event to the
mobile device, which wakes only enough to process the event and then returns to sleep.</li>
</ol>
</div>
<p>This can reduce the total data usage, and can therefore result in considerable power
savings.</p>
<p>As well as implementing the existing API and <code>text/event-stream</code> wire format as
defined by this specification and in more distributed ways as described above, formats of event
framing defined by <span>other applicable specifications</span> may be supported. This
specification does not define how they are to be parsed or processed.</p>
<h4>Garbage collection</h4>
<p>While an <code>EventSource</code> object's <code
data-x="dom-EventSource-readyState">readyState</code> is <code
data-x="dom-EventSource-CONNECTING">CONNECTING</code>, and the object has one or more event
listeners registered for <code data-x="event-open">open</code>, <code
data-x="event-message">message</code>, or <code data-x="event-error">error</code> events, there must
be a strong reference from the <code>Window</code> or <code>WorkerGlobalScope</code> object that
the <code>EventSource</code> object's constructor was invoked from to the <code>EventSource</code>
object itself.</p>
<p>While an <code>EventSource</code> object's <code
data-x="dom-EventSource-readyState">readyState</code> is <code
data-x="dom-EventSource-OPEN">OPEN</code>, and the object has one or more event listeners
registered for <code data-x="event-message">message</code> or <code
data-x="event-error">error</code> events, there must be a strong reference from the
<code>Window</code> or <code>WorkerGlobalScope</code> object that the <code>EventSource</code>
object's constructor was invoked from to the <code>EventSource</code> object itself.</p>
<p>While there is a task queued by an <code>EventSource</code> object on the <span>remote event
task source</span>, there must be a strong reference from the <code>Window</code> or
<code>WorkerGlobalScope</code> object that the <code>EventSource</code> object's constructor was
invoked from to that <code>EventSource</code> object.</p>
<p>If a user agent is to <dfn data-x="concept-EventSource-forcibly-close">forcibly close</dfn> an
<code>EventSource</code> object (this happens when a <code>Document</code> object goes away
permanently), the user agent must abort any instances of the <span
data-x="concept-fetch">fetch</span> algorithm started for this <code>EventSource</code> object,
and must set the <code data-x="dom-EventSource-readyState">readyState</code> attribute to <code
data-x="dom-EventSource-CLOSED">CLOSED</code>.</p> <!-- same as calling close() -->
<p>If an <code>EventSource</code> object is garbage collected while its connection is still open,
the user agent must abort any instance of the <span data-x="concept-fetch">fetch</span> algorithm
opened by this <code>EventSource</code>.</p> <!-- no need to throw tasks away or anything; for it
to get garbage collected, there can't be anything that would be able to receive those events -->
<h4>Implementation advice</h4>
<!-- NON-NORMATIVE SECTION -->
<p>User agents are strongly urged to provide detailed diagnostic information about
<code>EventSource</code> objects and their related network connections in their development
consoles, to aid authors in debugging code using this API.</p>
<p>For example, a user agent could have a panel displaying all the <code>EventSource</code>
objects a page has created, each listing the constructor's arguments, whether there was a network
error, what the CORS status of the connection is and what headers were sent by the client and
received from the server to lead to that status, the messages that were received and how they were
parsed, and so forth.</p>
<p>Implementations are especially encouraged to report detailed information to their development
consoles whenever an <code data-x="event-error">error</code> event is fired, since little to no
information can be made available in the events themselves.</p>
</div>
<h3 split-filename="web-messaging" id="web-messaging"><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h3>
<p>Web browsers, for security and privacy reasons, prevent documents in different domains from
affecting each other; that is, cross-site scripting is disallowed.</p>
<p>While this is an important security feature, it prevents pages from different domains from
communicating even when those pages are not hostile. This section introduces a messaging system
that allows documents to communicate with each other regardless of their source domain, in a way
designed to not enable cross-site scripting attacks.</p>
<p class="note" id="fingerprint-postMessage">
<!-- INSERT TRACKING -->
The <code data-x="dom-window-postMessage">postMessage()</code> API can be used as a <span>tracking
vector</span>.</p>
<h4>Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<div class="example">
<p>For example, if document A contains an <code>iframe</code> element that contains document B,
and script in document A calls <code data-x="dom-window-postMessage">postMessage()</code> on the
<code>Window</code> object of document B, then a message event will be fired on that object,
marked as originating from the <code>Window</code> of document A. The script in document A might
look like:</p>
<pre><code class="js">var o = document.getElementsByTagName('iframe')[0];
o.contentWindow.postMessage('Hello world', 'https://b.example.org/');</code></pre>
<p>To register an event handler for incoming events, the script would use <code
data-x="">addEventListener()</code> (or similar mechanisms). For example, the script in document B
might look like:</p>
<pre><code class="js">window.addEventListener('message', receiver, false);
function receiver(e) {
if (e.origin == 'https://example.com') {
if (e.data == 'Hello world') {
e.source.postMessage('Hello', e.origin);
} else {
alert(e.data);
}
}
}</code></pre>
<p>This script first checks the domain is the expected domain, and then looks at the message,
which it either displays to the user, or responds to by sending a message back to the document
which sent the message in the first place.</p>
</div>
<h4 id="security-postmsg">Security</h4>
<div w-nodev>
<h5>Authors</h5>
</div>
<p id="security-4" class="warning">Use of this API requires extra care to protect users from
hostile entities abusing a site for their own purposes.</p>
<p>Authors should check the <code data-x="dom-MessageEvent-origin">origin</code> attribute to
ensure that messages are only accepted from domains that they expect to receive messages from.
Otherwise, bugs in the author's message handling code could be exploited by hostile sites.</p>
<p>Furthermore, even after checking the <code data-x="dom-MessageEvent-origin">origin</code>
attribute, authors should also check that the data in question is of the expected format.
Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
unchecked processing of information sent using the <code
data-x="dom-window-postMessage">postMessage()</code> method could result in the attack being
propagated into the receiver.</p>
<p>Authors should not use the wildcard keyword (*) in the <var>targetOrigin</var>
argument in messages that contain any confidential information, as otherwise there is no way to
guarantee that the message is only delivered to the recipient to which it was intended.</p>
<hr>
<p>Authors who accept messages from any origin are encouraged to consider the risks of a
denial-of-service attack. An attacker could send a high volume of messages; if the receiving page
performs expensive computation or causes network traffic to be sent for each such message, the
attacker's message could be multiplied into a denial-of-service attack. Authors are encouraged to
employ rate limiting (only accepting a certain number of messages per minute) to make such attacks
impractical.</p>
<div w-nodev>
<h5>User agents</h5>
<p>The integrity of this API is based on the inability for scripts of one <span>origin</span> to
post arbitrary events (using <code data-x="">dispatchEvent()</code> or otherwise) to objects in
other origins (those that are not the <span data-x="same origin">same</span>).</p>
<p class="note">Implementers are urged to take extra care in the implementation of this feature.
It allows authors to transmit information from one domain to another domain, which is normally
disallowed for security reasons. It also requires that UAs be careful to allow access to certain
properties but not others.</p>
<hr>
<p>User agents are also encouraged to consider rate-limiting message traffic between different
<span data-x="origin">origins</span>, to protect naïve sites from denial-of-service
attacks.</p>
</div>
<h4>Posting messages</h4>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-window-postMessage-options">postMessage</span>(<var>message</var> [, <var>options</var> ])</code></dt>
<dd>
<p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
and arrays, can contain JavaScript values (strings, numbers, <code>Date</code> objects, etc.),
and can contain certain data objects such as <code>File</code> <code>Blob</code>,
<code>FileList</code>, and <code data-x="idl-ArrayBuffer">ArrayBuffer</code> objects.</p>
<p>Objects listed in the <code data-x="dom-StructuredSerializeOptions-transfer">transfer</code> member
of <var>options</var> are transferred, not just cloned, meaning that they are no longer usable
on the sending side.</p>
<p>A target origin can be specified using the <code
data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</code> member of
<var>options</var>. If not provided, it defaults to "<code data-x="">/</code>". This default
restricts the message to same-origin targets only.</p>
<p>If the origin of the target window doesn't match the given target origin, the message is
discarded, to avoid information leakage. To send the message to the target regardless of origin,
set the target origin to "<code data-x="">*</code>".</p>
<p>Throws a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code> if
<var>transfer</var> array contains duplicate objects or if <var>message</var> could not be
cloned.</p>
</dd>
<dt><code data-x=""><var>window</var>.<span data-x="dom-window-postMessage">postMessage</span>(<var>message</var>, <var>targetOrigin</var> [, <var>transfer</var> ])</code></dt>
<dd><p>This is an alternate version of <code
data-x="dom-window-postMessage-options">postMessage()</code> where the target origin is specified
as a parameter. Calling <code data-x="">window.postMessage(message, target, transfer)</code> is
equivalent to <code data-x="">window.postMessage(message, {targetOrigin,
transfer})</code>.</p></dd>
</dl>
<p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
that has just been navigated to a new <code>Document</code> is likely to result in the message not
receiving its intended recipient: the scripts in the target <span>browsing context</span> have to
have had time to set up listeners for the messages. Thus, for instance, in situations where a
message is to be sent to the <code>Window</code> of newly created child <code>iframe</code>,
authors are advised to have the child <code>Document</code> post a message to their parent
announcing their readiness to receive messages, and for the parent to wait for this message before
beginning posting messages.</p>
<div w-nodev>
<p>The <dfn>window post message steps</dfn>, given a <var>targetWindow</var>, <var>message</var>,
and <var>options</var>, are as follows:</p>
<ol> <!-- a lot of this is similar or identical to port.postMessage -->
<li><p>Let <var>targetRealm</var> be <var>targetWindow</var>'s <span
data-x="concept-global-object-realm">realm</span>.</p></li>
<li><p>Let <var>incumbentSettings</var> be the <span>incumbent settings object</span>.</p></li>
<!-- This is one of the few cases where incumbent is probably the right choice. Current or
relevant would mean that the MessageEvent's source property always points to the "calling"
window, in same-origin cases. See discussion at
https://github.com/whatwg/html/issues/1542#issuecomment-233502636 -->
<li><p>Let <var>targetOrigin</var> be <var>options</var>["<code
data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</code>"].</p></li>
<li><p>If <var>targetOrigin</var> is a single U+002F SOLIDUS character (/), then set
<var>targetOrigin</var> to <var>incumbentSettings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p>
<li>
<p>Otherwise, if <var>targetOrigin</var> is not a single U+002A ASTERISK character (*),
then:</p>
<ol>
<li><p>Let <var>parsedURL</var> be the result of running the <span>URL parser</span> on
<var>targetOrigin</var>.</p></li>
<li><p>If <var>parsedURL</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>targetOrigin</var> to <var>parsedURL</var>'s <span
data-x="concept-url-origin">origin</span>.</p></li>
</ol>
</li>
<li><p>Let <var>transfer</var> be <var>options</var>["<code
data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"].</p></li>
<li><p>Let <var>serializeWithTransferResult</var> be
<span>StructuredSerializeWithTransfer</span>(<var>message</var>, <var>transfer</var>). Rethrow
any exceptions.</p></li>
<li>
<p><span>Queue a global task</span> on the <dfn>posted message task source</dfn> given
<var>targetWindow</var> to run the following steps:</p>
<ol>
<li><p>If the <var>targetOrigin</var> argument is not a single literal U+002A ASTERISK character
(*) and <var>targetWindow</var>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="concept-document-origin">origin</span> is not
<span>same origin</span> with <var>targetOrigin</var>, then return.</p></li>
<li><p>Let <var>origin</var> be the <span data-x="serialization of an
origin">serialization</span> of <var>incumbentSettings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Let <var>source</var> be the <code>WindowProxy</code> object corresponding to
<var>incumbentSettings</var>'s <span data-x="concept-settings-object-global">global
object</span> (a <code>Window</code> object).</p></li>
<li>
<p>Let <var>deserializeRecord</var> be
<span>StructuredDeserializeWithTransfer</span>(<var>serializeWithTransferResult</var>,
<var>targetRealm</var>).</p>
<p>If this throws an exception, catch it, <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-messageerror">messageerror</code> at
<var>targetWindow</var>, using <code>MessageEvent</code>, with the <code
data-x="dom-MessageEvent-origin">origin</code> attribute initialized to <var>origin</var> and
the <code data-x="dom-MessageEvent-source">source</code> attribute initialized to
<var>source</var>, and then return.</p>
</li>
<li><p>Let <var>messageClone</var> be <var>deserializeRecord</var>.[[Deserialized]].</p></li>
<li><p>Let <var>newPorts</var> be a new <span>frozen array</span> consisting of all
<code>MessagePort</code> objects in <var>deserializeRecord</var>.[[TransferredValues]], if any,
maintaining their relative order.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-message">message</code> at <var>targetWindow</var>, using
<code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-origin">origin</code>
attribute initialized to <var>origin</var>, the <code
data-x="dom-MessageEvent-source">source</code> attribute initialized to <var>source</var>, the
<code data-x="dom-MessageEvent-data">data</code> attribute initialized to
<var>messageClone</var>, and the <code data-x="dom-MessageEvent-ports">ports</code> attribute
initialized to <var>newPorts</var>.</p></li>
</ol>
</li>
</ol>
<p>The <code>Window</code> interface's <dfn method for="Window"><code
data-x="dom-window-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> method steps are to run the <span>window post message
steps</span> given <span>this</span>, <var>message</var>, and <var>options</var>.</p>
<p>The <code>Window</code> interface's <dfn method for="Window"><code
data-x="dom-window-postMessage">postMessage(<var>message</var>, <var>targetOrigin</var>,
<var>transfer</var>)</code></dfn> method steps are to run the <span>window post message
steps</span> given <span>this</span>, <var>message</var>, and «[ "<code
data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</code>" →
<var>targetOrigin</var>, "<code data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"
→ <var>transfer</var> ]».</p>
</div>
<h3><dfn>Channel messaging</dfn></h3>
<h4>Introduction</h4>
<!-- NON-NORMATIVE SECTION -->
<p>To enable independent pieces of code (e.g. running in different <span data-x="browsing
context">browsing contexts</span>) to communicate directly, authors can use <span>channel
messaging</span>.</p>
<p>Communication channels in this mechanism are implemented as two-ways pipes, with a port at each
end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are
delivered as DOM events, without interrupting or blocking running <span data-x="concept-task">tasks</span>.</p>
<p>To create a connection (two "entangled" ports), the <code data-x="">MessageChannel()</code>
constructor is called:</p>
<pre><code class="js">var channel = new MessageChannel();</code></pre>
<p>One of the ports is kept as the local port, and the other port is sent to the remote code, e.g.
using <code data-x="dom-window-postMessage">postMessage()</code>:</p>
<pre><code class="js">otherWindow.postMessage('hello', 'https://example.com', [channel.port2]);</code></pre>
<p>To send messages, the <code data-x="dom-MessagePort-postMessage">postMessage()</code> method on
the port is used:</p>
<pre><code class="js">channel.port1.postMessage('hello');</code></pre>
<p>To receive messages, one listens to <code data-x="event-message">message</code> events:</p>
<pre><code class="js">channel.port1.onmessage = handleMessage;
function handleMessage(event) {
// message is in event.data
// ...
}</code></pre>
<p>Data sent on a port can be structured data; for example here an array of strings is passed on a
<code>MessagePort</code>:</p>
<pre><code class="js">port1.postMessage(['hello', 'world']);</code></pre>
<h5>Examples</h5>
<!-- NON-NORMATIVE SECTION -->
<div class="example">
<p>In this example, two JavaScript libraries are connected to each other using
<code>MessagePort</code>s. This allows the libraries to later be hosted in different frames, or
in <code>Worker</code> objects, without any change to the APIs.</p>
<pre><code class="html"><script src="contacts.js"></script> <!-- exposes a contacts object -->
<script src="compose-mail.js"></script> <!-- exposes a composer object -->
<script>
var channel = new MessageChannel();
composer.addContactsProvider(channel.port1);
contacts.registerConsumer(channel.port2);
</script></code></pre>
<p>Here's what the "addContactsProvider()" function's implementation could look like:</p>
<pre><code class="js">function addContactsProvider(port) {
port.onmessage = function (event) {
switch (event.data.messageType) {
case 'search-result': handleSearchResult(event.data.results); break;
case 'search-done': handleSearchDone(); break;
case 'search-error': handleSearchError(event.data.message); break;
// ...
}
};
};</code></pre>
<p>Alternatively, it could be implemented as follows:</p>
<pre><code class="js">function addContactsProvider(port) {
port.addEventListener('message', function (event) {
if (event.data.messageType == 'search-result')
handleSearchResult(event.data.results);
});
port.addEventListener('message', function (event) {
if (event.data.messageType == 'search-done')
handleSearchDone();
});
port.addEventListener('message', function (event) {
if (event.data.messageType == 'search-error')
handleSearchError(event.data.message);
});
// ...
port.start();
};</code></pre>
<p>The key difference is that when using <code
data-x="dom-EventTarget-addEventListener">addEventListener()</code>, the <code
data-x="dom-MessagePort-start">start()</code> method must also be invoked. When using <code
data-x="handler-MessageEventTarget-onmessage">onmessage</code>, the call to <code
data-x="dom-MessagePort-start">start()</code> is implied.</p>
<p>The <code data-x="dom-MessagePort-start">start()</code> method, whether called explicitly or
implicitly (by setting <code data-x="handler-MessageEventTarget-onmessage">onmessage</code>),
starts the flow of messages: messages posted on message ports are initially paused, so that they
don't get dropped on the floor before the script has had a chance to set up its handlers.</p>
</div>
<h5>Ports as the basis of an object-capability model on the web</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Ports can be viewed as a way to expose limited capabilities (in the object-capability model
sense) to other actors in the system. This can either be a weak capability system, where the ports
are merely used as a convenient model within a particular origin, or as a strong capability model,
where they are provided by one origin <var>provider</var> as the only mechanism by which
another origin <var>consumer</var> can effect change in or obtain information from <var>provider</var>.</p>
<p>For example, consider a situation in which a social web site embeds in one <code>iframe</code>
the user's email contacts provider (an address book site, from a second origin), and in a second
<code>iframe</code> a game (from a third origin). The outer social site and the game in the second
<code>iframe</code> cannot access anything inside the first <code>iframe</code>; together they can
only:</p>
<ul>
<li><p><span>Navigate</span> the <code>iframe</code> to a new <span>URL</span>, such as the same
<span>URL</span> but with a different <span data-x="concept-url-fragment">fragment</span>,
causing the <code>Window</code> in the <code>iframe</code> to receive a <code
data-x="event-hashchange">hashchange</code> event.</p></li>
<li><p>Resize the <code>iframe</code>, causing the <code>Window</code> in the <code>iframe</code>
to receive a <code data-x="event-resize">resize</code> event.</p></li>
<!-- anything else? -->
<li><p>Send a <code data-x="event-message">message</code> event to the <code>Window</code> in the
<code>iframe</code> using the <code data-x="dom-window-postMessage">window.postMessage()</code>
API.</p></li>
</ul>
<p>The contacts provider can use these methods, most particularly the third one, to provide an API
that can be accessed by other origins to manipulate the user's address book. For example, it could
respond to a message "<code data-x="">add-contact Guillaume Tell
<tell@pomme.example.net></code>" by adding the given person and email address to the user's
address book.</p>
<p>To avoid any site on the web being able to manipulate the user's contacts, the contacts
provider might only allow certain trusted sites, such as the social site, to do this.</p>
<p>Now suppose the game wanted to add a contact to the user's address book, and that the social
site was willing to allow it to do so on its behalf, essentially "sharing" the trust that the
contacts provider had with the social site. There are several ways it could do this; most simply,
it could just proxy messages between the game site and the contacts site. However, this solution
has a number of difficulties: it requires the social site to either completely trust the game site
not to abuse the privilege, or it requires that the social site verify each request to make sure
it's not a request that it doesn't want to allow (such as adding multiple contacts, reading the
contacts, or deleting them); it also requires some additional complexity if there's ever the
possibility of multiple games simultaneously trying to interact with the contacts provider.</p>
<p>Using message channels and <code>MessagePort</code> objects, however, all of these problems can
go away. When the game tells the social site that it wants to add a contact, the social site can
ask the contacts provider not for it to add a contact, but for the <em>capability</em> to add a
single contact. The contacts provider then creates a pair of <code>MessagePort</code> objects, and
sends one of them back to the social site, who forwards it on to the game. The game and the
contacts provider then have a direct connection, and the contacts provider knows to only honor a
single "add contact" request, nothing else. In other words, the game has been granted the
capability to add a single contact.</p>
<h5>Ports as the basis of abstracting out service implementations</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Continuing the example from the previous section, consider the contacts provider in particular.
While an initial implementation might have simply used <code>XMLHttpRequest</code> objects in the
service's <code>iframe</code>, an evolution of the service might instead want to use a <span
data-x="SharedWorker">shared worker</span> with a single <code>WebSocket</code> connection.</p>
<p>If the initial design used <code>MessagePort</code> objects to grant capabilities, or even just
to allow multiple simultaneous independent sessions, the service implementation can switch from
the <code>XMLHttpRequest</code>s-in-each-<code>iframe</code> model to the
shared-<code>WebSocket</code> model without changing the API at all: the ports on the service
provider side can all be forwarded to the shared worker without it affecting the users of the API
in the slightest.</p>
<h4>Message channels</h4>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>MessageChannel</dfn> {
<span data-x="dom-MessageChannel">constructor</span>();
readonly attribute <span>MessagePort</span> <span data-x="dom-MessageChannel-port1">port1</span>;
readonly attribute <span>MessagePort</span> <span data-x="dom-MessageChannel-port2">port2</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>channel</var> = new <span subdfn data-x="dom-MessageChannel">MessageChannel</span>()</code></dt>
<dd>
<p>Returns a new <code>MessageChannel</code> object with two new <code>MessagePort</code>
objects.</p>
</dd>
<dt><code data-x=""><var>channel</var>.<span subdfn data-x="dom-MessageChannel-port1">port1</span></code></dt>
<dd><p>Returns the first <code>MessagePort</code> object.</p></dd>
<dt><code data-x=""><var>channel</var>.<span subdfn data-x="dom-MessageChannel-port2">port2</span></code></dt>
<dd><p>Returns the second <code>MessagePort</code> object.</p></dd>
</dl>
<div w-nodev>
<p>A <code>MessageChannel</code> object has an associated <dfn>port 1</dfn> and an associated
<dfn>port 2</dfn>, both <code>MessagePort</code> objects.</p>
<p>The <dfn><code data-x="dom-MessageChannel">new MessageChannel()</code></dfn> constructor steps
are:</p>
<ol>
<li><p>Set <span>this</span>'s <span>port 1</span> to a <span>new</span>
<code>MessagePort</code> in <span>this</span>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p>Set <span>this</span>'s <span>port 2</span> to a <span>new</span>
<code>MessagePort</code> in <span>this</span>'s <span data-x="concept-relevant-realm">relevant
realm</span>.</p></li>
<li><p><span>Entangle</span> <span>this</span>'s <span>port 1</span> and <span>this</span>'s
<span>port 2</span>.</p></li>
</ol>
<p>The <dfn attribute for="MessageChannel"><code
data-x="dom-MessageChannel-port1">port1</code></dfn> getter steps are to return
<span>this</span>'s <span>port 1</span>.</p>
<p>The <dfn attribute for="MessageChannel"><code
data-x="dom-MessageChannel-port2">port2</code></dfn> getter steps are to return
<span>this</span>'s <span>port 2</span>.</p>
</div>
<h4 w-nodev><span id="the-messageeventtarget-abstract-interface"></span>The
<code>MessageEventTarget</code> mixin</h4>
<h4 w-dev>Properties present on <code>MessagePort</code>, <code>Worker</code>, and
<code>DedicatedWorkerGlobalScope</code></h4>
<pre><code class="idl">interface mixin <dfn interface>MessageEventTarget</dfn> {
attribute <span>EventHandler</span> <span data-x="handler-MessageEventTarget-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-MessageEventTarget-onmessageerror">onmessageerror</span>;
};</code></pre>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by <span w-nodev>objects implementing the
<code>MessageEventTarget</code> interface</span><span w-dev><code>MessagePort</code>,
<code>Worker</code>, and <code>DedicatedWorkerGlobalScope</code> objects</span>:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><span id="handler-messageport-onmessage"></span><span id="handler-worker-onmessage"></span><span id="handler-dedicatedworkerglobalscope-onmessage"></span><dfn attribute for="MessageEventTarget"><code data-x="handler-MessageEventTarget-onmessage">onmessage</code></dfn> <td> <code data-x="event-message">message</code>
<tr><td><span id="handler-messageport-onmessageerror"></span><span id="handler-worker-onmessageerror"></span><span id="handler-dedicatedworkerglobalscope-onmessageerror"></span><dfn attribute for="MessageEventTarget"><code data-x="handler-MessageEventTarget-onmessageerror">onmessageerror</code></dfn> <td> <code data-x="event-messageerror">messageerror</code>
</table>
<h4>Message ports</h4>
<p>Each channel has two message ports. Data sent through one port is received by the other port,
and vice versa.</p>
<pre><code class="idl">[Exposed=(Window,Worker,AudioWorklet), <span>Transferable</span>]
interface <dfn interface>MessagePort</dfn> : <span>EventTarget</span> {
undefined <span data-x="dom-MessagePort-postMessage">postMessage</span>(any message, sequence<<span data-x="idl-object">object</span>> transfer);
undefined <span data-x="dom-MessagePort-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
undefined <span data-x="dom-MessagePort-start">start</span>();
undefined <span data-x="dom-MessagePort-close">close</span>();
// event handlers
attribute <span>EventHandler</span> <span data-x="handler-MessagePort-onclose">onclose</span>;
};
<span>MessagePort</span> includes <span>MessageEventTarget</span>;
dictionary <dfn dictionary>StructuredSerializeOptions</dfn> {
sequence<<span data-x="idl-object">object</span>> <dfn dict-member for="StructuredSerializeOptions" data-x="dom-StructuredSerializeOptions-transfer">transfer</dfn> = [];
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>port</var>.<span subdfn data-x="dom-MessagePort-postMessage">postMessage</span>(<var>message</var> [, <var>transfer</var>])</code></dt>
<dt><code data-x=""><var>port</var>.<span subdfn data-x="dom-MessagePort-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="">transfer</span> }])</code></dt>
<dd>
<p>Posts a message through the channel. Objects listed in <var>transfer</var> are transferred,
not just cloned, meaning that they are no longer usable on the sending side.</p>
<p>Throws a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code> if
<var>transfer</var> contains duplicate objects or <var>port</var>, or if <var>message</var>
could not be cloned.</p>
</dd>
<dt><code data-x=""><var>port</var>.<span subdfn data-x="dom-MessagePort-start">start</span>()</code></dt>
<dd><p>Begins dispatching messages received on the port.</p></dd>
<dt><code data-x=""><var>port</var>.<span subdfn data-x="dom-MessagePort-close">close</span>()</code></dt>
<dd><p>Disconnects the port, so that it is no longer active.</p></dd>
</dl>
<div w-nodev>
<p>Each <code>MessagePort</code> object has a <dfn>message event target</dfn> (a
<code>MessageEventTarget</code>), to which the <code data-x="event-message">message</code> and <code
data-x="event-messageerror">messageerror</code> events are dispatched. Unless otherwise
specified, it defaults to the <code>MessagePort</code> object itself.</p>
<p>Each <code>MessagePort</code> object can be entangled with another (a symmetric relationship).
Each <code>MessagePort</code> object also has a <span>task source</span> called the <dfn>port
message queue</dfn>, initially empty. A <span>port message queue</span> can be enabled or
disabled, and is initially disabled. Once enabled, a port can never be disabled again (though
messages in the queue can get moved to another queue or removed altogether, which has much the
same effect). A <code>MessagePort</code> also has a <dfn>has been shipped</dfn> flag, which must
initially be false.</p>
<p>When a port's <span>port message queue</span> is enabled, the <span>event loop</span> must use
it as one of its <span data-x="task source">task sources</span>. When a port's <span>relevant
global object</span> is a <code>Window</code>, all <span data-x="concept-task">tasks</span> <span
data-x="queue a task">queued</span> on its <span>port message queue</span> must be associated with
the port's <span>relevant global object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p>
<p class="note">If the document is <span>fully active</span>, but the event listeners were all
created in the context of documents that are <em>not</em> <span>fully active</span>, then the
messages will not be received unless and until the documents become <span>fully active</span>
again.</p>
<p>Each <span>event loop</span> has a <span>task source</span> called the <dfn>unshipped port
message queue</dfn>. This is a virtual <span>task source</span>: it must act as if it contained
the <span data-x="concept-task">tasks</span> of each <span>port message queue</span> of each
<code>MessagePort</code> whose <span>has been shipped</span> flag is false, whose <span>port
message queue</span> is enabled, and whose <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span> is that <span>event loop</span>, in the order
in which they were added to their respective <span>task source</span>. When a <span
data-x="concept-task">task</span> would be removed from the <span>unshipped port message
queue</span>, it must instead be removed from its <span>port message queue</span>.</p>
<p>When a <code>MessagePort</code>'s <span>has been shipped</span> flag is false, its <span>port
message queue</span> must be ignored for the purposes of the <span>event loop</span>. (The
<span>unshipped port message queue</span> is used instead.)</p>
<p class="note">The <span>has been shipped</span> flag is set to true when a port, its twin, or
the object it was cloned from, is or has been transferred. When a <code>MessagePort</code>'s
<span>has been shipped</span> flag is true, its <span>port message queue</span> acts as a
first-class <span>task source</span>, unaffected to any <span>unshipped port message
queue</span>.</p>
<p>When the user agent is to <dfn>entangle</dfn> two <code>MessagePort</code> objects, it must run
the following steps:</p>
<ol>
<li>
<p>If one of the ports is already entangled, then disentangle it and the port that it was
entangled with.</p>
<p class="note">If those two previously entangled ports were the two ports of a
<code>MessageChannel</code> object, then that <code>MessageChannel</code> object no longer
represents an actual channel: the two ports in that object are no longer entangled.</p>
</li>
<li>
<p>Associate the two ports to be entangled, so that they form the two parts of a new channel.
(There is no <code>MessageChannel</code> object that represents this channel.)</p>
<p>Two ports <var>A</var> and <var>B</var> that have gone through this step
are now said to be entangled; one is entangled to the other, and vice versa.</p>
<p class="note">While this specification describes this process as instantaneous,
implementations are more likely to implement it via message passing. As with all algorithms, the
key is "merely" that the end result be indistinguishable, in a black-box sense, from the
specification.</p>
</li>
</ol>
<p>The <dfn>disentangle</dfn> steps, given a <code>MessagePort</code> <var>initiatorPort</var>
which initiates disentangling, are as follows:</p>
<ol>
<li><p>Let <var>otherPort</var> be the <code>MessagePort</code> which <var>initiatorPort</var>
was entangled with.</p></li>
<li><p><span>Assert</span>: <var>otherPort</var> exists.</p></li>
<li><p>Disentangle <var>initiatorPort</var> and <var>otherPort</var>, so that they are no longer
entangled or associated with each other.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-close">close</code> at <var>otherPort</var>.</p></li>
</ol>
<div class="note">
<p>The <code data-x="event-close">close</code> event will be fired even if the port is not
explicitly closed. The cases where this event is dispatched are:</p>
<ul>
<li>the <code data-x="dom-MessagePort-close">close()</code> method was called;</li>
<li>the <code>Document</code> was <span data-x="destroy a document">destroyed</span>; or</li>
<li>the <code>MessagePort</code> was <a href="#ports-and-garbage-collection">garbage
collected</a>.</li>
</ul>
<p>We only dispatch the event on <var>otherPort</var> because <var>initiatorPort</var> explicitly
triggered the close, its <code>Document</code> no longer exists, or it was already garbage
collected, as described above.</p>
</div>
<hr>
<p id="transferMessagePort"><code>MessagePort</code> objects are <span>transferable
objects</span>. Their <span>transfer steps</span>, given <var>value</var> and
<var>dataHolder</var>, are:</p>
<ol>
<li><p>Set <var>value</var>'s <span>has been shipped</span> flag to true.</p></li>
<li><p>Set <var>dataHolder</var>.[[PortMessageQueue]] to <var>value</var>'s <span>port message
queue</span>.</p></li>
<li>
<p>If <var>value</var> is entangled with another port <var>remotePort</var>, then:</p>
<ol>
<li><p>Set <var>remotePort</var>'s <span>has been shipped</span> flag to true.</p></li>
<li><p>Set <var>dataHolder</var>.[[RemotePort]] to <var>remotePort</var>.</p></li>
</ol>
</li>
<li><p>Otherwise, set <var>dataHolder</var>.[[RemotePort]] to null.</p></li>
</ol>
<p>Their <span>transfer-receiving steps</span>, given <var>dataHolder</var> and <var>value</var>,
are:</p>
<ol>
<li><p>Set <var>value</var>'s <span>has been shipped</span> flag to true.</p></li>
<li><p>Move all the <span data-x="concept-task">tasks</span> that are to fire <code
data-x="event-message">message</code> events in <var>dataHolder</var>.[[PortMessageQueue]] to the
<span>port message queue</span> of <var>value</var>, if any, leaving <var>value</var>'s
<span>port message queue</span> in its initial disabled state, and, if <var>value</var>'s
<span>relevant global object</span> is a <code>Window</code>, associating the moved <span
data-x="concept-task">tasks</span> with <var>value</var>'s <span>relevant global object</span>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>If <var>dataHolder</var>.[[RemotePort]] is not null, then <span>entangle</span>
<var>dataHolder</var>.[[RemotePort]] and <var>value</var>. (This will disentangle
<var>dataHolder</var>.[[RemotePort]] from the original port that was transferred.)</p></li>
</ol>
<hr>
<p>The <dfn>message port post message steps</dfn>, given <var>sourcePort</var>,
<var>targetPort</var>, <var>message</var>, and <var>options</var> are as follows:</p>
<ol> <!-- a lot of this is similar or identical to the window post message steps -->
<li><p>Let <var>transfer</var> be <var>options</var>["<code
data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"].</p></li>
<li><p>If <var>transfer</var> <span data-x="list contains">contains</span>
<var>sourcePort</var>, then throw a <span>"<code>DataCloneError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>doomed</var> be false.</p></li>
<li><p>If <var>targetPort</var> is not null and <var>transfer</var> <span data-x="list
contains">contains</span> <var>targetPort</var>, then set <var>doomed</var> to true and
optionally report to a developer console that the target port was posted to itself, causing the
communication channel to be lost.</p></li>
<li><p>Let <var>serializeWithTransferResult</var> be
<span>StructuredSerializeWithTransfer</span>(<var>message</var>, <var>transfer</var>). Rethrow
any exceptions.</p></li>
<li><p>If <var>targetPort</var> is null, or if <var>doomed</var> is true, then return.</p></li>
<!-- we don't throw an exception if there is no target port because this can happen at a moment's
notice. we don't return false because if the port is _about_ to be closed, the message might not
be listened for anyway. we don't do this before the steps above because otherwise you can tell
the difference (in whether the ports have become useless, or in when the structured clone
algorithm runs scripts). We don't throw an exception for 'doomed' being true, because this can't
necessarily be detected right now every time -->
<li>
<p>Add a <span data-x="concept-task">task</span> that runs the following steps to the <span>port
message queue</span> of <var>targetPort</var>:</p>
<ol>
<li>
<p>Let <var>finalTargetPort</var> be the <code>MessagePort</code> in whose <span>port message
queue</span> the task now finds itself.</p>
<p class="note">This can be different from <var>targetPort</var>, if <var>targetPort</var>
itself was transferred and thus all its tasks moved along with it.</p>
</li>
<li><p>Let <var>messageEventTarget</var> be <var>finalTargetPort</var>'s <span>message event
target</span>.</p></li>
<li><p>Let <var>targetRealm</var> be <var>finalTargetPort</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p>Let <var>deserializeRecord</var> be
<span>StructuredDeserializeWithTransfer</span>(<var>serializeWithTransferResult</var>,
<var>targetRealm</var>).</p>
<p>If this throws an exception, catch it, <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-messageerror">messageerror</code> at
<var>messageEventTarget</var>, using <code>MessageEvent</code>, and then return.
</li>
<li><p>Let <var>messageClone</var> be <var>deserializeRecord</var>.[[Deserialized]].</p></li>
<li><p>Let <var>newPorts</var> be a new <span>frozen array</span> consisting of all
<code>MessagePort</code> objects in <var>deserializeRecord</var>.[[TransferredValues]], if any,
maintaining their relative order.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-message">message</code> at <var>messageEventTarget</var>, using
<code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-data">data</code> attribute
initialized to <var>messageClone</var> and the <code
data-x="dom-MessageEvent-ports">ports</code> attribute initialized to
<var>newPorts</var>.</p></li>
</ol>
</li>
</ol>
<p>The <dfn method for="MessagePort"><code
data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>targetPort</var> be the port with which <span>this</span> is entangled, if any;
otherwise let it be null.</p></li>
<li><p>Run the <span>message port post message steps</span> providing <span>this</span>,
<var>targetPort</var>, <var>message</var> and <var>options</var>.</p></li>
</ol>
<p>The <dfn method for="MessagePort"><code
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>targetPort</var> be the port with which <span>this</span> is entangled, if any;
otherwise let it be null.</p></li>
<li><p>Let <var>options</var> be «[ "<code
data-x="dom-StructuredSerializeOptions-transfer">transfer</code>" → <var>transfer</var>
]».</p></li>
<li><p>Run the <span>message port post message steps</span> providing <span>this</span>,
<var>targetPort</var>, <var>message</var> and <var>options</var>.</p></li>
</ol>
<hr>
<p>The <dfn method for="MessagePort"><code data-x="dom-MessagePort-start">start()</code></dfn>
method steps are to enable <span>this</span>'s <span>port message queue</span>, if it is not
already enabled.</p>
<hr>
<p>The <dfn method for="MessagePort"><code data-x="dom-MessagePort-close">close()</code></dfn>
method steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <span>[[Detached]]</span> internal slot value to true.</p></li>
<li><p>If <span>this</span> is entangled, <span>disentangle</span> it.</p></li>
</ol>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>MessagePort</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="MessagePort"><code data-x="handler-MessagePort-onclose">onclose</code></dfn> <td> <code data-x="event-close">close</code>
</table>
<p>The first time a <code>MessagePort</code> object's <code
data-x="handler-MessageEventTarget-onmessage">onmessage</code> IDL attribute is set, the port's
<span>port message queue</span> must be enabled, as if the <code
data-x="dom-MessagePort-start">start()</code> method had been called.</p>
</div>
<h4 id="ports-and-garbage-collection">Ports and garbage collection</h4>
<div w-nodev>
<p>When a <code>MessagePort</code> object <var>o</var> is garbage collected, if <var>o</var> is
entangled, then the user agent must <span data-x="disentangle">disentangle</span>
<var>o</var>.</p>
<p>When a <code>MessagePort</code> object <var>o</var> is entangled and <code
data-x="event-message">message</code> or <code data-x="event-messageerror">messageerror</code>
event listener is registered, user agents must act as if <var>o</var>'s entangled
<code>MessagePort</code> object has a strong reference to <var>o</var>.</p>
<p>Furthermore, a <code>MessagePort</code> object must not be garbage collected while there
exists an event referenced by a <span data-x="concept-task">task</span> in a <span>task
queue</span> that is to be dispatched on that <code>MessagePort</code> object, or while the
<code>MessagePort</code> object's <span>port message queue</span> is enabled and not empty.</p>
<!-- we might not need to explicitly say the first part if UI Events is fixed to say that events
on a task queue prevent GC -->
<!-- ports in the ports attribute of a MessageEvent that isn't dispatched yet are safe because
the MessageEvent is safe -->
<div class="note">
<p>Thus, a message port can be received, given an event listener, and then forgotten, and so long
as that event listener could receive a message, the channel will be maintained.</p>
<p>Of course, if this was to occur on both sides of the channel, then both ports could be garbage
collected, since they would not be reachable from live code, despite having a strong reference to
each other. However, if a message port has a pending message, it is not garbage collected.</p>
</div>
</div>
<p class="note">Authors are strongly encouraged to explicitly close <code>MessagePort</code>
objects to disentangle them, so that their resources can be recollected. Creating many
<code>MessagePort</code> objects and discarding them without closing them can lead to high
transient memory usage since garbage collection is not necessarily performed promptly, especially
for <code>MessagePort</code>s where garbage collection can involve cross-process coordination.</p>
<h3><dfn data-x="broadcast channels">Broadcasting to other browsing contexts</dfn></h3>
<p>Pages on a single <span>origin</span> opened by the same user in the same user agent but in
different unrelated <span data-x="browsing context">browsing contexts</span> sometimes need to
send notifications to each other, for example "hey, the user logged in over here, check your
credentials again".</p>
<p>For elaborate cases, e.g. to manage locking of shared state, to manage synchronization of
resources between a server and multiple local clients, to share a <code>WebSocket</code>
connection with a remote host, and so forth, <span data-x="SharedWorker">shared workers</span> are
the most appropriate solution.</p>
<p>For simple cases, though, where a shared worker would be an unreasonable overhead, authors can
use the simple channel-based broadcast mechanism described in this section.</p>
<pre><code class="idl">[Exposed=(Window,Worker)]
interface <dfn interface>BroadcastChannel</dfn> : <span>EventTarget</span> {
<span data-x="dom-BroadcastChannel">constructor</span>(DOMString name);
readonly attribute DOMString <span data-x="dom-BroadcastChannel-name">name</span>;
undefined <span data-x="dom-BroadcastChannel-postMessage">postMessage</span>(any message);
undefined <span data-x="dom-BroadcastChannel-close">close</span>();
attribute <span>EventHandler</span> <span data-x="handler-BroadcastChannel-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-BroadcastChannel-onmessageerror">onmessageerror</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>broadcastChannel</var> = new <span subdfn data-x="dom-BroadcastChannel">BroadcastChannel</span>(<var>name</var>)</code></dt>
<dd>
<p>Returns a new <code>BroadcastChannel</code> object via which messages for the given channel
name can be sent and received.</p>
</dd>
<dt><code data-x=""><var>broadcastChannel</var>.<span subdfn data-x="dom-BroadcastChannel-name">name</span></code></dt>
<dd><p>Returns the channel name (as passed to the constructor).</p></dd>
<dt><code data-x=""><var>broadcastChannel</var>.<span subdfn data-x="dom-BroadcastChannel-postMessage">postMessage</span>(<var>message</var>)</code></dt>
<dd>
<p>Sends the given message to other <code>BroadcastChannel</code> objects set up for this
channel. Messages can be structured objects, e.g. nested objects and arrays.</p>
</dd>
<dt><code data-x=""><var>broadcastChannel</var>.<span subdfn data-x="dom-BroadcastChannel-close">close</span>()</code></dt>
<dd><p>Closes the <code>BroadcastChannel</code> object, opening it up to garbage
collection.</p></dd>
</dl>
<div w-nodev>
<p>A <code>BroadcastChannel</code> object has a <dfn>channel name</dfn> and a <dfn
data-x="concept-BroadcastChannel-closed">closed flag</dfn>.</p>
<p>The <dfn><code data-x="dom-BroadcastChannel">new BroadcastChannel(<var>name</var>)</code></dfn>
constructor steps are:</p>
<ol>
<li><p>Set <span>this</span>'s <span>channel name</span> to <var>name</var>.</p></li>
<li><p>Set <span>this</span>'s <span data-x="concept-BroadcastChannel-closed">closed flag</span>
to false.</p></li>
</ol>
<p>The <dfn attribute for="BroadcastChannel"><code
data-x="dom-BroadcastChannel-name">name</code></dfn> getter steps are to return
<span>this</span>'s <span>channel name</span>.</p>
<p>A <code>BroadcastChannel</code> object is said to be <dfn>eligible for messaging</dfn> when
its <span>relevant global object</span> is either:</p>
<ul>
<li><p>a <code>Window</code> object whose <span data-x="concept-document-window">associated
<code>Document</code></span> is <span>fully active</span>, or</p></li>
<li><p>a <code>WorkerGlobalScope</code> object whose <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag is false and whose
<span>worker</span> is not a <span>suspendable worker</span>.</p></li>
</ul>
<p>The <dfn method for="BroadcastChannel"><code
data-x="dom-BroadcastChannel-postMessage">postMessage(<var>message</var>)</code></dfn> method
steps are:</p>
<ol>
<li><p>If <span>this</span> is not <span>eligible for messaging</span>, then return.</p></li>
<li><p>If <span>this</span>'s <span data-x="concept-BroadcastChannel-closed">closed flag</span>
is true, then throw an <span>"<code>InvalidStateError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>serialized</var> be <span>StructuredSerialize</span>(<var>message</var>). Rethrow
any exceptions.</p></li>
<li><p>Let <var>sourceOrigin</var> be <span>this</span>'s <span>relevant settings object</span>'s
<span data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Let <var>sourceStorageKey</var> be the result of running <span>obtain a storage key for
non-storage purposes</span> with <span>this</span>'s <span>relevant settings
object</span>.</p></li>
<li>
<p>Let <var>destinations</var> be a list of <code>BroadcastChannel</code> objects that
match the following criteria:</p>
<ul>
<li><p>They are <span>eligible for messaging</span>.</p></li>
<li><p>The result of running <span>obtain a storage key for non-storage purposes</span> with
their <span>relevant settings object</span> <span data-x="storage key equal">equals</span>
<var>sourceStorageKey</var>.</p></li>
<li><p>Their <span>channel name</span> <span>is</span> <span>this</span>'s <span>channel
name</span>.</p></li>
</ul>
</li>
<li><p>Remove <var>source</var> from <var>destinations</var>.</p></li>
<li><p>Sort <var>destinations</var> such that all <code>BroadcastChannel</code> objects whose
<span data-x="relevant agent">relevant agents</span> are the same are sorted in creation order,
oldest first. (This does not define a complete ordering. Within this constraint, user agents may
sort the list in any <span>implementation-defined</span> manner.)</p></li>
<li>
<p>For each <var>destination</var> in <var>destinations</var>, <span>queue a global task</span>
on the <span>DOM manipulation task source</span> given <var>destination</var>'s <span>relevant
global object</span> to perform the following steps:</p>
<ol>
<li><p>If <var>destination</var>'s <span data-x="concept-BroadcastChannel-closed">closed
flag</span> is true, then abort these steps.</p></li>
<li><p>Let <var>targetRealm</var> be <var>destination</var>'s <span
data-x="concept-relevant-realm">relevant realm</span>.</p></li>
<li>
<p>Let <var>data</var> be <span>StructuredDeserialize</span>(<var>serialized</var>,
<var>targetRealm</var>).</p>
<p>If this throws an exception, catch it, <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-messageerror">messageerror</code> at
<var>destination</var>, using <code>MessageEvent</code>, with the <code
data-x="dom-MessageEvent-origin">origin</code> attribute initialized to the <span
data-x="serialization of an origin">serialization</span> of <var>sourceOrigin</var>, and then
abort these steps.</p>
</li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-message">message</code> at <var>destination</var>, using
<code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-data">data</code> attribute
initialized to <var>data</var> and the <code data-x="dom-MessageEvent-origin">origin</code>
attribute initialized to the <span data-x="serialization of an origin">serialization</span> of
<var>sourceOrigin</var>.</p></li>
</ol>
</li>
</ol>
<p>While a <code>BroadcastChannel</code> object whose <span
data-x="concept-BroadcastChannel-closed">closed flag</span> is false has an event listener
registered for <code data-x="event-message">message</code> or <code
data-x="event-messageerror">messageerror</code> events, there must be a strong reference from the
<code>BroadcastChannel</code> object's <span>relevant global object</span> to the
<code>BroadcastChannel</code> object itself.</p>
<p>The <dfn method for="BroadcastChannel"><code
data-x="dom-BroadcastChannel-close">close()</code></dfn> method steps are to set
<span>this</span>'s <span data-x="concept-BroadcastChannel-closed">closed flag</span> to true.</p>
</div>
<p class="note">Authors are strongly encouraged to explicitly close <code>BroadcastChannel</code>
objects when they are no longer needed, so that they can be garbage collected. Creating many
<code>BroadcastChannel</code> objects and discarding them while leaving them with an event
listener and without closing them can lead to an apparent memory leak, since the objects will
continue to live for as long as they have an event listener (or until their page or worker is
closed).</p>
<div w-nodev>
<hr>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by all objects implementing the
<code>BroadcastChannel</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="BroadcastChannel"><code data-x="handler-BroadcastChannel-onmessage">onmessage</code></dfn> <td> <code data-x="event-message">message</code>
<tr><td><dfn attribute for="BroadcastChannel"><code data-x="handler-BroadcastChannel-onmessageerror">onmessageerror</code></dfn> <td> <code data-x="event-messageerror">messageerror</code>
</table>
</div>
<div class="example">
<p>Suppose a page wants to know when the user logs out, even when the user does so from another
tab at the same site:</p>
<pre><code class="js">var authChannel = new BroadcastChannel('auth');
authChannel.onmessage = function (event) {
if (event.data == 'logout')
showLogout();
}
function logoutRequested() {
// called when the user asks us to log them out
doLogout();
showLogout();
authChannel.postMessage('logout');
}
function doLogout() {
// actually log the user out (e.g. clearing cookies)
// ...
}
function showLogout() {
// update the UI to indicate we're logged out
// ...
}</code></pre>
</div>
<h2 split-filename="workers" id="workers" dfn data-lt="web worker" export>Web workers</h2>
<h3>Introduction</h3>
<h4>Scope</h4>
<!-- NON-NORMATIVE SECTION -->
<p>This specification defines an API for running scripts in the background independently of any
user interface scripts.</p>
<p>This allows for long-running scripts that are not interrupted by scripts that respond to clicks
or other user interactions, and allows long tasks to be executed without yielding to keep the page
responsive.</p>
<p>Workers (as these background scripts are called herein) are relatively heavy-weight, and are
not intended to be used in large numbers. For example, it would be inappropriate to launch one
worker for each pixel of a four megapixel image. The examples below show some appropriate uses of
workers.</p>
<p>Generally, workers are expected to be long-lived, have a high start-up performance cost, and a
high per-instance memory cost.</p>
<h4>Examples</h4>
<!-- NON-NORMATIVE SECTION -->
<p>There are a variety of uses that workers can be put to. The following subsections show various
examples of this use.</p>
<h5>A background number-crunching worker</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The simplest use of workers is for performing a computationally
expensive task without interrupting the user interface.</p>
<p>In this example, the main document spawns a worker to (naïvely) compute prime numbers, and
progressively displays the most recently found prime number.</p>
<p>The main page is as follows:</p>
<pre><code class="html">EXAMPLE workers/primes/page.html</code></pre>
<p>The <code data-x="dom-Worker">Worker()</code> constructor call creates a worker and returns a
<code>Worker</code> object representing that worker, which is used to communicate with the worker.
That object's <code data-x="handler-MessageEventTarget-onmessage">onmessage</code> event handler
allows the code to receive messages from the worker.</p>
<p>The worker itself is as follows:</p>
<pre><code class="js">EXAMPLE workers/primes/worker.js</code></pre>
<p>The bulk of this code is simply an unoptimized search for a prime number. The <code
data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage()</code> method is used to send a
message back to the page when a prime is found.</p>
<p><a href="/demos/workers/primes/page.html">View this example online</a>.</p>
<h5 id="module-worker-example">Using a JavaScript module as a worker</h5>
<!-- NON-NORMATIVE SECTION -->
<p>All of our examples so far show workers that run <span data-x="classic script">classic
scripts</span>. Workers can instead be instantiated using <span data-x="module script">module
scripts</span>, which have the usual benefits: the ability to use the JavaScript
<code data-x="">import</code> statement to import other modules; strict mode by default; and
top-level declarations not polluting the worker's global scope.</p>
<p>As the <code data-x="">import</code> statement is available, the <code
data-x="dom-WorkerGlobalScope-importScripts">importScripts()</code> method will automatically fail
inside module workers.</p>
<p>In this example, the main document uses a worker to do off-main-thread image manipulation.
It imports the filters used from another module.</p>
<p>The main page is as follows:</p>
<pre><code class="html">EXAMPLE workers/modules/page.html</code></pre>
<p>The worker file is then:</p>
<pre><code class="js">EXAMPLE workers/modules/worker.js</code></pre>
<p>Which imports the file <code data-x="">filters.js</code>:</p>
<pre><code class="js">EXAMPLE workers/modules/filters.js</code></pre>
<p><a href="/demos/workers/modules/page.html">View this example online</a>.</p>
<h5>Shared workers introduction</h5>
<!-- NON-NORMATIVE SECTION -->
<p>This section introduces shared workers using a Hello World example. Shared workers use slightly
different APIs, since each worker can have multiple connections.</p>
<p>This first example shows how you connect to a worker and how a worker can send a message back
to the page when it connects to it. Received messages are displayed in a log.</p>
<p>Here is the HTML page:</p>
<pre><code class="html">EXAMPLE workers/shared/001/test.html</code></pre>
<p>Here is the JavaScript worker:</p>
<pre><code class="js">EXAMPLE workers/shared/001/test.js</code></pre>
<p><a href="/demos/workers/shared/001/test.html">View this example online</a>.</p>
<hr>
<p>This second example extends the first one by changing two things: first, messages are received
using <code data-x="">addEventListener()</code> instead of an <span data-x="event handler IDL
attributes">event handler IDL attribute</span>, and second, a message is sent <em>to</em> the
worker, causing the worker to send another message in return. Received messages are again
displayed in a log.</p>
<p>Here is the HTML page:</p>
<pre><code class="html">EXAMPLE workers/shared/002/test.html</code></pre>
<p>Here is the JavaScript worker:</p>
<pre><code class="js">EXAMPLE workers/shared/002/test.js</code></pre>
<p><a href="/demos/workers/shared/002/test.html">View this example online</a>.</p>
<hr>
<p>Finally, the example is extended to show how two pages can connect to the same worker; in this
case, the second page is merely in an <code>iframe</code> on the first page, but the same
principle would apply to an entirely separate page in a separate <span>top-level
traversable</span>.</p>
<p>Here is the outer HTML page:</p>
<pre><code class="html">EXAMPLE workers/shared/003/test.html</code></pre>
<p>Here is the inner HTML page:</p>
<pre><code class="html">EXAMPLE workers/shared/003/inner.html</code></pre>
<p>Here is the JavaScript worker:</p>
<pre><code class="js">EXAMPLE workers/shared/003/test.js</code></pre>
<p><a href="/demos/workers/shared/003/test.html">View this example online</a>.</p>
<h5>Shared state using a shared worker</h5>
<!-- NON-NORMATIVE SECTION -->
<p>In this example, multiple windows (viewers) can be opened that are all viewing the same map.
All the windows share the same map information, with a single worker coordinating all the viewers.
Each viewer can move around independently, but if they set any data on the map, all the viewers
are updated.</p>
<p>The main page isn't interesting, it merely provides a way to open the viewers:</p>
<pre><code class="html">EXAMPLE workers/multiviewer/page.html</code></pre>
<p>The viewer is more involved:</p>
<pre><code class="html">EXAMPLE workers/multiviewer/viewer.html</code></pre>
<p>There are several key things worth noting about the way the viewer is written.</p>
<p><strong>Multiple listeners</strong>. Instead of a single message processing function, the code
here attaches multiple event listeners, each one performing a quick check to see if it is relevant
for the message. In this example it doesn't make much difference, but if multiple authors wanted
to collaborate using a single port to communicate with a worker, it would allow for independent
code instead of changes having to all be made to a single event handling function.</p>
<p>Registering event listeners in this way also allows you to unregister specific listeners when
you are done with them, as is done with the <code data-x="">configure()</code> method in this
example.</p>
<p>Finally, the worker:</p>
<pre><code class="js">EXAMPLE workers/multiviewer/worker.js</code></pre>
<p><strong>Connecting to multiple pages</strong>. The script uses the <code
data-x="handler-SharedWorkerGlobalScope-onconnect">onconnect</code> event listener to listen for
multiple connections.</p>
<p><strong>Direct channels</strong>. When the worker receives a "msg" message from one viewer
naming another viewer, it sets up a direct connection between the two, so that the two viewers can
communicate directly without the worker having to proxy all the messages.</p>
<p><a href="/demos/workers/multiviewer/page.html">View this example online</a>.</p>
<h5>Delegation</h5>
<!-- NON-NORMATIVE SECTION -->
<p>With multicore CPUs becoming prevalent, one way to obtain better performance is to split
computationally expensive tasks amongst multiple workers. In this example, a computationally
expensive task that is to be performed for every number from 1 to 10,000,000 is farmed out to ten
subworkers.</p>
<p>The main page is as follows, it just reports the result:</p>
<pre><code class="html">EXAMPLE workers/multicore/page.html</code></pre>
<p>The worker itself is as follows:</p>
<pre><code class="js">EXAMPLE workers/multicore/worker.js</code></pre>
<p>It consists of a loop to start the subworkers, and then a handler
that waits for all the subworkers to respond.</p>
<p>The subworkers are implemented as follows:</p>
<pre><code class="js">EXAMPLE workers/multicore/core.js</code></pre>
<p>They receive two numbers in two events, perform the computation for the range of numbers thus
specified, and then report the result back to the parent.</p>
<p><a href="/demos/workers/multicore/page.html">View this example online</a>.</p>
<h5>Providing libraries</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Suppose that a cryptography library is made available that provides three tasks:</p>
<dl>
<dt>Generate a public/private key pair</dt>
<dd>Takes a port, on which it will send two messages, first the public key and then the private
key.</dd>
<dt>Given a plaintext and a public key, return the corresponding ciphertext</dt>
<dd>Takes a port, to which any number of messages can be sent, the first giving the public key,
and the remainder giving the plaintext, each of which is encrypted and then sent on that same
channel as the ciphertext. The user can close the port when it is done encrypting content.</dd>
<dt>Given a ciphertext and a private key, return the corresponding plaintext</dt>
<dd>Takes a port, to which any number of messages can be sent, the first giving the private key,
and the remainder giving the ciphertext, each of which is decrypted and then sent on that same
channel as the plaintext. The user can close the port when it is done decrypting content.</dd>
</dl>
<p>The library itself is as follows:</p>
<pre><code class="js">EXAMPLE workers/crypto/libcrypto-v1.js</code></pre>
<p>Note that the crypto functions here are just stubs and don't do real cryptography.</p>
<p>This library could be used as follows:</p>
<pre><code class="html">EXAMPLE workers/crypto/page.html</code></pre>
<p>A later version of the API, though, might want to offload all the crypto work onto subworkers.
This could be done as follows:</p>
<pre><code class="js">EXAMPLE workers/crypto/libcrypto-v2.js</code></pre>
<p>The little subworkers would then be as follows.</p>
<p>For generating key pairs:</p>
<pre><code class="js">EXAMPLE workers/crypto/libcrypto-v2-generator.js</code></pre>
<p>For encrypting:</p>
<pre><code class="js">EXAMPLE workers/crypto/libcrypto-v2-encryptor.js</code></pre>
<p>For decrypting:</p>
<pre><code class="js">EXAMPLE workers/crypto/libcrypto-v2-decryptor.js</code></pre>
<p>Notice how the users of the API don't have to even know that this is happening — the API
hasn't changed; the library can delegate to subworkers without changing its API, even though it is
accepting data using message channels.</p>
<p><a href="/demos/workers/crypto/page.html">View this example online</a>.</p>
<h4>Tutorials</h4>
<h5>Creating a dedicated worker</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Creating a worker requires a URL to a JavaScript file. The <code
data-x="dom-Worker">Worker()</code> constructor is invoked with the URL to that file as its only
argument; a worker is then created and returned:</p>
<pre><code class="js">var worker = new Worker('helper.js');</code></pre>
<p>If you want your worker script to be interpreted as a <span>module script</span> instead of
the default <span>classic script</span>, you need to use a slightly different signature:</p>
<pre><code class="js">var worker = new Worker('helper.mjs', { type: "module" });</code></pre>
<h5>Communicating with a dedicated worker</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Dedicated workers use <code>MessagePort</code> objects behind the scenes, and thus support all
the same features, such as sending structured data, transferring binary data, and transferring
other ports.</p>
<p>To receive messages from a dedicated worker, use the <code
data-x="handler-MessageEventTarget-onmessage">onmessage</code> <span data-x="event handler IDL
attributes">event handler IDL attribute</span> on the <code>Worker</code> object:</p>
<pre><code class="js">worker.onmessage = function (event) { ... };</code></pre>
<p>You can also use the <code data-x="dom-EventTarget-addEventListener">addEventListener()</code>
method.</p>
<p class="note">The implicit <code>MessagePort</code> used by dedicated workers has its <span>port
message queue</span> implicitly enabled when it is created, so there is no equivalent to the
<code>MessagePort</code> interface's <code data-x="dom-MessagePort-start">start()</code> method on
the <code>Worker</code> interface.</p>
<p>To <em>send</em> data to a worker, use the <code
data-x="dom-Worker-postMessage">postMessage()</code> method. Structured data can be sent over this
communication channel. To send <code data-x="idl-ArrayBuffer">ArrayBuffer</code> objects
efficiently (by transferring them rather than cloning them), list them in an array in the second
argument.</p>
<pre><code class="js">worker.postMessage({
operation: 'find-edges',
input: buffer, // an ArrayBuffer object
threshold: 0.6,
}, [buffer]);</code></pre>
<p>To receive a message inside the worker, the <code
data-x="handler-MessageEventTarget-onmessage">onmessage</code> <span data-x="event handler
IDL attributes">event handler IDL attribute</span> is used.</p>
<pre><code class="js">onmessage = function (event) { ... };</code></pre>
<p>You can again also use the <code
data-x="dom-EventTarget-addEventListener">addEventListener()</code> method.</p>
<p>In either case, the data is provided in the event object's <code
data-x="dom-MessageEvent-data">data</code> attribute.</p>
<p>To send messages back, you again use <code
data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage()</code>. It supports the
structured data in the same manner.</p>
<pre><code class="js">postMessage(event.data.input, [event.data.input]); // transfer the buffer back</code></pre>
<h5 dfn data-lt="shared worker">Shared workers</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Shared workers are identified by the URL of the script used to create it, optionally with an
explicit name. The name allows multiple instances of a particular shared worker to be started.</p>
<p>Shared workers are scoped by <span>origin</span>. Two different sites using the same names will
not collide. However, if a page tries to use the same shared worker name as another page on the
same site, but with a different script URL, it will fail.</p>
<p>Creating shared workers is done using the <code data-x="dom-SharedWorker">SharedWorker()</code>
constructor. This constructor takes the URL to the script to use for its first argument, and the
name of the worker, if any, as the second argument.</p>
<pre><code class="js">var worker = new SharedWorker('service.js');</code></pre>
<p>Communicating with shared workers is done with explicit <code>MessagePort</code> objects. The
object returned by the <code data-x="dom-SharedWorker">SharedWorker()</code> constructor holds a
reference to the port on its <code data-x="dom-SharedWorker-port">port</code> attribute.</p>
<pre><code class="js">worker.port.onmessage = function (event) { ... };
worker.port.postMessage('some message');
worker.port.postMessage({ foo: 'structured', bar: ['data', 'also', 'possible']});</code></pre>
<p>Inside the shared worker, new clients of the worker are announced using the <code
data-x="event-WorkerGlobalScope-connect">connect</code> event. The port for the new client is
given by the event object's <code data-x="dom-messageevent-source">source</code> attribute.</p>
<pre><code class="js">onconnect = function (event) {
var newPort = event.source;
// set up a listener
newPort.onmessage = function (event) { ... };
// send a message back to the port
newPort.postMessage('ready!'); // can also send structured data, of course
};</code></pre>
<h3>Infrastructure</h3>
<p>This standard defines two kinds of workers: dedicated workers, and shared workers. Dedicated
workers, once created, are linked to their creator, but message ports can be used to communicate
from a dedicated worker to multiple other browsing contexts or workers. Shared workers, on the
other hand, are named, and once created any script running in the same <span>origin</span> can
obtain a reference to that worker and communicate with it. <cite>Service Workers</cite> defines a
third kind. <ref>SW</ref></p>
<h4>The global scope</h4>
<p>The global scope is the "inside" of a worker.</p>
<h5>The <code subdfn>WorkerGlobalScope</code> common interface</h5>
<pre><code class="idl">[Exposed=Worker]
interface <dfn interface>WorkerGlobalScope</dfn> : <span>EventTarget</span> {
readonly attribute <span>WorkerGlobalScope</span> <span data-x="dom-WorkerGlobalScope-self">self</span>;
readonly attribute <span>WorkerLocation</span> <span data-x="dom-WorkerGlobalScope-location">location</span>;
readonly attribute <span>WorkerNavigator</span> <span data-x="dom-worker-navigator">navigator</span>;
undefined <span data-x="dom-WorkerGlobalScope-importScripts">importScripts</span>((<code data-x="tt-trustedscripturl">TrustedScriptURL</code> or USVString)... urls);
attribute <span>OnErrorEventHandler</span> <span data-x="handler-WorkerGlobalScope-onerror">onerror</span>;
attribute <span>EventHandler</span> <span data-x="handler-WorkerGlobalScope-onlanguagechange">onlanguagechange</span>;
attribute <span>EventHandler</span> <span data-x="handler-WorkerGlobalScope-onoffline">onoffline</span>;
attribute <span>EventHandler</span> <span data-x="handler-WorkerGlobalScope-ononline">ononline</span>;
attribute <span>EventHandler</span> <span data-x="handler-WorkerGlobalScope-onrejectionhandled">onrejectionhandled</span>;
attribute <span>EventHandler</span> <span data-x="handler-WorkerGlobalScope-onunhandledrejection">onunhandledrejection</span>;
};</code></pre>
<p><code>WorkerGlobalScope</code> serves as the base class for specific types of worker global
scope objects, including <code>DedicatedWorkerGlobalScope</code>,
<code>SharedWorkerGlobalScope</code>, and <code>ServiceWorkerGlobalScope</code>.</p>
<div w-nodev>
<p id="the-worker's-documents">A <code>WorkerGlobalScope</code> object has an associated <dfn
id="concept-WorkerGlobalScope-owner-set" export for="WorkerGlobalScope">owner set</dfn> (a
<span>set</span> of <code>Document</code> and <code>WorkerGlobalScope</code> objects). It is
initially empty and populated when the worker is created or obtained.</p>
<p class="note">It is a <span>set</span>, instead of a single owner, to accommodate
<code>SharedWorkerGlobalScope</code> objects.</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-type">type</dfn> ("<code data-x="">classic</code>" or "<code
data-x="">module</code>"). It is set during creation.</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-url">url</dfn> (null or a <span>URL</span>). It is initially
null.</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-name">name</dfn> (a string). It is set during creation.</p>
<p class="note">The <span data-x="concept-WorkerGlobalScope-name">name</span> can have different
semantics for each subclass of <code>WorkerGlobalScope</code>. For
<code>DedicatedWorkerGlobalScope</code> instances, it is simply a developer-supplied name, useful
mostly for debugging purposes. For <code>SharedWorkerGlobalScope</code> instances, it allows
obtaining a reference to a common shared worker via the <code
data-x="dom-SharedWorker">SharedWorker()</code> constructor. For
<code>ServiceWorkerGlobalScope</code> objects, it doesn't make sense (and as such isn't exposed
through the JavaScript API at all).</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-policy-container">policy container</dfn> (a <span>policy
container</span>). It is initially a new <span>policy container</span>.</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-embedder-policy">embedder policy</dfn> (an <span>embedder
policy</span>).</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-module-map">module map</dfn>. It is a <span>module map</span>,
initially empty.</p>
<p>A <code>WorkerGlobalScope</code> object has an associated <dfn export for="WorkerGlobalScope"
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</dfn> boolean. It is initially false.</p>
</div>
<dl class="domintro">
<dt><code data-x=""><var>workerGlobal</var>.<span subdfn data-x="dom-WorkerGlobalScope-self">self</span></code></dt>
<dd>Returns <var>workerGlobal</var>.</dd>
<dt><code data-x=""><var>workerGlobal</var>.<span subdfn data-x="dom-WorkerGlobalScope-location">location</span></code></dt>
<dd>Returns <var>workerGlobal</var>'s <code>WorkerLocation</code> object.</dd>
<dt><code data-x=""><var>workerGlobal</var>.<span subdfn data-x="dom-worker-navigator">navigator</span></code></dt>
<dd>Returns <var>workerGlobal</var>'s <code>WorkerNavigator</code> object.</dd>
<dt><code data-x=""><var>workerGlobal</var>.<span subdfn data-x="dom-WorkerGlobalScope-importScripts">importScripts</span>(...<var>urls</var>)</code></dt>
<dd>Fetches each <span>URL</span> in <var>urls</var>, executes them one-by-one in the order they
are passed, and then returns (or throws if something went amiss).</dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="WorkerGlobalScope"><code
data-x="dom-WorkerGlobalScope-self">self</code></dfn> attribute must return the
<code>WorkerGlobalScope</code> object itself.</p>
<p>The <dfn attribute for="WorkerGlobalScope"><code
data-x="dom-WorkerGlobalScope-location">location</code></dfn> attribute must return the
<code>WorkerLocation</code> object whose associated <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span> is
the <code>WorkerGlobalScope</code> object.</p>
<p class="note">While the <code>WorkerLocation</code> object is created after the
<code>WorkerGlobalScope</code> object, this is not problematic as it cannot be observed from
script.</p>
<hr>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by objects implementing the
<code>WorkerGlobalScope</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-onerror">onerror</code></dfn> <td> <code data-x="event-error">error</code>
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-onlanguagechange">onlanguagechange</code></dfn> <td> <code data-x="event-languagechange">languagechange</code> <!-- new -->
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-onoffline">onoffline</code></dfn> <td> <code data-x="event-offline">offline</code> <!-- new -->
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-ononline">ononline</code></dfn> <td> <code data-x="event-online">online</code> <!-- new -->
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-onrejectionhandled">onrejectionhandled</code></dfn> <td> <code data-x="event-rejectionhandled">rejectionhandled</code>
<tr><td><dfn attribute for="WorkerGlobalScope"><code data-x="handler-WorkerGlobalScope-onunhandledrejection">onunhandledrejection</code></dfn> <td> <code data-x="event-unhandledrejection">unhandledrejection</code>
</table>
<h5>Dedicated workers and the <code subdfn>DedicatedWorkerGlobalScope</code> interface</h5>
<pre><code class="idl">[Global=(Worker,DedicatedWorker),Exposed=DedicatedWorker]
interface <dfn interface>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span> {
[Replaceable] readonly attribute DOMString <span data-x="dom-DedicatedWorkerGlobalScope-name">name</span>;
undefined <span data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(any message, sequence<<span data-x="idl-object">object</span>> transfer);
undefined <span data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
undefined <span data-x="dom-DedicatedWorkerGlobalScope-close">close</span>();
};
<span>DedicatedWorkerGlobalScope</span> includes <span>MessageEventTarget</span>;</code></pre>
<p><code>DedicatedWorkerGlobalScope</code> objects have an associated <dfn>inside port</dfn> (a
<code>MessagePort</code>). This port is part of a channel that is set up when the worker is
created, but it is not exposed.<span w-nodev> This object must never be garbage collected before
the <code>DedicatedWorkerGlobalScope</code> object.</span></p>
<dl class="domintro">
<dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-name">name</span></code></dt>
<dd><p>Returns <var>dedicatedWorkerGlobal</var>'s <span
data-x="concept-WorkerGlobalScope-name">name</span>, i.e. the value given to the
<code>Worker</code> constructor. Primarily useful for debugging.</p></dd>
<dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(<var>message</var> [, <var>transfer</var> ])</code></dt>
<dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> } ])</code></dt>
<dd><p>Clones <var>message</var> and transmits it to the <code>Worker</code> object associated
with <var>dedicatedWorkerGlobal</var>. <var>transfer</var> can be passed as a list of objects
that are to be transferred rather than cloned.</p></dd>
<dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-close">close</span>()</code></dt>
<dd><p>Aborts <var>dedicatedWorkerGlobal</var>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="DedicatedWorkerGlobalScope"><code
data-x="dom-DedicatedWorkerGlobalScope-name">name</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-WorkerGlobalScope-name">name</span>. Its value
represents the name given to the worker using the <code>Worker</code> constructor, used primarily
for debugging purposes.</p>
<p>The <dfn method for="DedicatedWorkerGlobalScope"><code
data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> and <dfn method for="DedicatedWorkerGlobalScope"><code
data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> methods on <code>DedicatedWorkerGlobalScope</code> objects act as
if, when invoked, it immediately invoked the respective <code
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>, <var>transfer</var>)</code>
and <code data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code> on the port, with the same arguments, and returned the same return
value.</p>
<p>To <dfn export>close a worker</dfn>, given a <var>workerGlobal</var>, run these steps:</p>
<ol>
<li><p>Discard any <span data-x="concept-task">tasks</span> that have been added to
<var>workerGlobal</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span data-x="task queue">task
queues</span>.</p>
<li><p>Set <var>workerGlobal</var>'s <span data-x="dom-WorkerGlobalScope-closing">closing</span>
flag to true. (This prevents any further tasks from being queued.)</p></li>
</ol>
<p>The <dfn method for="DedicatedWorkerGlobalScope"><code
data-x="dom-DedicatedWorkerGlobalScope-close">close()</code></dfn> method steps are to
<span>close a worker</span> given <span>this</span>.</p>
<hr>
</div>
<h5>Shared workers and the <code subdfn>SharedWorkerGlobalScope</code> interface</h5>
<pre><code class="idl">[Global=(Worker,SharedWorker),Exposed=SharedWorker]
interface <dfn interface>SharedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span> {
[Replaceable] readonly attribute DOMString <span data-x="dom-SharedWorkerGlobalScope-name">name</span>;
undefined <span data-x="dom-SharedWorkerGlobalScope-close">close</span>();
attribute <span>EventHandler</span> <span data-x="handler-SharedWorkerGlobalScope-onconnect">onconnect</span>;
};</code></pre>
<div w-nodev>
<p>A <code>SharedWorkerGlobalScope</code> object has an associated <dfn
for="SharedWorkerGlobalScope"
data-x="concept-SharedWorkerGlobalScope-constructor-origin">constructor origin</dfn>, <dfn
for="SharedWorkerGlobalScope" data-x="concept-SharedWorkerGlobalScope-constructor-url">constructor
url</dfn>, and <dfn for="SharedWorkerGlobalScope"
data-x="concept-SharedWorkerGlobalScope-credentials">credentials</dfn>. They are initialized when
the <code>SharedWorkerGlobalScope</code> object is created, in the <span>run a worker</span>
algorithm.</p>
</div>
<p>Shared workers receive message ports through <code
data-x="event-WorkerGlobalScope-connect">connect</code> events on their <code>SharedWorkerGlobalScope</code> object for each
connection.</p>
<dl class="domintro">
<dt><code data-x=""><var>sharedWorkerGlobal</var>.<span subdfn data-x="dom-SharedWorkerGlobalScope-name">name</span></code></dt>
<dd><p>Returns <var>sharedWorkerGlobal</var>'s <span
data-x="concept-WorkerGlobalScope-name">name</span>, i.e. the value given to the
<code>SharedWorker</code> constructor. Multiple <code>SharedWorker</code> objects can correspond
to the same shared worker (and <code>SharedWorkerGlobalScope</code>), by reusing the same
name.</p></dd>
<dt><code data-x=""><var>sharedWorkerGlobal</var>.<span subdfn data-x="dom-SharedWorkerGlobalScope-close">close</span>()</code></dt>
<dd><p>Aborts <var>sharedWorkerGlobal</var>.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="SharedWorkerGlobalScope"><code
data-x="dom-SharedWorkerGlobalScope-name">name</code></dfn> getter steps are to return
<span>this</span>'s <span data-x="concept-WorkerGlobalScope-name">name</span>. Its value
represents the name that can be used to obtain a reference to the worker using the
<code>SharedWorker</code> constructor.</p>
<p>The <dfn method for="SharedWorkerGlobalScope"><code
data-x="dom-SharedWorkerGlobalScope-close">close()</code></dfn> method steps are to <span>close a
worker</span> given <span>this</span>.</p>
<hr>
</div>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by objects implementing the
<code>SharedWorkerGlobalScope</code> interface:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="SharedWorkerGlobalScope"><code data-x="handler-SharedWorkerGlobalScope-onconnect">onconnect</code></dfn> <td> <code data-x="event-WorkerGlobalScope-connect">connect</code>
</table>
<h4 id="worker-event-loop">The event loop</h4>
<p>A <span>worker event loop</span>'s <span data-x="task queue">task queues</span> only have
events, callbacks, and networking activity as <span data-x="concept-task">tasks</span>.<span
w-nodev> These <span data-x="worker event loop">worker event loops</span> are created by the
<span>run a worker</span> algorithm.</span></p>
<p>Each <code>WorkerGlobalScope</code> object has a <dfn data-x="dom-WorkerGlobalScope-closing"
export for="WorkerGlobalScope">closing</dfn> flag, <span w-nodev>which must be</span> initially
false, but which can get set to true <span w-nodev>by the algorithms in the processing model
section below</span><span w-dev>when the worker is requested to close</span>.</p>
<p>Once the <code>WorkerGlobalScope</code>'s <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag is set to true, the <span>event
loop</span>'s <span data-x="task queue">task queues</span> <span w-nodev>must</span> discard any
further <span data-x="concept-task">tasks</span> that would be added to them (tasks already on the
queue are unaffected except where otherwise specified). Effectively, once the <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag is true, timers stop firing,
notifications for all pending background operations are dropped, etc.</p>
<div w-nodev>
<h4>The worker's lifetime</h4>
<p>Workers communicate with other workers and with <code>Window</code>s through <span
data-x="channel messaging">message channels</span> and their <code>MessagePort</code>
objects.</p>
<p>Each <code>WorkerGlobalScope</code> object <var>worker global scope</var> has a list of
<dfn export>the worker's ports</dfn>, which consists of all the <code>MessagePort</code> objects
that are entangled with another port and that have one (but only one) port owned by <var>worker
global scope</var>. This list includes the implicit <code>MessagePort</code> in the case of <span
data-x="DedicatedWorkerGlobalScope">dedicated workers</span>.</p>
<p id="list-of-relevant-document-objects-to-add">Given an <span>environment settings
object</span> <var>o</var> when creating or obtaining a worker, the <dfn>relevant owner to
add</dfn> depends on the type of <span data-x="concept-settings-object-global">global
object</span> specified by <var>o</var>. If <var>o</var>'s <span
data-x="concept-settings-object-global">global object</span> is a <code>WorkerGlobalScope</code>
object (i.e., if we are creating a nested dedicated worker), then the relevant owner is that
global object. Otherwise, <var>o</var>'s <span data-x="concept-settings-object-global">global
object</span> is a <code>Window</code> object, and the relevant owner is that
<code>Window</code>'s <span data-x="concept-document-window">associated
<code>Document</code></span>.</p>
<hr>
<p>A worker is said to be a <dfn>permissible worker</dfn> if its <code>WorkerGlobalScope</code>'s
<span>owner set</span> is not <span data-x="list is empty">empty</span> or:</p>
<ul class=brief>
<li>its <span>owner set</span> has been <span data-x="list is empty">empty</span> for no more
than a short <span>implementation-defined</span> timeout value,</li>
<li>its <code>WorkerGlobalScope</code> object is a <code>SharedWorkerGlobalScope</code> object
(i.e., the worker is a shared worker), and</li>
<li>the user agent has a <span>navigable</span> whose <span data-x="nav-document">active
document</span> is not <span>completely loaded</span>.</li>
</ul>
<p class="note">The second part of this definition allows a shared worker to survive for a short
time while a page is loading, in case that page is going to contact the shared worker again. This
can be used by user agents as a way to avoid the cost of restarting a shared worker used by a site
when the user is navigating from page to page within that site.</p>
<p>A worker is said to be an <dfn>active needed worker</dfn> if any of its <span data-x="owner
set">owners</span> are either <code>Document</code> objects that are <span>fully active</span> or
<span data-x="active needed worker">active needed workers</span>.</p>
<p>A worker is said to be a <dfn>protected worker</dfn> if it is an <span>active needed
worker</span> and either it has outstanding timers, database transactions, or network connections,
or its list of <span>the worker's ports</span> is not empty, or its <code>WorkerGlobalScope</code>
is actually a <code>SharedWorkerGlobalScope</code> object (i.e., the worker is a shared
worker).</p>
<p>A worker is said to be a <dfn>suspendable worker</dfn> if it is not an <span>active needed
worker</span> but it is a <span>permissible worker</span>.</p>
<h4 id="worker-processing-model"><span id="processing-model-10"></span>Processing model</h4>
<p>When a user agent is to <dfn export>run a worker</dfn> for a script with <code>Worker</code> or
<code>SharedWorker</code> object <var>worker</var>, <span>URL</span> <var>url</var>,
<span>environment settings object</span> <var>outside settings</var>, <code>MessagePort</code>
<var>outside port</var>, and a <code>WorkerOptions</code> dictionary <var>options</var>, it must
run the following steps.</p>
<ol>
<li><p>Let <var>is shared</var> be true if <var>worker</var> is a <code>SharedWorker</code>
object, and false otherwise.</p></li>
<li><p>Let <var>owner</var> be the <span>relevant owner to add</span> given <var>outside
settings</var>.</p></li>
<li><p>Let <var>unsafeWorkerCreationTime</var> be the <span>unsafe shared current
time</span>.</p></li>
<li><p>Let <var>agent</var> be the result of <span data-x="obtain a dedicated/shared worker
agent">obtaining a dedicated/shared worker agent</span> given <var>outside settings</var> and
<var>is shared</var>. Run the rest of these steps in that agent.</p></li>
<li>
<p>Let <var>realm execution context</var> be the result of <span>creating a new realm</span>
given <var>agent</var> and the following customizations:</p>
<ul>
<li><p>For the global object, if <var>is shared</var> is true, create a new
<code>SharedWorkerGlobalScope</code> object. Otherwise, create a new
<code>DedicatedWorkerGlobalScope</code> object.</p></li>
</ul>
</li>
<li>
<p>Let <var>worker global scope</var> be the <span data-x="concept-realm-global">global
object</span> of <var>realm execution context</var>'s Realm component.
<p class="note">This is the <code>DedicatedWorkerGlobalScope</code> or
<code>SharedWorkerGlobalScope</code> object created in the previous step.</p>
</li>
<li><p><span>Set up a worker environment settings object</span> with <var>realm execution
context</var>, <var>outside settings</var>, and <var>unsafeWorkerCreationTime</var>, and let
<var>inside settings</var> be the result.</p></li>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-name">name</span> to the value of <var>options</var>'s
<code data-x="">name</code> member.</p></li>
<li><p><span data-x="set append">Append</span> <var>owner</var> to <var>worker global
scope</var>'s <span>owner set</span>.</p></li>
<li>
<p>If <var>is shared</var> is true, then:</p>
<ol>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-SharedWorkerGlobalScope-constructor-origin">constructor origin</span> to
<var>outside settings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-SharedWorkerGlobalScope-constructor-url">constructor url</span> to
<var>url</var>.</p></li>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-type">type</span> to the value of <var>options</var>'s
<code data-x="">type</code> member.</p></li>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-SharedWorkerGlobalScope-credentials">credentials</span> to the value of
<var>options</var>'s <code data-x="">credentials</code> member.
</p></li>
</ol>
</li>
<li><p>Let <var>destination</var> be "<code data-x="">sharedworker</code>" if <var>is
shared</var> is true, and "<code data-x="">worker</code>" otherwise.</p></li>
<li>
<p>Obtain <var>script</var> by switching on the value of <var>options</var>'s <code
data-x="">type</code> member:</p>
<dl class="switch">
<dt>"<code data-x="">classic</code>"</dt>
<dd><span>Fetch a classic worker script</span> given <var>url</var>, <var>outside
settings</var>, <var>destination</var>, <var>inside settings</var>, and with
<var>onComplete</var> and <var>performFetch</var> as defined below.</dd>
<dt>"<code data-x="">module</code>"</dt>
<dd><span>Fetch a module worker script graph</span> given <var>url</var>, <var>outside
settings</var>, <var>destination</var>, the value of the <code data-x="">credentials</code>
member of <var>options</var>, <var>inside settings</var>, and with <var>onComplete</var> and
<var>performFetch</var> as defined below.</dd>
</dl>
<p>In both cases, let <var>performFetch</var> be the following <span
data-x="fetching-scripts-perform-fetch">perform the fetch hook</span> given <var>request</var>,
<i data-x="fetching-scripts-is-top-level">isTopLevel</i> and <i
data-x="fetching-scripts-processCustomFetchResponse">processCustomFetchResponse</i>:</p>
<ol>
<li><p>If <var>isTopLevel</var> is false, <span data-x="concept-fetch">fetch</span>
<var>request</var> with <i data-x="processResponseConsumeBody">processResponseConsumeBody</i>
set to <var>processCustomFetchResponse</var>, and abort these steps.</p></li>
<li>Set <var>request</var>'s <span data-x="concept-request-reserved-client">reserved
client</span> to <var>inside settings</var>.</li>
<li>
<p><span data-x="concept-fetch">Fetch</span> <var>request</var> with <i
data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to the following steps
given <span data-x="concept-response">response</span> <var>response</var> and null, failure,
or a <span>byte sequence</span> <var>bodyBytes</var>:</p>
<ol>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-url">url</span> to <var>response</var>'s <span
data-x="concept-response-url">url</span>.</p></li>
<li><p><span data-x="initialize worker policy container">Initialize worker global scope's
policy container</span> given <var>worker global scope</var>, <var>response</var>, and
<var>inside settings</var>.</p></li>
<li><p>If the <span>Run CSP initialization for a global object</span> algorithm returns
"<code data-x="">Blocked</code>" when executed upon <var>worker global scope</var>, set
<var>response</var> to a <span>network error</span>. <ref>CSP</ref></p></li>
<li>
<p>If <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-embedder-policy">embedder policy</span>'s <span
data-x="embedder-policy-value">value</span> is <span>compatible with cross-origin
isolation</span> and <var>is shared</var> is true, then set <var>agent</var>'s <span>agent
cluster</span>'s <span data-x="agent-cluster-cross-origin-isolation">cross-origin isolation
mode</span> to "<code data-x="cross-origin-isolation-logical">logical</code>" or "<code
data-x="cross-origin-isolation-concrete">concrete</code>". The one chosen is
<span>implementation-defined</span>.</p>
<p class="XXX">This really ought to be set when the agent cluster is created, which requires
a redesign of this section.</p>
</li>
<li><p>If the result of <span data-x="check a global object's embedder policy">checking a
global object's embedder policy</span> with <var>worker global scope</var>, <var>outside
settings</var>, and <var>response</var> is false, then set <var>response</var> to a
<span>network error</span>.</p></li>
<li><p>Set <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</span> to true if <var>agent</var>'s <span>agent cluster</span>'s <span
data-x="agent-cluster-cross-origin-isolation">cross-origin isolation mode</span> is "<code
data-x="cross-origin-isolation-concrete">concrete</code>".</p></li>
<li><p>If <var>is shared</var> is false and <var>owner</var>'s <span
data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin isolated
capability</span> is false, then set <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</span> to false.</p></li>
<li>
<p>If <var>is shared</var> is false and <var>response</var>'s
<span data-x="concept-response-url">url</span>'s <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">data</code>", then set
<var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</span> to false.</p>
<p class="note">This is a conservative default for now, while we figure out how workers in
general, and <code data-x="data protocol">data:</code> URL workers in particular (which are
cross-origin from their owner), will be treated in the context of permissions policies. See
<a
href="https://github.com/w3c/webappsec-permissions-policy/issues/207">w3c/webappsec-permissions-policy
issue #207</a> for more details.</p>
</li>
<li><p>Run <var>processCustomFetchResponse</var> with <var>response</var> and
<var>bodyBytes</var>.</p></li>
</ol>
</li>
</ol>
<p>In both cases, let <var>onComplete</var> given <var>script</var> be the following steps:</p>
<ol>
<li><p>If <var>script</var> is null or if <var>script</var>'s <span
data-x="concept-script-error-to-rethrow">error to rethrow</span> is non-null, then:</p>
<ol>
<li><p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given
<var>worker</var>'s <span>relevant global object</span> to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
at <var>worker</var>.</p></li>
<li><p>Run the <span data-x="environment discarding steps">environment discarding steps</span>
for <var>inside settings</var>.</p></li>
<li><p>Abort these steps.</p></li>
</ol>
<li><p>Associate <var>worker</var> with <var>worker global scope</var>.</p></li>
<li><p>Let <var>inside port</var> be a <span>new</span> <code>MessagePort</code> object in
<var>inside settings</var>'s <span data-x="environment settings object's
realm">realm</span>.</p></li>
<li>
<p>If <var>is shared</var> is false, then:</p>
<ol>
<li><p>Set <var>inside port</var>'s <span>message event target</span> to <var>worker global
scope</var>.</p></li>
<li><p>Set <var>worker global scope</var>'s <span>inside port</span> to <var>inside
port</var>.</p></li>
</ol>
</li>
<li><p><span>Entangle</span> <var>outside port</var> and <var>inside port</var>.</p></li>
<li><p>Create a new <code>WorkerLocation</code> object and associate it with <var>worker global
scope</var>.</p>
<li>
<p><strong>Closing orphan workers</strong>: Start monitoring the worker such that no sooner than
it stops being a <span>protected worker</span>, and no later than it stops being a
<span>permissible worker</span>, <var>worker global scope</var>'s <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag is set to true.</p>
</li>
<li>
<p><strong>Suspending workers</strong>: Start monitoring the worker, such that whenever
<var>worker global scope</var>'s <span data-x="dom-WorkerGlobalScope-closing">closing</span>
flag is false and the worker is a <span>suspendable worker</span>, the user agent suspends
execution of script in that worker until such time as either the <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag switches to true or the worker stops
being a <span>suspendable worker</span>.</p>
</li>
<li><p>Set <var>inside settings</var>'s <span
data-x="concept-environment-execution-ready-flag">execution ready flag</span>.</p></li>
<li>
<p>If <var>script</var> is a <span>classic script</span>, then <span data-x="run a classic
script">run the classic script</span> <var>script</var>. Otherwise, it is a <span>module
script</span>; <span data-x="run a module script">run the module script</span>
<var>script</var>.</p>
<p class="note">In addition to the usual possibilities of returning a value or failing due to
an exception, this could be <span data-x="abort a running script">prematurely aborted</span> by
the <span>terminate a worker</span> algorithm defined below.</p>
</li>
<li><p>Enable <var>outside port</var>'s <span>port message queue</span>.</p></li>
<li><p>If <var>is shared</var> is false, enable the <span>port message queue</span>
of the worker's implicit port.</p></li>
<li><p>If <var>is shared</var> is true, then <span>queue a global task</span> on <span>DOM
manipulation task source</span> given <var>worker global scope</var> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-WorkerGlobalScope-connect">connect</code> at <var>worker global scope</var>, using
<code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-data">data</code> attribute
initialized to the empty string, the <code data-x="dom-MessageEvent-ports">ports</code> attribute
initialized to a new <span>frozen array</span> containing <var>inside port</var>, and the <code
data-x="dom-MessageEvent-source">source</code> attribute initialized to <var>inside
port</var>.</p></li>
<li><p>Enable the <span data-x="dfn-client-message-queue">client message queue</span> of the
<code>ServiceWorkerContainer</code> object whose associated <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span> is
<var>worker global scope</var>'s <span>relevant settings object</span>.</p></li>
<li>
<p><strong>Event loop<!-- labeled for ease of discussion --></strong>: Run the <span>responsible
event loop</span> specified by <var>inside settings</var> until it is destroyed.</p>
<p class="note">The handling of events or the execution of callbacks by <span
data-x="concept-task">tasks</span> run by the <span>event loop</span> might get <span
data-x="abort a running script">prematurely aborted</span> by the <span>terminate a
worker</span> algorithm defined below.</p>
<p class="note">The worker processing model remains on this step until the event loop is
destroyed, which happens after the <span data-x="dom-WorkerGlobalScope-closing">closing</span>
flag is set to true, as described in the <span>event loop</span> processing model.</p>
</li>
<li>
<p><span data-x="map clear">Clear</span> the <var>worker global scope</var>'s
<span>map of active timers</span>.</p>
</li>
<li>
<p>Disentangle all the ports in the list of <span>the worker's ports</span>.</p>
</li>
<li>
<!-- this has no normative impact but makes it clearer that the worker is irrelevant now, and
doesn't have to survive until its Documents all die off too --> <p><span data-x="list
empty">Empty</span> <var>worker global scope</var>'s <span>owner set</span>.</p>
</li>
</ol>
</li>
</ol>
<hr>
<p>When a user agent is to <dfn export>terminate a worker</dfn>, it must run the following steps
<span>in parallel</span> with the worker's main loop (the "<span>run a worker</span>" processing
model defined above):</p>
<ol>
<li><p>Set the worker's <code>WorkerGlobalScope</code> object's <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag to true.</p></li>
<li><p>If there are any <span data-x="concept-task">tasks</span> queued in the
<code>WorkerGlobalScope</code> object's <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span data-x="task queue">task
queues</span>, discard them without processing them.</p></li>
<li><p><span data-x="abort a running script">Abort the script</span> currently running in the
worker.</p></li>
<li><p>If the worker's <code>WorkerGlobalScope</code> object is actually a
<code>DedicatedWorkerGlobalScope</code> object (i.e. the worker is a dedicated worker), then
empty the <span>port message queue</span> of the port that the worker's implicit port is
entangled with.</p></li>
</ol>
<p>User agents may invoke the <span>terminate a worker</span> algorithm when a worker stops being
an <span>active needed worker</span> and the worker continues executing even after its <span
data-x="dom-WorkerGlobalScope-closing">closing</span> flag was set to true.</p>
</div>
<h4>Runtime script errors</h4>
<p>Whenever an uncaught runtime script error occurs in one of the worker's scripts, if the error
did not occur while handling a previous script error, the user agent will <span data-x="report an
exception">report</span> it for the worker's <code>WorkerGlobalScope</code> object.</p>
<h4>Creating workers</h4>
<h5 w-nodev><span id="the-abstractworker-abstract-interface"></span>The
<code>AbstractWorker</code> mixin</h5>
<h5 w-dev>Properties present on both <code>Worker</code> and <code>SharedWorker</code></h5>
<pre><code class="idl">interface mixin <dfn interface>AbstractWorker</dfn> {
attribute <span>EventHandler</span> <span data-x="handler-AbstractWorker-onerror">onerror</span>;
};</code></pre>
<p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
as <span>event handler IDL attributes</span>, by <span w-nodev>objects implementing the
<code>AbstractWorker</code> interface</span><span w-dev><code>Worker</code> and
<code>SharedWorker</code> objects</span>:</p>
<table>
<thead>
<tr><th><span data-x="event handlers">Event handler</span> <th><span>Event handler event type</span>
<tbody>
<tr><td><dfn attribute for="AbstractWorker"><code data-x="handler-AbstractWorker-onerror">onerror</code></dfn> <td> <code data-x="event-error">error</code>
</table>
<div w-nodev>
<h5>Script settings for workers</h5>
<p>To <dfn>set up a worker environment settings object</dfn>, given a <span>JavaScript execution
context</span> <var>execution context</var>, an <span>environment settings object</span>
<var>outside settings</var>, and a number <var>unsafeWorkerCreationTime</var>:</p>
<ol>
<li><p>Let <var>inherited origin</var> be <var>outside settings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>
<li><p>Let <var>realm</var> be the value of <var>execution context</var>'s Realm
component.</p></li>
<li><p>Let <var>worker global scope</var> be <var>realm</var>'s <span
data-x="concept-realm-global">global object</span>.</p></li>
<li>
<p>Let <var>settings object</var> be a new <span>environment settings object</span> whose algorithms
are defined as follows:</p>
<dl>
<dt>The <span>realm execution context</span></dt>
<dd>
<p>Return <var>execution context</var>.
</dd>
<dt>The <span data-x="concept-settings-object-module-map">module map</span></dt>
<dd>
<p>Return <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-module-map">module map</span>.</p>
</dd>
<dt>The <span>API base URL</span></dt>
<dd>
<p>Return <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-url">url</span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-origin">origin</span></dt>
<dd>
<p>Return a unique <span data-x="concept-origin-opaque">opaque origin</span> if <var>worker
global scope</var>'s <span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-scheme">scheme</span> is "<code data-x="">data</code>", and <var>inherited
origin</var> otherwise.</p>
</dd>
<dt>The <span data-x="concept-settings-object-policy-container">policy container</span></dt>
<dd>
<p>Return <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-policy-container">policy container</span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin
isolated capability</span></dt>
<dd><p>Return <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p></dd>
<dt>The <span data-x="concept-settings-object-time-origin">time origin</span></dt>
<dd><p>Return the result of <span data-x="coarsen time">coarsening</span>
<var>unsafeWorkerCreationTime</var> with <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-cross-origin-isolated-capability">cross-origin isolated
capability</span>.</p></dd>
</dl>
</li>
<li><p>Set <var>settings object</var>'s <span data-x="concept-environment-id">id</span> to a new
unique opaque string, <span data-x="concept-environment-creation-url">creation URL</span> to
<var>worker global scope</var>'s <span>url</span>, <span>top-level creation URL</span> to null,
<span data-x="concept-environment-target-browsing-context">target browsing context</span> to
null, and <span data-x="concept-environment-active-service-worker">active service worker</span>
to null.</p></li>
<li><p>If <var>worker global scope</var> is a <code>DedicatedWorkerGlobalScope</code> object,
then set <var>settings object</var>'s <span>top-level origin</span> to <var>outside
settings</var>'s <span>top-level origin</span>.</p></li>
<li>
<p>Otherwise, set <var>settings object</var>'s <span>top-level origin</span> to an
<span>implementation-defined</span> value.</p>
<p class="XXX">See <a href="https://privacycg.github.io/storage-partitioning/">Client-Side
Storage Partitioning</a> for the latest on properly defining this.</p>
</li>
<li><p>Set <var>realm</var>'s [[HostDefined]] field to <var>settings object</var>.</p></li>
<li><p>Return <var>settings object</var>.</p></li>
</ol>
</div>
<h5>Dedicated workers and the <code subdfn>Worker</code> interface</h5>
<pre><code class="idl">[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface <dfn interface>Worker</dfn> : <span>EventTarget</span> {
<span data-x="dom-Worker">constructor</span>((<code data-x="tt-trustedscripturl">TrustedScriptURL</code> or USVString) scriptURL, optional <span>WorkerOptions</span> options = {});
undefined <span data-x="dom-Worker-terminate">terminate</span>();
undefined <span data-x="dom-Worker-postMessage">postMessage</span>(any message, sequence<<span data-x="idl-object">object</span>> transfer);
undefined <span data-x="dom-Worker-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
};
dictionary <dfn dictionary>WorkerOptions</dfn> {
<span>WorkerType</span> type = "classic";
<span>RequestCredentials</span> credentials = "same-origin"; // credentials is only used if type is "module"
DOMString name = "";
};
enum <dfn enum>WorkerType</dfn> { "classic", "module" };
<span>Worker</span> includes <span>AbstractWorker</span>;
<span>Worker</span> includes <span>MessageEventTarget</span>;</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>worker</var> = new <span subdfn data-x="dom-Worker">Worker</span>(<var>scriptURL</var> [, <var>options</var> ])</code></dt>
<dd><p>Returns a new <code>Worker</code> object. <var>scriptURL</var> will be fetched and
executed in the background, creating a new global environment for which <var>worker</var>
represents the communication channel. <var>options</var> can be used to define the <span
data-x="concept-WorkerGlobalScope-name">name</span> of that global environment via the <code
data-x="">name</code> option, primarily for debugging purposes. It can also ensure this new
global environment supports JavaScript modules (specify <code data-x="">type: "module"</code>),
and if that is specified, can also be used to specify how <var>scriptURL</var> is fetched through
the <code data-x="">credentials</code> option.</p></dd>
<dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-terminate">terminate</span>()</code></dt>
<dd>Aborts <var>worker</var>'s associated global environment.</dd>
<dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-postMessage">postMessage</span>(<var>message</var> [, <var>transfer</var> ])</code></dt>
<dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> } ])</code></dt>
<dd><p>Clones <var>message</var> and transmits it to <var>worker</var>'s global environment.
<var>transfer</var> can be passed as a list of objects that are to be transferred rather than
cloned.</p></dd>
</dl>
<div w-nodev>
<p>Each <code>Worker</code> object has an associated <dfn for="Worker">outside port</dfn> (a
<code>MessagePort</code>). This port is part of a channel that is set up when the worker is
created, but it is not exposed. This object must never be garbage collected before the
<code>Worker</code> object.</p>
<p>The <dfn method for="Worker"><code data-x="dom-Worker-terminate">terminate()</code></dfn>
method, when invoked, must cause the <span>terminate a worker</span> algorithm to be run on the
worker with which the object is associated.</p>
<p>The <dfn method for="Worker"><code
data-x="dom-Worker-postMessage">postMessage(<var>message</var>, <var>transfer</var>)</code></dfn>
and <dfn method for="Worker"><code
data-x="dom-Worker-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> methods on <code>Worker</code> objects act as if, when invoked,
they immediately invoked the respective <code
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>, <var>transfer</var>)</code>
and <code data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code> on <span>this</span>'s <span>outside port</span>, with the same
arguments, and returned the same return value.</p>
</div>
<div class="example">
<p>The <code data-x="dom-Worker-postMessage">postMessage()</code>
method's first argument can be structured data:</p>
<pre><code class="js">worker.postMessage({opcode: 'activate', device: 1938, parameters: [23, 102]});</code></pre>
</div>
<div w-nodev>
<hr>
<p>When the <dfn constructor for="Worker"><code data-x="dom-Worker">Worker(<var>scriptURL</var>,
<var>options</var>)</code></dfn> constructor is invoked, the user agent must run the following
steps:</p>
<ol>
<li><p>Let <var>compliantScriptURL</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedscripturl">TrustedScriptURL</code>, <span>this</span>'s <span>relevant global
object</span>, <var>scriptURL</var>, "<code data-x="">Worker constructor</code>", and "<code
data-x="">script</code>".</p></li>
<li><p>Let <var>outside settings</var> be the <span>current settings object</span>.</p>
<li>
<p>Let <var>worker URL</var> be the result of <span>encoding-parsing a URL</span> given
<var>compliantScriptURL</var>, relative to <var>outside settings</var>.</p>
<p class="note">Any <span data-x="same origin">same-origin</span> URL (including <code
data-x="blob protocol">blob:</code> URLs) can be used. <code data-x="data protocol">data:</code>
URLs can also be used, but they create a worker with an <span
data-x="concept-origin-opaque">opaque origin</span>.</p>
</li>
<li><p>If <var>worker URL</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>worker</var> be a new <code>Worker</code> object.</p></li>
<li><p>Let <var>outside port</var> be a <span>new</span> <code>MessagePort</code> in <var>outside
settings</var>'s <span data-x="environment settings object's realm">realm</span>.</p></li>
<li><p>Set <var>outside port</var>'s <span>message event target</span> to
<var>worker</var>.</p></li>
<li><p>Set <var>worker</var>'s <span>outside port</span> to <var>outside port</var>.</p></li>
<li>
<p>Run this step <span>in parallel</span>:</p>
<ol>
<li><p><span>Run a worker</span> given <var>worker</var>, <var>worker URL</var>, <var>outside
settings</var>, <var>outside port</var>, and <var>options</var>.</p></li>
</ol>
</li>
<li><p>Return <var>worker</var>.</p></li>
</ol>
</div>
<h5>Shared workers and the <code subdfn>SharedWorker</code> interface</h5>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>SharedWorker</dfn> : <span>EventTarget</span> {
<span data-x="dom-SharedWorker">constructor</span>((<code data-x="tt-trustedscripturl">TrustedScriptURL</code> or USVString) scriptURL, optional (DOMString or <span>WorkerOptions</span>) options = {});
readonly attribute <span>MessagePort</span> <span data-x="dom-SharedWorker-port">port</span>;
};
<span>SharedWorker</span> includes <span>AbstractWorker</span>;</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>sharedWorker</var> = new <span subdfn data-x="dom-SharedWorker">SharedWorker</span>(<var>scriptURL</var> [, <var>name</var> ])</code></dt>
<dd><p>Returns a new <code>SharedWorker</code> object. <var>scriptURL</var> will be fetched and
executed in the background, creating a new global environment for which <var>sharedWorker</var>
represents the communication channel. <var>name</var> can be used to define the <span
data-x="concept-WorkerGlobalScope-name">name</span> of that global environment.</p></dd>
<dt><code data-x=""><var>sharedWorker</var> = new <span data-x="dom-SharedWorker">SharedWorker</span>(<var>scriptURL</var> [, <var>options</var> ])</code></dt>
<dd><p>Returns a new <code>SharedWorker</code> object. <var>scriptURL</var> will be fetched and
executed in the background, creating a new global environment for which <var>sharedWorker</var>
represents the communication channel. <var>options</var> can be used to define the <span
data-x="concept-WorkerGlobalScope-name">name</span> of that global environment via the <code
data-x="">name</code> option. It can also ensure this new global environment supports JavaScript
modules (specify <code data-x="">type: "module"</code>), and if that is specified, can also be
used to specify how <var>scriptURL</var> is fetched through the <code
data-x="">credentials</code> option. Note that attempting to construct a shared worker with
<var>options</var> whose <code data-x="">type</code> or <code data-x="">credentials</code> values
mismatch an existing shared worker will cause the returned <var>sharedWorker</var> to fire an
error event and not connect to the existing shared worker.</p></dd>
<dt><code data-x=""><var>sharedWorker</var>.<span subdfn data-x="dom-SharedWorker-port">port</span></code></dt>
<dd><p>Returns <var>sharedWorker</var>'s <code>MessagePort</code> object which can be used to
communicate with the global environment.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="SharedWorker"><code data-x="dom-SharedWorker-port">port</code></dfn>
attribute must return the value it was assigned by the object's constructor. It represents the
<code>MessagePort</code> for communicating with the shared worker.</p>
<p>A user agent has an associated <dfn>shared worker manager</dfn> which is the result of
<span>starting a new parallel queue</span>.</p>
<p class="note">Each user agent has a single <span>shared worker manager</span> for simplicity.
Implementations could use one per <span>origin</span>; that would not be observably different and
enables more concurrency.</p>
<p>When the <dfn constructor for="SharedWorker"><code
data-x="dom-SharedWorker">SharedWorker(<var>scriptURL</var>, <var>options</var>)</code></dfn>
constructor is invoked:</p>
<ol>
<li><p>Let <var>compliantScriptURL</var> be the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedscripturl">TrustedScriptURL</code>, <span>this</span>'s <span>relevant global
object</span>, <var>scriptURL</var>, "<code data-x="">SharedWorker constructor</code>", and
"<code data-x="">script</code>".</p></li>
<li><p>If <var>options</var> is a <code data-x="idl-DOMString">DOMString</code>, set
<var>options</var> to a new <code>WorkerOptions</code> dictionary whose <code
data-x="">name</code> member is set to the value of <var>options</var> and whose other members
are set to their default values.</p></li>
<li><p>Let <var>outside settings</var> be the <span>current settings object</span>.</p></li>
<li>
<p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>compliantScriptURL</var>, relative to <var>outside settings</var>.</p>
<p class="note">Any <span data-x="same origin">same-origin</span> URL (including <code
data-x="blob protocol">blob:</code> URLs) can be used. <code data-x="data protocol">data:</code>
URLs can also be used, but they create a worker with an <span
data-x="concept-origin-opaque">opaque origin</span>.</p>
</li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>worker</var> be a new <code>SharedWorker</code> object.</p></li>
<li><p>Let <var>outside port</var> be a <span>new</span> <code>MessagePort</code> in <var>outside
settings</var>'s <span data-x="environment settings object's realm">realm</span>.</p></li>
<li><p>Assign <var>outside port</var> to the <code data-x="dom-SharedWorker-port">port</code>
attribute of <var>worker</var>.</p></li>
<li><p>Let <var>callerIsSecureContext</var> be true if <var>outside settings</var> is a
<span>secure context</span>; otherwise, false.</p></li>
<li><p>Let <var>outside storage key</var> be the result of running <span>obtain a storage key
for non-storage purposes</span> given <var>outside settings</var>.</p></li>
<li>
<p><span>Enqueue the following steps</span> to the <span>shared worker manager</span>:</p>
<ol>
<li><p>Let <var>worker global scope</var> be null.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>scope</var> in the list of all
<code>SharedWorkerGlobalScope</code> objects:</p>
<ol>
<li><p>Let <var>worker storage key</var> be the result of running <span>obtain a storage
key for non-storage purposes</span> given <var>scope</var>'s <span>relevant settings
object</span>.</p></li>
<li>
<p>If all of the following are true:</p>
<ul>
<li><var>worker storage key</var> <span data-x="storage key equal">equals</span>
<var>outside storage key</var>;</li>
<li><var>scope</var>'s <span data-x="dom-WorkerGlobalScope-closing">closing</span> flag
is false;</li>
<li><var>scope</var>'s <span data-x="concept-SharedWorkerGlobalScope-constructor-url">
constructor url</span> <span data-x="concept-url-equals">equals</span>
<var>urlRecord</var>; and</li>
<li><var>scope</var>'s <span data-x="concept-WorkerGlobalScope-name">name</span> equals
the value of <var>options</var>'s <code data-x="">name</code> member,</li>
</ul>
<p>then:</p>
<ol>
<li><p>Set <var>worker global scope</var> to <var>scope</var>.</p></li>
<li><p><span>Break</span>.</p></li>
</ol>
</li>
</ol>
<p class="note"><code data-x="data protocol">data:</code> URLs create a worker with an <span
data-x="concept-origin-opaque">opaque origin</span>. Both the <span
data-x="concept-SharedWorkerGlobalScope-constructor-origin">constructor origin</span> and
<span data-x="concept-SharedWorkerGlobalScope-constructor-url">constructor url</span> are
compared so the same <code data-x="data protocol">data:</code> URL can be used within an
<span>origin</span> to get to the same <code>SharedWorkerGlobalScope</code> object, but cannot
be used to bypass the <span>same origin</span> restriction.</p>
</li>
<li>
<p>If <var>worker global scope</var> is not null, but the user agent has been
configured to disallow communication between the worker represented by the <var>worker global
scope</var> and the <span data-x="concept-script">scripts</span> whose <span
data-x="concept-script-settings-object">settings object</span> is <var>outside settings</var>,
then set <var>worker global scope</var> to null.</p>
<p class="note">For example, a user agent could have a development mode that isolates a
particular <span>top-level traversable</span> from all other pages, and scripts in that
development mode could be blocked from connecting to shared workers running in the normal
browser mode.</p>
</li>
<li><p>If <var>worker global scope</var> is not null, then check if <var>worker global
scope</var>'s <span data-x="concept-WorkerGlobalScope-type">type</span> and <span
data-x="concept-SharedWorkerGlobalScope-credentials">credentials</span> match the
<var>options</var> values. If not, <span>queue a task</span> to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-error">error</code>
and abort these steps.</p></li>
<li>
<p>If <var>worker global scope</var> is not null, then run these subsubsteps:</p>
<ol>
<li><p>Let <var>settings object</var> be the <span>relevant settings object</span> for
<var>worker global scope</var>.</p></li>
<li><p>Let <var>workerIsSecureContext</var> be true if <var>settings object</var> is a
<span>secure context</span>; otherwise, false.</p></li>
<li><p>If <var>workerIsSecureContext</var> is not <var>callerIsSecureContext</var>, then
<span>queue a task</span> to <span data-x="concept-event-fire">fire an event</span> named
<code data-x="event-error">error</code> at <var>worker</var> and abort these steps.
<ref>SECURE-CONTEXTS</ref></p></li>
<li><p>Associate <var>worker</var> with <var>worker global scope</var>.</p></li>
<li><p>Let <var>inside port</var> be a <span>new</span> <code>MessagePort</code> in
<var>settings object</var>'s <span data-x="environment settings object's
realm">realm</span>.</p></li>
<li><p><span>Entangle</span> <var>outside port</var> and <var>inside port</var>.</p></li>
<li><p><span>Queue a task</span>, using the <span>DOM manipulation task source</span>, to
<span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-WorkerGlobalScope-connect">connect</code> at <var>worker global scope</var>,
using <code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-data">data</code>
attribute initialized to the empty string, the <code
data-x="dom-MessageEvent-ports">ports</code> attribute initialized to a new <span>frozen
array</span> containing only <var>inside port</var>, and the <code
data-x="dom-MessageEvent-source">source</code> attribute initialized to <var>inside
port</var>.</p></li>
<li><p><span data-x="set append">Append</span> the <span>relevant owner to add</span> given
<var>outside settings</var> to <var>worker global scope</var>'s <span>owner
set</span>.</p></li>
</ol>
</li>
<li><p>Otherwise, <span>in parallel</span>, <span>run a worker</span> given <var>worker</var>,
<var>urlRecord</var>, <var>outside settings</var>, <var>outside port</var>, and
<var>options</var>.</p></li>
</ol>
</li>
<li><p>Return <var>worker</var>.</p></li>
</ol>
</div>
<h4 id="navigator.hardwareconcurrency">Concurrent hardware capabilities</h4>
<pre><code class="idl">interface mixin <dfn interface>NavigatorConcurrentHardware</dfn> {
readonly attribute unsigned long long <span data-x="dom-navigator-hardwareConcurrency">hardwareConcurrency</span>;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>self</var>.<span data-x="dom-navigator">navigator</span>.<span subdfn data-x="dom-navigator-hardwareConcurrency">hardwareConcurrency</span></code></dt>
<dd><p>Returns the number of logical processors potentially available to the user agent.</p></dd>
</dl>
<div w-nodev>
<p>
<!--INSERT TRACKING-->
The <dfn attribute for="NavigatorConcurrentHardware"><code
data-x="dom-navigator-hardwareConcurrency">navigator.hardwareConcurrency</code></dfn> attribute's
getter must return a number between 1 and the number of logical processors potentially available
to the user agent. If this cannot be determined, the getter must return 1.</p>
<p>User agents should err toward exposing the number of logical processors available, using lower
values only in cases where there are user-agent specific limits in place (such as a limitation
on the number of <span data-x="Worker">workers</span> that can be created) or when the user agent
desires to limit fingerprinting possibilities.</p>
</div>
<h3>APIs available to workers</h3>
<div w-nodev>
<h4>Importing scripts and libraries</h4>
<p>The <dfn method for="WorkerGlobalScope"><code
data-x="dom-WorkerGlobalScope-importScripts">importScripts(...<var>urls</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>Let <var>urlStrings</var> be « ».</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>url</var> of <var>urls</var>:</p>
<ol>
<li><p><span data-x="list append">Append</span> the result of invoking the <span
data-x="tt-getcompliantstring">Get Trusted Type compliant string</span> algorithm with <code
data-x="tt-trustedscripturl">TrustedScriptURL</code>, <span>this</span>'s <span>relevant global
object</span>, <var>url</var>, "<code data-x="">WorkerGlobalScope importScripts</code>", and
"<code data-x="">script</code>" to <var>urlStrings</var>.</p></li>
</ol>
</li>
<li><p><span>Import scripts into worker global scope</span> given <span>this</span> and
<var>urlStrings</var>.</p></li>
</ol>
<p>To <dfn export>import scripts into worker global scope</dfn>, given a
<code>WorkerGlobalScope</code> object <var>worker global scope</var>, a <span>list</span> of
<span data-x="scalar value string">scalar value strings</span> <var>urls</var>, and an optional
<span data-x="fetching-scripts-perform-fetch">perform the fetch hook</span>
<var>performFetch</var>:</p>
<ol>
<li><p>If <var>worker global scope</var>'s <span
data-x="concept-WorkerGlobalScope-type">type</span> is "<code data-x="">module</code>", throw a
<code>TypeError</code> exception.</p></li>
<li><p>Let <var>settings object</var> be the <span>current settings object</span>.</p></li>
<li><p>If <var>urls</var> is empty, return.</p></li>
<li><p>Let <var>urlRecords</var> be « ».</p></li>
<li>
<p>For each <var>url</var> of <var>urls</var>:</p>
<ol>
<li><p>Let <var>urlRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>url</var>, relative to <var>settings object</var>.</p></li>
<li><p>If <var>urlRecord</var> is failure, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p><span data-x="list append">Append</span> <var>urlRecord</var> to
<var>urlRecords</var>.</p></li>
</ol>
</li>
<li>
<p>For each <var>urlRecord</var> of <var>urlRecords</var>:</p>
<ol>
<li><p><span>Fetch a classic worker-imported script</span> given <var>urlRecord</var> and
<var>settings object</var>, passing along <var>performFetch</var> if provided. If this
succeeds, let <var>script</var> be the result. Otherwise, rethrow the exception.</p></li>
<li>
<p><span data-x="run a classic script">Run the classic script</span> <var>script</var>, with
the rethrow errors argument set to true.</p>
<p class="note"><var>script</var> will run until it either returns, fails to parse, fails to
catch an exception, or gets <span data-x="abort a running script">prematurely aborted</span>
by the <span>terminate a worker</span> algorithm defined above.</p>
<p>If an exception was thrown or if the script was <span data-x="abort a running
script">prematurely aborted</span>, then abort all these steps, letting the exception or
aborting continue to be processed by the calling <span
data-x="concept-script">script</span>.</p>
</li>
</ol>
</li>
</ol>
<p class="note"><cite>Service Workers</cite> is an example of a specification that runs this
algorithm with its own <span data-x="fetching-scripts-perform-fetch">perform the fetch
hook</span>. <ref>SW</ref></p>
</div>
<h4 id="the-workernavigator-object">The <code subdfn>WorkerNavigator</code> interface</h4>
<div w-nodev>
<p>The <dfn attribute for="WorkerGlobalScope"><code
data-x="dom-worker-navigator">navigator</code></dfn> attribute of the
<code>WorkerGlobalScope</code> interface must return an instance of the
<code>WorkerNavigator</code> interface, which represents the identity and state of the user agent
(the client):</p>
</div>
<pre><code class="idl">[Exposed=Worker]
interface <dfn interface>WorkerNavigator</dfn> {};
<span>WorkerNavigator</span> includes <span>NavigatorID</span>;
<span>WorkerNavigator</span> includes <span>NavigatorLanguage</span>;
<span>WorkerNavigator</span> includes <span>NavigatorOnLine</span>;
<span>WorkerNavigator</span> includes <span>NavigatorConcurrentHardware</span>;</code></pre>
<div w-dev>
<p>The <code>WorkerNavigator</code> interface implements a subset of the <code>Navigator</code>
interface, consisting of the following APIs:</p>
<ul class="brief">
<li><a href="#client-identification">Client identification</a></li>
<li><a href="#language-preferences">Language preferences</a></li>
<li><a href="#navigator.online">Browser state</a></li>
<li><a href="#navigator.hardwareconcurrency">Concurrent hardware capabilities</a></li>
</ul>
</div>
<h4 id="worker-locations">The <code subdfn>WorkerLocation</code> interface</h4>
<pre><code class="idl">[Exposed=Worker]
interface <dfn interface>WorkerLocation</dfn> {
stringifier readonly attribute USVString <span data-x="dom-WorkerLocation-href">href</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-origin">origin</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-protocol">protocol</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-host">host</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-hostname">hostname</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-port">port</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-pathname">pathname</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-search">search</span>;
readonly attribute USVString <span data-x="dom-WorkerLocation-hash">hash</span>;
};</code></pre>
<p w-dev>The <code>WorkerLocation</code> interface is like the <code>Location</code> interface,
but lacks the <code data-x="dom-Location-assign">assign()</code>, <code
data-x="dom-Location-replace">replace()</code>, <code data-x="dom-Location-reload">reload()</code>,
and <code data-x="dom-Location-ancestorOrigins">ancestorOrigins</code> members.</p>
<div w-nodev>
<p>A <code>WorkerLocation</code> object has an associated <dfn
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</dfn> (a
<code>WorkerGlobalScope</code> object).
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-href">href</code></dfn> getter steps are to return <span>this</span>'s
<span data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code>
object</span>'s <span data-x="concept-WorkerGlobalScope-url">url</span>, <span
data-x="concept-url-serializer">serialized</span>.</p>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-origin">origin</code></dfn> getter steps are to return the <span
data-x="serialization of an origin">serialization</span> of <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-origin">origin</span>.</p>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-protocol">protocol</code></dfn> getter steps are to return
<span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-scheme">scheme</span>, followed by "<code data-x="">:</code>".</p>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-host">host</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>url</var> be <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-host">host</span> is null, return the empty
string.</p></li>
<li><p>If <var>url</var>'s <span data-x="concept-url-port">port</span> is null, return
<var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>.</p></li>
<li><p>Return <var>url</var>'s <span data-x="concept-url-host">host</span>, <span data-x="host
serializer">serialized</span>, followed by "<code data-x="">:</code>" and <var>url</var>'s <span
data-x="concept-url-port">port</span>, <span data-x="serialize an
integer">serialized</span>.</p></li>
</ol>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-hostname">hostname</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>host</var> be <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-host">host</span>.</p></li>
<li><p>If <var>host</var> is null, return the empty string.</p></li>
<li><p>Return <var>host</var>, <span data-x="host serializer">serialized</span>.</p></li>
</ol>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-port">port</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>port</var> be <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-port">port</span>.</p></li>
<li><p>If <var>port</var> is null, return the empty string.</p></li>
<li><p>Return <var>port</var>, <span data-x="serialize an integer">serialized</span>.</p></li>
</ol>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-pathname">pathname</code></dfn> getter steps are to return the result
of <span data-x="URL path serializer">URL path serializing</span> <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>.</p>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-search">search</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>query</var> be <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-query">query</span>.</p></li>
<li><p>If <var>query</var> is either null or the empty string, return the empty string.</p></li>
<li><p>Return "<code data-x="">?</code>", followed by <var>query</var>.</p></li>
</ol>
<p>The <dfn attribute for="WorkerLocation"><code
data-x="dom-WorkerLocation-hash">hash</code></dfn> getter steps are:</p>
<ol>
<li><p>Let <var>fragment</var> be <span>this</span>'s <span
data-x="concept-WorkerLocation-WorkerGlobalScope"><code>WorkerGlobalScope</code> object</span>'s
<span data-x="concept-WorkerGlobalScope-url">url</span>'s <span
data-x="concept-url-fragment">fragment</span>.</p></li>
<li><p>If <var>fragment</var> is either null or the empty string, return the empty string.</p></li>
<li><p>Return "<code data-x="">#</code>", followed by <var>fragment</var>.</p></li>
</ol>
</div>
<h2 split-filename="worklets" id="worklets">Worklets</h2>
<h3 id="worklets-intro">Introduction</h3>
<!-- NON-NORMATIVE SECTION -->
<p>Worklets are a piece of specification infrastructure which can be used for running scripts
independent of the main JavaScript execution environment, while not requiring any particular
implementation model.</p>
<p>The worklet infrastructure specified here cannot be used directly by web developers. Instead,
other specifications build upon it to create directly-usable worklet types, specialized for
running in particular parts of the browser implementation pipeline.</p>
<h4 id="worklets-motivations">Motivations</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Allowing extension points to rendering, or other sensitive parts of the implementation pipeline
such as audio output, is difficult. If extension points were done with full access to the APIs
available on <code>Window</code>, engines would need to abandon previously-held assumptions for
what could happen in the middle of those phases. For example, during the layout phase, rendering
engines assume that no DOM will be modified.</p>
<p>Additionally, defining extension points in the <code>Window</code> environment would restrict
user agents to performing work in the same thread as the <code>Window</code> object. (Unless
implementations added complex, high-overhead infrastructure to allow thread-safe APIs, as well
as thread-joining guarantees.)</p>
<p>Worklets are designed to allow extension points, while keeping guarantees that user agents
currently rely on. This is done through new global environments, based on subclasses of
<code>WorkletGlobalScope</code>.</p>
<p>Worklets are similar to web workers. However, they:</p>
<ul>
<li><p>Are thread-agnostic. That is, they are not designed to run on a dedicated separate thread,
like each worker is. Implementations can run worklets wherever they choose (including on the main
thread).</p></li>
<li><p>Are able to have multiple duplicate instances of the global scope created, for the purpose
of parallelism.</p></li>
<li><p>Do not use an event-based API. Instead, classes are registered on the global scope, whose
methods are invoked by the user agent.</p></li>
<li><p>Have a reduced API surface on the global scope.</p></li>
<li><p>Have a lifetime for their <span>global object</span> which is defined by other
specifications, often in an <span>implementation-defined</span> manner.</p></li>
</ul>
<p>As worklets have relatively high overhead, they are best used sparingly. Due to this, a given
<code>WorkletGlobalScope</code> is expected to be shared between multiple separate scripts. (This
is similar to how a single <code>Window</code> is shared between multiple separate scripts.)</p>
<p>Worklets are a general technology that serve different use cases. Some worklets, such as those
defined in <cite>CSS Painting API</cite>, provide extension points intended for stateless,
idempotent, and short-running computations, which have special considerations as described in the
next couple of sections. Others, such as those defined in <cite>Web Audio API</cite>, are used for
stateful, long-running operations. <ref>CSSPAINT</ref> <ref>WEBAUDIO</ref></p>
<h4 id="worklets-idempotent">Code idempotence</h4>
<p>Some specifications which use worklets are intended to allow user agents to parallelize work
over multiple threads, or to move work between threads as required. In these specifications, user
agents might invoke methods on a web-developer-provided class in an
<span>implementation-defined</span> order.</p>
<p>As a result of this, to prevent interoperability issues, authors who register classes on such
<code>WorkletGlobalScope</code>s should make their code idempotent. That is, a method or set of
methods on the class should produce the same output given a particular input.</p>
<p>This specification uses the following techniques in order to encourage authors to write code in
an idempotent way:</p>
<ul>
<li>
<p>No reference to the global object is available (i.e., there is no counterpart to <code
data-x="dom-WorkerGlobalScope-self">self</code> on <code>WorkletGlobalScope</code>).</p>
<p class="XXX">Although this was the intention when worklets were first specified, the
introduction of <code data-x="">globalThis</code> has made it no longer true. See <a
href="https://github.com/whatwg/html/issues/6059">issue #6059</a> for more discussion.</p>
</li>
<li><p>Code is loaded as a <span>module script</span>, which results in the code being executed
in strict mode and with no shared <code data-x="">this</code> referencing the global
proxy.</p></li>
</ul>
<p>Together, these restrictions help prevent two different scripts from sharing state using
properties of the <span>global object</span>.</p>
<p>Additionally, specifications which use worklets and intend to allow
<span>implementation-defined</span> behavior must obey the following:</p>
<ul>
<li><p>They must require user agents to always have at least two <code>WorkletGlobalScope</code>
instances per <code>Worklet</code>, and randomly assign a method or set of methods on a class to
a particular <code>WorkletGlobalScope</code> instance. These specifications may provide an
opt-out under memory constraints.</p></li>
<li><p>These specifications must allow user agents to create and destroy instances of their
<code>WorkletGlobalScope</code> subclasses at any time.</p></li>
</ul>
<h4 id="worklets-speculative">Speculative evaluation</h4>
<p>Some specifications which use worklets can invoke methods on a web-developer-provided class
based on the state of the user agent. To increase concurrency between threads, a user agent may
invoke a method speculatively, based on potential future states.</p>
<p>In these specifications, user agents might invoke such methods at any time, and with any
arguments, not just ones corresponding to the current state of the user agent. The results of such
speculative evaluations are not displayed immediately, but can be cached for use if the user agent
state matches the speculated state. This can increase the concurrency between the user agent and
worklet threads.</p>
<p>As a result of this, to prevent interoperability risks between user agents, authors who
register classes on such <code>WorkletGlobalScope</code>s should make their code stateless. That
is, the only effect of invoking a method should be its result, and not any side effects such as
updating mutable state.</p>
<p>The same techniques which encourage <a href="#worklets-idempotent">code idempotence</a> also
encourage authors to write stateless code.</p>
<div class="non-normative">
<h3 id="worklets-examples">Examples</h3>
<!-- NON-NORMATIVE SECTION -->
<p>For these examples, we'll use a fake worklet. The <code>Window</code> object provides two
<code>Worklet</code> instances, which each run code in their own collection of
<code>FakeWorkletGlobalScope</code>s:
<pre class="extract"><code class="idl">partial interface <span>Window</span> {
[SameObject, SecureContext] readonly attribute <span>Worklet</span> <span>fakeWorklet1</span>;
[SameObject, SecureContext] readonly attribute <span>Worklet</span> <span>fakeWorklet2</span>;
};</code></pre>
<dl class="domintro" w-dev>
<dt><code data-x="">window.fakeWorklet1</code></dt>
<dd>Returns one of the fake worklets.</dd>
<dt><code data-x="">window.fakeWorklet2</code></dt>
<dd>Returns another of the fake worklets.</dd>
</dl>
<p><span w-nodev>Each <code>Window</code> has two <code>Worklet</code> instances, <dfn>fake
worklet 1</dfn> and <dfn>fake worklet 2</dfn>. </span>Both of these have their <span>worklet
global scope type</span> set to <code>FakeWorkletGlobalScope</code>, and their <span>worklet
destination type</span> set to "<code data-x="">fakeworklet</code>". User agents should create at
least two <code>FakeWorkletGlobalScope</code> instances per worklet.</p>
<p class="note">"<code data-x="">fakeworklet</code>" is not actually a valid <span
data-x="concept-request-destination">destination</span> per <cite>Fetch</cite>. But this
illustrates how real worklets would generally have their own worklet-type-specific destination.
<ref>FETCH</ref></p>
<div w-nodev>
<p>The <dfn noexport><code>fakeWorklet1</code></dfn> getter steps are to return
<span>this</span>'s <span>fake worklet 1</span>.</p>
<p>The <dfn noexport><code>fakeWorklet2</code></dfn> getter steps are to return
<span>this</span>'s <span>fake worklet 2</span>.</p>
</div>
<hr>
<pre class="extract"><code class="idl">[Global=(Worklet,FakeWorklet),
Exposed=FakeWorklet,
SecureContext]
interface <dfn interface noexport>FakeWorkletGlobalScope</dfn> : <span>WorkletGlobalScope</span> {
undefined <span data-x="dom-FakeWorkletGlobalScope-registerFake">registerFake</span>(DOMString type, <span data-x="idl-Function">Function</span> classConstructor);
};</code></pre>
<p w-dev>Inside a <code subdfn>FakeWorkletGlobalScope</code>, the following global method is
available:</p>
<dl class="domintro" w-dev>
<dt><code data-x="">registerFake(<var>type</var>, <var>classConstructor</var>)</code></dt>
<dd>Registers the JavaScript class given by <var>classConstructor</var> for use when the user
agent later wants to do some operation specified by <var>type</var>.</dd>
</dl>
<div w-nodev>
<p>Each <code>FakeWorkletGlobalScope</code> has a <dfn>registered class constructors map</dfn>,
which is an <span>ordered map</span>, initially empty.</p>
<p>The <dfn data-x="dom-FakeWorkletGlobalScope-registerFake"
noexport><code>registerFake(<var>type</var>, <var>classConstructor</var>)</code></dfn> method
steps are to set <span>this</span>'s <span>registered class constructors
map</span>[<var>type</var>] to <var>classConstructor</var>.</p>
</div>
<h4 id="worklets-examples-loading">Loading scripts</h4>
<!-- NON-NORMATIVE SECTION -->
<p>To load scripts into <span>fake worklet 1</span>, a web developer would write:</p>
<pre><code class="js">window.fakeWorklet1.addModule('script1.mjs');
window.fakeWorklet1.addModule('script2.mjs');</code></pre>
<p>Note that which script finishes fetching and runs first is dependent on network timing: it
could be either <code data-x="">script1.mjs</code> or <code data-x="">script2.mjs</code>. This
generally won't matter for well-written scripts intended to be loaded in worklets, if they follow
the suggestions about preparing for <a href="#worklets-speculative">speculative
evaluation</a>.</p>
<p>If a web developer wants to perform a task only after the scripts have successfully run and
loaded into some worklets, they could write:</p>
<pre><code class="js">Promise.all([
window.fakeWorklet1.addModule('script1.mjs'),
window.fakeWorklet2.addModule('script2.mjs')
]).then(() => {
// Do something which relies on those scripts being loaded.
});</code></pre>
<hr>
<p>Another important point about script-loading is that loaded scripts can be run in multiple
<code>WorkletGlobalScope</code>s per <code>Worklet</code>, as discussed in the section on <a
href="#worklets-idempotent">code idempotence</a>. In particular, the specification above
for <span>fake worklet 1</span> and <span>fake worklet 2</span> require this. So, consider a
scenario such as the following:</p>
<pre><code class="js">// script.mjs
console.log("Hello from a FakeWorkletGlobalScope!");</code></pre>
<pre><code class="js">// app.mjs
window.fakeWorklet1.addModule("script.mjs");</code></pre>
<p>This could result in output such as the following from a user agent's console:</p>
<pre><code data-x="">[fakeWorklet1#1] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#4] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#2] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#3] Hello from a FakeWorkletGlobalScope!</code></pre>
<p>If the user agent at some point decided to kill and restart the third instance of
<code>FakeWorkletGlobalScope</code>, the console would again print <code
data-x="">[fakeWorklet1#3] Hello from a FakeWorkletGlobalScope!</code> when this occurs.</p>
<h4 id="worklets-example-registering">Registering a class and invoking its methods</h4>
<!-- NON-NORMATIVE SECTION -->
<p>Let's say that one of the intended usages of our fake worklet by web developers is to allow
them to customize the highly-complex process of boolean negation. They might register their
customization as follows:</p>
<pre><code class="js">// script.mjs
registerFake('negation-processor', class {
process(arg) {
return !arg;
}
});</code></pre>
<pre><code class="js">// app.mjs
window.fakeWorklet1.addModule("script.mjs");</code></pre>
<p>To make use of such registered classes, the specification for fake worklets could define a <dfn
data-x="FakeWorkletGlobalScope-process">find the opposite of true</dfn> algorithm, given a
<code>Worklet</code> <var>worklet</var><span w-dev>, which invokes the <code
data-x="">process</code> method on any class registered to one of <var>worklet</var>'s global
scopes as having type "<code data-x="">negation-processor</code>", with true as the argument, and
then uses the result in some way.</span><span w-nodev>:</span></p>
<div w-nodev>
<ol>
<li><p>Optionally, <span>create a worklet global scope</span> for <var>worklet</var>.</p></li>
<li><p>Let <var>workletGlobalScope</var> be one of <var>worklet</var>'s <span
data-x="concept-Worklet-global-scopes">global scopes</span>, chosen in an
<span>implementation-defined</span> manner.</p></li>
<li><p>Let <var>classConstructor</var> be <var>workletGlobalScope</var>'s <span>registered class
constructors map</span>["<code data-x="">negation-processor</code>"].</p></li>
<li><p>Let <var>classInstance</var> be the result of <span
data-x="es-constructing-callback-functions">constructing</span> <var>classConstructor</var>, with
no arguments.</p></li>
<li><p>Let <var>function</var> be <span data-x="js-Get">Get</span>(<var>classInstance</var>,
"<code data-x="">process</code>"). Rethrow any exceptions.</p>
<li><p>Let <var>callback</var> be the result of <span
data-x="concept-idl-convert">converting</span> <var>function</var> to a Web IDL <code
data-x="idl-Function">Function</code> instance.</p></li>
<li><p>Return the result of <span data-x="es-invoking-callback-functions">invoking</span>
<var>callback</var> with « true » and "<code data-x="">rethrow</code>", and with <i
data-x="dfn-callback-this-value">callback this value</i> set to
<var>classInstance</var>.</p></li>
</ol>
<p class="note">Another, perhaps better, specification architecture would be to extract the "<code
data-x="">process</code>" property and convert it into a <code
data-x="idl-Function">Function</code> at registration time, as part of the <code
data-x="dom-FakeWorkletGlobalScope-registerFake">registerFake()</code> method steps.</p>
</div>
</div>
<h3 id="worklets-infrastructure">Infrastructure</h3>
<h4 id="worklets-global">The global scope</h4>
<p>Subclasses of <code subdfn>WorkletGlobalScope</code> are used to create <span data-x="global
object">global objects</span> wherein code loaded into a particular <code>Worklet</code> can
execute.</p>
<pre><code class="idl">[Exposed=Worklet, SecureContext]
interface <dfn interface>WorkletGlobalScope</dfn> {};</code></pre>
<p class="note">Other specifications are intended to subclass <code>WorkletGlobalScope</code>,
adding APIs to register a class, as well as other APIs specific for their worklet type.</p>
<div w-nodev>
<p>Each <code>WorkletGlobalScope</code> has an associated <dfn
data-x="concept-WorkletGlobalScope-module-map">module map</dfn>. It is a <span>module map</span>,
initially empty.</p>
</div>
<h5 id="worklet-agents-and-event-loops">Agents and event loops</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Each <code>WorkletGlobalScope</code> is contained in its own <span>worklet agent</span>, which
has its corresponding <span data-x="concept-agent-event-loop">event loop</span>. However, in
practice, implementation of these agents and event loops is expected to be different from most
others.</p>
<p>A <span>worklet agent</span> exists for each <code>WorkletGlobalScope</code> since, in theory,
an implementation could use a separate thread for each <code>WorkletGlobalScope</code> instance,
and allowing this level of parallelism is best done using agents. However, because their
[[CanBlock]] value is false, there is no requirement that agents and threads are one-to-one. This
allows implementations the freedom to execute scripts loaded into a worklet on any thread,
including one running code from other agents with [[CanBlock]] of false, such as the thread of a
<span>similar-origin window agent</span> ("the main thread"). Contrast this with <span
data-x="dedicated worker agent">dedicated worker agents</span>, whose true value for [[CanBlock]]
effectively requires them to get a dedicated operating system thread.</p>
<p>Worklet <span data-x="event loop">event loops</span> are also somewhat special. They are only
used for <span data-x="concept-task">tasks</span> associated with <code
data-x="dom-Worklet-addModule">addModule()</code>, tasks wherein the user agent invokes
author-defined methods, and <span data-x="microtask">microtasks</span>. Thus, even though the <a
href="#event-loop-processing-model">event loop processing model</a> specifies that all event loops
run continuously, implementations can achieve observably-equivalent results using a simpler
strategy, which just <span data-x="es-invoking-callback-functions">invokes</span> author-provided
methods and then relies on that process to <span>perform a microtask checkpoint</span>.</p>
<div w-nodev>
<h5 id="worklets-creation-termination">Creation and termination</h5>
<p>To <dfn export>create a worklet global scope</dfn> for a <code>Worklet</code>
<var>worklet</var>:</p>
<ol>
<li><p>Let <var>outsideSettings</var> be <var>worklet</var>'s <span>relevant settings
object</span>.</p></li>
<li><p>Let <var>agent</var> be the result of <span data-x="obtain a worklet agent">obtaining a
worklet agent</span> given <var>outsideSettings</var>. Run the rest of these steps in that
agent.</p></li>
<li>
<p>Let <var>realmExecutionContext</var> be the result of <span>creating a new realm</span> given
<var>agent</var> and the following customizations:</p>
<ul>
<li><p>For the global object, create a new object of the type given by <var>worklet</var>'s
<span>worklet global scope type</span>.</p></li>
</ul>
</li>
<li><p>Let <var>workletGlobalScope</var> be the <span data-x="concept-realm-global">global
object</span> of <var>realmExecutionContext</var>'s Realm component.</p></li>
<li><p>Let <var>insideSettings</var> be the result of <span data-x="set up a worklet environment
settings object">setting up a worklet environment settings object</span> given
<var>realmExecutionContext</var> and <var>outsideSettings</var>.</p></li>
<li><p>Let <var>pendingAddedModules</var> be a <span data-x="list clone">clone</span> of
<var>worklet</var>'s <span data-x="concept-Worklet-added-modules-list">added modules
list</span>.</p></li>
<li>
<p>Let <var>runNextAddedModule</var> be the following steps:</p>
<ol>
<li>
<p>If <var>pendingAddedModules</var> <span data-x="list is empty">is not empty</span>, then:</p>
<ol>
<li><p>Let <var>moduleURL</var> be the result of <span data-x="dequeue">dequeueing</span>
from <var>pendingAddedModules</var>.</p></li>
<li>
<p><span>Fetch a worklet script graph</span> given <var>moduleURL</var>,
<var>insideSettings</var>, <var>worklet</var>'s <span>worklet destination type</span>, <span
class="XXX">what credentials mode?</span>, <var>insideSettings</var>, <var>worklet</var>'s
<span data-x="concept-Worklet-module-responses-map">module responses map</span>, and with
the following steps given <var>script</var>:</p>
<p class="note">This will not actually perform a network request, as it will just reuse
<span data-x="concept-response">responses</span> from <var>worklet</var>'s <span
data-x="concept-Worklet-module-responses-map">module responses map</span>. The main
purpose of this step is to create a new <var>workletGlobalScope</var>-specific <span>module
script</span> from the <span data-x="concept-response">response</span>.</p>
<ol>
<li><p><span>Assert</span>: <var>script</var> is not null, since the fetch succeeded and
the source text was successfully parsed when <var>worklet</var>'s <span
data-x="concept-Worklet-module-responses-map">module responses map</span> was initially
populated with <var>moduleURL</var>.</p></li>
<li><p><span>Run a module script</span> given <var>script</var>.</p></li>
<li><p>Run <var>runNextAddedModule</var>.</p></li>
</ol>
</li>
<li>Abort these steps.</li>
</ol>
</li>
<li><p><span data-x="list append">Append</span> <var>workletGlobalScope</var> to
<var>outsideSettings</var>'s <span data-x="concept-settings-object-global">global
object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span data-x="concept-Document-worklet-global-scopes">worklet
global scopes</span>.</p></li>
<li><p><span data-x="list append">Append</span> <var>workletGlobalScope</var> to
<var>worklet</var>'s <span data-x="concept-Worklet-global-scopes">global
scopes</span>.</p></li>
<li><p>Run the <span>responsible event loop</span> specified by
<var>insideSettings</var>.</p></li>
</ol>
</li>
<li><p>Run <var>runNextAddedModule</var>.</p></li>
</ol>
<p>To <dfn export>terminate a worklet global scope</dfn> given a <code>WorkletGlobalScope</code>
<var>workletGlobalScope</var>:</p>
<ol>
<li><p>Let <var>eventLoop</var> be <var>workletGlobalScope</var>'s <span>relevant agent</span>'s
<span data-x="concept-agent-event-loop">event loop</span>.</p></li>
<li><p>If there are any <span data-x="concept-task">tasks</span> queued in <var>eventLoop</var>'s
<span data-x="task queue">task queues</span>, discard them without processing them.</p></li>
<li><p>Wait for <var>eventLoop</var> to complete the <span>currently running
task</span>.</p></li>
<li><p>If the previous step doesn't complete within an <span>implementation-defined</span> period
of time, then <span data-x="abort a running script">abort the script</span> currently running in
the worklet.</p></li>
<li><p>Destroy <var>eventLoop</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>workletGlobalScope</var> from the <span
data-x="concept-Worklet-global-scopes">global scopes</span> of the <code>Worklet</code> whose
<span data-x="concept-Worklet-global-scopes">global scopes</span> contains
<var>workletGlobalScope</var>.</p></li>
<li><p><span data-x="list remove">Remove</span> <var>workletGlobalScope</var> from the <span
data-x="concept-Document-worklet-global-scopes">worklet global scopes</span> of the
<code>Document</code> whose <span data-x="concept-Document-worklet-global-scopes">worklet global
scopes</span> contains <var>workletGlobalScope</var>.</p></li>
</ol>
<h5>Script settings for worklets</h5>
<p>To <dfn>set up a worklet environment settings object</dfn>, given a <span>JavaScript
execution context</span> <var>executionContext</var> and an <span>environment settings
object</span> <var>outsideSettings</var>:</p>
<ol>
<li><p>Let <var>origin</var> be a unique <span data-x="concept-origin-opaque">opaque
origin</span>.</p></li>
<li><p>Let <var>inheritedAPIBaseURL</var> be <var>outsideSettings</var>'s <span>API base
URL</span>.</p></li>
<li><p>Let <var>inheritedPolicyContainer</var> be a <span data-x="clone a policy
container">clone</span> of <var>outsideSettings</var>'s <span
data-x="concept-settings-object-policy-container">policy container</span>.</p></li>
<li><p>Let <var>realm</var> be the value of <var>executionContext</var>'s Realm
component.</p></li>
<li><p>Let <var>workletGlobalScope</var> be <var>realm</var>'s <span
data-x="concept-realm-global">global object</span>.</p></li>
<li>
<p>Let <var>settingsObject</var> be a new <span>environment settings object</span> whose
algorithms are defined as follows:</p>
<dl>
<dt>The <span>realm execution context</span></dt>
<dd>
<p>Return <var>executionContext</var>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-module-map">module map</span></dt>
<dd>
<p>Return <var>workletGlobalScope</var>'s <span
data-x="concept-WorkletGlobalScope-module-map">module map</span>.</p>
</dd>
<dt>The <span>API base URL</span></dt>
<dd>
<p>Return <var>inheritedAPIBaseURL</var>.</p>
<p class="note">Unlike workers or other globals derived from a single resource, worklets have
no primary resource; instead, multiple scripts, each with their own URL, are loaded into the
global scope via <code
data-x="dom-Worklet-addModule">worklet.addModule()</code>. So this <span>API base URL</span>
is rather unlike that of other globals. However, so far this doesn't matter, as no APIs
available to worklet code make use of the <span>API base URL</span>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-origin">origin</span></dt>
<dd>
<p>Return <var>origin</var>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-policy-container">policy container</span></dt>
<dd>
<p>Return <var>inheritedPolicyContainer</var>.</p>
</dd>
<dt>The <span data-x="concept-settings-object-cross-origin-isolated-capability">cross-origin
isolated capability</span></dt>
<dd><p>Return <span class="XXX">TODO</span>.</p></dd>
<dt>The <span data-x="concept-settings-object-time-origin">time origin</span></dt>
<dd><p><span>Assert</span>: this algorithm is never called, because the <span
data-x="concept-settings-object-time-origin">time origin</span> is not available in a worklet
context.</p></dd>
</dl>
</li>
<li><p>Set <var>settingsObject</var>'s <span data-x="concept-environment-id">id</span> to a new
unique opaque string, <span data-x="concept-environment-creation-url">creation URL</span> to
<var>inheritedAPIBaseURL</var>, <span>top-level creation URL</span> to null, <span>top-level
origin</span> to <var>outsideSettings</var>'s <span>top-level origin</span>, <span
data-x="concept-environment-target-browsing-context">target browsing context</span> to null, and
<span data-x="concept-environment-active-service-worker">active service worker</span> to
null.</p></li>
<li><p>Set <var>realm</var>'s [[HostDefined]] field to <var>settingsObject</var>.</p></li>
<li><p>Return <var>settingsObject</var>.</p></li>
</ol>
</div>
<h4 id="worklets-worklet">The <code>Worklet</code> class</h4>
<p>The <code subdfn>Worklet</code> class provides the capability to add module scripts into its
associated <code>WorkletGlobalScope</code>s. The user agent can then create classes registered on
the <code>WorkletGlobalScope</code>s and invoke their methods.</p>
<pre><code class="idl">[Exposed=Window, SecureContext]
interface <dfn interface>Worklet</dfn> {
[NewObject] <span data-x="idl-Promise">Promise</span><undefined> <span data-x="dom-Worklet-addModule">addModule</span>(USVString moduleURL, optional <span>WorkletOptions</span> options = {});
};
dictionary <dfn dictionary>WorkletOptions</dfn> {
<span>RequestCredentials</span> <dfn dict-member for="WorkletOptions" data-x="dom-WorkletOptions-credentials">credentials</dfn> = "same-origin";
};</code></pre>
<p>Specifications that create <code>Worklet</code> instances must specify the following for a
given instance:</p>
<ul>
<li><p>its <dfn export>worklet global scope type</dfn>, which must be a Web IDL type that <span
data-x="inherit">inherits</span> from <code>WorkletGlobalScope</code>; and</p></li>
<li><p>its <dfn export>worklet destination type</dfn>, which must be a <span
data-x="concept-request-destination">destination</span>, and is used when fetching
scripts.</p></li>
</ul>
<dl class="domintro">
<dt><code data-x="">await <var>worklet</var>.<span subdfn data-x="dom-Worklet-addModule">addModule</span>(<var>moduleURL</var>[, { <span data-x="dom-WorkletOptions-credentials">credentials</span> }])</code></dt>
<dd>
<p>Loads and executes the <span>module script</span> given by <var>moduleURL</var> into all of
<var>worklet</var>'s <span data-x="concept-Worklet-global-scopes">global scopes</span>. It can
also create additional global scopes as part of this process, depending on the worklet type. The
returned promise will fulfill once the script has been successfully loaded and run in all global
scopes.</p>
<p>The <code data-x="dom-WorkletOptions-credentials">credentials</code> option can be set to a
<span data-x="concept-request-credentials-mode">credentials mode</span> to modify the
script-fetching process. It defaults to "<code data-x="">same-origin</code>".</p>
<p>Any failures in <span data-x="fetch a worklet script graph">fetching</span> the script or its
dependencies will cause the returned promise to be rejected with an
<span>"<code>AbortError</code>"</span> <code>DOMException</code>. Any errors in parsing the
script or its dependencies will cause the returned promise to be rejected with the exception
generated during parsing.</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Worklet</code> has a <span>list</span> of <dfn
data-x="concept-Worklet-global-scopes" export for="Worklet">global scopes</dfn>, which contains
instances of the <code>Worklet</code>'s <span>worklet global scope type</span>. It is initially
empty.</p>
<p>A <code>Worklet</code> has an <dfn data-x="concept-Worklet-added-modules-list">added modules
list</dfn>, which is a <span>list</span> of <span data-x="URL">URLs</span>, initially empty.
Access to this list should be thread-safe.</p>
<p>A <code>Worklet</code> has a <dfn data-x="concept-Worklet-module-responses-map">module
responses map</dfn>, which is an <span>ordered map</span> from <span data-x="URL">URLs</span> to
either "<code data-x="">fetching</code>" or <span data-x="tuple">tuples</span> consisting of a
<span data-x="concept-response">response</span> and either null, failure, or a <span>byte
sequence</span> representing the response body. This map is initially empty, and access to it
should be thread-safe.</p>
<div class="note">
<p>The <span data-x="concept-Worklet-added-modules-list">added modules list</span> and <span
data-x="concept-Worklet-module-responses-map">module responses map</span> exist to ensure that
<code>WorkletGlobalScope</code>s created at different times get equivalent <span data-x="module
script">module scripts</span> run in them, based on the same source text. This allows the
creation of additional <code>WorkletGlobalScope</code>s to be transparent to the author.</p>
<p>In practice, user agents are not expected to implement these data structures, and the
algorithms that consult them, using thread-safe programming techniques. Instead, when <code
data-x="dom-Worklet-addModule">addModule()</code> is called, user agents can fetch the module
graph on the main thread, and send the fetched source text (i.e., the important data contained in
the <span data-x="concept-Worklet-module-responses-map">module responses map</span>) to each
thread which has a <code>WorkletGlobalScope</code>.</p>
<p>Then, when a user agent <span data-x="create a worklet global scope">creates</span> a new
<code>WorkletGlobalScope</code> for a given <code>Worklet</code>, it can simply send the map of
fetched source text and the list of entry points from the main thread to the thread containing
the new <code>WorkletGlobalScope</code>.</p>
</div>
<p>The <dfn method for="Worklet"
data-x="dom-Worklet-addModule"><code>addModule(<var>moduleURL</var>,
<var>options</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>outsideSettings</var> be the <span>relevant settings object</span> of
<span>this</span>.</p></li>
<li><p>Let <var>moduleURLRecord</var> be the result of <span>encoding-parsing a URL</span> given
<var>moduleURL</var>, relative to <var>outsideSettings</var>.</p></li>
<li><p>If <var>moduleURLRecord</var> is failure, then return <span>a promise rejected with</span>
a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>Let <var>promise</var> be a new promise.</p></li>
<li><p>Let <var>workletInstance</var> be <span>this</span>.</p></li>
<li>
<p>Run the following steps <span>in parallel</span>:</p>
<ol>
<li>
<p>If <var>workletInstance</var>'s <span data-x="concept-Worklet-global-scopes">global
scopes</span> <span data-x="list is empty">is empty</span>, then:</p>
<ol>
<li><p><span>Create a worklet global scope</span> given <var>workletInstance</var>.</p></li>
<li><p>Optionally, <span data-x="create a worklet global scope">create</span> additional
global scope instances given <var>workletInstance</var>, depending on the specific worklet in
question and its specification.</p></li>
<li><p>Wait for all steps of the <span data-x="create a worklet global scope">creation</span>
process(es) — including those taking place within the <span data-x="worklet agent">worklet
agents</span> — to complete, before moving on.</p></li>
</ol>
</li>
<li><p>Let <var>pendingTasks</var> be <var>workletInstance</var>'s <span
data-x="concept-Worklet-global-scopes">global scopes</span>'s <span data-x="list
size">size</span>.</p></li>
<li><p>Let <var>addedSuccessfully</var> be false.</p></li>
<li>
<p><span data-x="list iterate">For each</span> <var>workletGlobalScope</var> of
<var>workletInstance</var>'s <span data-x="concept-Worklet-global-scopes">global
scopes</span>, <span>queue a global task</span> on the <span>networking task source</span>
given <var>workletGlobalScope</var> to <span>fetch a worklet script graph</span> given
<var>moduleURLRecord</var>, <var>outsideSettings</var>, <var>workletInstance</var>'s
<span>worklet destination type</span>, <var>options</var>["<code
data-x="dom-WorkletOptions-credentials">credentials</code>"], <var>workletGlobalScope</var>'s
<span>relevant settings object</span>, <var>workletInstance</var>'s <span
data-x="concept-Worklet-module-responses-map">module responses map</span>, and the following
steps given <var>script</var>:</p>
<p class="note">Only the first of these fetches will actually perform a network request; the
ones for other <code>WorkletGlobalScope</code>s will reuse <span
data-x="concept-response">responses</span> from <var>workletInstance</var>'s <span
data-x="concept-Worklet-module-responses-map">module responses map</span>.</p>
<ol>
<li>
<p>If <var>script</var> is null, then:</p>
<ol>
<li>
<p><span>Queue a global task</span> on the <span>networking task source</span> given
<var>workletInstance</var>'s <span>relevant global object</span> to perform the following
steps:</p>
<ol>
<li>
<p>If <var>pendingTasks</var> is not −1, then:</p>
<ol>
<li><p>Set <var>pendingTasks</var> to −1.</p></li>
<li><p>Reject <var>promise</var> with an <span>"<code>AbortError</code>"</span>
<code>DOMException</code>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Abort these steps.</p></li>
</ol>
</li>
<li>
<p>If <var>script</var>'s <span data-x="concept-script-error-to-rethrow">error to
rethrow</span> is not null, then:</p>
<ol>
<li>
<p><span>Queue a global task</span> on the <span>networking task source</span> given
<var>workletInstance</var>'s <span>relevant global object</span> to perform the following
steps:</p>
<ol>
<li>
<p>If <var>pendingTasks</var> is not −1, then:</p>
<ol>
<li><p>Set <var>pendingTasks</var> to −1.</p></li>
<li><p>Reject <var>promise</var> with <var>script</var>'s <span
data-x="concept-script-error-to-rethrow">error to rethrow</span>.</p></li>
</ol>
</li>
</ol>
</li>
<li><p>Abort these steps.</p></li>
</ol>
</li>
<li>
<p>If <var>addedSuccessfully</var> is false, then:</p>
<ol>
<li><p><span data-x="list append">Append</span> <var>moduleURLRecord</var> to
<var>workletInstance</var>'s <span data-x="concept-Worklet-added-modules-list">added
modules list</span>.</p></li>
<li><p>Set <var>addedSuccessfully</var> to true.</p></li>
</ol>
</li>
<li><p><span>Run a module script</span> given <var>script</var>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>networking task source</span> given
<var>workletInstance</var>'s <span>relevant global object</span> to perform the following
steps:</p>
<ol>
<li>
<p>If <var>pendingTasks</var> is not −1, then:</p>
<ol>
<li><p>Set <var>pendingTasks</var> to <var>pendingTasks</var> − 1.</p></li>
<li><p>If <var>pendingTasks</var> is 0, then resolve <var>promise</var>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li><p>Return <var>promise</var>.</p></li>
</ol>
</div>
<h4 id="worklets-lifetime">The worklet's lifetime</h4>
<p>The lifetime of a <code>Worklet</code> has no special considerations; it is tied to the object
it belongs to, such as the <code>Window</code>.</p>
<div w-nodev>
<p>Each <code>Document</code> has a <dfn data-x="concept-Document-worklet-global-scopes">worklet
global scopes</dfn>, which is a <span>set</span> of <code>WorkletGlobalScope</code>s, initially
empty.</p>
</div>
<p>The lifetime of a <code>WorkletGlobalScope</code> is, at a minimum, tied to the
<code>Document</code> whose <span data-x="concept-Document-worklet-global-scopes">worklet global
scopes</span> contain it. In particular, <span data-x="destroy a document">destroying</span> the
<code>Document</code> will <span data-x="terminate a worklet global scope">terminate</span> the
corresponding <code>WorkletGlobalScope</code> and allow it to be garbage-collected.</p>
<p>Additionally, user agents may, at any time, <span data-x="terminate a worklet global
scope">terminate</span> a given <code>WorkletGlobalScope</code>, unless the specification defining
the corresponding worklet type says otherwise. For example, they might terminate them if the
<span>worklet agent</span>'s <span data-x="concept-agent-event-loop">event loop</span> has no
<span data-x="concept-task">tasks</span> queued, or if the user agent has no pending operations
planning to make use of the worklet, or if the user agent detects abnormal operations such as
infinite loops or callbacks exceeding imposed time limits.</p>
<p>Finally, specifications for specific worklet types can give more specific details on when to
<span data-x="create a worklet global scope">create</span> <code>WorkletGlobalScope</code>s for a
given worklet type. For example, they might create them during specific processes that call upon
worklet code, as in the <a href="#worklets-example-registering">example</a>.</p>
<h2 split-filename="webstorage" id="webstorage">Web storage</h2>
<h3>Introduction</h3>
<!-- NON-NORMATIVE SECTION -->
<p>This specification introduces two related mechanisms, similar to HTTP session cookies, for
storing name-value pairs on the client side. <ref>COOKIES</ref></p>
<p>The first is designed for scenarios where the user is carrying out a single transaction, but
could be carrying out multiple transactions in different windows at the same time.</p>
<p>Cookies don't really handle this case well. For example, a user could be buying plane tickets
in two different windows, using the same site. If the site used cookies to keep track of which
ticket the user was buying, then as the user clicked from page to page in both windows, the ticket
currently being purchased would "leak" from one window to the other, potentially causing the user
to buy two tickets for the same flight without noticing.</p>
<p>To address this, this specification introduces the <code
data-x="dom-sessionStorage">sessionStorage</code> getter. Sites can add data to the session
storage, and it will be accessible to any page from the same site opened in that window.</p>
<div class="example">
<p>For example, a page could have a checkbox that the user ticks to
indicate that they want insurance:</p>
<pre><code class="html"><label>
<input type="checkbox" onchange="sessionStorage.insurance = checked ? 'true' : ''">
I want insurance on this trip.
</label></code></pre>
<p>A later page could then check, from script, whether the user had checked the checkbox or
not:</p>
<pre><code class="js">if (sessionStorage.insurance) { ... }</code></pre>
<p>If the user had multiple windows opened on the site, each one would have its own individual
copy of the session storage object.</p>
</div>
<!--
sessionStorage.flightDeparture = 'OSL';
sessionStorage.flightArrival = 'NYC';
for (var i in forms[0].elements)
sessionStorage["data_" + i.name] = i.value;
// if we add storage of non-strings
if (!sessionStorage[documents])
sessionStorage[documents] = {};
sessionStorage[documents][filename] = <document/>;
-->
<p>The second storage mechanism is designed for storage that spans multiple windows, and lasts
beyond the current session. In particular, web applications might wish to store megabytes of user
data, such as entire user-authored documents or a user's mailbox, on the client side for
performance reasons.</p>
<p>Again, cookies do not handle this case well, because they are transmitted with every
request.</p>
<p>The <code data-x="dom-localStorage">localStorage</code> getter is used to access a page's local
storage area.</p>
<div class="example">
<p>The site at example.com can display a count of how many times the user has loaded its page by
putting the following at the bottom of its page:</p>
<pre><code class="html"><p>
You have viewed this page
<span id="count">an untold number of</span>
time(s).
</p>
<script>
if (!localStorage.pageLoadCount)
localStorage.pageLoadCount = 0;
localStorage.pageLoadCount = parseInt(localStorage.pageLoadCount) + 1;
document.getElementById('count').textContent = localStorage.pageLoadCount;
</script></code></pre>
</div>
<p>Each site has its own separate storage area.</p>
<p class="warning">The <code data-x="dom-localStorage">localStorage</code> getter provides access
to shared state. This specification does not define the interaction with other agent clusters
in a multiprocess user agent, and authors are encouraged to assume that there is no locking
mechanism. A site could, for instance, try to read the value of a key, increment its value, then
write it back out, using the new value as a unique identifier for the session; if the site does
this twice in two different browser windows at the same time, it might end up using the same
"unique" identifier for both sessions, with potentially disastrous effects.</p>
<h3 id="storage">The API</h3>
<h4>The <code>Storage</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>Storage</dfn> {
readonly attribute unsigned long <span data-x="dom-Storage-length">length</span>;
DOMString? <span data-x="dom-Storage-key">key</span>(unsigned long index);
getter DOMString? <span data-x="dom-Storage-getItem">getItem</span>(DOMString key);
setter undefined <span data-x="dom-Storage-setItem">setItem</span>(DOMString key, DOMString value);
deleter undefined <span data-x="dom-Storage-removeItem">removeItem</span>(DOMString key);
undefined <span data-x="dom-Storage-clear">clear</span>();
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>storage</var>.<span subdfn data-x="dom-Storage-length">length</span></code></dt>
<dd><p>Returns the number of key/value pairs.</p></dd>
<dt><code data-x=""><var>storage</var>.<span subdfn data-x="dom-Storage-key">key</span> (<var>n</var>)</code></dt>
<dd><p>Returns the name of the <var>n</var>th key, or null if <var>n</var> is greater than or
equal to the number of key/value pairs.</p></dd>
<dt><code data-x=""><var>value</var> = <var>storage</var>.<span subdfn data-x="dom-Storage-getItem">getItem</span> (<var>key</var>)</code></dt>
<dt><code data-x=""><var>value</var> = <var>storage</var>[<var>key</var>]</code></dt>
<dd><p>Returns the current value associated with the given <var>key</var>, or null if the given
<var>key</var> does not exist.</p></dd>
<dt><code data-x=""><var>storage</var>.<span subdfn data-x="dom-Storage-setItem">setItem</span> (<var>key</var>, <var>value</var>)</code></dt>
<dt><code data-x=""><var>storage</var>[<var>key</var>] = <var>value</var></code></dt>
<dd>
<p>Sets the value of the pair identified by <var>key</var> to <var>value</var>, creating a new
key/value pair if none existed for <var>key</var> previously.</p>
<p>Throws a <span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception
if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage
for the site, or if the quota has been exceeded.)</p>
<p>Dispatches a <code data-x="event-storage">storage</code> event on <code>Window</code> objects
holding an equivalent <code>Storage</code> object.</p>
</dd>
<dt><code data-x=""><var>storage</var>.<span subdfn data-x="dom-Storage-removeItem">removeItem</span> (<var>key</var>)</code></dt>
<dt><code>delete</code> <var>storage</var>[<var>key</var>]</dt>
<dd>
<p>Removes the key/value pair with the given <var>key</var>, if a key/value pair with the given
<var>key</var> exists.</p>
<p>Dispatches a <code data-x="event-storage">storage</code> event on <code>Window</code> objects
holding an equivalent <code>Storage</code> object.</p>
</dd>
<dt><code data-x=""><var>storage</var>.<span subdfn data-x="dom-Storage-clear">clear</span>()</code></dt>
<dd>
<p>Removes all key/value pairs, if there are any.</p>
<p>Dispatches a <code data-x="event-storage">storage</code> event on <code>Window</code> objects
holding an equivalent <code>Storage</code> object.</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Storage</code> object has an associated:</p>
<dl>
<dt><dfn data-x="concept-Storage-map">map</dfn>
<dd>A <span>storage proxy map</span>.</dd>
<dt><dfn data-x="concept-Storage-type">type</dfn>
<dd>"<code data-x="">local</code>" or "<code data-x="">session</code>".
</dl>
<p>To <dfn data-x="concept-Storage-reorder">reorder</dfn> a <code>Storage</code> object
<var>storage</var>, reorder <var>storage</var>'s <span data-x="concept-Storage-map">map</span>'s
<span data-x="map entry">entries</span> in an <span>implementation-defined</span> manner.</p>
<p class="note">Unfortunate as it is, iteration order is not defined and can change upon most
mutations.</p>
<p>To <dfn data-x="concept-Storage-broadcast">broadcast</dfn> a <code>Storage</code> object
<var>storage</var>, given a <var>key</var>, <var>oldValue</var>, and <var>newValue</var>, run
these steps:</p>
<ol>
<li><p>Let <var>thisDocument</var> be <var>storage</var>'s <span>relevant global object</span>'s <span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>
<li><p>Let <var>url</var> be the <span data-x="concept-url-serializer">serialization</span> of
<var>thisDocument</var>'s <span data-x="concept-document-url">URL</span>.</p></li>
<li>
<p>Let <var>remoteStorages</var> be all <code>Storage</code> objects excluding
<var>storage</var> whose:</p>
<ul>
<li><span data-x="concept-Storage-type">type</span> is <var>storage</var>'s <span
data-x="concept-Storage-type">type</span></li>
<li><span>relevant settings object</span>'s <span>origin</span> is <span>same origin</span>
with <var>storage</var>'s <span>relevant settings object</span>'s <span>origin</span>.</li>
</ul>
<p>and, if <span data-x="concept-Storage-type">type</span> is "<code data-x="">session</code>",
whose <span>relevant settings object</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>node navigable</span>'s <span
data-x="nav-traversable">traversable navigable</span> is <var>thisDocument</var>'s <span>node
navigable</span>'s <span data-x="nav-traversable">traversable navigable</span>.</p>
</li>
<li>
<p><span data-x="list iterate">For each</span> <var>remoteStorage</var> of
<var>remoteStorages</var>: <span>queue a global task</span> on the <span>DOM manipulation task
source</span> given <var>remoteStorage</var>'s <span>relevant global object</span> to <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-storage">storage</code> at <var>remoteStorage</var>'s <span>relevant global
object</span>, using <code>StorageEvent</code>, with <code
data-x="dom-StorageEvent-key">key</code> initialized to <var>key</var>, <code
data-x="dom-StorageEvent-oldValue">oldValue</code> initialized to <var>oldValue</var>, <code
data-x="dom-StorageEvent-newValue">newValue</code> initialized to <var>newValue</var>, <code
data-x="dom-StorageEvent-url">url</code> initialized to <var>url</var>, and <code
data-x="dom-StorageEvent-storageArea">storageArea</code> initialized to
<var>remoteStorage</var>.</p>
<!-- This ignores the fact that Storage objects that are part of the same agent should not get
their own tasks, much like the text that predates it. -->
<p class="note">The <code>Document</code> object associated with the resulting <span
data-x="concept-task">task</span> is not necessarily <span>fully active</span>, but events fired
on such objects are ignored by the <span>event loop</span> until the <code>Document</code>
becomes <span>fully active</span> again.</p>
</li>
</ol>
<hr>
<p>The <dfn attribute for="Storage"><code data-x="dom-Storage-length">length</code></dfn> getter
steps are to return <span>this</span>'s <span data-x="concept-Storage-map">map</span>'s <span
data-x="map size">size</span>.</p>
<p>The <dfn method for="Storage"><code data-x="dom-Storage-key">key(<var>index</var>)</code></dfn>
method steps are:</p>
<ol>
<li><p>If <var>index</var> is greater than or equal to <span>this</span>'s <span
data-x="concept-Storage-map">map</span>'s <span data-x="map size">size</span>, then return
null.</p></li>
<li><p>Let <var>keys</var> be the result of running <span data-x="map get the keys">get the
keys</span> on <span>this</span>'s <span data-x="concept-Storage-map">map</span>.
<li><p>Return <var>keys</var>[<var>index</var>].</p></li>
</ol>
<p>The <span>supported property names</span> on a <code>Storage</code> object <var>storage</var>
are the result of running <span data-x="map get the keys">get the keys</span> on
<var>storage</var>'s <span data-x="concept-Storage-map">map</span>.</p>
<p>The <dfn method for="Storage"><code
data-x="dom-Storage-getItem">getItem(<var>key</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-Storage-map">map</span>[<var>key</var>] does
not <span data-x="map exists">exist</span>, then return null.</p></li>
<li><p>Return <span>this</span>'s <span
data-x="concept-Storage-map">map</span>[<var>key</var>].</p></li>
</ol>
<p>The <dfn method for="Storage"><code data-x="dom-Storage-setItem">setItem(<var>key</var>,
<var>value</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>Let <var>oldValue</var> be null.</p></li>
<li><p>Let <var>reorder</var> be true.</p></li>
<li>
<p>If <span>this</span>'s <span data-x="concept-Storage-map">map</span>[<var>key</var>]
<span data-x="map exists">exists</span>:</p>
<ol>
<li><p>Set <var>oldValue</var> to <span>this</span>'s <span
data-x="concept-Storage-map">map</span>[<var>key</var>].</p></li>
<li><p>If <var>oldValue</var> <span>is</span> <var>value</var>, then return.</p></li>
<li><p>Set <var>reorder</var> to false.</p></li>
</ol>
</li>
<li><p>If <var>value</var> cannot be stored, then throw a
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception.</p></li>
<li><p><span data-x="map set">Set</span> <span>this</span>'s <span
data-x="concept-Storage-map">map</span>[<var>key</var>] to <var>value</var>.</p></li>
<li><p>If <var>reorder</var> is true, then <span data-x="concept-Storage-reorder">reorder</span>
<span>this</span>.</p></li>
<li><p><span data-x="concept-Storage-broadcast">Broadcast</span> <span>this</span> with
<var>key</var>, <var>oldValue</var>, and <var>value</var>.</p></li>
</ol>
<p>The <dfn method for="Storage"><code
data-x="dom-Storage-removeItem">removeItem(<var>key</var>)</code></dfn> method steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-Storage-map">map</span>[<var>key</var>] does
not <span data-x="map exists">exist</span>, then return.</p></li>
<li><p>Set <var>oldValue</var> to <span>this</span>'s <span
data-x="concept-Storage-map">map</span>[<var>key</var>].</p></li>
<li><p><span data-x="map remove">Remove</span> <span>this</span>'s <span
data-x="concept-Storage-map">map</span>[<var>key</var>].</p></li>
<li><p><span data-x="concept-Storage-reorder">Reorder</span> <span>this</span>.</p></li>
<li><p><span data-x="concept-Storage-broadcast">Broadcast</span> <span>this</span> with
<var>key</var>, <var>oldValue</var>, and null.</p></li>
</ol>
<p>The <dfn method for="Storage"><code data-x="dom-Storage-clear">clear()</code></dfn> method
steps are:</p>
<ol>
<li><p><span data-x="map clear">Clear</span> <span>this</span>'s <span
data-x="concept-Storage-map">map</span>.</p></li>
<li><p><span data-x="concept-Storage-broadcast">Broadcast</span> <span>this</span> with null,
null, and null.</p></li>
</ol>
</div>
<h4 id="the-sessionstorage-attribute">The <code data-x="dom-sessionStorage">sessionStorage</code> getter</h4>
<pre><code class="idl">interface mixin <dfn interface>WindowSessionStorage</dfn> {
readonly attribute <span>Storage</span> <span data-x="dom-sessionStorage">sessionStorage</span>;
};
<span>Window</span> includes <span>WindowSessionStorage</span>;</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-sessionStorage">sessionStorage</span></code></dt>
<dd>
<p>Returns the <code>Storage</code> object associated with that <var>window</var>'s origin's
session storage area.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the
<code>Document</code>'s <span data-x="concept-document-origin">origin</span> is an <span
data-x="concept-origin-opaque">opaque origin</span> or if the request violates a policy decision
(e.g., if the user agent is configured to not allow the page to persist data).</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Document</code> object has an associated <dfn>session storage holder</dfn>, which is
null or a <code>Storage</code> object. It is initially null.</p>
<p>
<!--INSERT TRACKING-->
The <dfn attribute for="WindowSessionStorage"><code
data-x="dom-sessionStorage">sessionStorage</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>session storage holder</span> is non-null, then return
<span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>session storage holder</span>.</p></li>
<li><p>Let <var>map</var> be the result of running <span>obtain a session storage bottle
map</span> with <span>this</span>'s <span>relevant settings object</span> and "<code
data-x="">sessionStorage</code>".</p></li>
<li><p>If <var>map</var> is failure, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>storage</var> be a new <code>Storage</code> object whose <span
data-x="concept-Storage-map">map</span> is <var>map</var>.
<li><p>Set <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>session storage holder</span> to
<var>storage</var>.</p></li>
<li><p>Return <var>storage</var>.</p></li>
</ol>
<p class="note">After <span>creating a new auxiliary browsing context and document</span>, the
session storage <a href="#copy-session-storage">is copied</a> over.</p>
</div>
<h4 id="the-localstorage-attribute">The <code data-x="dom-localStorage">localStorage</code> getter</h4>
<pre><code class="idl">interface mixin <dfn interface>WindowLocalStorage</dfn> {
readonly attribute <span>Storage</span> <span data-x="dom-localStorage">localStorage</span>;
};
<span>Window</span> includes <span>WindowLocalStorage</span>;</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>window</var>.<span subdfn data-x="dom-localStorage">localStorage</span></code></dt>
<dd>
<p>Returns the <code>Storage</code> object associated with <var>window</var>'s origin's local
storage area.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the
<code>Document</code>'s <span data-x="concept-document-origin">origin</span> is an <span
data-x="concept-origin-opaque">opaque origin</span> or if the request violates a policy decision
(e.g., if the user agent is configured to not allow the page to persist data).</p>
</dd>
</dl>
<div w-nodev>
<p>A <code>Document</code> object has an associated <dfn>local storage holder</dfn>, which is null
or a <code>Storage</code> object. It is initially null.</p>
<p>
<!--INSERT TRACKING-->
The <dfn attribute for="WindowLocalStorage"><code
data-x="dom-localStorage">localStorage</code></dfn> getter steps are:</p>
<ol>
<li><p>If <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>local storage holder</span> is non-null, then return
<span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>local storage holder</span>.</p></li>
<li><p>Let <var>map</var> be the result of running <span>obtain a local storage bottle map</span>
with <span>this</span>'s <span>relevant settings object</span> and "<code
data-x="">localStorage</code>".</p></li>
<li><p>If <var>map</var> is failure, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Let <var>storage</var> be a new <code>Storage</code> object whose <span
data-x="concept-Storage-map">map</span> is <var>map</var>.
<li><p>Set <span>this</span>'s <span data-x="concept-document-window">associated
<code>Document</code></span>'s <span>local storage holder</span> to <var>storage</var>.</p></li>
<li><p>Return <var>storage</var>.</p></li>
</ol>
</div>
<h4>The <code>StorageEvent</code> interface</h4>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>StorageEvent</dfn> : <span>Event</span> {
constructor(DOMString type, optional <span>StorageEventInit</span> eventInitDict = {});
readonly attribute DOMString? <span data-x="dom-StorageEvent-key">key</span>;
readonly attribute DOMString? <span data-x="dom-StorageEvent-oldValue">oldValue</span>;
readonly attribute DOMString? <span data-x="dom-StorageEvent-newValue">newValue</span>;
readonly attribute USVString <span data-x="dom-StorageEvent-url">url</span>;
readonly attribute <span>Storage</span>? <span data-x="dom-StorageEvent-storageArea">storageArea</span>;
undefined <span data-x="dom-StorageEvent-initStorageEvent">initStorageEvent</span>(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional DOMString? key = null, optional DOMString? oldValue = null, optional DOMString? newValue = null, optional USVString url = "", optional Storage? storageArea = null);
};
dictionary <dfn dictionary>StorageEventInit</dfn> : <span>EventInit</span> {
DOMString? key = null;
DOMString? oldValue = null;
DOMString? newValue = null;
USVString url = "";
<span>Storage</span>? storageArea = null;
};</code></pre>
<dl class="domintro">
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-StorageEvent-key">key</span></code></dt>
<dd><p>Returns the key of the storage item being changed.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-StorageEvent-oldValue">oldValue</span></code></dt>
<dd><p>Returns the old value of the key of the storage item whose value is being
changed.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-StorageEvent-newValue">newValue</span></code></dt>
<dd><p>Returns the new value of the key of the storage item whose value is being
changed.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-StorageEvent-url">url</span></code></dt>
<dd><p>Returns the <span data-x="concept-document-url">URL</span> of the document whose storage
item changed.</p></dd>
<dt><code data-x=""><var>event</var>.<span subdfn data-x="dom-StorageEvent-storageArea">storageArea</span></code></dt>
<dd><p>Returns the <code>Storage</code> object that was affected.</p></dd>
</dl>
<div w-nodev>
<p>The <dfn attribute for="StorageEvent"><code data-x="dom-StorageEvent-key">key</code></dfn>,
<dfn attribute for="StorageEvent"><code data-x="dom-StorageEvent-oldValue">oldValue</code></dfn>,
<dfn attribute for="StorageEvent"><code data-x="dom-StorageEvent-newValue">newValue</code></dfn>,
<dfn attribute for="StorageEvent"><code data-x="dom-StorageEvent-url">url</code></dfn>, and <dfn
attribute for="StorageEvent"><code data-x="dom-StorageEvent-storageArea">storageArea</code></dfn>
attributes must return the values they were initialized to.</p>
<!-- handwavy, file bugs if there are interop issues -->
<p>The <dfn method for="StorageEvent"><code
data-x="dom-StorageEvent-initStorageEvent">initStorageEvent(<var>type</var>, <var>bubbles</var>,
<var>cancelable</var>, <var>key</var>, <var>oldValue</var>, <var>newValue</var>, <var>url</var>,
<var>storageArea</var>)</code></dfn> method must initialize the event in a manner analogous to the
similarly-named <code data-x="dom-Event-initEvent">initEvent()</code> method. <ref>DOM</ref></p>
</div>
<h3>Privacy</h3>
<h4>User tracking</h4>
<p>A third-party advertiser (or any entity capable of getting content distributed to multiple
sites) could use a unique identifier stored in its local storage area to track a user across
multiple sessions, building a profile of the user's interests to allow for highly targeted
advertising. In conjunction with a site that is aware of the user's real identity (for example an
e-commerce site that requires authenticated credentials), this could allow oppressive groups to
target individuals with greater accuracy than in a world with purely anonymous web usage.</p>
<p>There are a number of techniques that can be used to mitigate the risk of user tracking:</p>
<dl>
<dt>Blocking third-party storage</dt>
<dd>
<p>User agents may restrict access to the <code data-x="dom-localStorage">localStorage</code>
objects to scripts originating at the domain of the <span data-x="nav-document">active
document</span> of the <span>top-level traversable</span>, for instance denying access to the
API for pages from other domains running in <code>iframe</code>s.</p>
</dd>
<dt>Expiring stored data</dt>
<dd>
<p>User agents may, possibly in a manner configured by the user, automatically delete stored
data after a period of time.</p>
<p>For example, a user agent could be configured to treat third-party local storage areas as
session-only storage, deleting the data once the user had closed all the <span
data-x="navigable">navigables</span> that could access it.</p>
<p>This can restrict the ability of a site to track a user, as the site would then only be able
to track the user across multiple sessions when they authenticate with the site itself (e.g. by
making a purchase or logging in to a service).</p>
<p>However, this also reduces the usefulness of the API as a long-term storage mechanism. It can
also put the user's data at risk, if the user does not fully understand the implications of data
expiration.</p>
</dd>
<dt>Treating persistent storage as cookies</dt>
<dd>
<p>If users attempt to protect their privacy by clearing cookies without also clearing data
stored in the local storage area, sites can defeat those attempts by using the two features as
redundant backup for each other. User agents should present the interfaces for clearing these in
a way that helps users to understand this possibility and enables them to delete data in all
persistent storage features simultaneously. <ref>COOKIES</ref></p>
</dd>
<dt>Site-specific safelisting of access to local storage areas</dt> <dd>
<p>User agents may allow sites to access session storage areas in
an unrestricted manner, but require the user to authorize access
to local storage areas.</p>
</dd>
<dt>Origin-tracking of stored data</dt>
<dd>
<p>User agents may record the <span data-x="origin">origins</span> of sites that contained
content from third-party origins that caused data to be stored.</p>
<p>If this information is then used to present the view of data currently in persistent storage,
it would allow the user to make informed decisions about which parts of the persistent storage
to prune. Combined with a blocklist ("delete this data and prevent this domain from ever storing
data again"), the user can restrict the use of persistent storage to sites that they trust.</p>
</dd>
<dt>Shared blocklists</dt>
<dd>
<p>User agents may allow users to share their persistent storage domain blocklists.</p>
<p>This would allow communities to act together to protect their privacy.</p>
</dd>
</dl>
<p>While these suggestions prevent trivial use of this API for user tracking, they do not block it
altogether. Within a single domain, a site can continue to track the user during a session, and
can then pass all this information to the third party along with any identifying information
(names, credit card numbers, addresses) obtained by the site. If a third party cooperates with
multiple sites to obtain such information, a profile can still be created.</p>
<p>However, user tracking is to some extent possible even with no cooperation from the user agent
whatsoever, for instance by using session identifiers in URLs, a technique already commonly used
for innocuous purposes but easily repurposed for user tracking (even retroactively). This
information can then be shared with other sites, using visitors' IP addresses and other
user-specific data (e.g. user-agent headers and configuration settings) to combine separate
sessions into coherent user profiles.</p>
<div w-nodev>
<h4>Sensitivity of data</h4>
<p>User agents should treat persistently stored data as potentially sensitive; it's quite possible
for emails, calendar appointments, health records, or other confidential documents to be stored
in this mechanism.</p>
<p>To this end, user agents should ensure that when deleting data, it is promptly deleted from the
underlying storage.</p>
</div>
<h3 id="security-storage">Security</h3>
<h4>DNS spoofing attacks</h4>
<p>Because of the potential for DNS spoofing attacks, one cannot guarantee that a host claiming to
be in a certain domain really is from that domain. To mitigate this, pages can use TLS. Pages
using TLS can be sure that only the user, software working on behalf of the user, and other pages
using TLS that have certificates identifying them as being from the same domain, can access their
storage areas.</p>
<h4>Cross-directory attacks</h4>
<p>Different authors sharing one host name, for example users hosting content on the now defunct
<code data-x="">geocities.com</code>, all share one local storage object. There is no feature to
restrict the access by pathname. Authors on shared hosts are therefore urged to avoid using these
features, as it would be trivial for other authors to read the data and overwrite it.</p>
<p class="note">Even if a path-restriction feature was made available, the usual DOM scripting
security model would make it trivial to bypass this protection and access the data from any
path.</p>
<div w-nodev>
<h4>Implementation risks</h4>
<p>The two primary risks when implementing these persistent storage features are letting hostile
sites read information from other domains, and letting hostile sites write information that is
then read from other domains.</p>
<p>Letting third-party sites read data that is not supposed to be read from their domain causes
<em>information leakage</em>. For example, a user's shopping wishlist on one domain could be used
by another domain for targeted advertising; or a user's work-in-progress confidential documents
stored by a word-processing site could be examined by the site of a competing company.</p>
<p>Letting third-party sites write data to the persistent storage of other domains can result in
<em>information spoofing</em>, which is equally dangerous. For example, a hostile site could add
items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID
that the hostile site can then use to track the user's actions on the victim site.</p>
<p>Thus, strictly following the <span>origin</span> model described in this specification is
important for user security.</p>
</div>
<h2 split-filename="syntax" id="syntax"><dfn>The HTML syntax</dfn></h2>
<p class="note">This section only describes the rules for resources labeled with an <span>HTML
MIME type</span>. Rules for XML resources are discussed in the section below entitled "<span>The
XML syntax</span>".</p>
<h3 id="writing">Writing HTML documents</h3>
<div w-nodev>
<p><i>This section only applies to documents, authoring tools, and markup generators. In
particular, it does not apply to conformance checkers; conformance checkers must use the
requirements given in the next section ("parsing HTML documents").</i></p>
</div>
<p>Documents must consist of the following parts, in the given
order:</p>
<ol>
<li>Optionally, a single U+FEFF BYTE ORDER MARK (BOM) character.</li>
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
<li>A <span data-x="syntax-doctype">DOCTYPE</span>.
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
<li>The <span>document element</span>, in the form of an <code>html</code> <span
data-x="syntax-elements">element</span>.</li>
<li>Any number of <span data-x="syntax-comments">comments</span> and <span>ASCII
whitespace</span>.</li>
</ol>
<p>The various types of content mentioned above are described in the next few sections.</p>
<p>In addition, there are some restrictions on how <span data-x="character encoding
declaration">character encoding declarations</span> are to be serialized, as discussed in the
section on that topic.</p>
<div class="note">
<p><span>ASCII whitespace</span> before the <code>html</code> element, at the start of the
<code>html</code> element and before the <code>head</code> element, will be dropped when the
document is parsed; <span>ASCII whitespace</span> <em>after</em> the <code>html</code> element
will be parsed as if it were at the end of the <code>body</code> element. Thus, <span>ASCII
whitespace</span> around the <span>document element</span> does not round-trip.</p>
<p>It is suggested that newlines be inserted after the DOCTYPE, after any comments that are
before the document element, after the <code>html</code> element's start tag (if it is not <span
data-x="syntax-tag-omission">omitted</span>), and after any comments that are inside the
<code>html</code> element but before the <code>head</code> element.</p>
</div>
<p>Many strings in the HTML syntax (e.g. the names of elements and their attributes) are
case-insensitive, but only for <span data-x="ASCII upper alpha">ASCII upper alphas</span> and
<span data-x="ASCII lower alpha">ASCII lower alphas</span>. For convenience, in this section this
is just referred to as "case-insensitive".</p>
<h4>The DOCTYPE</h4>
<p>A <dfn data-x="syntax-doctype">DOCTYPE</dfn> is a <!-- mostly useless but nonetheless -->
required preamble.</p>
<p class="note">DOCTYPEs are required for legacy reasons. When omitted, browsers tend to use a
different rendering mode that is incompatible with some specifications. Including the DOCTYPE in a
document ensures that the browser makes a best-effort attempt at following the relevant
specifications.</p>
<p>A DOCTYPE must consist of the following components, in this order:</p>
<ol class="brief">
<li>A string that is an <span>ASCII case-insensitive</span> match for the string "<code data-x=""><!DOCTYPE</code>".</li>
<li>One or more <span>ASCII whitespace</span>.</li>
<li>A string that is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">html</code>".</li>
<li>Optionally, a <span>DOCTYPE legacy string</span>.</li>
<li>Zero or more <span>ASCII whitespace</span>.</li>
<li>A U+003E GREATER-THAN SIGN character (>).</li>
</ol>
<p class="note">In other words, <code data-x=""><!DOCTYPE html></code>, case-insensitively.</p>
<hr>
<p>For the purposes of HTML generators that cannot output HTML markup with the short DOCTYPE
"<code data-x=""><!DOCTYPE html></code>", a <dfn>DOCTYPE legacy string</dfn> may be inserted
into the DOCTYPE (in the position defined above). This string must consist of:</p>
<ol class="brief">
<li>One or more <span>ASCII whitespace</span>.</li>
<li>A string that is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">SYSTEM</code>".</li>
<li>One or more <span>ASCII whitespace</span>.</li>
<li>A U+0022 QUOTATION MARK or U+0027 APOSTROPHE character (the <i>quote mark</i>).</li>
<li>The literal string "<code>about:legacy-compat</code>".</li>
<li>A matching U+0022 QUOTATION MARK or U+0027 APOSTROPHE character (i.e. the same character as in the earlier step labeled <i>quote mark</i>).</li>
</ol>
<p class="note">In other words, <code data-x=""><!DOCTYPE html SYSTEM "about:legacy-compat"></code> or
<code data-x=""><!DOCTYPE html SYSTEM 'about:legacy-compat'></code>, case-insensitively except for the
part in single or double quotes.</p>
<p>The <span>DOCTYPE legacy string</span> should not be used unless the document is generated from
a system that cannot output the shorter string.</p>
<h4>Elements</h4>
<p>There are six different kinds of <dfn data-x="syntax-elements">elements</dfn>: <span>void
elements</span>, <span>the <code data-x="">template</code> element</span>, <span>raw text
elements</span>, <span>escapable raw text elements</span>, <span>foreign elements</span>, and
<span>normal elements</span>.</p>
<dl>
<dt><dfn>Void elements</dfn></dt>
<dd><code>area</code>, <code>base</code>, <code>br</code>, <code>col</code>, <code>embed</code>,
<code>hr</code>, <code>img</code>, <code>input</code>, <code>link</code>, <code>meta</code>,
<code>source</code>, <code>track</code>, <code>wbr</code></dd>
<!-- non-conforming elements treated as void by the parser are not listed here: basefont,
bgsound, frame, param, keygen -->
<dt><dfn>The <code data-x="">template</code> element</dfn></dt>
<dd><code>template</code></dd>
<dt><dfn>Raw text elements</dfn></dt>
<dd><code>script</code>, <code>style</code></dd> <!-- iframe and noscript don't count as raw text
for syntax purposes -->
<dt><dfn>Escapable raw text elements</dfn></dt>
<dd><code>textarea</code>, <code>title</code></dd>
<dt><dfn>Foreign elements</dfn></dt>
<dd>Elements from the <span>MathML namespace</span> and the <span>SVG namespace</span>.</dd>
<dt><dfn>Normal elements</dfn></dt>
<dd>All other allowed <span>HTML elements</span> are normal elements.</dd>
</dl>
<p><dfn data-x="syntax-tags">Tags</dfn> are used to delimit the start and end of elements in the
markup. <span data-x="raw text elements">Raw text</span>, <span data-x="escapable raw text
elements">escapable raw text</span>, and <span data-x="normal elements">normal</span> elements have
a <span data-x="syntax-start-tag">start tag</span> to indicate where they begin, and an <span
data-x="syntax-end-tag">end tag</span> to indicate where they end. The start and end tags of
certain <span>normal elements</span> can be <span data-x="syntax-tag-omission">omitted</span>, as
described below in the section on <span data-x="syntax-tag-omission">optional tags</span>. Those
that cannot be omitted must not be omitted. <span>Void elements</span> only have a start tag; end
tags must not be specified for <span>void elements</span>. <span>Foreign elements</span> must
either have a start tag and an end tag, or a start tag that is marked as self-closing, in which
case they must not have an end tag.</p>
<p>The <span data-x="concept-html-contents">contents</span> of the element must be placed between
just after the start tag (which <span data-x="syntax-tag-omission">might be implied, in certain
cases</span>) and just before the end tag (which again, <span data-x="syntax-tag-omission">might be
implied in certain cases</span>). The exact allowed contents of each individual element depend on
the <span data-x="content models">content model</span> of that element, as described earlier in
this specification. Elements must not contain content that their content model disallows. In
addition to the restrictions placed on the contents by those content models, however, the five
types of elements have additional <em>syntactic</em> requirements.</p>
<p><span>Void elements</span> can't have any contents (since there's no end tag, no content can be
put between the start tag and the end tag).</p>
<p id="template-syntax"><span>The <code data-x="">template</code> element</span> can have
<span>template contents</span>, but such <span>template contents</span> are not children of the
<code>template</code> element itself. Instead, they are stored in a <code>DocumentFragment</code>
associated with a different <code>Document</code> — without a <span>browsing context</span> — so
as to avoid the <code>template</code> contents interfering with the main <code>Document</code>.
The markup for the <span>template contents</span> of a <code>template</code> element is placed
just after the <code>template</code> element's start tag and just before <code>template</code>
element's end tag (as with other elements), and may consist of any <span
data-x="syntax-text">text</span>, <span data-x="syntax-charref">character references</span>, <span
data-x="syntax-elements">elements</span>, and <span data-x="syntax-comments">comments</span>, but
the text must not contain the character U+003C LESS-THAN SIGN (<) or an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>.</p>
<p><span>Raw text elements</span> can have <span data-x="syntax-text">text</span>, though it has <a
href="#cdata-rcdata-restrictions">restrictions</a> described below.</p>
<p><span>Escapable raw text elements</span> can have <span data-x="syntax-text">text</span> and
<span data-x="syntax-charref">character references</span>, but the text must not contain an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>. There are also <a
href="#cdata-rcdata-restrictions">further restrictions</a> described below.</p>
<p><span>Foreign elements</span> whose start tag is marked as self-closing can't have any contents
(since, again, as there's no end tag, no content can be put between the start tag and the end
tag). <span>Foreign elements</span> whose start tag is <em>not</em> marked as self-closing can
have <span data-x="syntax-text">text</span>, <span data-x="syntax-charref">character
references</span>, <span data-x="syntax-cdata">CDATA sections</span>, other <span
data-x="syntax-elements">elements</span>, and <span data-x="syntax-comments">comments</span>, but
the text must not contain the character U+003C LESS-THAN SIGN (<) or an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>.</p>
<div class="note">
<p>The HTML syntax does not support namespace declarations, even in <span>foreign
elements</span>.</p>
<p>For instance, consider the following HTML fragment:</p>
<pre><code class="html"><p>
<svg>
<metadata>
<!-- this is invalid -->
<cdr:license xmlns:cdr="https://www.example.com/cdr/metadata" name="MIT"/>
</metadata>
</svg>
</p></code></pre>
<p>The innermost element, <code data-x="">cdr:license</code>, is actually in the SVG namespace, as
the "<code data-x="">xmlns:cdr</code>" attribute has no effect (unlike in XML). In fact, as the
comment in the fragment above says, the fragment is actually non-conforming. This is because
<cite>SVG 2</cite> does not define any elements called "<code data-x="">cdr:license</code>" in
the SVG namespace.</p>
</div>
<p><span>Normal elements</span> can have <span data-x="syntax-text">text</span>, <span
data-x="syntax-charref">character references</span>, other <span
data-x="syntax-elements">elements</span>, and <span data-x="syntax-comments">comments</span>, but
the text must not contain the character U+003C LESS-THAN SIGN (<) or an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>. Some <span>normal elements</span>
also have <a href="#element-restrictions">yet more restrictions</a> on what content they are
allowed to hold, beyond the restrictions imposed by the content model and those described in this
paragraph. Those restrictions are described below.</p>
<p>Tags contain a <dfn data-x="syntax-tag-name">tag name</dfn>, giving the element's name. HTML
elements all have names that only use <span data-x="ASCII alphanumeric">ASCII
alphanumerics</span>. In the HTML syntax, tag names, even those for <span>foreign elements</span>,
may be written with any mix of lower- and uppercase letters that, when converted to all-lowercase,
matches the element's tag name; tag names are case-insensitive.</p>
<h5>Start tags</h5>
<p><dfn data-x="syntax-start-tag">Start tags</dfn> must have the following format:</p>
<ol>
<li>The first character of a start tag must be a U+003C LESS-THAN SIGN character (<).</li>
<li>The next few characters of a start tag must be the element's <span
data-x="syntax-tag-name">tag name</span>.</li>
<li>If there are to be any attributes in the next step, there must first be one or more
<span>ASCII whitespace</span>.</li>
<li>Then, the start tag may have a number of attributes, the <span
data-x="syntax-attributes">syntax for which</span> is described below. Attributes must be
separated from each other by one or more <span>ASCII whitespace</span>.</li>
<li>After the attributes, or after the <span data-x="syntax-tag-name">tag name</span> if there
are no attributes, there may be one or more <span>ASCII whitespace</span>. (Some attributes are
required to be followed by a space. See the <span data-x="syntax-attributes">attributes
section</span> below.)</li>
<li>Then, if the element is one of the <span>void elements</span>, or if the element is a <span
data-x="foreign elements">foreign element</span>, then there may be a single U+002F SOLIDUS
character (/), which on <span>foreign elements</span> marks the start tag as self-closing. On
<span>void elements</span>, it does not mark the start tag as self-closing but instead is
unnecessary and has no effect of any kind. For such void elements, it should be used only with
caution — especially since, if directly preceded by an <a href="#unquoted">unquoted attribute
value</a>, it becomes part of the attribute value rather than being discarded by the
parser.</li>
<li>Finally, start tags must be closed by a U+003E GREATER-THAN SIGN character (>).</li>
</ol>
<h5>End tags</h5>
<p><dfn data-x="syntax-end-tag">End tags</dfn> must have the following format:</p>
<ol>
<li>The first character of an end tag must be a U+003C LESS-THAN SIGN character (<).</li>
<li>The second character of an end tag must be a U+002F SOLIDUS character (/).</li>
<li>The next few characters of an end tag must be the element's <span data-x="syntax-tag-name">tag
name</span>.</li>
<li>After the tag name, there may be one or more <span>ASCII whitespace</span>.</li>
<li>Finally, end tags must be closed by a U+003E GREATER-THAN SIGN character (>).</li>
</ol>
<h5>Attributes</h5>
<p><dfn data-x="syntax-attributes">Attributes</dfn> for an element are expressed inside the
element's start tag.</p>
<p>Attributes have a name and a value. <dfn data-x="syntax-attribute-name">Attribute names</dfn>
must consist of one or more characters other than <span data-x="control">controls</span>,
U+0020 SPACE, U+0022 ("), U+0027 ('), U+003E (>), U+002F (/), U+003D (=), and <span
data-x="noncharacter">noncharacters</span>. In the HTML syntax, attribute names, even those for
<span>foreign elements</span>, may be written with any mix of <span data-x="ASCII lower
alpha">ASCII lower</span> and <span data-x="ASCII upper alpha">ASCII upper alphas</span>.</p>
<p><dfn data-x="syntax-attribute-value">Attribute values</dfn> are a mixture of <span
data-x="syntax-text">text</span> and <span data-x="syntax-charref">character references</span>,
except with the additional restriction that the text cannot contain an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>.</p>
<p>Attributes can be specified in four different ways:</p>
<dl>
<dt>Empty attribute syntax</dt>
<dd>
<p>Just the <span data-x="syntax-attribute-name">attribute name</span>. The value is implicitly
the empty string.</p>
<div class="example">
<p>In the following example, the <code data-x="attr-fe-disabled">disabled</code> attribute is
given with the empty attribute syntax:</p>
<pre><code class="html"><input <em>disabled</em>></code></pre>
</div>
<p>If an attribute using the empty attribute syntax is to be followed by another attribute, then
there must be <span>ASCII whitespace</span> separating the two.</p>
</dd>
<dt id="unquoted">Unquoted attribute value syntax</dt>
<dd>
<p>The <span data-x="syntax-attribute-name">attribute name</span>, followed by zero or more
<span>ASCII whitespace</span>, followed by a single U+003D EQUALS SIGN character, followed by
zero or more <span>ASCII whitespace</span>, followed by the <span
data-x="syntax-attribute-value">attribute value</span>, which, in addition to the requirements
given above for attribute values, must not contain any literal <span>ASCII whitespace</span>,
any U+0022 QUOTATION MARK characters ("), U+0027 APOSTROPHE characters ('), U+003D
EQUALS SIGN characters (=), U+003C LESS-THAN SIGN characters (<), U+003E GREATER-THAN SIGN
characters (>), or U+0060 GRAVE ACCENT characters (`), and must not be the empty string.</p>
<!-- The ` character is in this list on a temporary basis, waiting for IE to fix its parsing bug
whereby it treats ` as an attribute value delimiter. Otherwise, escaping software that
tries to be clever and not use quotes when it doesn't need to could be tricked by an
attacker.
Posit a site that allows the user to input text that is used verbatim in two attributes,
such that the user can set the first attribute's value to:
`
...and the second to:
` onload='...payload...' end=x
...with the assumption that the site is going to not quote the first one, and quote the
second one with double quotes:
<body data-x=` class="` onload='...payload...' end=x">
In IE, this is treated as:
<body data-x=' class="'
onload='...payload...'
end='x"'>
-->
<div class="example">
<p>In the following example, the <code data-x="attr-input-value">value</code> attribute is given
with the unquoted attribute value syntax:</p>
<pre><code class="html"><input <em>value=yes</em>></code></pre>
</div>
<p>If an attribute using the unquoted attribute syntax is to be followed by another attribute or
by the optional U+002F SOLIDUS character (/) allowed in step 6 of the <span
data-x="syntax-start-tag">start tag</span> syntax above, then there must be <span>ASCII
whitespace</span> separating the two.</p>
</dd>
<dt>Single-quoted attribute value syntax</dt>
<dd>
<p>The <span data-x="syntax-attribute-name">attribute name</span>, followed by zero or more
<span>ASCII whitespace</span>, followed by a single U+003D EQUALS SIGN character, followed by
zero or more <span>ASCII whitespace</span>, followed by a single U+0027 APOSTROPHE character
('), followed by the <span data-x="syntax-attribute-value">attribute value</span>, which, in
addition to the requirements given above for attribute values, must not contain any literal
U+0027 APOSTROPHE characters ('), and finally followed by a second single U+0027 APOSTROPHE
character (').</p>
<div class="example">
<p>In the following example, the <code data-x="attr-input-type">type</code> attribute is given
with the single-quoted attribute value syntax:</p>
<pre><code class="html"><input <em>type='checkbox'</em>></code></pre>
</div>
<p>If an attribute using the single-quoted attribute syntax is to be followed by another
attribute, then there must be <span>ASCII whitespace</span> separating the two.</p>
</dd>
<dt>Double-quoted attribute value syntax</dt>
<dd>
<p>The <span data-x="syntax-attribute-name">attribute name</span>, followed by zero or more
<span>ASCII whitespace</span>, followed by a single U+003D EQUALS SIGN character, followed by
zero or more <span>ASCII whitespace</span>, followed by a single U+0022 QUOTATION MARK character
("), followed by the <span data-x="syntax-attribute-value">attribute value</span>, which, in
addition to the requirements given above for attribute values, must not contain any literal
U+0022 QUOTATION MARK characters ("), and finally followed by a second single U+0022 QUOTATION
MARK character (").</p>
<div class="example">
<p>In the following example, the <code data-x="attr-fe-name">name</code> attribute is given with
the double-quoted attribute value syntax:</p>
<pre><code class="html"><input <em>name="be evil"</em>></code></pre>
</div>
<p>If an attribute using the double-quoted attribute syntax is to be followed by another
attribute, then there must be <span>ASCII whitespace</span> separating the two.</p>
</dd>
</dl>
<p>There must never be two or more attributes on the same start tag whose names are an <span>ASCII
case-insensitive</span> match for each other.</p>
<hr>
<p>When a <span data-x="foreign elements">foreign element</span> has one of the namespaced
attributes given by the local name and namespace of the first and second cells of a row from the
following table, it must be written using the name given by the third cell from the same row.</p>
<table>
<thead>
<tr> <th> Local name <th> Namespace <th> Attribute name
<tbody>
<tr> <td> <code data-x="">actuate</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:actuate</code>
<tr> <td> <code data-x="">arcrole</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:arcrole</code>
<tr> <td> <code data-x="">href</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:href</code>
<tr> <td> <code data-x="">role</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:role</code>
<tr> <td> <code data-x="">show</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:show</code>
<tr> <td> <code data-x="">title</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:title</code>
<tr> <td> <code data-x="">type</code> <td> <span>XLink namespace</span> <td> <code data-x="">xlink:type</code>
<tr> <td> <code data-x="">lang</code> <td> <span>XML namespace</span> <td> <code data-x="">xml:lang</code>
<tr> <td> <code data-x="">space</code> <td> <span>XML namespace</span> <td> <code data-x="">xml:space</code>
<tr> <td> <code data-x="">xmlns</code> <td> <span>XMLNS namespace</span> <td> <code data-x="">xmlns</code>
<tr> <td> <code data-x="">xlink</code> <td> <span>XMLNS namespace</span> <td> <code data-x="">xmlns:xlink</code>
</table>
<p>No other namespaced attribute can be expressed in <span>the HTML syntax</span>.</p>
<p class="note">Whether the attributes in the table above are conforming or not is defined by
other specifications (e.g. <cite>SVG 2</cite> and <cite>MathML</cite>); this section only
describes the syntax rules if the attributes are serialized using the HTML syntax.</p>
<h5>Optional tags</h5>
<p>Certain tags can be <dfn data-x="syntax-tag-omission">omitted</dfn>.</p>
<p class="note">Omitting an element's <span data-x="syntax-start-tag">start tag</span> in the
situations described below does not mean the element is not present; it is implied, but it is
still there. For example, an HTML document always has a root <code>html</code> element, even if
the string <code data-x=""><html></code> doesn't appear anywhere in the markup.</p>
<!-- <html> -->
<p>An <code>html</code> element's <span data-x="syntax-start-tag">start tag</span> may be omitted
if the first thing inside the <code>html</code> element is not a <span
data-x="syntax-comments">comment</span>.</p>
<div class="example">
<p>For example, in the following case it's ok to remove the "<code data-x=""><html></code>"
tag:</p>
<pre><code class="html"><!DOCTYPE HTML>
<strong><html></strong>
<head>
<title>Hello</title>
</head>
<body>
<p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>Doing so would make the document look like this:</p>
<pre><code class="html"><!DOCTYPE HTML>
<head>
<title>Hello</title>
</head>
<body>
<p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>This has the exact same DOM. In particular, note that whitespace around the <span>document
element</span> is ignored by the parser. The following example would also have the exact same
DOM:</p>
<pre><code class="html"><!DOCTYPE HTML><head>
<title>Hello</title>
</head>
<body>
<p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>However, in the following example, removing the start tag moves the comment to before the
<code>html</code> element:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html>
<strong><!-- where is this comment in the DOM? --></strong>
<head>
<title>Hello</title>
</head>
<body>
<p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>With the tag removed, the document actually turns into the same as this:</p>
<pre><code class="html"><!DOCTYPE HTML>
<!-- where is this comment in the DOM? -->
<small><html></small>
<head>
<title>Hello</title>
</head>
<body>
<p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>This is why the tag can only be removed if it is not followed by a comment: removing the tag
when there is a comment there changes the document's resulting parse tree. Of course, if the
position of the comment does not matter, then the tag can be omitted, as if the comment had been
moved to before the start tag in the first place.</p>
</div>
<!-- </html> -->
<p>An <code>html</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>html</code> element is not immediately followed by a <span
data-x="syntax-comments">comment</span>.</p>
<!-- <head> -->
<p>A <code>head</code> element's <span data-x="syntax-start-tag">start tag</span> may be omitted if
the element is empty, or if the first thing inside the <code>head</code> element is an
element.</p>
<!-- </head> -->
<p>A <code>head</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>head</code> element is not immediately followed by <span>ASCII whitespace</span> or a
<span data-x="syntax-comments">comment</span>.</p>
<!-- <body> -->
<p>A <code>body</code> element's <span data-x="syntax-start-tag">start tag</span> may be omitted
if the element is empty, or if the first thing inside the <code>body</code> element is not
<span>ASCII whitespace</span> or a <span data-x="syntax-comments">comment</span>, except if the
first thing inside the <code>body</code> element is a <code>meta</code>, <code>noscript</code>,
<code>link</code>, <code>script</code>, <code>style</code>, or <code>template</code> element.
<!-- Note that even if the </head> end tag is present, the parser makes <style> and <script>
elements between </head> and <body> end up in the <head> instead of implying the <body> --></p>
<!-- </body> -->
<p>A <code>body</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>body</code> element is not immediately followed by a <span
data-x="syntax-comments">comment</span>.</p>
<div class="example">
<p>Note that in the example above, the <code>head</code> element start and end tags, and the
<code>body</code> element start tag, can't be omitted, because they are surrounded by
whitespace:</p>
<pre><code class="html"><!DOCTYPE HTML>
<html><strong>
</strong><head><strong>
</strong><title>Hello</title><strong>
</strong></head><strong>
</strong><body><strong>
</strong><p>Welcome to this example.</p>
</body>
</html></code></pre>
<p>(The <code>body</code> and <code>html</code> element end tags could be omitted without
trouble; any spaces after those get parsed into the <code>body</code> element anyway.)</p>
<p>Usually, however, whitespace isn't an issue. If we first remove the whitespace we don't care
about:</p>
<pre><code class="html"><!DOCTYPE HTML><html><head><title>Hello</title></head><body><p>Welcome to this example.</p></body></html></code></pre>
<p>Then we can omit a number of tags without affecting the DOM:</p>
<pre><code class="html"><!DOCTYPE HTML><title>Hello</title><p>Welcome to this example.</p></code></pre>
<p>At that point, we can also add some whitespace back:</p>
<pre><code class="html"><!DOCTYPE HTML>
<title>Hello</title>
<p>Welcome to this example.</p></code></pre>
<p>This would be equivalent to this document, with the omitted tags shown in their
parser-implied positions; the only whitespace text node that results from this is the newline at
the end of the <code>head</code> element:</p>
<pre><code class="html"><!DOCTYPE HTML>
<small><html><head></small><title>Hello</title>
<small></head><body></small><p>Welcome to this example.</p><small></body></html></small></code></pre>
</div>
<!-- </li> -->
<p>An <code>li</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>li</code> element is immediately followed by another <code>li</code> element or if there is
no more content in the parent element.</p>
<!-- </dt> -->
<p>A <code>dt</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>dt</code> element is immediately followed by another <code>dt</code> element or a
<code>dd</code> element.</p>
<!-- </dd> -->
<p>A <code>dd</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>dd</code> element is immediately followed by another <code>dd</code> element or a
<code>dt</code> element, or if there is no more content in the parent element.</p>
<!-- </p> -->
<p>A <code>p</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>p</code> element is immediately followed by an <code>address</code>, <code>article</code>,
<code>aside</code>, <code>blockquote</code>, <code>details</code>, <code>dialog</code>,
<code>div</code>, <code>dl</code>, <code>fieldset</code>, <code>figcaption</code>,
<code>figure</code>, <code>footer</code>, <code>form</code>, <code>h1</code>, <code>h2</code>,
<code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code>, <code>header</code>,
<code>hgroup</code>, <code>hr</code>, <code>main</code>, <code>menu</code>, <code>nav</code>,
<code>ol</code>, <code>p</code>, <code>pre</code>, <code>search</code>, <code>section</code>,
<code>table</code>, or <code>ul</code> element, or if there is no more content in the parent
element and the parent element is an <span data-x="HTML elements">HTML element</span> that is not
an <code>a</code>, <code>audio</code>, <code>del</code>, <code>ins</code>, <code>map</code>,
<code>noscript</code>, or <code>video</code> element, or an <span>autonomous custom
element</span>.</p>
<div class="example">
<p>We can thus simplify the earlier example further:
<pre><code class="html"><!DOCTYPE HTML><title>Hello</title><p>Welcome to this example.</code></pre>
</div>
<!-- </rt> -->
<p>An <code>rt</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>rt</code> element is immediately followed by an <code>rt</code> or <code>rp</code> element,
or if there is no more content in the parent element.</p>
<!-- </rp> -->
<p>An <code>rp</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>rp</code> element is immediately followed by an <code>rt</code> or <code>rp</code> element,
or if there is no more content in the parent element.</p>
<!-- </optgroup> (the text assumes <optgroup> can only be inside a <select>; commented out text
below can handle the non-<select> case if we ever allow it) -->
<p>An <code>optgroup</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted
if the <code>optgroup</code> element <!--has an ancestor <code>select</code> element and--> is
immediately followed by another <code>optgroup</code> element, if it is immediately followed by an
<code>hr</code> element, or if <!--all of the elements that are ancestors of the
<code>optgroup</code> element, up to and including the first ancestor element that is not an
<code>optgroup</code> element, have no more content--> there is no more content in the parent
element.</p>
<!-- so e.g. the max number of </optgroup>s are omitted here:
<select><optgroup></select>
<p id=x><optgroup></optgroup>x</p>
<p id=x><optgroup><optgroup></optgroup></optgroup>x</p>
<p><optgroup id=x><optgroup></optgroup>x</p>
<p><optgroup><optgroup id=x>x</p>
-->
<!-- </option> -->
<p>An <code>option</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>option</code> element is immediately followed by another <code>option</code> element, if
it is immediately followed by an <code>optgroup</code> element, if it is immediately followed by
an <code>hr</code> element, or if there is no more content in the parent element.</p>
<!-- <colgroup> -->
<p>A <code>colgroup</code> element's <span data-x="syntax-start-tag">start tag</span> may be
omitted if the first thing inside the <code>colgroup</code> element is a <code>col</code> element,
and if the element is not immediately preceded by another <code>colgroup</code> element whose
<span data-x="syntax-end-tag">end tag</span> has been omitted. (It can't be omitted if the element
is empty.)</p>
<!-- </colgroup> -->
<p>A <code>colgroup</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted
if the <code>colgroup</code> element is not immediately followed by <span>ASCII whitespace</span>
or a <span data-x="syntax-comments">comment</span>.</p>
<!-- </caption> -->
<p>A <code>caption</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>caption</code> element is not immediately followed by <span>ASCII whitespace</span> or a
<span data-x="syntax-comments">comment</span>.</p>
<!-- </thead> -->
<p>A <code>thead</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>thead</code> element is immediately followed by a <code>tbody</code> or
<code>tfoot</code> element.</p>
<!-- <tbody> -->
<p>A <code>tbody</code> element's <span data-x="syntax-start-tag">start tag</span> may be omitted
if the first thing inside the <code>tbody</code> element is a <code>tr</code> element, and if the
element is not immediately preceded by a <code>tbody</code>, <code>thead</code>, or
<code>tfoot</code> element whose <span data-x="syntax-end-tag">end tag</span> has been omitted. (It
can't be omitted if the element is empty.)</p>
<!-- </tbody> -->
<p>A <code>tbody</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
the <code>tbody</code> element is immediately followed by a <code>tbody</code> or
<code>tfoot</code> element, or if there is no more content in the parent element.</p>
<!-- </tfoot> -->
<p>A <code>tfoot</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if
there is no more content in the parent element.</p>
<!-- </tr> -->
<p>A <code>tr</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>tr</code> element is immediately followed by another <code>tr</code> element, or if there is
no more content in the parent element.</p>
<!-- </td> -->
<p>A <code>td</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>td</code> element is immediately followed by a <code>td</code> or <code>th</code> element,
or if there is no more content in the parent element.</p>
<!-- </th> -->
<p>A <code>th</code> element's <span data-x="syntax-end-tag">end tag</span> may be omitted if the
<code>th</code> element is immediately followed by a <code>td</code> or <code>th</code> element,
or if there is no more content in the parent element.</p>
<div class="example">
<p>The ability to omit all these table-related tags makes table markup much terser.</p>
<p>Take this example:</p>
<pre><code class="html"><table>
<caption>37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)</caption>
<colgroup><col><col><col></colgroup>
<thead>
<tr>
<th>Function</th>
<th>Control Unit</th>
<th>Central Station</th>
</tr>
</thead>
<tbody>
<tr>
<td>Headlights</td>
<td>✔</td>
<td>✔</td>
</tr>
<tr>
<td>Interior Lights</td>
<td>✔</td>
<td>✔</td>
</tr>
<tr>
<td>Electric locomotive operating sounds</td>
<td>✔</td>
<td>✔</td>
</tr>
<tr>
<td>Engineer's cab lighting</td>
<td></td>
<td>✔</td>
</tr>
<tr>
<td>Station Announcements - Swiss</td>
<td></td>
<td>✔</td>
</tr>
</tbody>
</table></code></pre>
<p>The exact same table, modulo some whitespace differences, could be marked up as follows:</p>
<pre><code class="html"><table>
<caption>37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)
<colgroup><col><col><col>
<thead>
<tr>
<th>Function
<th>Control Unit
<th>Central Station
<tbody>
<tr>
<td>Headlights
<td>✔
<td>✔
<tr>
<td>Interior Lights
<td>✔
<td>✔
<tr>
<td>Electric locomotive operating sounds
<td>✔
<td>✔
<tr>
<td>Engineer's cab lighting
<td>
<td>✔
<tr>
<td>Station Announcements - Swiss
<td>
<td>✔
</table></code></pre>
<p>Since the cells take up much less room this way, this can be made even terser by having each
row on one line:</p>
<pre><code class="html"><table>
<caption>37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)
<colgroup><col><col><col>
<thead>
<tr> <th>Function <th>Control Unit <th>Central Station
<tbody>
<tr> <td>Headlights <td>✔ <td>✔
<tr> <td>Interior Lights <td>✔ <td>✔
<tr> <td>Electric locomotive operating sounds <td>✔ <td>✔
<tr> <td>Engineer's cab lighting <td> <td>✔
<tr> <td>Station Announcements - Swiss <td> <td>✔
</table></code></pre>
<p>The only differences between these tables, at the DOM level, is with the precise position of
the (in any case semantically-neutral) whitespace.</p>
</div>
<p><strong>However</strong>, a <span data-x="syntax-start-tag">start tag</span> must never be
omitted if it has any attributes.</p>
<div class="example">
<p>Returning to the earlier example with all the whitespace removed and then all the optional
tags removed:</p>
<pre><code class="html"><!DOCTYPE HTML><title>Hello</title><p>Welcome to this example.</code></pre>
<p>If the <code>body</code> element in this example had to have a <code
data-x="attr-class">class</code> attribute and the <code>html</code> element had to have a <code
data-x="attr-lang">lang</code> attribute, the markup would have to become:</p>
<pre><code class="html"><!DOCTYPE HTML><html lang="en"><title>Hello</title><body class="demo"><p>Welcome to this example.</code></pre>
</div>
<p class="note">This section assumes that the document is conforming, in particular, that there
are no <span data-x="content models">content model</span> violations. Omitting tags in the fashion
described in this section in a document that does not conform to the <span>content models</span>
described in this specification is likely to result in unexpected DOM differences (this is, in
part, what the content models are designed to avoid).</p>
<h5 id="element-restrictions">Restrictions on content models</h5>
<p>For historical reasons, certain elements have extra restrictions beyond even the restrictions
given by their content model.</p>
<p>A <code>table</code> element must not contain <code>tr</code> elements, even though these
elements are technically allowed inside <code>table</code> elements according to the content
models described in this specification. (If a <code>tr</code> element is put inside a
<code>table</code> in the markup, it will in fact imply a <code>tbody</code> start tag before
it.)</p>
<p>A single <span data-x="syntax-newlines">newline</span> may be placed immediately after the <span
data-x="syntax-start-tag">start tag</span> of <code>pre</code> and <code>textarea</code> elements.
This does not affect the processing of the element. The otherwise optional <span
data-x="syntax-newlines">newline</span> <em>must</em> be included if the element's contents
themselves start with a <span data-x="syntax-newlines">newline</span> (because otherwise the
leading newline in the contents would be treated like the optional newline, and ignored).</p>
<div class="example">
<p>The following two <code>pre</code> blocks are equivalent:</p>
<pre><code class="html"><pre>Hello</pre></code></pre>
<pre><code class="html"><pre><br>Hello</pre></code></pre>
</div>
<h5 id="cdata-rcdata-restrictions">Restrictions on the contents of raw text and escapable raw text elements</h5>
<p>The text in <span data-x="raw text elements">raw text</span> and <span>escapable raw text
elements</span> must not contain any occurrences of the string "<code data-x=""></</code>"
(U+003C LESS-THAN SIGN, U+002F SOLIDUS) followed by characters that case-insensitively match the
tag name of the element followed by one of U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
(LF), U+000C FORM FEED (FF), U+000D CARRIAGE RETURN (CR), U+0020 SPACE, U+003E GREATER-THAN SIGN
(>), or U+002F SOLIDUS (/).</p>
<h4>Text</h4>
<p><dfn data-x="syntax-text">Text</dfn> is allowed inside elements, attribute values, and comments.
Extra constraints are placed on what is and what is not allowed in text based on where the text is
to be put, as described in the other sections.</p>
<h5>Newlines</h5>
<p><dfn data-x="syntax-newlines">Newlines</dfn> in HTML may be represented either as U+000D
CARRIAGE RETURN (CR) characters, U+000A LINE FEED (LF) characters, or pairs of U+000D CARRIAGE
RETURN (CR), U+000A LINE FEED (LF) characters in that order.</p>
<p>Where <span data-x="syntax-charref">character references</span> are allowed, a character
reference of a U+000A LINE FEED (LF) character (but not a U+000D CARRIAGE RETURN (CR) character)
also represents a <span data-x="syntax-newlines">newline</span>.</p>
<h4>Character references</h4>
<p>In certain cases described in other sections, <span data-x="syntax-text">text</span> may be
mixed with <dfn data-x="syntax-charref">character references</dfn>. These can be used to escape
characters that couldn't otherwise legally be included in <span
data-x="syntax-text">text</span>.</p>
<p>Character references must start with a U+0026 AMPERSAND character (&). Following this,
there are three possible kinds of character references:</p>
<dl>
<dt>Named character references</dt>
<dd>The ampersand must be followed by one of the names given in the <span>named character
references</span> section, using the same case. <span w-nodev>The name must be one that is
terminated by a U+003B SEMICOLON character (;).</span></dd>
<dt>Decimal numeric character reference</dt>
<dd>The ampersand must be followed by a U+0023 NUMBER SIGN character (#), followed by one or more
<span>ASCII digits</span>, representing a base-ten integer that corresponds to a code point that
is allowed according to the definition below. The digits must then be followed by a U+003B
SEMICOLON character (;).</dd>
<dt>Hexadecimal numeric character reference</dt>
<dd>The ampersand must be followed by a U+0023 NUMBER SIGN character (#), which must be followed
by either a U+0078 LATIN SMALL LETTER X character (x) or a U+0058 LATIN CAPITAL LETTER X
character (X), which must then be followed by one or more <span>ASCII hex digits</span>,
representing a hexadecimal integer that corresponds to a code point that is allowed according to
the definition below. The digits must then be followed by a U+003B SEMICOLON character (;).</dd>
</dl>
<p>The numeric character reference forms described above are allowed to reference any code point
excluding U+000D CR, <span data-x="noncharacter">noncharacters</span>, and <span
data-x="control">controls</span> other than <span>ASCII whitespace</span>.</p>
<p>An <dfn data-x="syntax-ambiguous-ampersand">ambiguous ampersand</dfn> is a U+0026 AMPERSAND
character (&) that is followed by one or more <span data-x="ASCII alphanumeric">ASCII
alphanumerics</span>, followed by a U+003B SEMICOLON character (;), where these characters do not
match any of the names given in the <span>named character references</span> section.</p>
<h4>CDATA sections</h4>
<p><dfn data-x="syntax-cdata">CDATA sections</dfn> must consist of the following components, in
this order:</p>
<ol>
<li>The string "<code data-x=""><![CDATA[</code>".</li>
<li>Optionally, <span data-x="syntax-text">text</span>, with the additional restriction that the
text must not contain the string "<code data-x="">]]></code>".</li>
<li>The string "<code data-x="">]]></code>".</li>
</ol>
<div class="example">
<p>CDATA sections can only be used in foreign content (MathML or SVG). In this example, a CDATA
section is used to escape the contents of a <span>MathML <code>ms</code></span> element:</p>
<pre><code class="html"><p>You can add a string to a number, but this stringifies the number:</p>
<math>
<ms><![CDATA[x<y]]></ms>
<mo>+</mo>
<mn>3</mn>
<mo>=</mo>
<ms><![CDATA[x<y3]]></ms>
</math></code></pre>
</div>
<h4>Comments</h4>
<p><dfn data-x="syntax-comments">Comments</dfn> must have the following format:</p>
<ol>
<li>The string "<code data-x=""><!--</code>".</li>
<li>Optionally, <span data-x="syntax-text">text</span>, with the additional restriction that the
text must not start with the string "<code data-x="">></code>", nor start with the string
"<code data-x="">-></code>", nor contain the strings "<code data-x=""><!--</code>", "<code
data-x="">--></code>", or "<code data-x="">--!></code>", nor end with the string "<code
data-x=""><!-</code>".</li>
<li>The string "<code data-x="">--></code>".</li>
</ol>
<p class="note">The <span data-x="syntax-text">text</span> is allowed to end with the string
"<code data-x=""><!</code>", as in <code data-x=""><!--My favorite operators are > and
<!--></code>.</p>
<!--HTMLPARSER-->
<div w-nodev>
<h3 split-filename="parsing" id="parsing">Parsing HTML documents</h3>
<p><i>This section only applies to user agents, data mining tools, and conformance
checkers.</i></p>
<p class="note">The rules for parsing XML documents into DOM trees are covered by the next
section, entitled "<span>The XML syntax</span>".</p>
<p>User agents must use the parsing rules described in this section to generate the DOM trees from
<code>text/html</code> resources. Together, these rules define what is referred to as the
<dfn export>HTML parser</dfn>.</p>
<div class="note">
<p>While the HTML syntax described in this specification bears a close resemblance to SGML and
XML, it is a separate language with its own parsing rules.</p>
<p>Some earlier versions of HTML (in particular from HTML2 to HTML4) were based on SGML and used
SGML parsing rules. However, few (if any) web browsers ever implemented true SGML parsing for
HTML documents; the only user agents to strictly handle HTML as an SGML application have
historically been validators. The resulting confusion — with validators claiming documents
to have one representation while widely deployed web browsers interoperably implemented a
different representation — has wasted decades of productivity. This version of HTML thus
returns to a non-SGML basis.</p>
<p>Authors interested in using SGML tools in their authoring pipeline are encouraged to use XML
tools and the XML serialization of HTML.</p>
</div>
<p>For the purposes of conformance checkers, if a resource is determined to be in <span>the HTML
syntax</span>, then it is an <span data-x="HTML documents">HTML document</span>.</p>
<p class="note">As stated <span data-x="HTML elements">in the terminology section</span>,
references to <span data-x="element type">element types</span> that do not explicitly specify a
namespace always refer to elements in the <span>HTML namespace</span>. For example, if the spec
talks about "a <code>menu</code> element", then that is an element with the local name "<code
data-x="">menu</code>", the namespace "<code data-x="">http://www.w3.org/1999/xhtml</code>", and
the interface <code>HTMLMenuElement</code>. Where possible, references to such elements are
hyperlinked to their definition.</p>
</div>
<div w-nodev>
<h4>Overview of the parsing model</h4>
<p class="overview"><img src="/images/parsing-model-overview.svg" width="345" height="535" alt="" class="darkmode-aware"></p>
<p>The input to the HTML parsing process consists of a stream of <span data-x="code point">code
points</span>, which is passed through a <span>tokenization</span> stage followed by a <span>tree
construction</span> stage. The output is a <code>Document</code> object.</p>
<p class="note">Implementations that <a href="#non-scripted">do not support scripting</a> do not
have to actually create a DOM <code>Document</code> object, but the DOM tree in such cases is
still used as the model for the rest of the specification.</p>
<p>In the common case, the data handled by the tokenization stage comes from the network, but
<span data-x="dynamic markup insertion">it can also come from script</span> running in the user
agent, e.g. using the <code data-x="dom-document-write">document.write()</code> API.</p>
<p id="nestedParsing">There is only one set of states for the tokenizer stage and the tree
construction stage, but the tree construction stage is reentrant, meaning that while the tree
construction stage is handling one token, the tokenizer might be resumed, causing further tokens
to be emitted and processed before the first token's processing is complete.</p>
<div class="example">
<p>In the following example, the tree construction stage will be called upon to handle a "p"
start tag token while handling the "script" end tag token:</p>
<pre><code class="html">...
<script>
document.write('<p>');
</script>
...</code></pre>
</div>
<p>To handle these cases, parsers have a <dfn>script nesting level</dfn>, which must be initially
set to zero, and a <dfn>parser pause flag</dfn>, which must be initially set to false.</p>
</div>
<div w-nodev>
<h4><dfn data-x="parse error">Parse errors</dfn></h4>
<p>This specification defines the parsing rules for HTML documents, whether they are syntactically
correct or not. Certain points in the parsing algorithm are said to be <span data-x="parse
error">parse errors</span>. The error handling for parse errors is well-defined (that's the
processing rules described throughout this specification), but user agents, while parsing an HTML
document, may <span data-x="abort a parser">abort the parser</span> at the first <span>parse
error</span> that they encounter for which they do not wish to apply the rules described in this
specification.</p>
<p>Conformance checkers must report at least one parse error condition to the user if one or more
parse error conditions exist in the document and must not report parse error conditions if none
exist in the document. Conformance checkers may report more than one parse error condition if more
than one parse error condition exists in the document.</p>
<p class="note">Parse errors are only errors with the <em>syntax</em> of HTML. In addition to
checking for parse errors, conformance checkers will also verify that the document obeys all the
other conformance requirements described in this specification.</p>
<p>Some parse errors have dedicated codes outlined in the table below that should be used by
conformance checkers in reports.</p>
<p><i>Error descriptions in the table below are non-normative.</i></p>
<table class="parse-error-table">
<thead>
<tr>
<th>Code
<th>Description
<tbody>
<tr>
<td><dfn data-x="parse-error-abrupt-closing-of-empty-comment">abrupt-closing-of-empty-comment</dfn>
<td><p>This error occurs if the parser encounters an empty <span
data-x="syntax-comments">comment</span> that is abruptly closed by a U+003E (>) <span>code
point</span> (i.e., <code data-x=""><!--></code> or <code data-x=""><!---></code>). The
parser behaves as if the comment is closed correctly.</p>
<tr>
<td><dfn data-x="parse-error-abrupt-doctype-public-identifier">abrupt-doctype-public-identifier</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> in the
<span data-x="syntax-doctype">DOCTYPE</span> public identifier (e.g., <code
data-x=""><!DOCTYPE html PUBLIC "foo></code>). In such a case, if the DOCTYPE is correctly
placed as a document preamble, the parser sets the <code>Document</code> to <span>quirks
mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-abrupt-doctype-system-identifier">abrupt-doctype-system-identifier</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> in the
<span data-x="syntax-doctype">DOCTYPE</span> system identifier (e.g., <code
data-x=""><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "foo></code>). In such a case,
if the DOCTYPE is correctly placed as a document preamble, the parser sets the
<code>Document</code> to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-absence-of-digits-in-numeric-character-reference">absence-of-digits-in-numeric-character-reference</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that doesn't contain any digits (e.g., <code
data-x="">&#qux;</code>). In this case the parser doesn't resolve the character
reference.</p>
<tr>
<td><dfn data-x="parse-error-cdata-in-html-content">cdata-in-html-content</dfn>
<td><p>This error occurs if the parser encounters a <span data-x="syntax-cdata">CDATA
section</span> outside of foreign content (SVG or MathML). The parser treats such CDATA
sections (including leading "<code data-x="">[CDATA[</code>" and trailing "<code
data-x="">]]</code>" strings) as comments.</p>
<tr>
<td><dfn data-x="parse-error-character-reference-outside-unicode-range">character-reference-outside-unicode-range</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that references a <span>code point</span>
that is greater than the valid Unicode range. The parser resolves such a character reference to
a U+FFFD REPLACEMENT CHARACTER.</p>
<tr>
<td><dfn data-x="parse-error-control-character-in-input-stream">control-character-in-input-stream</dfn>
<td><p>This error occurs if the <span>input stream</span> contains a <span
data-x="control">control</span> <span>code point</span> that is not <span>ASCII
whitespace</span> or U+0000 NULL. Such code points are parsed as-is and usually, where parsing
rules don't apply any additional restrictions, make their way into the DOM.</p>
<tr>
<td><dfn data-x="parse-error-control-character-reference">control-character-reference</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that references a <span
data-x="control">control</span> <span>code point</span> that is not <span>ASCII
whitespace</span> or is a U+000D CARRIAGE RETURN. The parser resolves such character references
as-is except C1 control references that are replaced according to the <span>numeric character
reference end state</span>.</p>
<tr>
<td><dfn data-x="parse-error-duplicate-attribute">duplicate-attribute</dfn>
<td><p>This error occurs if the parser encounters an <span
data-x="syntax-attributes">attribute</span> in a tag that already has an attribute with the
same name. The parser ignores all such duplicate occurrences of the attribute.
<tr>
<td><dfn data-x="parse-error-end-tag-with-attributes">end-tag-with-attributes</dfn>
<td><p>This error occurs if the parser encounters an <span data-x="syntax-end-tag">end
tag</span> with <span data-x="syntax-attributes">attributes</span>. Attributes in end tags are
ignored and do not make their way into the DOM.</p>
<tr>
<td><dfn data-x="parse-error-end-tag-with-trailing-solidus">end-tag-with-trailing-solidus</dfn>
<td><p>This error occurs if the parser encounters an <span data-x="syntax-end-tag">end
tag</span> that has a U+002F (/) <span>code point</span> right before the closing U+003E (>)
code point (e.g., <code data-x=""></div/></code>). Such a tag is treated as a regular end
tag.</p>
<tr>
<td><dfn data-x="parse-error-eof-before-tag-name">eof-before-tag-name</dfn>
<td><p>This error occurs if the parser encounters the end of the <span>input stream</span>
where a tag name is expected. In this case the parser treats the beginning of a <span
data-x="syntax-start-tag">start tag</span> (i.e., <code data-x=""><</code>) or an <span
data-x="syntax-end-tag">end tag</span> (i.e., <code data-x=""></</code>) as text
content.</p>
<tr>
<td><dfn data-x="parse-error-eof-in-cdata">eof-in-cdata</dfn>
<td><p>This error occurs if the parser encounters the end of the <span>input stream</span> in a
<span data-x="syntax-cdata">CDATA section</span>. The parser treats such CDATA sections as if
they are closed immediately before the end of the input stream.</p>
<tr>
<td><dfn data-x="parse-error-eof-in-comment">eof-in-comment</dfn>
<td><p>This error occurs if the parser encounters the end of the <span>input stream</span> in a
<span data-x="syntax-comments">comment</span>. The parser treats such comments as if they are
closed immediately before the end of the input stream.</p>
<tr>
<td><dfn data-x="parse-error-eof-in-doctype">eof-in-doctype</dfn>
<td><p>This error occurs if the parser encounters the end of the input stream in a <span
data-x="syntax-doctype">DOCTYPE</span>. In such a case, if the DOCTYPE is correctly placed as a
document preamble, the parser sets the <code>Document</code> to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</dfn>
<td>
<p>This error occurs if the parser encounters the end of the <span>input stream</span> in text
that resembles an <span data-x="syntax-comments">HTML comment</span> inside
<code>script</code> element content (e.g., <code data-x=""><script><!-- foo</code>).</p>
<p class="note">Syntactic structures that resemble HTML comments in <code>script</code>
elements are parsed as text content. They can be a part of a scripting language-specific
syntactic structure or be treated as an HTML-like comment, if the scripting language supports
them (e.g., parsing rules for HTML-like comments can be found in Annex B of the JavaScript
specification). The common reason for this error is a violation of the <span data-x="script
content restrictions">restrictions for contents of <code>script</code> elements</span>. <ref>JAVASCRIPT</ref></p>
<tr>
<td><dfn data-x="parse-error-eof-in-tag">eof-in-tag</dfn>
<td><p>This error occurs if the parser encounters the end of the <span>input stream</span> in a
<span data-x="syntax-start-tag">start tag</span> or an <span data-x="syntax-end-tag">end
tag</span> (e.g., <code data-x=""><div id=</code>). Such a tag is ignored.</p>
<tr>
<td><dfn data-x="parse-error-incorrectly-closed-comment">incorrectly-closed-comment</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-comments">comment</span> that is closed by the "<code data-x="">--!></code>"
<span>code point</span> sequence. The parser treats such comments as if they are correctly
closed by the "<code data-x="">--></code>" code point sequence.</p>
<tr>
<td><dfn data-x="parse-error-incorrectly-opened-comment">incorrectly-opened-comment</dfn>
<td>
<p>This error occurs if the parser encounters the "<code data-x=""><!</code>" <span>code
point</span> sequence that is not immediately followed by two U+002D (-) code points and that
is not the start of a <span data-x="syntax-doctype">DOCTYPE</span> or a <span
data-x="syntax-cdata">CDATA section</span>. All content that follows the "<code
data-x=""><!</code>" code point sequence up to a U+003E (>) code point (if present) or to
the end of the <span>input stream</span> is treated as a comment.</p>
<p class="note">One possible cause of this error is using an XML markup declaration (e.g.,
<code data-x=""><!ELEMENT br EMPTY></code>) in HTML.</p>
<tr>
<td><dfn data-x="parse-error-invalid-character-sequence-after-doctype-name">invalid-character-sequence-after-doctype-name</dfn>
<td><p>This error occurs if the parser encounters any <span>code point</span> sequence other
than "<code data-x="">PUBLIC</code>" and "<code data-x="">SYSTEM</code>" keywords after a <span
data-x="syntax-doctype">DOCTYPE</span> name. In such a case, the parser ignores any following
public or system identifiers, and if the DOCTYPE is correctly placed as a document preamble,
and if the <span>parser cannot change the mode flag</span> is false, sets the <code>Document</code>
to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-invalid-first-character-of-tag-name">invalid-first-character-of-tag-name</dfn>
<td>
<p>This error occurs if the parser encounters a <span>code point</span> that is not an
<span>ASCII alpha</span> where first code point of a <span data-x="syntax-start-tag">start
tag</span> name or an <span data-x="syntax-end-tag">end tag</span> name is expected. If a
start tag was expected such code point and a preceding U+003C (<) is treated as text
content, and all content that follows is treated as markup. Whereas, if an end tag was
expected, such code point and all content that follows up to a U+003E (>) code point (if
present) or to the end of the <span>input stream</span> is treated as a comment.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><42></42></code></pre>
<p>This will be parsed into:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t3"><code>#text</code>: <span data-x=""><42></span></li><li class="t8"><code>#comment</code>: <span data-x="">42</span></li></ul></li></ul></li></ul>
</div>
<p class="note">While the first code point of a tag name is limited to an <span>ASCII
alpha</span>, a wide range of code points (including <span>ASCII digits</span>) is allowed in
subsequent positions.</p>
<tr>
<td><dfn data-x="parse-error-missing-attribute-value">missing-attribute-value</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> where an
<span data-x="syntax-attributes">attribute</span> value is expected (e.g., <code
data-x=""><div id=></code>). The parser treats the attribute as having an empty value.</p>
<tr>
<td><dfn data-x="parse-error-missing-doctype-name">missing-doctype-name</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-doctype">DOCTYPE</span> that is missing a name (e.g., <code
data-x=""><!DOCTYPE></code>). In such a case, if the DOCTYPE is correctly placed as a
document preamble, the parser sets the <code>Document</code> to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-missing-doctype-public-identifier">missing-doctype-public-identifier</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> where
start of the <span data-x="syntax-doctype">DOCTYPE</span> public identifier is expected (e.g.,
<code data-x=""><!DOCTYPE html PUBLIC ></code>). In such a case, if the DOCTYPE is correctly
placed as a document preamble, the parser sets the <code>Document</code> to <span>quirks
mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-missing-doctype-system-identifier">missing-doctype-system-identifier</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> where
start of the <span data-x="syntax-doctype">DOCTYPE</span> system identifier is expected (e.g.,
<code data-x=""><!DOCTYPE html SYSTEM ></code>). In such a case, if the DOCTYPE is correctly
placed as a document preamble, the parser sets the <code>Document</code> to <span>quirks
mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-missing-end-tag-name">missing-end-tag-name</dfn>
<td><p>This error occurs if the parser encounters a U+003E (>) <span>code point</span> where an
<span data-x="syntax-end-tag">end tag</span> name is expected, i.e., <code
data-x=""></></code>. The parser ignores the whole "<code data-x=""></></code>" code
point sequence.</p>
<tr>
<td><dfn data-x="parse-error-missing-quote-before-doctype-public-identifier">missing-quote-before-doctype-public-identifier</dfn>
<td><p>This error occurs if the parser encounters the <span
data-x="syntax-doctype">DOCTYPE</span> public identifier that is not preceded by a quote (e.g.,
<code data-x=""><!DOCTYPE html PUBLIC -//W3C//DTD HTML 4.01//EN"></code>). In such a case,
the parser ignores the public identifier, and if the DOCTYPE is correctly placed as a document
preamble, sets the <code>Document</code> to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-missing-quote-before-doctype-system-identifier">missing-quote-before-doctype-system-identifier</dfn>
<td><p>This error occurs if the parser encounters the <span
data-x="syntax-doctype">DOCTYPE</span> system identifier that is not preceded by a quote (e.g.,
<code data-x=""><!DOCTYPE html SYSTEM
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"></code>). In such a case, the parser
ignores the system identifier, and if the DOCTYPE is correctly placed as a document preamble,
sets the <code>Document</code> to <span>quirks mode</span>.</p>
<tr>
<td><dfn data-x="parse-error-missing-semicolon-after-character-reference">missing-semicolon-after-character-reference</dfn>
<td>
<p>This error occurs if the parser encounters a <span data-x="syntax-charref">character
reference</span> that is not terminated by a U+003B (;) <span>code point</span>. Usually the
parser behaves as if character reference is terminated by the U+003B (;) code point; however,
there are some ambiguous cases in which the parser includes subsequent code points in the
character reference.</p>
<p class="example">For example, <code data-x="">&not;in</code> will be parsed as "<code
data-x="">¬in</code>" whereas <code data-x="">&notin</code> will be parsed as "<code
data-x="">∉</code>".</p>
<tr>
<td><dfn data-x="parse-error-missing-whitespace-after-doctype-public-keyword">missing-whitespace-after-doctype-public-keyword</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-doctype">DOCTYPE</span> whose "<code data-x="">PUBLIC</code>" keyword and public
identifier are not separated by <span>ASCII whitespace</span>. In this case the parser behaves
as if ASCII whitespace is present.</p>
<tr>
<td><dfn data-x="parse-error-missing-whitespace-after-doctype-system-keyword">missing-whitespace-after-doctype-system-keyword</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-doctype">DOCTYPE</span> whose "<code data-x="">SYSTEM</code>" keyword and system
identifier are not separated by <span>ASCII whitespace</span>. In this case the parser behaves
as if ASCII whitespace is present.</p>
<tr>
<td><dfn data-x="parse-error-missing-whitespace-before-doctype-name">missing-whitespace-before-doctype-name</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-doctype">DOCTYPE</span> whose "<code data-x="">DOCTYPE</code>" keyword and name
are not separated by <span>ASCII whitespace</span>. In this case the parser behaves as if ASCII
whitespace is present.</p>
<tr>
<td><dfn data-x="parse-error-missing-whitespace-between-attributes">missing-whitespace-between-attributes</dfn>
<td><p>This error occurs if the parser encounters <span
data-x="syntax-attributes">attributes</span> that are not separated by <span>ASCII
whitespace</span> (e.g., <code data-x=""><div id="foo"class="bar"></code>). In this case the
parser behaves as if ASCII whitespace is present.</p>
<tr>
<td><dfn data-x="parse-error-missing-whitespace-between-doctype-public-and-system-identifiers">missing-whitespace-between-doctype-public-and-system-identifiers</dfn>
<td><p>This error occurs if the parser encounters a <span
data-x="syntax-doctype">DOCTYPE</span> whose public and system identifiers are not separated by
<span>ASCII whitespace</span>. In this case the parser behaves as if ASCII whitespace is
present.</p>
<tr>
<td><dfn data-x="parse-error-nested-comment">nested-comment</dfn>
<td><p>This error occurs if the parser encounters a nested <span
data-x="syntax-comments">comment</span> (e.g., <code data-x=""><!-- <!-- nested -->
--></code>). Such a comment will be closed by the first occurring "<code data-x="">--></code>"
<span>code point</span> sequence and everything that follows will be treated as markup.</p>
<tr>
<td><dfn data-x="parse-error-noncharacter-character-reference">noncharacter-character-reference</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that references a <span>noncharacter</span>.
The parser resolves such character references as-is.</p>
<tr>
<td><dfn data-x="parse-error-noncharacter-in-input-stream">noncharacter-in-input-stream</dfn>
<td><p>This error occurs if the <span>input stream</span> contains a <span>noncharacter</span>.
Such <span data-x="code point">code points</span> are parsed as-is and usually, where parsing
rules don't apply any additional restrictions, make their way into the DOM.</p>
<tr>
<td><dfn data-x="parse-error-non-void-html-element-start-tag-with-trailing-solidus">non-void-html-element-start-tag-with-trailing-solidus</dfn>
<td>
<p>This error occurs if the parser encounters a <span data-x="syntax-start-tag">start
tag</span> for an element that is not in the list of <span>void elements</span> or is not a
part of foreign content (i.e., not an SVG or MathML element) that has a U+002F (/) <span>code
point</span> right before the closing U+003E (>) code point. The parser behaves as if the
U+002F (/) is not present.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><div/><span></span><span></span></code></pre>
<p>This will be parsed into:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>div</code><ul><li class="t1"><code>span</code></li><li class="t1"><code>span</code></li></ul></li></ul></li></ul></li></ul>
</div>
<p class="note">The trailing U+002F (/) in a start tag name can be used only in foreign
content to specify self-closing tags. (Self-closing tags don't exist in HTML.) It is also
allowed for void elements, but doesn't have any effect in this case.</p>
<tr>
<td><dfn data-x="parse-error-null-character-reference">null-character-reference</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that references a U+0000 NULL <span>code
point</span>. The parser resolves such character references to a U+FFFD REPLACEMENT
CHARACTER.</p>
<tr>
<td><dfn data-x="parse-error-surrogate-character-reference">surrogate-character-reference</dfn>
<td><p>This error occurs if the parser encounters a numeric <span
data-x="syntax-charref">character reference</span> that references a <span>surrogate</span>.
The parser resolves such character references to a U+FFFD REPLACEMENT CHARACTER.</p>
<tr>
<td><dfn data-x="parse-error-surrogate-in-input-stream">surrogate-in-input-stream</dfn>
<td>
<p>This error occurs if the <span>input stream</span> contains a <span
data-x="surrogate">surrogate</span>. Such <span data-x="code point">code points</span> are
parsed as-is and usually, where parsing rules don't apply any additional restrictions, make
their way into the DOM.</p>
<p class="note">Surrogates can only find their way into the input stream via script APIs such
as <code data-x="dom-document-write">document.write()</code>.</p>
<tr>
<td><dfn data-x="parse-error-unexpected-character-after-doctype-system-identifier">unexpected-character-after-doctype-system-identifier</dfn>
<td><p>This error occurs if the parser encounters any <span data-x="code point">code
points</span> other than <span>ASCII whitespace</span> or closing U+003E (>) after the <span
data-x="syntax-doctype">DOCTYPE</span> system identifier. The parser ignores these code
points.</p>
<tr>
<td><dfn data-x="parse-error-unexpected-character-in-attribute-name">unexpected-character-in-attribute-name</dfn>
<td>
<p>This error occurs if the parser encounters a U+0022 ("), U+0027 ('), or U+003C (<)
<span>code point</span> in an <span data-x="syntax-attribute-name">attribute name</span>. The
parser includes such code points in the attribute name.</p>
<p class="note">Code points that trigger this error are usually a part of another syntactic
construct and can be a sign of a typo around the attribute name.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><div foo<div></code></pre>
<p>Due to a forgotten U+003E (>) code point after <code data-x="">foo</code> the parser
treats this markup as a single <code>div</code> element with a "<code
data-x="">foo<div</code>" attribute.</p>
<p>As another example of this error, consider the following markup:</p>
<pre><code class="html"><div id'bar'></code></pre>
<p>Due to a forgotten U+003D (=) code point between an attribute name and value the parser
treats this markup as a <code>div</code> element with the attribute "<code
data-x="">id'bar'</code>" that has an empty value.</p>
</div>
<tr>
<td><dfn data-x="parse-error-unexpected-character-in-unquoted-attribute-value">unexpected-character-in-unquoted-attribute-value</dfn>
<td>
<p>This error occurs if the parser encounters a U+0022 ("), U+0027 ('), U+003C (<), U+003D
(=), or U+0060 (`) <span>code point</span> in an unquoted <span
data-x="syntax-attribute-value">attribute value</span>. The parser includes such code points
in the attribute value.</p>
<p class="note">Code points that trigger this error are usually a part of another syntactic
construct and can be a sign of a typo around the attribute value.</p>
<p class="note">U+0060 (`) is in the list of code points that trigger this error because
certain legacy user agents treat it as a quote.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><div foo=b'ar'></code></pre>
<p>Due to a misplaced U+0027 (') code point the parser sets the value of the "<code
data-x="">foo</code>" attribute to "<code data-x="">b'ar'</code>".</p>
</div>
<tr>
<td><dfn data-x="parse-error-unexpected-equals-sign-before-attribute-name">unexpected-equals-sign-before-attribute-name</dfn>
<td>
<p>This error occurs if the parser encounters a U+003D (=) <span>code point</span> before an
attribute name. In this case the parser treats U+003D (=) as the first code point of the
attribute name.</p>
<p class="note">The common reason for this error is a forgotten attribute name.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><div foo="bar" ="baz"></code></pre>
<p>Due to a forgotten attribute name the parser treats this markup as a <code>div</code>
element with two attributes: a "<code data-x="">foo</code>" attribute with a "<code
data-x="">bar</code>" value and a "<code data-x="">="baz"</code>" attribute with an empty
value.</p>
</div>
<tr>
<td><dfn data-x="parse-error-unexpected-null-character">unexpected-null-character</dfn>
<td><p>This error occurs if the parser encounters a U+0000 NULL <span>code point</span> in the
<span>input stream</span> in certain positions. In general, such code points are either
ignored or, for security reasons, replaced with a U+FFFD REPLACEMENT CHARACTER.</p>
<tr>
<td><dfn data-x="parse-error-unexpected-question-mark-instead-of-tag-name">unexpected-question-mark-instead-of-tag-name</dfn>
<td>
<p>This error occurs if the parser encounters a U+003F (?) <span>code point</span> where first
code point of a <span data-x="syntax-start-tag">start tag</span> name is expected. The U+003F
(?) and all content that follows up to a U+003E (>) code point (if present) or to the end of
the <span>input stream</span> is treated as a comment.</p>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><?xml-stylesheet type="text/css" href="style.css"?></code></pre>
<p>This will be parsed into:</p>
<ul class="domTree"><li class="t8"><code>#comment</code>: <span data-x="">?xml-stylesheet type="text/css" href="style.css"?</span></li><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code></li></ul></li></ul>
</div>
<p class="note">The common reason for this error is an XML processing instruction (e.g., <code
data-x=""><?xml-stylesheet type="text/css" href="style.css"?></code>) or an XML declaration
(e.g., <code data-x=""><?xml version="1.0" encoding="UTF-8"?></code>) being used in
HTML.</p>
<tr>
<td><dfn data-x="parse-error-unexpected-solidus-in-tag">unexpected-solidus-in-tag</dfn>
<td><p>This error occurs if the parser encounters a U+002F (/) <span>code point</span> that is
not a part of a quoted <span data-x="syntax-attributes">attribute</span> value and not
immediately followed by a U+003E (>) code point in a tag (e.g., <code data-x=""><div /
id="foo"></code>). In this case the parser behaves as if it encountered <span>ASCII
whitespace</span>.</p>
<tr>
<td><dfn data-x="parse-error-unknown-named-character-reference">unknown-named-character-reference</dfn>
<td><p>This error occurs if the parser encounters an <span
data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>. In this case the parser doesn't
resolve the <span data-x="syntax-charref">character reference</span>.</p>
</table>
</div>
<div w-nodev>
<h4>The <dfn>input byte stream</dfn></h4>
<p>The stream of code points that comprises the input to the tokenization stage will be initially
seen by the user agent as a stream of bytes (typically coming over the network or from the local
file system). The bytes encode the actual characters according to a particular <i>character
encoding</i>, which the user agent uses to decode the bytes into characters.</p>
<p class="note">For XML documents, the algorithm user agents are required to use to determine the
character encoding is given by <cite>XML</cite>. This section does not apply to XML documents.
<ref>XML</ref></p>
<p>Usually, the <span>encoding sniffing algorithm</span> defined below is used to determine the
character encoding.</p>
<p>Given a character encoding, the bytes in the <span>input byte stream</span> must be converted
to characters for the tokenizer's <span>input stream</span>, by passing the <span>input byte
stream</span> and character encoding to <span>decode</span>.</p>
<p class="note">A leading Byte Order Mark (BOM) causes the character encoding argument to be
ignored and will itself be skipped.</p>
<p class="note">Bytes or sequences of bytes in the original byte stream that did not conform to
the Encoding standard (e.g. invalid UTF-8 byte sequences in a UTF-8 input byte stream) are errors
that conformance checkers are expected to report. <ref>ENCODING</ref></p>
<p class="warning">The decoder algorithms describe how to handle invalid input; for security
reasons, it is imperative that those rules be followed precisely. Differences in how invalid byte
sequences are handled can result in, amongst other problems, script injection vulnerabilities
("XSS").</p>
<p>When the HTML parser is decoding an input byte stream, it uses a character encoding and a <dfn
data-x="concept-encoding-confidence">confidence</dfn>. The confidence is either <i>tentative</i>,
<i>certain</i>, or <i>irrelevant</i>. The encoding used, and whether the confidence in that
encoding is <i>tentative</i> or <i>certain</i>, is <a href="#meta-charset-during-parse">used
during the parsing</a> to determine whether to <span>change the encoding</span>. If no encoding is
necessary, e.g. because the parser is operating on a Unicode stream and doesn't have to use a
character encoding at all, then the <span data-x="concept-encoding-confidence">confidence</span> is
<i>irrelevant</i>.</p>
<p class="note">Some algorithms feed the parser by directly adding characters to the <span>input
stream</span> rather than adding bytes to the <span>input byte stream</span>.</p>
<h5>Parsing with a known character encoding</h5>
<p>When the HTML parser is to operate on an input byte stream that has <dfn export>a known
definite encoding</dfn>, then the character encoding is that encoding and the <span
data-x="concept-encoding-confidence">confidence</span> is <i>certain</i>.</p>
<h5>Determining the character encoding</h5>
<p>In some cases, it might be impractical to unambiguously determine the encoding before parsing
the document. Because of this, this specification provides for a two-pass mechanism with an
optional pre-scan. Implementations are allowed, as described below, to apply a simplified parsing
algorithm to whatever bytes they have available before beginning to parse the document. Then, the
real parser is started, using a tentative encoding derived from this pre-parse and other
out-of-band metadata. If, while the document is being loaded, the user agent discovers a character
encoding declaration that conflicts with this information, then the parser can get reinvoked to
perform a parse of the document with the real encoding.</p>
<p id="documentEncoding">User agents must use the following algorithm, called the <dfn>encoding
sniffing algorithm</dfn>, to determine the character encoding to use when decoding a document in
the first pass. This algorithm takes as input any out-of-band metadata available to the user agent
(e.g. the <span data-x="Content-Type">Content-Type metadata</span> of the document) and all the
bytes available so far, and returns a character encoding and a <span
data-x="concept-encoding-confidence">confidence</span> that is either <i>tentative</i> or
<i>certain</i>.</p>
<ol>
<li>
<p>If the result of <span data-x="BOM sniff">BOM sniffing</span> is an encoding, return that
encoding with <span data-x="concept-encoding-confidence">confidence</span> <i>certain</i>.</p>
<p class="note">Although the <span>decode</span> algorithm will itself change the encoding to
use based on the presence of a byte order mark, this algorithm sniffs the BOM as well in order
to set the correct <span>document's character encoding</span> and <span
data-x="concept-encoding-confidence">confidence</span>.</p>
</li>
<li>
<p>If the user has explicitly instructed the user agent to override the document's character
encoding with a specific encoding, optionally return that encoding with the <span
data-x="concept-encoding-confidence">confidence</span> <i>certain</i>.</p>
<p class="note">Typically, user agents remember such user requests across sessions, and in some
cases apply them to documents in <code>iframe</code>s as well.</p>
</li>
<li>
<p>The user agent may wait for more bytes of the resource to be available, either in this step
or at any later step in this algorithm. For instance, a user agent might wait 500ms or 1024
bytes, whichever came first. In general preparsing the source to find the encoding improves
performance, as it reduces the need to throw away the data structures used when parsing upon
finding the encoding information. However, if the user agent delays too long to obtain data to
determine the encoding, then the cost of the delay could outweigh any performance improvements
from the preparse.</p>
<p class="note">The authoring conformance requirements for character encoding declarations limit
them to only appearing <a href="#charset1024">in the first 1024 bytes</a>. User agents are
therefore encouraged to use the prescan algorithm below (as invoked by these steps) on the first
1024 bytes, but not to stall beyond that.</p>
</li>
<li><p>If the transport layer specifies a character encoding, and it is supported, return that
encoding with the <span data-x="concept-encoding-confidence">confidence</span> <i>certain</i>.</p></li>
<li>
<p>Optionally <span data-x="prescan a byte stream to determine its encoding">prescan the byte
stream to determine its encoding</span>, with the <i><span data-x="prescan-end-condition">end
condition</span></i> being when the user agent decides that scanning further bytes would not be
efficient. User agents are encouraged to only prescan the first 1024 bytes. User agents may
decide that scanning <em>any</em> bytes is not efficient, in which case these substeps are
entirely skipped.</p>
<p>The aforementioned algorithm returns either a character encoding or failure. If it returns a
character encoding, then return the same encoding, with <span
data-x="concept-encoding-confidence">confidence</span> <i>tentative</i>.</p>
</li>
<li>
<p>If the <span>HTML parser</span> for which this algorithm is being run is associated with a
<code>Document</code> <var>d</var> whose <span data-x="doc-container-document">container
document</span> is non-null, then:</p>
<ol>
<li><p>Let <var>parentDocument</var> be <var>d</var>'s <span
data-x="doc-container-document">container document</span>.</p></li>
<li><p>If <var>parentDocument</var>'s <span data-x="concept-document-origin">origin</span> is
<span>same origin</span> with <var>d</var>'s <span
data-x="concept-document-origin">origin</span> and <var>parentDocument</var>'s <span
data-x="document's character encoding">character encoding</span> is not
<span>UTF-16BE/LE</span>, then return <var>parentDocument</var>'s <span data-x="document's
character encoding">character encoding</span>, with the <span
data-x="concept-encoding-confidence">confidence</span> <i>tentative</i>.</p></li>
</ol>
</li>
<li><p>Otherwise, if the user agent has information on the likely encoding for this page, e.g.
based on the encoding of the page when it was last visited, then return that encoding, with the
<span data-x="concept-encoding-confidence">confidence</span> <i>tentative</i>.</p></li>
<li>
<p>The user agent may attempt to autodetect the character encoding from applying frequency
analysis or other algorithms to the data stream. Such algorithms may use information about the
resource other than the resource's contents, including the address of the resource. If
autodetection succeeds in determining a character encoding, and that encoding is a supported
encoding, then return that encoding, with the <span
data-x="concept-encoding-confidence">confidence</span> <i>tentative</i>.
<ref>UNIVCHARDET</ref></p>
<p class="note">User agents are generally discouraged from attempting to autodetect encodings
for resources obtained over the network, since doing so involves inherently non-interoperable
heuristics. Attempting to detect encodings based on an HTML document's preamble is especially
tricky since HTML markup typically uses only ASCII characters, and HTML documents tend to begin
with a lot of markup rather than with text content.</p>
<p class="note">The UTF-8 encoding has a highly detectable bit pattern. Files from the local
file system that contain bytes with values greater than 0x7F which match the UTF-8 pattern are
very likely to be UTF-8, while documents with byte sequences that do not match it are very
likely not. When a user agent can examine the whole file, rather than just the preamble,
detecting for UTF-8 specifically can be especially effective. <ref>PPUTF8</ref>
<ref>UTF8DET</ref></p>
</li>
<li>
<p>Otherwise, return an <span>implementation-defined</span> or user-specified default character
encoding, with the <span data-x="concept-encoding-confidence">confidence</span>
<i>tentative</i>.</p>
<p>In controlled environments or in environments where the encoding of documents can be
prescribed (for example, for user agents intended for dedicated use in new networks), the
comprehensive <code data-x="">UTF-8</code> encoding is suggested.</p>
<p>In other environments, the default encoding is typically dependent on the user's locale (an
approximation of the languages, and thus often encodings, of the pages that the user is likely
to frequent). The following table gives suggested defaults based on the user's locale, for
compatibility with legacy content. Locales are identified by BCP 47 language tags.
<ref>BCP47</ref> <ref>ENCODING</ref></p>
<!-- based on three sources:
1. Mozilla 1.9.1 localizations: http://mxr.mozilla.org/l10n-mozilla1.9.1/find?string=global%2Fintl.properties&tree=l10n-mozilla1.9.1&hint= (though this data was apparently misinterpreted in some cases)
2. Windows Vista encodings: http://msdn.microsoft.com/en-us/goglobal/bb896001
3. Chrome encodings: https://code.google.com/p/chromium/codesearch#search/&q=IDS_DEFAULT_ENCODING
several assumptions were made in this process; amongst them:
- ISO-8859-1 and windows-1252 are the same (supported by encoding.spec.whatwg.org)
- ISO-8859-9 and windows-1254 are the same (supported by encoding.spec.whatwg.org)
- windows-31J and Shift_JIS are the same (supported by encoding.spec.whatwg.org)
- windows-932 is close enough to Shift_JIS to be treated as equivalent (supported by wikipedia)
- windows-936 is basically the same as GBK which is a subset of gb18030 (supported by wikipedia), but use GBK for its conservative encoder
- windows-950 is basically the same as Big5 (supported by wikipedia)
- Firefox's UTF-8 defaults are all bogus
-->
<table>
<thead>
<tr>
<th colspan=2>Locale language
<th>Suggested default encoding
<tbody>
<!-- af, Afrikaans, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- am, Amharic, uses windows-1252: Firefox and Chrome agreed -->
<tr>
<td>ar
<td>Arabic
<td><span>windows-1256</span> <!-- Windows Vista and Chrome agreed -->
<!-- arn-CL, Mapudungun (Chile), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- az, Azeri, is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1254 -->
<!-- Subsequent observation from Firefox telemetry changed this: -->
<tr>
<td>az
<td>Azeri
<td><span>windows-1254</span>
<!-- az-Cyrl-AZ, Azeri (Cyrillic, Azerbaijan), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- ba-RU, Bashkir (Russia), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- ba wasn't listed at all because none of the sources knew about it. However, further feedback has changed this: -->
<tr>
<td>ba
<td>Bashkir
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- be, Belarusian, was not initially listed here because Windows Vista wanted windows-1251, Chrome wanted <none>, and Firefox wanted ISO-8859-5 -->
<!-- further feedback has changed this: -->
<tr>
<td>be
<td>Belarusian
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- be-BY, Belarusian (Belarus), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<tr>
<td>bg
<td>Bulgarian
<td><span>windows-1251</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- bn, Bengali, uses windows-1252: Firefox and Chrome agreed -->
<!-- br-FR, Breton (France), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- bs-Cyrl-BA, Bosnian (Cyrillic, Bosnia and Herzegovina), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- bs-Latn-BA, Bosnian (Latin, Bosnia and Herzegovina), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- ca, Catalan, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- co-FR, Corsican (France), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>cs
<td>Czech
<td><span>windows-1250</span> <!-- Windows Vista and Chrome agreed (but disagreed with Firefox, which reportedly agreed on Windows but thought the encoding should be ISO-8859-2 on Mac and Linux) -->
<!-- cy-GB, Welsh (United Kingdom), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- da, Danish, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- de, German, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- el, Greek, was not initially listed here because Windows Vista wanted windows-1253, Chrome wanted ISO-8859-7, and Firefox wanted ISO-8859-7 but looked liked it wanted windows-1252 -->
<!-- el-GR, Greek (Greece), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1253 -->
<!-- further feedback has changed this: -->
<tr>
<td>el
<td>Greek
<td><span>ISO-8859-7</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23090 -->
<!-- en, English, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- es, Spanish, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<tr>
<td>et
<td>Estonian
<td><span>windows-1257</span> <!-- Windows Vista and Chrome agreed -->
<!-- eu, Basque, uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>fa
<td>Persian
<td><span>windows-1256</span> <!-- Windows Vista and Chrome agreed -->
<!-- fi, Finnish, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- fil, Filipino, uses windows-1252: Firefox and Chrome agreed -->
<!-- fo, Faroese, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- fr, French, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- fy-NL, Frisian (Netherlands), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- ga-IE, Irish (Ireland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- gl, Galician, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- gsw-FR, Alsatian (France), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- gu, Gujarati, uses windows-1252: Firefox and Chrome agreed -->
<!-- ha-Latn-NG, Hausa (Latin, Nigeria), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>he
<td>Hebrew
<td><span>windows-1255</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- hi, Hindi, uses windows-1252: Firefox and Chrome agreed -->
<tr>
<td>hr
<td>Croatian
<td><span>windows-1250</span> <!-- Windows Vista and Chrome agreed -->
<tr>
<td>hu
<td>Hungarian
<td><span>ISO-8859-2</span> <!-- Chrome and Firefox agreed (but disagreed with Windows Vista, which thought the encoding should be windows-1250) -->
<!-- hu-HU, Hungarian (Hungary), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- id, Indonesian, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- ig-NG, Igbo (Nigeria), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- is, Icelandic, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- it, Italian, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- iu-Latn-CA, Inuktitut (Latin, Canada), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>ja
<td>Japanese
<td><span>Shift_JIS</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- kk, Kazakh, was not initially listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- further feedback has changed this: -->
<tr>
<td>kk
<td>Kazakh
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- kl-GL, Greenlandic (Greenland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- kn, Kannada, uses windows-1252: Firefox and Chrome agreed -->
<tr>
<td>ko
<td>Korean
<td><span>EUC-KR</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<tr>
<td>ku
<td>Kurdish
<td><span>windows-1254</span> <!-- Best guess -->
<!-- ky, Kyrgyz, was not initially listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- further feedback has changed this: -->
<tr>
<td>ky
<td>Kyrgyz
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- lb-LU, Luxembourgish (Luxembourg), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>lt
<td>Lithuanian
<td><span>windows-1257</span> <!-- Windows Vista, Chrome, and Windows Firefox agreed; Linux and Mac Firefox reportedly disagreed -->
<tr>
<td>lv
<td>Latvian
<td><span>windows-1257</span> <!-- Windows Vista and Chrome agreed (but disagreed with Firefox, which thought the encoding should be ISO-8859-13) -->
<!-- mk, Macedonian, was not initially listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- further feedback has changed this: -->
<tr>
<td>mk
<td>Macedonian
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- ml, Malayalam, uses windows-1252: Firefox and Chrome agreed -->
<!-- mn, Mongolian, is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- moh-CA, Mohawk (Mohawk), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- mr, Marathi, uses windows-1252: Firefox and Chrome agreed -->
<!-- ms, Malay, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- nb, Norwegian Bokmål, uses windows-1252: Firefox and Chrome agreed -->
<!-- nl, Dutch, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- nn-NO, Norwegian, Nynorsk (Norway), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- no, Norwegian, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- nso-ZA, Sesotho sa Leboa (South Africa), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- oc-FR, Occitan (France), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>pl
<td>Polish
<td><span>ISO-8859-2</span> <!-- Chrome and Firefox agreed (but disagreed with Windows Vista, which thought the encoding should be windows-1250) -->
<!-- pl-PL, Polish (Poland), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- prs-AF, Dari (Afghanistan), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1256 -->
<!-- pt, Portuguese, uses windows-1252: Windows Vista and Firefox agreed -->
<!-- qut-GT, K'iche (Guatemala), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- quz-BO, Quechua (Bolivia), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- quz-EC, Quechua (Ecuador), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- quz-PE, Quechua (Peru), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- rm-CH, Romansh (Switzerland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- ro, Romanian, is not listed here because Windows Vista wanted windows-1250, Chrome wanted ISO-8859-2, and Firefox wanted <none> -->
<!-- ro-RO, Romanian (Romania), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<tr>
<td>ru
<td>Russian
<td><span>windows-1251</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- rw-RW, Kinyarwanda (Rwanda), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- sah-RU, Yakut (Russia), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- sah wasn't listed at all because none of the sources knew about it. However, further feedback has changed this: -->
<tr>
<td>sah
<td>Yakut
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- se-FI, Sami, Northern (Finland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- se-NO, Sami, Northern (Norway), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- se-SE, Sami, Northern (Sweden), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>sk
<td>Slovak
<td><span>windows-1250</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<tr>
<td>sl
<td>Slovenian
<td><span>ISO-8859-2</span> <!-- Chrome and Firefox agreed (but disagreed with Windows Vista, which thought the encoding should be windows-1250) -->
<!-- sl-SI, Slovenian (Slovenia), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- sma-NO, Sami, Southern (Norway), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- sma-SE, Sami, Southern (Sweden), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- smj-NO, Sami, Lule (Norway), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- smj-SE, Sami, Lule (Sweden), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- smn-FI, Sami, Inari (Finland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- sms-FI, Sami, Skolt (Finland), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- sq, Albanian, is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<tr>
<td>sr
<td>Serbian
<td><span>windows-1251</span> <!-- Windows Vista and Chrome agreed -->
<!-- sr-Latn-BA, Serbian (Latin, Bosnia and Herzegovina), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- sr-Latn-SP, Serbian (Latin, Serbia), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- sv, Swedish, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- sw, Kiswahili, uses windows-1252: Windows Vista, Chrome, and Firefox agreed -->
<!-- ta, Tamil, uses windows-1252: Firefox and Chrome agreed -->
<!-- te, Telugu, uses windows-1252: Firefox and Chrome agreed -->
<!-- tg-Cyrl-TJ, Tajik (Cyrillic, Tajikistan), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- tg wasn't listed at all because none of the sources knew about it. However, further feedback has changed this: -->
<tr>
<td>tg
<td>Tajik
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<tr>
<td>th
<td>Thai
<td><span>windows-874</span> <!-- Windows Vista, Chrome, and Firefox agree (though Firefox didn't always) -->
<!-- tk-TM, Turkmen (Turkmenistan), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1250 -->
<!-- tn-ZA, Setswana (South Africa), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>tr
<td>Turkish
<td><span>windows-1254</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- tt, Tatar, was not initially listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<!-- further feedback has changed this: -->
<tr>
<td>tt
<td>Tatar
<td><span>windows-1251</span> <!-- per https://www.w3.org/Bugs/Public/show_bug.cgi?id=23089 -->
<!-- tzm-Latn-DZ, Tamazight (Latin, Algeria), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- ug-CN, Uighur (PRC), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1256 -->
<tr>
<td>uk
<td>Ukrainian
<td><span>windows-1251</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<!-- ur, Urdu, is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1256 -->
<!-- uz, Uzbek, is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1254 -->
<!-- uz-Cyrl-UZ, Uzbek (Cyrillic, Uzbekistan), is not listed here because neither Chrome nor Firefox knew about it. For what it's worth, Windows Vista wanted windows-1251 -->
<tr>
<td>vi
<td>Vietnamese
<td><span>windows-1258</span> <!-- Windows Vista and Chrome agreed -->
<!-- wee-DE, Lower Sorbian (Germany), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- wen-DE, Upper Sorbian (Germany), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- wo-SN, Wolof (Senegal), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- xh-ZA, isiXhosa (South Africa), uses windows-1252: Windows Vista and Firefox agreed -->
<!-- yo-NG, Yoruba (Nigeria), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td>zh-Hans, zh-CN, zh-SG
<td>Chinese, Simplified
<td><span>GBK</span> <!-- Windows Vista, Chrome, and Firefox agreed -->
<tr>
<td>zh-Hant, zh-HK, zh-MO, zh-TW
<td>Chinese, Traditional
<td><span>Big5</span> <!-- Windows Vista, Chrome, and Firefox agreed (though Firefox didn't always) -->
<!-- zu-ZA, isiZulu (South Africa), uses windows-1252: Windows Vista and Firefox agreed -->
<tr>
<td colspan=2>All other locales
<td><span>windows-1252</span>
</table>
<p class="tablenote"><small>The contents of this table are derived from the intersection of
Windows, Chrome, and Firefox defaults.</small></p>
</li>
</ol>
<p>The <span>document's character encoding</span> must immediately be set to the value returned
from this algorithm, at the same time as the user agent uses the returned value to select the
decoder to use for the input byte stream.</p>
<hr>
<p>When an algorithm requires a user agent to <dfn export>prescan a byte stream to determine its
encoding</dfn>, given some defined <dfn data-x="prescan-end-condition" export for="prescan a byte
stream to determine its encoding"><var>end condition</var></dfn>, then it must run the following
steps. If at any point during these steps (including during instances of the <span
data-x="concept-get-attributes-when-sniffing">get an attribute</span> algorithm invoked by this
one) the user agent either runs out of bytes (meaning the <var>position</var> pointer created in
the first step below goes beyond the end of the byte stream obtained so far) or reaches its
<var>end condition</var>, then abort the <span>prescan a byte stream to determine its
encoding</span> algorithm and return the result <span
data-x="concept-get-xml-encoding-when-sniffing">get an XML encoding</span> applied to the same
bytes that the <span>prescan a byte stream to determine its encoding</span> algorithm was applied
to. Otherwise, these steps will return a character encoding.</p>
<ol>
<li><p>Let <var>position</var> be a pointer to a byte in the input byte stream, initially
pointing at the first byte.</p></li>
<li>
<p>Prescan for UTF-16 XML declarations: If <var>position</var> points to:</p>
<dl class="switch">
<dt>A sequence of bytes starting with: 0x3C, 0x0, 0x3F, 0x0, 0x78, 0x0 (case-sensitive UTF-16
little-endian '<?x')</dt>
<dd><p>Return <span>UTF-16LE</span>.</p></dd>
<dt>A sequence of bytes starting with: 0x0, 0x3C, 0x0, 0x3F, 0x0, 0x78 (case-sensitive UTF-16
big-endian '<?x')</dt>
<dd><p>Return <span>UTF-16BE</span>.</p></dd>
</dl>
<p class="note">For historical reasons, the prefix is two bytes longer than in <a
href="https://www.w3.org/TR/REC-xml/#sec-guessing">Appendix F</a> of <cite>XML</cite> and the
encoding name is not checked.</p>
</li>
<li>
<p><i>Loop</i>: If <var>position</var> points to:</p>
<dl class="switch">
<dt>A sequence of bytes starting with: 0x3C 0x21 0x2D 0x2D (`<code
data-x=""><!--</code>`)</dt>
<dd>
<p>Advance the <var>position</var> pointer so that it points at the first 0x3E byte
which is preceded by two 0x2D bytes (i.e. at the end of an ASCII '-->' sequence) and comes
after the 0x3C byte that was found. (The two 0x2D bytes can be the same as those in the
'<!--' sequence.)</p>
</dd>
<dt>A sequence of bytes starting with: 0x3C, 0x4D or 0x6D, 0x45 or 0x65, 0x54 or 0x74, 0x41 or 0x61, and one of 0x09, 0x0A, 0x0C, 0x0D, 0x20, 0x2F (case-insensitive ASCII '<meta' followed by a space or slash)</dt>
<dd>
<ol>
<li><p>Advance the <var>position</var> pointer so that it points at the next 0x09,
0x0A, 0x0C, 0x0D, 0x20, or 0x2F byte (the one in sequence of characters matched
above).</p></li>
<li><p>Let <var>attribute list</var> be an empty list of strings.</p></li> <!-- so
long as we only care about http-equiv, content, and charset, this can be a 3-bit bitfield -->
<li><p>Let <var>got pragma</var> be false.</p></li>
<li><p>Let <var>need pragma</var> be null.</p></li>
<li><p>Let <var>charset</var> be the null value (which, for the purposes of this
algorithm, is distinct from an unrecognized encoding or the empty string).</p></li>
<li><p><i>Attributes</i>: <span data-x="concept-get-attributes-when-sniffing">Get an
attribute</span> and its value. If no attribute was sniffed, then jump to the
<i>processing</i> step below.</p></li>
<li><p>If the attribute's name is already in <var>attribute list</var>, then return
to the step labeled <i>attributes</i>.</p>
<li><p>Add the attribute's name to <var>attribute list</var>.</p>
<li>
<p>Run the appropriate step from the following list, if one applies:</p>
<dl class="switch">
<dt>If the attribute's name is "<code data-x="">http-equiv</code>"</dt>
<dd><p>If the attribute's value is "<code data-x="">content-type</code>", then set <var>got pragma</var> to true.</p></dd>
<dt>If the attribute's name is "<code data-x="">content</code>"</dt>
<dd><p>Apply the <span>algorithm for extracting a character encoding from a
<code>meta</code> element</span>, giving the attribute's value as the string to parse. If a
character encoding is returned, and if <var>charset</var> is still set to null,
let <var>charset</var> be the encoding returned, and set <var>need
pragma</var> to true.</p></dd>
<dt>If the attribute's name is "<code data-x="">charset</code>"</dt>
<dd><p>Let <var>charset</var> be the result of <span>getting an encoding</span>
from the attribute's value, and set <var>need pragma</var> to false.</p></dd>
</dl>
</li>
<li><p>Return to the step labeled <i>attributes</i>.</p></li>
<li><p><i>Processing</i>: If <var>need pragma</var> is null, then jump to the step
below labeled <i>next byte</i>.</p></li>
<li><p>If <var>need pragma</var> is true but <var>got pragma</var> is
false, then jump to the step below labeled <i>next byte</i>.</p></li>
<li><p>If <var>charset</var> is failure, then jump to the step below labeled <i>next
byte</i>.</p></li>
<!-- the next two steps are redundant with steps in the 'change the encoding' algorithm -->
<li><p>If <var>charset</var> is <span>UTF-16BE/LE</span>, then set <var>charset</var> to
<span>UTF-8</span>.
<li><p>If <var>charset</var> is <span>x-user-defined</span>, then set <var>charset</var> to
<span>windows-1252</span>.</p></li>
<li><p>Return <var>charset</var>.</p></li>
</ol>
</dd>
<dt>A sequence of bytes starting with a 0x3C byte (<), optionally a 0x2F byte (/), and
finally a byte in the range 0x41-0x5A or 0x61-0x7A (A-Z or a-z)</dt>
<dd>
<ol>
<li><p>Advance the <var>position</var> pointer so that it points at the next 0x09 (HT),
0x0A (LF), 0x0C (FF), 0x0D (CR), 0x20 (SP), or 0x3E (>) byte.</p></li>
<li><p>Repeatedly <span data-x="concept-get-attributes-when-sniffing">get an attribute</span>
until no further attributes can be found, then jump to the step below labeled <i>next
byte</i>.</p></li>
</ol>
</dd>
<dt>A sequence of bytes starting with: 0x3C 0x21 (`<code data-x=""><!</code>`)</dt>
<dt>A sequence of bytes starting with: 0x3C 0x2F (`<code data-x=""></</code>`)</dt>
<dt>A sequence of bytes starting with: 0x3C 0x3F (`<code data-x=""><?</code>`)</dt>
<dd>
<p>Advance the <var>position</var> pointer so that it points at the first 0x3E byte (>) that
comes after the 0x3C byte that was found.</p>
</dd>
<dt>Any other byte</dt>
<dd>
<p>Do nothing with that byte.</p>
</dd>
</dl>
</li>
<li><i>Next byte</i>: Move <var>position</var> so it points at the next byte in the
input byte stream, and return to the step above labeled <i>loop</i>.</li>
</ol>
<p>When the <span>prescan a byte stream to determine its encoding</span> algorithm says to <dfn
data-x="concept-get-attributes-when-sniffing">get an attribute</dfn>, it means doing this:</p>
<ol>
<li><p>If the byte at <var>position</var> is one of 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR),
0x20 (SP), or 0x2F (/) then advance <var>position</var> to the next byte and redo this
step.</p></li>
<li><p>If the byte at <var>position</var> is 0x3E (>), then abort the <span
data-x="concept-get-attributes-when-sniffing">get an attribute</span> algorithm. There isn't
one.</p></li>
<li><p>Otherwise, the byte at <var>position</var> is the start of the attribute name.
Let <var>attribute name</var> and <var>attribute value</var> be the empty
string.</p></li>
<li><p>Process the byte at <var>position</var> as follows:</p>
<dl class="switch">
<dt>If it is 0x3D (=), and the <var>attribute name</var> is longer than the empty string</dt>
<dd>Advance <var>position</var> to the next byte and jump to the step below labeled
<i>value</i>.</dd>
<dt>If it is 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), or 0x20 (SP)</dt>
<dd>Jump to the step below labeled <i>spaces</i>.</dd>
<dt>If it is 0x2F (/) or 0x3E (>)</dt>
<dd>Abort the <span data-x="concept-get-attributes-when-sniffing">get an attribute</span>
algorithm. The attribute's name is the value of <var>attribute name</var>, its value
is the empty string.</dd>
<dt>If it is in the range 0x41 (A) to 0x5A (Z)</dt>
<dd>Append the code point <var>b</var>+0x20 to <var>attribute name</var>
(where <var>b</var> is the value of the byte at <var>position</var>). (This converts the input
to lowercase.)</dd>
<dt>Anything else</dt>
<dd>Append the code point with the same value as the byte at <var>position</var> to
<var>attribute name</var>. (It doesn't actually matter how bytes outside the ASCII range are
handled here, since only ASCII bytes can contribute to the detection of a character
encoding.)</dd>
</dl>
</li>
<li><p>Advance <var>position</var> to the next byte and return to the previous
step.</p></li>
<li><p><i>Spaces</i>: If the byte at <var>position</var> is one of 0x09 (HT), 0x0A (LF), 0x0C
(FF), 0x0D (CR), or 0x20 (SP) then advance <var>position</var> to the next byte, then, repeat
this step.</p></li>
<li><p>If the byte at <var>position</var> is <em>not</em> 0x3D (=), abort the <span
data-x="concept-get-attributes-when-sniffing">get an attribute</span> algorithm. The attribute's
name is the value of <var>attribute name</var>, its value is the empty string.</p></li>
<li><p>Advance <var>position</var> past the 0x3D (=) byte.</p></li>
<li><p><i>Value</i>: If the byte at <var>position</var> is one of 0x09 (HT), 0x0A (LF), 0x0C
(FF), 0x0D (CR), or 0x20 (SP) then advance <var>position</var> to the next byte, then, repeat
this step.</p></li>
<li><p>Process the byte at <var>position</var> as follows:</p>
<dl class="switch">
<dt>If it is 0x22 (") or 0x27 (')</dt>
<dd>
<ol>
<li>Let <var>b</var> be the value of the byte at <var>position</var>.</li>
<li><i>Quote loop</i>: Advance <var>position</var> to the next byte.</li>
<li>If the value of the byte at <var>position</var> is the value of <var>b</var>, then advance <var>position</var> to the next byte and abort the
"get an attribute" algorithm. The attribute's name is the value of <var>attribute
name</var>, and its value is the value of <var>attribute value</var>.</li>
<li>Otherwise, if the value of the byte at <var>position</var> is in the range 0x41 (A) to
0x5A (Z), then append a code point to <var>attribute value</var> whose value is 0x20 more
than the value of the byte at <var>position</var>.</li>
<li>Otherwise, append a code point to <var>attribute value</var> whose value is the same as
the value of the byte at <var>position</var>.</li>
<li>Return to the step above labeled <i>quote loop</i>.</li>
</ol>
</dd>
<dt>If it is 0x3E (>)</dt>
<dd>Abort the <span data-x="concept-get-attributes-when-sniffing">get an attribute</span>
algorithm. The attribute's name is the value of <var>attribute name</var>, its value
is the empty string.</dd>
<dt>If it is in the range 0x41 (A) to 0x5A (Z)</dt>
<dd>Append a code point <var>b</var>+0x20 to <var>attribute value</var>
(where <var>b</var> is the value of the byte at <var>position</var>). Advance
<var>position</var> to the next byte.</dd>
<dt>Anything else</dt>
<dd>Append a code point with the same value as the byte at <var>position</var> to
<var>attribute value</var>. Advance <var>position</var> to the next byte.</dd>
</dl>
</li>
<li><p>Process the byte at <var>position</var> as
follows:</p>
<dl class="switch">
<dt>If it is 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), 0x20 (SP), or 0x3E (>)</dt>
<dd>Abort the <span data-x="concept-get-attributes-when-sniffing">get an attribute</span>
algorithm. The attribute's name is the value of <var>attribute name</var> and its
value is the value of <var>attribute value</var>.</dd>
<dt>If it is in the range 0x41 (A) to 0x5A (Z)</dt>
<dd>Append a code point <var>b</var>+0x20 to <var>attribute value</var>
(where <var>b</var> is the value of the byte at <var>position</var>).</dd>
<dt>Anything else</dt>
<dd>Append a code point with the same value as the byte at <var>position</var> to
<var>attribute value</var>.</dd>
</dl>
</li>
<li><p>Advance <var>position</var> to the next byte and return to the previous
step.</p></li>
</ol>
<p>When the <span>prescan a byte stream to determine its encoding</span> algorithm is aborted
without returning an encoding, <dfn data-x="concept-get-xml-encoding-when-sniffing">get an XML
encoding</dfn> means doing this.</p>
<p class="note">Looking for syntax resembling an XML declaration, even in <code>text/html</code>,
is necessary for compatibility with existing content.</p>
<ol>
<li><p>Let <var>encodingPosition</var> be a pointer to the start of the stream.</p></li>
<li><p>If <var>encodingPosition</var> does not point to the start of a byte sequence 0x3C, 0x3F,
0x78, 0x6D, 0x6C (`<code data-x=""><?xml</code>`), then return failure.</p></li>
<li><p>Let <var>xmlDeclarationEnd</var> be a pointer to the next byte in the input byte stream
which is 0x3E (>). If there is no such byte, then return failure.</p></li>
<li><p>Set <var>encodingPosition</var> to the position of the first occurrence of the subsequence
of bytes 0x65, 0x6E, 0x63, 0x6F, 0x64, 0x69, 0x6E, 0x67 (`<code data-x="">encoding</code>`) at or
after the current <var>encodingPosition</var>. If there is no such sequence, then return
failure.</p></li>
<li><p>Advance <var>encodingPosition</var> past the 0x67 (g) byte.</p></li>
<li><p>While the byte at <var>encodingPosition</var> is less than or equal to 0x20 (i.e., it is
either an ASCII space or control character), advance <var>encodingPosition</var> to the next
byte.</p></li>
<li><p>If the byte at <var>encodingPosition</var> is not 0x3D (=), then return failure.</p></li>
<li><p>Advance <var>encodingPosition</var> to the next byte.</p></li>
<li><p>While the byte at <var>encodingPosition</var> is less than or equal to 0x20 (i.e., it is
either an ASCII space or control character), advance <var>encodingPosition</var> to the next
byte.</p></li>
<li><p>Let <var>quoteMark</var> be the byte at <var>encodingPosition</var>.</p></li>
<li><p>If <var>quoteMark</var> is not either 0x22 (") or 0x27 ('), then return failure.</p></li>
<li><p>Advance <var>encodingPosition</var> to the next byte.</p></li>
<li><p>Let <var>encodingEndPosition</var> be the position of the next occurrence of
<var>quoteMark</var> at or after <var>encodingPosition</var>. If <var>quoteMark</var> does not
occur again, then return failure.</p></li>
<li><p>Let <var>potentialEncoding</var> be the sequence of the bytes between
<var>encodingPosition</var> (inclusive) and <var>encodingEndPosition</var> (exclusive).</p></li>
<li><p>If <var>potentialEncoding</var> contains one or more bytes whose byte value is 0x20 or
below, then return failure.</p></li>
<li><p>Let <var>encoding</var> be the result of <span>getting an encoding</span> given
<var>potentialEncoding</var> <span data-x="isomorphic decode">isomorphic decoded</span>.</p></li>
<li><p>If the <var>encoding</var> is <span>UTF-16BE/LE</span>, then change it to
<span>UTF-8</span>.</p></li>
<li><p>Return <var>encoding</var>.</p></li>
</ol>
<p>For the sake of interoperability, user agents should not use a pre-scan algorithm that returns
different results than the one described above. (But, if you do, please at least let us know, so
that we can improve this algorithm and benefit everyone...)</p>
<h5>Character encodings</h5>
<p>User agents must support the encodings defined in <cite>Encoding</cite>, including, but
not limited to,
<dfn data-x-href="https://encoding.spec.whatwg.org/#utf-8">UTF-8</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#iso-8859-2">ISO-8859-2</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#iso-8859-7">ISO-8859-7</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#iso-8859-8">ISO-8859-8</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-874">windows-874</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1250">windows-1250</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1251">windows-1251</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1252">windows-1252</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1254">windows-1254</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1255">windows-1255</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1256">windows-1256</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1257">windows-1257</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#windows-1258">windows-1258</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#gbk">GBK</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#big5">Big5</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#iso-2022-jp">ISO-2022-JP</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#shift_jis">Shift_JIS</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#euc-kr">EUC-KR</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#utf-16be">UTF-16BE</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#utf-16le">UTF-16LE</dfn>,
<dfn data-x-href="https://encoding.spec.whatwg.org/#utf-16be-le"
id="utf-16-encoding">UTF-16BE/LE</dfn>, and
<dfn data-x-href="https://encoding.spec.whatwg.org/#x-user-defined">x-user-defined</dfn>.
User agents must not support other encodings.</p>
<p class="note">The above prohibits supporting, for example, CESU-8, UTF-7, BOCU-1, SCSU, EBCDIC,
and UTF-32. This specification does not make any attempt to support prohibited encodings in its
algorithms; support and use of prohibited encodings would thus lead to unexpected behavior.
<ref>CESU8</ref> <ref>UTF7</ref> <ref>BOCU1</ref> <ref>SCSU</ref></p>
<h5>Changing the encoding while parsing</h5>
<p>When the parser requires the user agent to <dfn>change the encoding</dfn>, it must run the
following steps. This might happen if the <span>encoding sniffing algorithm</span> described above
failed to find a character encoding, or if it found a character encoding that was not the actual
encoding of the file.</p>
<ol>
<li><p>If the encoding that is already being used to interpret the input stream is
<span>UTF-16BE/LE</span>, then set the <span
data-x="concept-encoding-confidence">confidence</span> to <i>certain</i> and return. The new
encoding is ignored; if it was anything but the same encoding, then it would be clearly
incorrect.</p></li>
<!-- the next two steps are redundant with similar logic in the sniffer -->
<!-- if you add anything else here, then factor it out into a common algorithm -->
<li><p>If the new encoding is <span>UTF-16BE/LE</span>, then change it to
<span>UTF-8</span>.</p></li>
<li><p>If the new encoding is <span>x-user-defined</span>, then change it to
<span>windows-1252</span>.</p></li> <!-- apparently this was a Chrome invention, later picked up
by Mozilla -->
<li><p>If the new encoding is identical or equivalent to the encoding that is already being used
to interpret the input stream, then set the <span
data-x="concept-encoding-confidence">confidence</span> to <i>certain</i> and return.
This happens when the encoding information found in the file matches what the <span>encoding
sniffing algorithm</span> determined to be the encoding, and in the second pass through the
parser if the first pass found that the encoding sniffing algorithm described in the earlier
section failed to find the right encoding.</p></li>
<li><p>If all the bytes up to the last byte converted by the current decoder have the same
Unicode interpretations in both the current encoding and the new encoding, and if the user agent
supports changing the converter on the fly, then the user agent may change to the new converter
for the encoding on the fly. Set the <span>document's character encoding</span> and the encoding
used to convert the input stream to the new encoding, set the <span
data-x="concept-encoding-confidence">confidence</span> to <i>certain</i>, and return.</p></li>
<li><p>Otherwise, restart the <span>navigate</span><!--DONAV reparse--> algorithm, with <i
data-x="navigation-hh">historyHandling</i> set to "<code
data-x="NavigationHistoryBehavior-replace">replace</code>" and other inputs kept the same, but
this time skip the <span>encoding sniffing algorithm</span> and instead just set the encoding to
the new encoding and the <span data-x="concept-encoding-confidence">confidence</span> to
<i>certain</i>. Whenever possible, this should be done without actually contacting the network
layer (the bytes should be re-parsed from memory), even if, e.g., the document is marked as not
being cacheable. If this is not possible and contacting the network layer would involve repeating
a request that uses a method other than `<code data-x="">GET</code>`, then instead set the <span
data-x="concept-encoding-confidence">confidence</span> to <i>certain</i> and ignore the new
encoding. The resource will be misinterpreted. User agents may notify the user of the situation,
to aid in application development.</p></li>
</ol>
<p class="note">This algorithm is only invoked when a new encoding is found declared on a
<code>meta</code> element.</p> <!-- this is important for the x-user-defined stuff in particular
-->
<h5>Preprocessing the input stream</h5>
<p>The <dfn>input stream</dfn> consists of the characters pushed into it as the <span>input byte
stream</span> is decoded or from the various APIs that directly manipulate the input stream.</p>
<p>Any occurrences of <span data-x="surrogate">surrogates</span> are <span
data-x="parse-error-surrogate-in-input-stream">surrogate-in-input-stream</span>
<span data-x="parse error">parse errors</span>. Any occurrences of <span
data-x="noncharacter">noncharacters</span> are <span
data-x="parse-error-noncharacter-in-input-stream">noncharacter-in-input-stream</span>
<span data-x="parse error">parse errors</span> and any occurrences of <span
data-x="control">controls</span> other than <span>ASCII whitespace</span> and U+0000 NULL
characters are <span
data-x="parse-error-control-character-in-input-stream">control-character-in-input-stream</span>
<span data-x="parse error">parse errors</span>.</p>
<p class="note">The handling of U+0000 NULL characters varies based on where the characters are
found and happens at the later stages of the parsing. They are either ignored or, for security
reasons, replaced with a U+FFFD REPLACEMENT CHARACTER. This handling is, by necessity, spread
across both the tokenization stage and the tree construction stage.</p>
<p>Before the <span>tokenization</span> stage, the input stream must be preprocessed by <span
data-x="normalize newlines">normalizing newlines</span>. Thus, newlines in HTML DOMs are
represented by U+000A LF characters, and there are never any U+000D CR characters in the input to
the <span>tokenization</span> stage.</p>
<p>The <dfn>next input character</dfn> is the first character in the <span>input stream</span>
that has not yet been <dfn data-x="">consumed</dfn> or explicitly ignored by the requirements in
this section. Initially, the <i data-x="next input character">next input character</i> is the
first character in the input. The <dfn>current input character</dfn> is the last character to have
been <i>consumed</i>.</p>
<p>The <dfn>insertion point</dfn> is the position (just before a character or just before the end
of the input stream) where content inserted using <code
data-x="dom-document-write">document.write()</code> is actually inserted. The insertion point is
relative to the position of the character immediately after it, it is not an absolute offset into
the input stream. Initially, the insertion point is undefined.</p>
<p>The "EOF" character in the tables below is a conceptual character representing the end of the
<span>input stream</span>. If the parser is a <span>script-created parser</span>, then the end of
the <span>input stream</span> is reached when an <dfn>explicit "EOF" character</dfn> (inserted by
the <code data-x="dom-document-close">document.close()</code> method) is consumed. Otherwise, the
"EOF" character is not a real character in the stream, but rather the lack of any further
characters.</p>
</div>
<div w-nodev>
<h4>Parse state</h4>
<h5>The insertion mode</h5>
<p>The <dfn>insertion mode</dfn> is a state variable that controls the primary operation of the
tree construction stage.</p>
<p>Initially, the <span>insertion mode</span> is "<span data-x="insertion mode:
initial">initial</span>". It can change to "<span data-x="insertion mode: before html">before
html</span>", "<span data-x="insertion mode: before head">before head</span>", "<span
data-x="insertion mode: in head">in head</span>", "<span data-x="insertion mode: in head
noscript">in head noscript</span>", "<span data-x="insertion mode: after head">after head</span>",
"<span data-x="insertion mode: in body">in body</span>", "<span data-x="insertion mode:
text">text</span>", "<span data-x="insertion mode: in table">in table</span>", "<span
data-x="insertion mode: in table text">in table text</span>", "<span data-x="insertion mode: in
caption">in caption</span>", "<span data-x="insertion mode: in column group">in column
group</span>", "<span data-x="insertion mode: in table body">in table body</span>", "<span
data-x="insertion mode: in row">in row</span>", "<span data-x="insertion mode: in cell">in
cell</span>", "<span data-x="insertion mode: in select">in select</span>", "<span data-x="insertion
mode: in select in table">in select in table</span>", "<span data-x="insertion mode: in
template">in template</span>", "<span data-x="insertion mode: after body">after body</span>",
"<span data-x="insertion mode: in frameset">in frameset</span>", "<span data-x="insertion mode:
after frameset">after frameset</span>", "<span data-x="insertion mode: after after body">after
after body</span>", and "<span data-x="insertion mode: after after frameset">after after
frameset</span>" during the course of the parsing, as described in the <span>tree
construction</span> stage. The insertion mode affects how tokens are processed and whether CDATA
sections are supported.</p>
<p>Several of these modes, namely "<span data-x="insertion mode: in head">in head</span>", "<span
data-x="insertion mode: in body">in body</span>", "<span data-x="insertion mode: in table">in
table</span>", and "<span data-x="insertion mode: in select">in select</span>", are special, in
that the other modes defer to them at various times. When the algorithm below says that the user
agent is to do something "<dfn>using the rules for</dfn> the <var>m</var> insertion
mode", where <var>m</var> is one of these modes, the user agent must use the rules
described under the <var>m</var> <span>insertion mode</span>'s section, but must leave
the <span>insertion mode</span> unchanged unless the rules in <var>m</var> themselves
switch the <span>insertion mode</span> to a new value.</p>
<p>When the insertion mode is switched to "<span data-x="insertion mode: text">text</span>" or
"<span data-x="insertion mode: in table text">in table text</span>", the <dfn>original insertion
mode</dfn> is also set. This is the insertion mode to which the tree construction stage will
return.</p>
<p>Similarly, to parse nested <code>template</code> elements, a <dfn>stack of template insertion
modes</dfn> is used. It is initially empty. The <dfn>current template insertion mode</dfn> is the
insertion mode that was most recently added to the <span>stack of template insertion modes</span>.
The algorithms in the sections below will <i>push</i> insertion modes onto this stack, meaning
that the specified insertion mode is to be added to the stack, and <i>pop</i> insertion modes from
the stack, which means that the most recently added insertion mode must be removed from the
stack.</p>
<hr>
<p>When the steps below require the UA to <dfn>reset the insertion mode appropriately</dfn>, it
means the UA must follow these steps:</p>
<ol>
<li><p>Let <var>last</var> be false.</p></li>
<li><p>Let <var>node</var> be the last node in the <span>stack of open
elements</span>.</p></li>
<li><p><i>Loop</i>: If <var>node</var> is the first node in the stack of open elements, then set
<var>last</var> to true, and, if the parser was created as part of the <span>HTML fragment
parsing algorithm</span> (<span>fragment case</span>), set <var>node</var> to the <var
data-x="concept-frag-parse-context">context</var> element passed to that algorithm.</p></li>
<li>
<p>If <var>node</var> is a <code>select</code> element, run these substeps:</p>
<ol>
<li><p>If <var>last</var> is true, jump to the step below labeled
<i>done</i>.</p></li>
<li><p>Let <var>ancestor</var> be <var>node</var>.</p></li>
<li><p><i>Loop</i>: If <var>ancestor</var> is the first node in the <span>stack of
open elements</span>, jump to the step below labeled <i>done</i>.</p></li>
<li><p>Let <var>ancestor</var> be the node before <var>ancestor</var> in the
<span>stack of open elements</span>.</p></li>
<li><p>If <var>ancestor</var> is a <code>template</code> node, jump to the step below
labeled <i>done</i>.</p></li>
<li><p>If <var>ancestor</var> is a <code>table</code> node, switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in select in table">in select in table</span>"
and return.</p></li> <!-- consider
<table><tr><td><select><template></template><caption></table>
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2374 -->
<li><p>Jump back to the step labeled <i>loop</i>.</p></li>
<li><p><i>Done</i>: Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in
select">in select</span>" and return.</p></li>
</ol>
</li>
<li><p>If <var>node</var> is a <code>td</code> or <code>th</code> element and <var>last</var> is
false, then switch the <span>insertion mode</span> to "<span data-x="insertion mode: in cell">in
cell</span>" and return.</p></li>
<li><p>If <var>node</var> is a <code>tr</code> element, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in row">in row</span>" and return.</p></li>
<li><p>If <var>node</var> is a <code>tbody</code>, <code>thead</code>, or
<code>tfoot</code> element, then switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in table body">in table body</span>" and return.</p></li>
<li><p>If <var>node</var> is a <code>caption</code> element, then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in caption">in caption</span>" and
return.</p></li>
<li><p>If <var>node</var> is a <code>colgroup</code> element, then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in column group">in column
group</span>" and return.</p></li>
<li><p>If <var>node</var> is a <code>table</code> element, then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in table">in table</span>" and
return.</p></li>
<li><p>If <var>node</var> is a <code>template</code> element, then switch the
<span>insertion mode</span> to the <span>current template insertion mode</span> and
return.</p></li>
<!-- <li><p>If <var>node</var> is a <code>head</code> element and <var>last</var> is true, then switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in body">in body</span>" ("<span data-x="insertion mode: in body">in
body</span>"! <em> not "<span data-x="insertion mode: in head">in head</span>"</em>!) and return.
(<span>fragment case</span>)</p></li> --><!-- The above is only here in case people
think that the spec accidentally omitted it and try to "fix" it. Note that noscript-in-head is
also handled this way. This is all intentional. The only thing it doesn't handle is the
scripting-disabled fragment parsing case for a <head> element containing a <noscript> which
itself contains something other than a <link> or a <style> element; you'd expect that to break
out of the <noscript> but it doesn't. This is an edge case that doesn't affect the spec, since
the algorithm for fragment parsing is only used for innerHTML/outerHTML/insertAdjacentHTML(),
where we know scripting is enabled. -->
<li><p>If <var>node</var> is a <code>head</code> element and <var>last</var> is
false, then switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head">in
head</span>" and return.</p></li> <!-- for the case of <head><template></template>...
-->
<li><p>If <var>node</var> is a <code>body</code> element, then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in body">in body</span>" and
return.</p></li>
<li><p>If <var>node</var> is a <code>frameset</code> element, then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in frameset">in frameset</span>" and
return. (<span>fragment case</span>)</p></li>
<li>
<p>If <var>node</var> is an <code>html</code> element, run these substeps:</p>
<ol>
<li><p>If the <span><code>head</code> element pointer</span> is null, switch the
<span>insertion mode</span> to "<span data-x="insertion mode: before head">before head</span>"
and return. (<span>fragment case</span>)</p></li>
<li><p>Otherwise, the <span><code>head</code> element pointer</span> is not null, switch the
<span>insertion mode</span> to "<span data-x="insertion mode: after head">after head</span>" and
return.</p></li> <!-- consider <html><head></head><template></template> -->
</ol>
</li>
<li><p>If <var>last</var> is true, then switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in body">in body</span>" and return. (<span>fragment
case</span>)</p></li>
<li><p>Let <var>node</var> now be the node before <var>node</var> in the
<span>stack of open elements</span>.</p></li>
<li><p>Return to the step labeled <i>loop</i>.</p></li>
</ol>
<h5>The stack of open elements</h5>
<p>Initially, the <dfn>stack of open elements</dfn> is empty. The stack grows downwards; the
topmost node on the stack is the first one added to the stack, and the bottommost node of the
stack is the most recently added node in the stack (notwithstanding when the stack is manipulated
in a random access fashion as part of <a href="#adoptionAgency">the handling for misnested
tags</a>).</p>
<p class="note">The "<span data-x="insertion mode: before html">before html</span>"
<span>insertion mode</span> creates the <code>html</code> <span>document element</span>, which is
then added to the stack.</p>
<p class="note">In the <span>fragment case</span>, the <span>stack of open elements</span> is
initialized to contain an <code>html</code> element that is created as part of <span data-x="html
fragment parsing algorithm">that algorithm</span>. (The <span>fragment case</span> skips the
"<span data-x="insertion mode: before html">before html</span>" <span>insertion mode</span>.)</p>
<p>The <code>html</code> node, however it is created, is the topmost node of the stack. It only
gets popped off the stack when the parser <span data-x="stop parsing">finishes</span>.</p>
<p>The <dfn>current node</dfn> is the bottommost node in this <span>stack of open
elements</span>.</p>
<p>The <dfn>adjusted current node</dfn> is the <i data-x="concept-frag-parse-context">context</i>
element if the parser was created as part of the <span>HTML fragment parsing algorithm</span> and
the <span>stack of open elements</span> has only one element in it (<span>fragment case</span>);
otherwise, the <span>adjusted current node</span> is the <span>current node</span>.</p>
<p>When the <span>current node</span> is removed from the <span>stack of open elements</span>,
<span>process internal resource links</span> given the <span>current node</span>'s
<span>node document</span>.</p>
<p>Elements in the <span>stack of open elements</span> fall into the following categories:</p>
<dl>
<dt><dfn>Special</dfn></dt>
<dd>
<p>The following elements have varying levels of special parsing rules: HTML's
<code>address</code>, <code>applet</code>, <code>area</code>, <code>article</code>,
<code>aside</code>, <code>base</code>, <code>basefont</code>, <code>bgsound</code>,
<code>blockquote</code>, <code>body</code>, <code>br</code>, <code>button</code>,
<code>caption</code>, <code>center</code>, <code>col</code>, <code>colgroup</code>,
<code>dd</code>, <code>details</code>, <code>dir</code>, <code>div</code>, <code>dl</code>,
<code>dt</code>, <code>embed</code>, <code>fieldset</code>, <code>figcaption</code>,
<code>figure</code>, <code>footer</code>, <code>form</code>, <code>frame</code>,
<code>frameset</code>, <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>,
<code>h5</code>, <code>h6</code>, <code>head</code>, <code>header</code>, <code>hgroup</code>,
<code>hr</code>, <code>html</code>, <code>iframe</code>, <!-- <code>image</code>, (commented
out because this isn't an element that can end up on the stack, so it doesn't matter) -->
<code>img</code>, <code>input</code>, <code>keygen</code>, <code>li</code>, <code>link</code>,
<code>listing</code>, <code>main</code>, <code>marquee</code>, <code>menu</code>,
<code>meta</code>, <code>nav</code>, <code>noembed</code>, <code>noframes</code>,
<code>noscript</code>, <code>object</code>, <code>ol</code>, <code>p</code>,
<code>param</code>, <code>plaintext</code>, <code>pre</code>, <code>script</code>,
<code>search</code>, <code>section</code>, <code>select</code>, <code>source</code>,
<code>style</code>, <code>summary</code>, <code>table</code>, <code>tbody</code>,
<code>td</code>, <code>template</code>, <code>textarea</code>, <code>tfoot</code>,
<code>th</code>, <code>thead</code>, <code>title</code>, <code>tr</code>, <code>track</code>,
<code>ul</code>, <code>wbr</code>, <code>xmp</code>; <span>MathML <code>mi</code></span>,
<span>MathML <code>mo</code></span>, <span>MathML <code>mn</code></span>, <span>MathML
<code>ms</code></span>, <span>MathML <code>mtext</code></span>, and <span>MathML
<code>annotation-xml</code></span>; and <span>SVG <code>foreignObject</code></span>, <span>SVG
<code>desc</code></span>, and <span>SVG <code>title</code></span>.</p> <!-- we could actually
put all non-HTML elements in this list, I think -->
<p class="note">An <code data-x="">image</code> start tag token is handled by the tree builder,
but it is not in this list because it is not an element; it gets turned into an <code>img</code>
element.</p>
</dd>
<dt><dfn>Formatting</dfn></dt>
<dd><p>The following HTML elements are those that end up in the <span>list of active formatting
elements</span>: <code>a</code>, <code>b</code>, <code>big</code>, <code>code</code>,
<code>em</code>, <code>font</code>, <code>i</code>, <code>nobr</code>, <code>s</code>,
<code>small</code>, <code>strike</code>, <code>strong</code>, <code>tt</code>, and
<code>u</code>.</p></dd>
<dt><dfn>Ordinary</dfn></dt>
<dd><p>All other elements found while parsing an HTML document.</p></dd>
</dl>
<p class="note">Typically, the <span>special</span> elements have the start and end tag tokens
handled specifically, while <span>ordinary</span> elements' tokens fall into "any other start tag"
and "any other end tag" clauses, and some parts of the tree builder check if a particular element
in the <span>stack of open elements</span> is in the <span>special</span> category. However, some
elements (e.g., the <code>option</code> element) have their start or end tag tokens handled
specifically, but are still not in the <span>special</span> category, so that they get the
<span>ordinary</span> handling elsewhere.</p>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in the specific
scope">have an element <var>target node</var> in a specific scope</dfn> consisting of a
list of element types <var>list</var> when the following algorithm terminates in a match
state:</p>
<ol>
<li><p>Initialize <var>node</var> to be the <span>current node</span> (the bottommost
node of the stack).</p></li>
<li><p>If <var>node</var> is <var>target node</var>, terminate in a match state.</p></li>
<li><p>Otherwise, if <var>node</var> is one of the element types in <var>list</var>, terminate in a failure state.</p></li>
<li><p>Otherwise, set <var>node</var> to the previous entry in the <span>stack of open
elements</span> and return to step 2. (This will never fail, since the loop will always terminate
in the previous step if the top of the stack — an <code>html</code> element — is
reached.)</p></li>
</ol>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in scope">have a
particular element in scope</dfn> when it <span data-x="has an element in the specific scope">has
that element in the specific scope</span> consisting of the following element types:</p>
<ul class="brief">
<li><code>applet</code></li>
<li><code>caption</code></li>
<li><code>html</code></li> <!-- (This can only happen if the <var>node</var> is the topmost node of the <span>stack of open elements</span>, and prevents the next step from being invoked if there are no more elements in the stack.) -->
<li><code>table</code></li>
<li><code>td</code></li>
<li><code>th</code></li>
<li><code>marquee</code></li>
<li><code>object</code></li>
<li><code>template</code></li>
<li><span>MathML <code>mi</code></span></li>
<li><span>MathML <code>mo</code></span></li>
<li><span>MathML <code>mn</code></span></li>
<li><span>MathML <code>ms</code></span></li>
<li><span>MathML <code>mtext</code></span></li>
<li><span>MathML <code>annotation-xml</code></span></li>
<li><span>SVG <code>foreignObject</code></span></li>
<li><span>SVG <code>desc</code></span></li>
<li><span>SVG <code>title</code></span></li>
</ul>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in list item
scope">have a particular element in list item scope</dfn> when it <span data-x="has an element in
the specific scope">has that element in the specific scope</span> consisting of the following
element types:</p>
<ul class="brief">
<li>All the element types listed above for the <i data-x="has an element in scope">has an element in scope</i> algorithm.</li>
<li><code>ol</code> in the <span>HTML namespace</span></li>
<li><code>ul</code> in the <span>HTML namespace</span></li>
</ul>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in button
scope">have a particular element in button scope</dfn> when it <span data-x="has an element in the
specific scope">has that element in the specific scope</span> consisting of the following element
types:</p>
<ul class="brief">
<li>All the element types listed above for the <i data-x="has an element in scope">has an element in scope</i> algorithm.</li>
<li><code>button</code> in the <span>HTML namespace</span></li>
</ul>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in table
scope">have a particular element in table scope</dfn> when it <span data-x="has an element in the
specific scope">has that element in the specific scope</span> consisting of the following element
types:</p>
<ul class="brief">
<li><code>html</code> in the <span>HTML namespace</span></li> <!-- (This can only happen if the
<var>node</var> is the topmost node of the <span>stack of open elements</span>, and
prevents the next step from being invoked if there are no more elements in the stack.) -->
<li><code>table</code> in the <span>HTML namespace</span></li>
<li><code>template</code> in the <span>HTML namespace</span></li>
</ul>
<p>The <span>stack of open elements</span> is said to <dfn data-x="has an element in select
scope">have a particular element in select scope</dfn> when it <span data-x="has an element in the
specific scope">has that element in the specific scope</span> consisting of all element types
<em>except</em> the following:</p>
<ul class="brief">
<!--<li><code>select</code> in the <span>HTML namespace</span></li>-->
<li><code>optgroup</code> in the <span>HTML namespace</span></li>
<li><code>option</code> in the <span>HTML namespace</span></li>
</ul>
<p>Nothing happens if at any time any of the elements in the <span>stack of open elements</span>
are moved to a new location in, or removed from, the <code>Document</code> tree. In particular,
the stack is not changed in this situation. This can cause, amongst other strange effects, content
to be appended to nodes that are no longer in the DOM.</p>
<p class="note">In some cases (namely, when <a href="#adoptionAgency">closing misnested formatting
elements</a>), the stack is manipulated in a random-access fashion.</p>
<h5>The list of active formatting elements</h5>
<p>Initially, the <dfn>list of active formatting elements</dfn> is empty. It is used to handle
mis-nested <span data-x="formatting">formatting element tags</span>.</p>
<p>The list contains elements in the <span>formatting</span> category, and <span
data-x="concept-parser-marker">markers</span>. The <dfn
data-x="concept-parser-marker">markers</dfn> are inserted when entering <code>applet</code>,
<code>object</code>, <code>marquee</code>, <code>template</code>, <code>td</code>,
<code>th</code>, and <code>caption</code> elements, and are used to prevent formatting from
"leaking" <em>into</em> <code>applet</code>, <code>object</code>, <code>marquee</code>,
<code>template</code>, <code>td</code>, <code>th</code>, and <code>caption</code> elements.</p>
<p>In addition, each element in the <span>list of active formatting elements</span> is associated
with the token for which it was created, so that further elements can be created for that token if
necessary.</p>
<p>When the steps below require the UA to <dfn>push onto the list of active formatting
elements</dfn> an element <var>element</var>, the UA must perform the following
steps:</p>
<ol id="noah">
<li><p>If there are already three elements in the <span>list of active formatting elements</span>
after the last <span data-x="concept-parser-marker">marker</span>, if any, or anywhere in the
list if there are no <span data-x="concept-parser-marker">markers</span>, that have the same tag
name, namespace, and attributes as <var>element</var>, then remove the earliest such
element from the <span>list of active formatting elements</span>. For these purposes, the
attributes must be compared as they were when the elements were created by the parser; two
elements have the same attributes if all their parsed attributes can be paired such that the two
attributes in each pair have identical names, namespaces, and values (the order of the attributes
does not matter).</p>
<p class="note">This is the Noah's Ark clause. But with three per family instead of two.</p></li>
<!-- A sort of polyamorous Noah's Ark, if you will. -->
<li><p>Add <var>element</var> to the <span>list of active formatting
elements</span>.</p></li>
</ol>
<p>When the steps below require the UA to <dfn>reconstruct the active formatting elements</dfn>,
the UA must perform the following steps:</p>
<ol>
<li><p>If there are no entries in the <span>list of active formatting elements</span>, then there
is nothing to reconstruct; stop this algorithm.</p></li>
<li><p>If the last (most recently added) entry in the <span>list of active formatting
elements</span> is a <span data-x="concept-parser-marker">marker</span>, or if it is an element
that is in the <span>stack of open elements</span>, then there is nothing to reconstruct; stop
this algorithm.</p></li>
<li><p>Let <var>entry</var> be the last (most recently added) element in the <span>list
of active formatting elements</span>.</p></li>
<li><p><i>Rewind</i>: If there are no entries before <var>entry</var> in the <span>list
of active formatting elements</span>, then jump to the step labeled <i>create</i>.</p></li>
<li><p>Let <var>entry</var> be the entry one earlier than <var>entry</var> in
the <span>list of active formatting elements</span>.</p></li>
<li><p>If <var>entry</var> is neither a <span
data-x="concept-parser-marker">marker</span> nor an element that is also in the <span>stack of
open elements</span>, go to the step labeled <i>rewind</i>.</p></li>
<li><p><i>Advance</i>: Let <var>entry</var> be the element one later than <var>entry</var> in the <span>list of active formatting elements</span>.</p></li>
<li><p><i>Create</i>: <span>Insert an HTML element</span> for the token for which the element
<var>entry</var> was created, to obtain <var>new element</var>.</p></li>
<li><p>Replace the entry for <var>entry</var> in the list with an entry for <var>new element</var>.</p></li>
<li><p>If the entry for <var>new element</var> in the <span>list of active formatting
elements</span> is not the last entry in the list, return to the step labeled
<i>advance</i>.</p></li>
</ol>
<p>This has the effect of reopening all the formatting elements that were opened in the current
body, cell, or caption (whichever is youngest) that haven't been explicitly closed.</p>
<p class="note">The way this specification is written, the <span>list of active formatting
elements</span> always consists of elements in chronological order with the least recently added
element first and the most recently added element last (except for while steps 7 to 10 of the
above algorithm are being executed, of course).</p>
<p>When the steps below require the UA to <dfn>clear the list of active formatting elements up to
the last marker</dfn>, the UA must perform the following steps:</p>
<ol>
<li><p>Let <var>entry</var> be the last (most recently added) entry in the <span>list of
active formatting elements</span>.</p></li>
<li><p>Remove <var>entry</var> from the <span>list of active formatting
elements</span>.</p></li>
<li><p>If <var>entry</var> was a <span data-x="concept-parser-marker">marker</span>,
then stop the algorithm at this point. The list has been cleared up to the last <span
data-x="concept-parser-marker">marker</span>.</p></li>
<li><p>Go to step 1.</p></li>
</ol>
<h5>The element pointers</h5>
<p>Initially, the <dfn><code data-x="">head</code> element pointer</dfn> and the <dfn><code
data-x="">form</code> element pointer</dfn> are both null.</p>
<p>Once a <code>head</code> element has been parsed (whether implicitly or explicitly) the
<span><code data-x="">head</code> element pointer</span> gets set to point to this node.</p>
<p>The <span><code data-x="">form</code> element pointer</span> points to the last
<code>form</code> element that was opened and whose end tag has not yet been seen. It is used to
make form controls associate with forms in the face of dramatically bad markup, for historical
reasons. It is ignored inside <code>template</code> elements.</p>
<h5>Other parsing state flags</h5>
<p>The <dfn>scripting flag</dfn> is set to "enabled" if <span data-x="concept-n-script">scripting
was enabled</span> for the <code>Document</code> with which the parser is associated when the
parser was created, and "disabled" otherwise.</p>
<p class="note">The <span>scripting flag</span> can be enabled even when the parser was created as
part of the <span>HTML fragment parsing algorithm</span>, even though <code>script</code> elements
don't execute in that case.</p>
<p>The <dfn>frameset-ok flag</dfn> is set to "ok" when the parser is created. It is set to "not
ok" after certain tokens are seen.</p>
</div>
<div w-nodev>
<h4><dfn>Tokenization</dfn></h4>
<p>Implementations must act as if they used the following state machine to tokenize HTML. The
state machine must start in the <span>data state</span>. Most states consume a single character,
which may have various side-effects, and either switches the state machine to a new state to
<span>reconsume</span> the <span>current input character</span>, or switches it to a new state to
consume the <span data-x="next input character">next character</span>, or stays in the same state
to consume the next character. Some states have more complicated behavior and can consume several
characters before switching to another state. In some cases, the tokenizer state is also changed
by the tree construction stage.</p>
<p>When a state says to <dfn>reconsume</dfn> a matched character in a specified state, that means
to switch to that state, but when it attempts to consume the <span>next input character</span>,
provide it with the <span>current input character</span> instead.</p>
<p>The exact behavior of certain states depends on the <span>insertion mode</span> and the
<span>stack of open elements</span>. Certain states also use a <dfn><var data-x="temporary
buffer">temporary buffer</var></dfn> to track progress, and the <span>character reference
state</span> uses a <dfn><var data-x="return state">return state</var></dfn> to return to the
state it was invoked from.</p>
<p>The output of the tokenization step is a series of zero or more of the following tokens:
DOCTYPE, start tag, end tag, comment, character, end-of-file. DOCTYPE tokens have a name, a public
identifier, a system identifier, and a <dfn><i>force-quirks flag</i></dfn>. When a DOCTYPE token
is created, its name, public identifier, and system identifier must be marked as missing (which is
a distinct state from the empty string), and the <i data-x="force-quirks flag">force-quirks flag</i> must be set to
<i>off</i> (its other state is <i>on</i>). Start and end tag tokens have a tag name, a <dfn
data-x="self-closing flag">self-closing flag</dfn>, and a list of attributes, each of which has a
name and a value. When a start or end tag token is created, its <i data-x="self-closing
flag">self-closing flag</i> must be unset (its other state is that it be set), and its attributes
list must be empty. Comment and character tokens have data.</p>
<p>When a token is emitted, it must immediately be handled by the <span>tree construction</span>
stage. The tree construction stage can affect the state of the tokenization stage, and can insert
additional characters into the stream. (For example, the <code>script</code> element can result in
scripts executing and using the <span>dynamic markup insertion</span> APIs to insert characters
into the stream being tokenized.)</p>
<p class="note">Creating a token and emitting it are distinct actions. It is possible for a token
to be created but implicitly abandoned (never emitted), e.g. if the file ends unexpectedly while
processing the characters that are being parsed into a start tag token.</p>
<p>When a start tag token is emitted with its <i data-x="self-closing flag">self-closing flag</i> set, if the flag is not
<dfn data-x="acknowledge self-closing flag">acknowledged</dfn> when it is processed by the tree
construction stage, that is a <span
data-x="parse-error-non-void-html-element-start-tag-with-trailing-solidus">non-void-html-element-start-tag-with-trailing-solidus</span>
<span>parse error</span>.</p>
<p>When an end tag token is emitted with attributes, that is an <span
data-x="parse-error-end-tag-with-attributes">end-tag-with-attributes</span> <span>parse
error</span>.</p>
<p>When an end tag token is emitted with its <i data-x="self-closing flag">self-closing flag</i>
set, that is an <span
data-x="parse-error-end-tag-with-trailing-solidus">end-tag-with-trailing-solidus</span>
<span>parse error</span>.</p>
<p>An <dfn>appropriate end tag token</dfn> is an end tag token whose tag name matches the tag name
of the last start tag to have been emitted from this tokenizer, if any. If no start tag has been
emitted from this tokenizer, then no end tag token is appropriate.</p>
<p>A <span data-x="syntax-charref">character reference</span> is said to be <dfn
data-x="charref-in-attribute">consumed as part of an attribute</dfn> if the <var data-x="return
state">return state</var> is either <span>attribute value (double-quoted) state</span>,
<span>attribute value (single-quoted) state</span>, or <span>attribute value (unquoted)
state</span>.</p>
<p>When a state says to <dfn>flush code points consumed as a character reference</dfn>, it means
that for each <span>code point</span> in the <var data-x="temporary buffer">temporary
buffer</var> (in the order they were added to the buffer) user agent must append the code point
from the buffer to the current attribute's value if the character reference was <span
data-x="charref-in-attribute">consumed as part of an attribute</span>, or emit the code point as a
character token otherwise.</p>
<p id="check-parser-pause-flag">Before each step of the tokenizer, the user agent must first check
the <span>parser pause flag</span>. If it is true, then the tokenizer must abort the processing of
any nested invocations of the tokenizer, yielding control back to the caller.</p>
<p>The tokenizer state machine consists of the states defined in the following subsections.</p>
<!-- Order of the lists below is supposed to be non-error then error, by unicode, then EOF, ending
with "anything else" -->
<h5><dfn>Data state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0026 AMPERSAND (&)</dt>
<dd>Set the <var data-x="return state">return state</var> to the <span>data state</span>.
Switch to the <span>character reference state</span>.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>tag open state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit the <span>current input character</span> as a character token.</dd>
<dt>EOF</dt>
<dd>Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>RCDATA state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0026 AMPERSAND (&)</dt>
<dd>Set the <var data-x="return state">return state</var> to the <span>RCDATA state</span>.
Switch to the <span>character reference state</span>.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>RCDATA less-than sign state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>RAWTEXT state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>RAWTEXT less-than sign state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data less-than sign state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>PLAINTEXT state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>Tag open state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0021 EXCLAMATION MARK (!)</dt>
<dd>Switch to the <span>markup declaration open state</span>.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>Switch to the <span>end tag open state</span>.</dd>
<dt><span>ASCII alpha</span></dt>
<dd>Create a new start tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>tag name state</span>.
<dt>U+003F QUESTION MARK (?)</dt>
<dd>This is an <span
data-x="parse-error-unexpected-question-mark-instead-of-tag-name">unexpected-question-mark-instead-of-tag-name</span>
<span>parse error</span>. Create a comment token whose data is the empty string.
<span>Reconsume</span> in the <span>bogus comment state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-before-tag-name">eof-before-tag-name</span>
<span>parse error</span>. Emit a U+003C LESS-THAN SIGN character token and an end-of-file
token.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-invalid-first-character-of-tag-name">invalid-first-character-of-tag-name</span>
<span>parse error</span>. Emit a U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in
the <span>data state</span>.</dd>
</dl>
<h5><dfn>End tag open state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span>ASCII alpha</span></dt>
<dd>Create a new end tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>tag name state</span>.
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span data-x="parse-error-missing-end-tag-name">missing-end-tag-name</span>
<span>parse error</span>. Switch to the <span>data state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-before-tag-name">eof-before-tag-name</span>
<span>parse error</span>. Emit a U+003C LESS-THAN SIGN character token, a U+002F SOLIDUS
character token and an end-of-file token.
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-invalid-first-character-of-tag-name">invalid-first-character-of-tag-name</span>
<span>parse error</span>. Create a comment token whose data is the empty string.
<span>Reconsume</span> in the <span>bogus comment state</span>.</dd>
</dl>
<h5><dfn>Tag name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before attribute name state</span>.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>Switch to the <span>self-closing start tag state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current tag token.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current tag token's tag name.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current tag token's tag
name.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span> <span>parse error</span>.
Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current tag token's tag name.</dd>
</dl>
<h5><dfn>RCDATA less-than sign state</dfn></h5>
<!-- identical to the RAWTEXT less-than sign state, except s/RAWTEXT/RCDATA/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002F SOLIDUS (/)</dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Switch to
the <span>RCDATA end tag open state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in the <span>RCDATA
state</span>.</dd>
</dl>
<h5><dfn>RCDATA end tag open state</dfn></h5>
<!-- identical to the RAWTEXT (and Script data) end tag open state, except s/RAWTEXT/RCDATA/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span>ASCII alpha</span></dt>
<dd>Create a new end tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>RCDATA end tag name state</span>.
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token and a U+002F SOLIDUS character token.
<span>Reconsume</span> in the <span>RCDATA state</span>.</dd>
</dl>
<h5><dfn>RCDATA end tag name state</dfn></h5>
<!-- identical to the RAWTEXT (and Script data) end tag name state, except s/RAWTEXT/RCDATA/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>before attribute name state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>self-closing start tag state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>data state</span> and emit the current tag token. Otherwise, treat it as per the "anything
else" entry below.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current tag token's tag name. Append the <span>current input
character</span> to the <var data-x="temporary buffer">temporary buffer</var>.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the current tag token's tag name. Append
the <span>current input character</span> to the <var data-x="temporary buffer">temporary
buffer</var>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token, a U+002F SOLIDUS character token, and a
character token for each of the characters in the <var data-x="temporary buffer">temporary
buffer</var> (in the order they were added to the buffer). <span>Reconsume</span> in the
<span>RCDATA state</span>.</dd>
</dl>
<h5><dfn>RAWTEXT less-than sign state</dfn></h5>
<!-- identical to the RCDATA less-than sign state, except s/RCDATA/RAWTEXT/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002F SOLIDUS (/)</dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Switch to
the <span>RAWTEXT end tag open state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in the <span>RAWTEXT
state</span>.</dd>
</dl>
<h5><dfn>RAWTEXT end tag open state</dfn></h5>
<!-- identical to the RCDATA (and Script data) end tag open state, except s/RCDATA/RAWTEXT/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span>ASCII alpha</span></dt>
<dd>Create a new end tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>RAWTEXT end tag name state</span>.
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token and a U+002F SOLIDUS character token.
<span>Reconsume</span> in the <span>RAWTEXT state</span>.</dd>
</dl>
<h5><dfn>RAWTEXT end tag name state</dfn></h5>
<!-- identical to the RCDATA (and Script data) end tag name state, except s/RCDATA/RAWTEXT/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>before attribute name state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>self-closing start tag state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>data state</span> and emit the current tag token. Otherwise, treat it as per the "anything
else" entry below.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current tag token's tag name. Append the <span>current input
character</span> to the <var data-x="temporary buffer">temporary buffer</var>.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the current tag token's tag name. Append
the <span>current input character</span> to the <var data-x="temporary buffer">temporary
buffer</var>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token, a U+002F SOLIDUS character token, and a
character token for each of the characters in the <var data-x="temporary buffer">temporary
buffer</var> (in the order they were added to the buffer). <span>Reconsume</span> in the
<span>RAWTEXT state</span>.</dd>
</dl>
<h5><dfn>Script data less-than sign state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002F SOLIDUS (/)</dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Switch to
the <span>script data end tag open state</span>.</dd>
<dt>U+0021 EXCLAMATION MARK (!)</dt>
<dd>Switch to the <span>script data escape start state</span>. Emit a U+003C LESS-THAN SIGN
character token and a U+0021 EXCLAMATION MARK character token.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in the <span>script data
state</span>.</dd>
</dl>
<h5><dfn>Script data end tag open state</dfn></h5>
<!-- identical to the RCDATA (and RAWTEXT) end tag open state, except s/RCDATA/Script data/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span>ASCII alpha</span></dt>
<dd>Create a new end tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>script data end tag name state</span>.
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token and a U+002F SOLIDUS character token.
<span>Reconsume</span> in the <span>script data state</span>.</dd>
</dl>
<h5><dfn>Script data end tag name state</dfn></h5>
<!-- identical to the RCDATA (and RAWTEXT) end tag name state, except s/RCDATA/Script data/g -->
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>before attribute name state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>self-closing start tag state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>data state</span> and emit the current tag token. Otherwise, treat it as per the "anything
else" entry below.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current tag token's tag name. Append the <span>current input
character</span> to the <var data-x="temporary buffer">temporary buffer</var>.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the current tag token's tag name. Append
the <span>current input character</span> to the <var data-x="temporary buffer">temporary
buffer</var>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token, a U+002F SOLIDUS character token, and a
character token for each of the characters in the <var data-x="temporary buffer">temporary
buffer</var> (in the order they were added to the buffer). <span>Reconsume</span> in the
<span>script data state</span>.</dd>
</dl>
<h5><dfn>Script data escape start state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data escape start dash state</span>. Emit a U+002D HYPHEN-MINUS
character token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>script data state</span>.</dd>
</dl>
<h5><dfn>Script data escape start dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data escaped dash dash state</span>. Emit a U+002D HYPHEN-MINUS
character token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>script data state</span>.</dd>
</dl>
<h5><dfn>Script data escaped state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data escaped dash state</span>. Emit a U+002D HYPHEN-MINUS
character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data escaped less-than sign state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data escaped dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data escaped dash dash state</span>. Emit a U+002D HYPHEN-MINUS
character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data escaped less-than sign state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Switch to the <span>script data escaped state</span>. Emit a U+FFFD REPLACEMENT
CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Switch to the <span>script data escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data escaped dash dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Emit a U+002D HYPHEN-MINUS character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data escaped less-than sign state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>script data state</span>. Emit a U+003E GREATER-THAN SIGN character
token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Switch to the <span>script data escaped state</span>. Emit a U+FFFD REPLACEMENT
CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Switch to the <span>script data escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data escaped less-than sign state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002F SOLIDUS (/)</dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Switch to
the <span>script data escaped end tag open state</span>.</dd>
<dt><span>ASCII alpha</span></dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Emit a
U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in the <span>script data double
escape start state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token. <span>Reconsume</span> in the <span>script data
escaped state</span>.</dd>
</dl>
<h5><dfn>Script data escaped end tag open state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span>ASCII alpha</span></dt>
<dd>Create a new end tag token, set its tag name to the empty string. <span>Reconsume</span> in
the <span>script data escaped end tag name state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token and a U+002F SOLIDUS character token.
<span>Reconsume</span> in the <span>script data escaped state</span>.</dd>
</dl>
<h5><dfn>Script data escaped end tag name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>before attribute name state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>self-closing start tag state</span>. Otherwise, treat it as per the "anything else" entry
below.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the current end tag token is an <span>appropriate end tag token</span>, then switch to the
<span>data state</span> and emit the current tag token. Otherwise, treat it as per the "anything
else" entry below.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current tag token's tag name. Append the <span>current input
character</span> to the <var data-x="temporary buffer">temporary buffer</var>.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the current tag token's tag name. Append
the <span>current input character</span> to the <var data-x="temporary buffer">temporary
buffer</var>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+003C LESS-THAN SIGN character token, a U+002F SOLIDUS character token, and a
character token for each of the characters in the <var data-x="temporary buffer">temporary buffer
</var> (in the order they were added to the buffer). <span>Reconsume</span> in the <span>script
data escaped state</span>.</dd>
</dl>
<h5><dfn>Script data double escape start state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dt>U+002F SOLIDUS (/)</dt>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the <var data-x="temporary buffer">temporary buffer</var> is the string "<code
data-x="">script</code>", then switch to the <span>script data double escaped state</span>.
Otherwise, switch to the <span>script data escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the <var data-x="temporary buffer">temporary buffer</var>. Emit the
<span>current input character</span> as a character token.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the <var data-x="temporary
buffer">temporary buffer</var>. Emit the <span>current input character</span> as a character
token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>script data escaped state</span>.</dd>
</dl>
<h5><dfn>Script data double escaped state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data double escaped dash state</span>. Emit a U+002D HYPHEN-MINUS
character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data double escaped less-than sign state</span>. Emit a U+003C
LESS-THAN SIGN character token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Emit a U+FFFD REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data double escaped dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>script data double escaped dash dash state</span>. Emit a U+002D
HYPHEN-MINUS character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data double escaped less-than sign state</span>. Emit a U+003C
LESS-THAN SIGN character token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Switch to the <span>script data double escaped state</span>. Emit a U+FFFD
REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Switch to the <span>script data double escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data double escaped dash dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Emit a U+002D HYPHEN-MINUS character token.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Switch to the <span>script data double escaped less-than sign state</span>. Emit a U+003C
LESS-THAN SIGN character token.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>script data state</span>. Emit a U+003E GREATER-THAN SIGN character
token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Switch to the <span>script data double escaped state</span>. Emit a U+FFFD
REPLACEMENT CHARACTER character token.</dd>
<dt>EOF</dt>
<dd>This is an <span
data-x="parse-error-eof-in-script-html-comment-like-text">eof-in-script-html-comment-like-text</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Switch to the <span>script data double escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
</dl>
<h5><dfn>Script data double escaped less-than sign state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002F SOLIDUS (/)</dt>
<dd>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Switch to
the <span>script data double escape end state</span>. Emit a U+002F SOLIDUS character token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>script data double escaped state</span>.</dd>
</dl>
<h5><dfn>Script data double escape end state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dt>U+002F SOLIDUS (/)</dt>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>If the <var data-x="temporary buffer">temporary buffer</var> is the string "<code
data-x="">script</code>", then switch to the <span>script data escaped state</span>. Otherwise,
switch to the <span>script data double escaped state</span>. Emit the <span>current input
character</span> as a character token.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the <var data-x="temporary buffer">temporary buffer</var>. Emit the
<span>current input character</span> as a character token.</dd>
<dt><span>ASCII lower alpha</span></dt>
<dd>Append the <span>current input character</span> to the <var data-x="temporary
buffer">temporary buffer</var>. Emit the <span>current input character</span> as a character
token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>script data double escaped state</span>.</dd>
</dl>
<h5><dfn>Before attribute name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dt>EOF</dt>
<dd><span>Reconsume</span> in the <span>after attribute name state</span>.</dd>
<dt>U+003D EQUALS SIGN (=)</dt>
<dd>This is an <span
data-x="parse-error-unexpected-equals-sign-before-attribute-name">unexpected-equals-sign-before-attribute-name</span>
<span>parse error</span>. Start a new attribute in the current tag token. Set that attribute's
name to the <span>current input character</span>, and its value to the empty string. Switch to
the <span>attribute name state</span>.</dd>
<dt>Anything else</dt>
<dd>Start a new attribute in the current tag token. Set that attribute name and value to the
empty string. <span>Reconsume</span> in the <span>attribute name state</span>.</dd>
</dl>
<h5><dfn>Attribute name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dt>U+002F SOLIDUS (/)</dt>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dt>EOF</dt>
<dd><span>Reconsume</span> in the <span>after attribute name state</span>.</dd>
<dt>U+003D EQUALS SIGN (=)</dt>
<dd>Switch to the <span>before attribute value state</span>.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current attribute's name.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current attribute's
name.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dt>U+0027 APOSTROPHE (')</dt>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>This is an <span
data-x="parse-error-unexpected-character-in-attribute-name">unexpected-character-in-attribute-name</span>
<span>parse error</span>. Treat it as per the "anything else" entry below.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current attribute's name.</dd>
</dl>
<p>When the user agent leaves the attribute name state (and before emitting the tag token, if
appropriate), the complete attribute's name must be compared to the other attributes on the same
token; if there is already an attribute on the token with the exact same name, then this is a
<span data-x="parse-error-duplicate-attribute">duplicate-attribute</span> <span>parse error</span>
and the new attribute must be removed from the token.</p>
<p class="note">If an attribute is so removed from a token, it, and the value that gets associated
with it, if any, are never subsequently used by the parser, and are therefore effectively
discarded. Removing the attribute in this way does not change its status as the "current
attribute" for the purposes of the tokenizer, however.</p>
<h5><dfn>After attribute name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>Switch to the <span>self-closing start tag state</span>.</dd>
<dt>U+003D EQUALS SIGN (=)</dt>
<dd>Switch to the <span>before attribute value state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current tag token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Start a new attribute in the current tag token. Set that attribute name and value to the
empty string. <span>Reconsume</span> in the <span>attribute name state</span>.</dd>
</dl>
<h5><dfn>Before attribute value state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Switch to the <span>attribute value (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Switch to the <span>attribute value (single-quoted) state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span data-x="parse-error-missing-attribute-value">missing-attribute-value</span>
<span>parse error</span>. Switch to the <span>data state</span>. Emit the current tag token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>attribute value (unquoted) state</span>.</dd>
</dl>
<h5><dfn>Attribute value (double-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Switch to the <span>after attribute value (quoted) state</span>.</dd>
<dt>U+0026 AMPERSAND (&)</dt>
<dd>Set the <var data-x="return state">return state</var> to the <span>attribute value
(double-quoted) state</span>. Switch to the <span>character reference state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current attribute's
value.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span> <span>parse error</span>.
Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current attribute's value.</dd>
</dl>
<h5><dfn>Attribute value (single-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Switch to the <span>after attribute value (quoted) state</span>.</dd>
<dt>U+0026 AMPERSAND (&)</dt>
<dd>Set the <var data-x="return state">return state</var> to the <span>attribute value
(single-quoted) state</span>. Switch to the <span>character reference state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current attribute's
value.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span> <span>parse error</span>.
Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current attribute's value.</dd>
</dl>
<h5><dfn>Attribute value (unquoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before attribute name state</span>.</dd>
<dt>U+0026 AMPERSAND (&)</dt>
<dd>Set the <var data-x="return state">return state</var> to the <span>attribute value
(unquoted) state</span>. Switch to the <span>character reference state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current tag token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current attribute's
value.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dt>U+0027 APOSTROPHE (')</dt>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dt>U+003D EQUALS SIGN (=)</dt>
<dt>U+0060 GRAVE ACCENT (`)</dt>
<dd>This is an <span
data-x="parse-error-unexpected-character-in-unquoted-attribute-value">unexpected-character-in-unquoted-attribute-value</span>
<span>parse error</span>. Treat it as per the "anything else" entry below.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current attribute's value.</dd>
</dl>
<h5><dfn>After attribute value (quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before attribute name state</span>.</dd>
<dt>U+002F SOLIDUS (/)</dt>
<dd>Switch to the <span>self-closing start tag state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current tag token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span> <span>parse error</span>.
Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-between-attributes">missing-whitespace-between-attributes</span>
<span>parse error</span>. <span>Reconsume</span> in the <span>before attribute name state</span>.
</dd>
</dl>
<h5><dfn>Self-closing start tag state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Set the <i data-x="self-closing flag">self-closing flag</i> of the current tag token. Switch
to the <span>data state</span>. Emit the current tag token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-tag">eof-in-tag</span>
<span>parse error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-unexpected-solidus-in-tag">unexpected-solidus-in-tag</span> <span>parse
error</span>. <span>Reconsume</span> in the <span>before attribute name state</span>.</dd>
</dl>
<h5><dfn>Bogus comment state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current comment token.</dd>
<dt>EOF</dt>
<dd>Emit the comment. Emit an end-of-file token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the comment token's data.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the comment token's data.</dd>
</dl>
<h5><dfn>Markup declaration open state</dfn></h5>
<p>If the next few characters are:</p>
<dl class="switch">
<dt>Two U+002D HYPHEN-MINUS characters (-)</dt>
<dd>Consume those two characters, create a comment token whose data is the empty string, and
switch to the <span>comment start state</span>.</dd>
<dt><span>ASCII case-insensitive</span> match for the word "DOCTYPE"</dt>
<dd>Consume those characters and switch to the <span>DOCTYPE state</span>.</dd>
<dt>The string "[CDATA[" (the five uppercase letters "CDATA" with a U+005B LEFT SQUARE BRACKET
character before and after)</dt>
<dd>Consume those characters. If there is an <span>adjusted current node</span> and it is not
an element in the <span>HTML namespace</span>, then switch to the <span>CDATA section
state</span>. Otherwise, this is a <span
data-x="parse-error-cdata-in-html-content">cdata-in-html-content</span> <span>parse
error</span>. Create a comment token whose data is the "[CDATA[" string. Switch to the
<span>bogus comment state</span>.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-incorrectly-opened-comment">incorrectly-opened-comment</span>
<span>parse error</span>. Create a comment token whose data is the empty string. Switch to the
<span>bogus comment state</span> (don't consume anything in the current state).</dd>
</dl>
<h5><dfn>Comment start state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment start dash state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-closing-of-empty-comment">abrupt-closing-of-empty-comment</span> <span>parse
error</span>. Switch to the <span>data state</span>. Emit the current comment token.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>Comment start dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment end state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-closing-of-empty-comment">abrupt-closing-of-empty-comment</span> <span>parse
error</span>. Switch to the <span>data state</span>. Emit the current comment token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-comment">eof-in-comment</span> <span>parse
error</span>. Emit the current comment token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append a U+002D HYPHEN-MINUS character (-) to the comment token's data.
<span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn id="comment">Comment state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Append the <span>current input character</span> to the comment token's data. Switch to the
<span>comment less-than sign state</span>.</dd>
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment end dash state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the comment token's data.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-comment">eof-in-comment</span> <span>parse
error</span>. Emit the current comment token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the comment token's data.</dd>
</dl>
<h5><dfn>Comment less-than sign state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0021 EXCLAMATION MARK (!)</dt>
<dd>Append the <span>current input character</span> to the comment token's data. Switch to the
<span>comment less-than sign bang state</span>.</dd>
<dt>U+003C LESS-THAN SIGN (<)</dt>
<dd>Append the <span>current input character</span> to the comment token's data.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>Comment less-than sign bang state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment less-than sign bang dash state</span>.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>Comment less-than sign bang dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment less-than sign bang dash dash state</span>.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>comment end dash state</span>.</dd>
</dl>
<h5><dfn>Comment less-than sign bang dash dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dt>EOF</dt>
<dd><span>Reconsume</span> in the <span>comment end state</span>.</dd>
<dt>Anything else</dt>
<dd>This is a <span data-x="parse-error-nested-comment">nested-comment</span> <span>parse
error</span>. <span>Reconsume</span> in the <span>comment end state</span>.</dd>
</dl>
<h5><dfn>Comment end dash state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Switch to the <span>comment end state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-comment">eof-in-comment</span> <span>parse
error</span>. Emit the current comment token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append a U+002D HYPHEN-MINUS character (-) to the comment token's data.
<span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>Comment end state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current comment token.</dd>
<dt>U+0021 EXCLAMATION MARK (!)</dt>
<dd>Switch to the <span>comment end bang state</span>.</dd>
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Append a U+002D HYPHEN-MINUS character (-) to the comment token's data.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-comment">eof-in-comment</span> <span>parse
error</span>. Emit the current comment token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append two U+002D HYPHEN-MINUS characters (-) to the comment token's data.
<span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>Comment end bang state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+002D HYPHEN-MINUS (-)</dt>
<dd>Append two U+002D HYPHEN-MINUS characters (-) and a U+0021 EXCLAMATION MARK character (!) to
the comment token's data. Switch to the <span>comment end dash state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-incorrectly-closed-comment">incorrectly-closed-comment</span> <span>parse
error</span>. Switch to the <span>data state</span>. Emit the current comment token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-comment">eof-in-comment</span> <span>parse
error</span>. Emit the current comment token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append two U+002D HYPHEN-MINUS characters (-) and a U+0021 EXCLAMATION MARK character (!) to
the comment token's data. <span>Reconsume</span> in the <span>comment state</span>.</dd>
</dl>
<h5><dfn>DOCTYPE state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before DOCTYPE name state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd><span>Reconsume</span> in the <span>before DOCTYPE name state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Create a new DOCTYPE token. Set its <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Emit the current token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-before-doctype-name">missing-whitespace-before-doctype-name</span>
<span>parse error</span>. <span>Reconsume</span> in the <span>before DOCTYPE name state</span>.
</dd>
</dl>
<h5><dfn>Before DOCTYPE name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Create a new DOCTYPE token. Set the token's name to the lowercase version of the
<span>current input character</span> (add 0x0020 to the character's code point). Switch to the
<span>DOCTYPE name state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Create a new DOCTYPE token. Set the token's name to a U+FFFD REPLACEMENT CHARACTER
character. Switch to the <span>DOCTYPE name state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span data-x="parse-error-missing-doctype-name">missing-doctype-name</span>
<span>parse error</span>. Create a new DOCTYPE token. Set its <i
data-x="force-quirks flag">force-quirks flag</i> to <i>on</i>. Switch to the <span>data
state</span>. Emit the current token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Create a new DOCTYPE token. Set its <i data-x="force-quirks flag"> force-quirks
flag</i> to <i>on</i>. Emit the current token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Create a new DOCTYPE token. Set the token's name to the <span>current input character</span>.
Switch to the <span>DOCTYPE name state</span>.</dd>
</dl>
<h5><dfn>DOCTYPE name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>after DOCTYPE name state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt><span>ASCII upper alpha</span></dt>
<dd>Append the lowercase version of the <span>current input character</span> (add 0x0020 to the
character's code point) to the current DOCTYPE token's name.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current DOCTYPE token's
name.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current DOCTYPE token's name.</dd>
</dl>
<h5><dfn>After DOCTYPE name state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>
<p>If the six characters starting from the <span>current input character</span> are an
<span>ASCII case-insensitive</span> match for the word "PUBLIC", then consume those characters
and switch to the <span>after DOCTYPE public keyword state</span>.</p>
<p>Otherwise, if the six characters starting from the <span>current input character</span> are
an <span>ASCII case-insensitive</span> match for the word "SYSTEM", then consume those
characters and switch to the <span>after DOCTYPE system keyword state</span>.</p>
<p>Otherwise, this is an <span
data-x="parse-error-invalid-character-sequence-after-doctype-name">invalid-character-sequence-after-doctype-name</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</p>
</dd>
</dl>
<h5><dfn>After DOCTYPE public keyword state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before DOCTYPE public identifier state</span>.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-after-doctype-public-keyword">missing-whitespace-after-doctype-public-keyword</span>
<span>parse error</span>. Set the current DOCTYPE token's public identifier to the empty string (not
missing), then switch to the <span>DOCTYPE public identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-after-doctype-public-keyword">missing-whitespace-after-doctype-public-keyword</span>
<span>parse error</span>. Set the current DOCTYPE token's public identifier to the empty string (not
missing), then switch to the <span>DOCTYPE public identifier (single-quoted) state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span
data-x="parse-error-missing-doctype-public-identifier">missing-doctype-public-identifier</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-public-identifier">missing-quote-before-doctype-public-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>Before DOCTYPE public identifier state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Set the current DOCTYPE token's public identifier to the empty string (not missing), then switch to
the <span>DOCTYPE public identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Set the current DOCTYPE token's public identifier to the empty string (not missing), then switch to
the <span>DOCTYPE public identifier (single-quoted) state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span
data-x="parse-error-missing-doctype-public-identifier">missing-doctype-public-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-public-identifier">missing-quote-before-doctype-public-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>DOCTYPE public identifier (double-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Switch to the <span>after DOCTYPE public identifier state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current DOCTYPE token's
public identifier.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-doctype-public-identifier">abrupt-doctype-public-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current DOCTYPE token's public
identifier.</dd>
</dl>
<h5><dfn>DOCTYPE public identifier (single-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Switch to the <span>after DOCTYPE public identifier state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current DOCTYPE token's
public identifier.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-doctype-public-identifier">abrupt-doctype-public-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current DOCTYPE token's public
identifier.</dd>
</dl>
<h5><dfn>After DOCTYPE public identifier state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>between DOCTYPE public and system identifiers state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-between-doctype-public-and-system-identifiers">missing-whitespace-between-doctype-public-and-system-identifiers</span>
<span>parse error</span>. Set the current DOCTYPE token's system identifier to the empty string (not
missing), then switch to the <span>DOCTYPE system identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-between-doctype-public-and-system-identifiers">missing-whitespace-between-doctype-public-and-system-identifiers</span>
<span>parse error</span>. Set the current DOCTYPE token's system identifier to the empty string (not
missing), then switch to the <span>DOCTYPE system identifier (single-quoted) state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-system-identifier">missing-quote-before-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>Between DOCTYPE public and system identifiers state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Set the current DOCTYPE token's system identifier to the empty string (not missing), then switch to
the <span>DOCTYPE system identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Set the current DOCTYPE token's system identifier to the empty string (not missing), then switch to
the <span>DOCTYPE system identifier (single-quoted) state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-system-identifier">missing-quote-before-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>After DOCTYPE system keyword state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Switch to the <span>before DOCTYPE system identifier state</span>.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-after-doctype-system-keyword">missing-whitespace-after-doctype-system-keyword</span>
<span>parse error</span>. Set the current DOCTYPE token's system identifier to the empty string (not
missing), then switch to the <span>DOCTYPE system identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>This is a <span
data-x="parse-error-missing-whitespace-after-doctype-system-keyword">missing-whitespace-after-doctype-system-keyword</span>
<span>parse error</span>. Set the current DOCTYPE token's system identifier to the empty string (not
missing), then switch to the <span>DOCTYPE system identifier (single-quoted) state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span
data-x="parse-error-missing-doctype-system-identifier">missing-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-system-identifier">missing-quote-before-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>Before DOCTYPE system identifier state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Set the current DOCTYPE token's system identifier to the empty string (not missing), then switch to
the <span>DOCTYPE system identifier (double-quoted) state</span>.</dd>
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Set the current DOCTYPE token's system identifier to the empty string (not missing), then switch to
the <span>DOCTYPE system identifier (single-quoted) state</span>.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is a <span
data-x="parse-error-missing-doctype-system-identifier">missing-doctype-system-identifier</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-quote-before-doctype-system-identifier">missing-quote-before-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>.</dd>
</dl>
<h5><dfn>DOCTYPE system identifier (double-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0022 QUOTATION MARK (")</dt>
<dd>Switch to the <span>after DOCTYPE system identifier state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current DOCTYPE token's
system identifier.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-doctype-system-identifier">abrupt-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current DOCTYPE token's system
identifier.</dd>
</dl>
<h5><dfn>DOCTYPE system identifier (single-quoted) state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0027 APOSTROPHE (')</dt>
<dd>Switch to the <span>after DOCTYPE system identifier state</span>.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Append a U+FFFD REPLACEMENT CHARACTER character to the current DOCTYPE token's
system identifier.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>This is an <span
data-x="parse-error-abrupt-doctype-system-identifier">abrupt-doctype-system-identifier</span>
<span>parse error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks
flag</i> to <i>on</i>. Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Append the <span>current input character</span> to the current DOCTYPE token's system
identifier.</dd>
</dl>
<h5><dfn>After DOCTYPE system identifier state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0009 CHARACTER TABULATION (tab)</dt>
<dt>U+000A LINE FEED (LF)</dt>
<dt>U+000C FORM FEED (FF)</dt>
<!--<dt>U+000D CARRIAGE RETURN (CR)</dt>-->
<dt>U+0020 SPACE</dt>
<dd>Ignore the character.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the current DOCTYPE token.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-doctype">eof-in-doctype</span> <span>parse
error</span>. Set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>. Emit the current DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-unexpected-character-after-doctype-system-identifier">unexpected-character-after-doctype-system-identifier</span>
<span>parse error</span>. <span>Reconsume</span> in the <span>bogus DOCTYPE state</span>. (This
does <em>not</em> set the current DOCTYPE token's <i data-x="force-quirks flag">force-quirks flag</i> to
<i>on</i>.)</dd>
</dl>
<h5><dfn>Bogus DOCTYPE state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>. Emit the DOCTYPE token.</dd>
<dt>U+0000 NULL</dt>
<dd>This is an <span
data-x="parse-error-unexpected-null-character">unexpected-null-character</span> <span>parse
error</span>. Ignore the character.</dd>
<dt>EOF</dt>
<dd>Emit the DOCTYPE token. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Ignore the character.</dd>
</dl>
<h5><dfn>CDATA section state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+005D RIGHT SQUARE BRACKET (])</dt>
<dd>Switch to the <span>CDATA section bracket state</span>.</dd>
<dt>EOF</dt>
<dd>This is an <span data-x="parse-error-eof-in-cdata">eof-in-cdata</span> <span>parse
error</span>. Emit an end-of-file token.</dd>
<dt>Anything else</dt>
<dd>Emit the <span>current input character</span> as a character token.</dd>
</dl>
<p class="note">U+0000 NULL characters are handled in the tree construction stage, as part of the
<span data-x="insertion mode: in foreign content">in foreign content</span> insertion mode, which
is the only place where CDATA sections can appear.</p>
<h5><dfn>CDATA section bracket state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+005D RIGHT SQUARE BRACKET (])</dt>
<dd>Switch to the <span>CDATA section end state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit a U+005D RIGHT SQUARE BRACKET character token. <span>Reconsume</span> in the
<span>CDATA section state</span>.</dd>
</dl>
<h5><dfn>CDATA section end state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+005D RIGHT SQUARE BRACKET (])</dt>
<dd>Emit a U+005D RIGHT SQUARE BRACKET character token.</dd>
<dt>U+003E GREATER-THAN SIGN (>)</dt>
<dd>Switch to the <span>data state</span>.</dd>
<dt>Anything else</dt>
<dd>Emit two U+005D RIGHT SQUARE BRACKET character tokens. <span>Reconsume</span> in the
<span>CDATA section state</span>.</dd>
</dl>
<h5><dfn>Character reference state</dfn></h5>
<p>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Append
a U+0026 AMPERSAND (&) character to the <var data-x="temporary buffer">temporary
buffer</var>. Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII alphanumeric">ASCII alphanumeric</span></dt>
<dd><span>Reconsume</span> in the <span>named character reference state</span>.</dd>
<dt>U+0023 NUMBER SIGN (#)</dt>
<dd>Append the <span>current input character</span> to the
<var data-x="temporary buffer">temporary buffer</var>. Switch to the <span>numeric character
reference state</span>.</dd>
<dt>Anything else</dt>
<dd><span>Flush code points consumed as a character reference</span>. <span>Reconsume</span> in
the <var data-x="return state">return state</var>.</dd>
</dl>
<h5><dfn>Named character reference state</dfn></h5>
<p>Consume the maximum number of characters possible, where the consumed characters are one of the
identifiers in the first column of the <span>named character references</span> table. Append each
character to the <var data-x="temporary buffer">temporary buffer</var> when it's consumed.</p>
<dl class="switch">
<dt>If there is a match</dt>
<dd>
<p>If the character reference was <span data-x="charref-in-attribute">consumed as part of an
attribute</span>, and the last character matched is not a U+003B SEMICOLON character (;), and
the <span>next input character</span> is either a U+003D EQUALS SIGN character (=) or an
<span>ASCII alphanumeric</span>, then, for historical reasons, <span>flush code points consumed
as a character reference</span> and switch to the <var data-x="return state">return state</var>.
</p>
<!-- "=" added because of https://www.w3.org/Bugs/Public/show_bug.cgi?id=9207#c5 -->
<p>Otherwise:</p>
<ol>
<li><p>If the last character matched is not a U+003B SEMICOLON character (;), then this is a
<span
data-x="parse-error-missing-semicolon-after-character-reference">missing-semicolon-after-character-reference</span>
<span>parse error</span>.</p></li>
<li><p>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string.
Append one or two characters corresponding to the character reference name (as given by the
second column of the <span>named character references</span> table) to the <var
data-x="temporary buffer">temporary buffer</var>.</p></li>
<li><span>Flush code points consumed as a character reference</span>. Switch to the <var
data-x="return state">return state</var>.</li>
</ol>
</dd>
<dt>Otherwise</dt>
<dd><span>Flush code points consumed as a character reference</span>. Switch to the
<span>ambiguous ampersand state</span>.</dd>
</dl>
<div class="example">
<p>If the markup contains (not in an attribute) the string <code data-x="">I'm &notit; I
tell you</code>, the character reference is parsed as "not", as in, <code data-x="">I'm ¬it;
I tell you</code> (and this is a parse error). But if the markup was <code data-x="">I'm
&notin; I tell you</code>, the character reference would be parsed as "notin;", resulting
in <code data-x="">I'm ∉ I tell you</code> (and no parse error).</p>
<p>However, if the markup contains the string <code data-x="">I'm &notit; I tell you</code>
in an attribute, no character reference is parsed and string remains intact (and there is no
parse error).</p>
</div>
<h5><dfn>Ambiguous ampersand state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII alphanumeric">ASCII alphanumeric</span></dt>
<dd>If the character reference was <span data-x="charref-in-attribute">consumed as part of an
attribute</span>, then append the <span>current input character</span> to the current
attribute's value. Otherwise, emit the <span>current input character</span> as a character
token.</dd>
<dt>U+003B SEMICOLON (;)</dt>
<dd>This is an <span
data-x="parse-error-unknown-named-character-reference">unknown-named-character-reference</span>
<span>parse error</span>. <span>Reconsume</span> in the <var data-x="return state">return
state</var>.
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <var data-x="return state">return state</var>.</dd>
</dl>
<h5><dfn>Numeric character reference state</dfn></h5>
<p>Set the <dfn><var data-x="character reference code">character reference code</var></dfn> to
zero (0).</p>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt>U+0078 LATIN SMALL LETTER X</dt>
<dt>U+0058 LATIN CAPITAL LETTER X</dt>
<dd>Append the <span>current input character</span> to the <var data-x="temporary
buffer">temporary buffer</var>. Switch to the <span>hexadecimal character reference start
state</span>.</dd>
<dt>Anything else</dt>
<dd><span>Reconsume</span> in the <span>decimal character reference start state</span>.</dd>
</dl>
<h5><dfn>Hexadecimal character reference start state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII hex digits">ASCII hex digit</span></dt>
<dd><span>Reconsume</span> in the <span>hexadecimal character reference state</span>.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-absence-of-digits-in-numeric-character-reference">absence-of-digits-in-numeric-character-reference</span>
<span>parse error</span>. <span>Flush code points consumed as a character reference</span>.
<span>Reconsume</span> in the <var data-x="return state">return state</var>.</dd>
</dl>
<h5><dfn>Decimal character reference start state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII digits">ASCII digit</span></dt>
<dd><span>Reconsume</span> in the <span>decimal character reference state</span>.</dd>
<dt>Anything else</dt>
<dd>This is an <span
data-x="parse-error-absence-of-digits-in-numeric-character-reference">absence-of-digits-in-numeric-character-reference</span>
<span>parse error</span>. <span>Flush code points consumed as a character reference</span>.
<span>Reconsume</span> in the <var data-x="return state">return state</var>.</dd>
</dl>
<h5><dfn>Hexadecimal character reference state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII digits">ASCII digit</span></dt>
<dd>Multiply the <var data-x="character reference code">character reference code</var> by 16.
Add a numeric version of the <span>current input character</span> (subtract 0x0030 from the
character's code point) to the <var data-x="character reference code">character reference
code</var>.</dd>
<dt><span>ASCII upper hex digit</span></dt>
<dd>Multiply the <var data-x="character reference code">character reference code</var> by 16.
Add a numeric version of the <span>current input character</span> as a hexadecimal digit
(subtract 0x0037 from the character's code point) to the <var data-x="character reference
code">character reference code</var>.</dd>
<dt><span>ASCII lower hex digit</span></dt>
<dd>Multiply the <var data-x="character reference code">character reference code</var> by 16.
Add a numeric version of the <span>current input character</span> as a hexadecimal digit
(subtract 0x0057 from the character's code point) to the <var data-x="character reference
code">character reference code</var>.</dd>
<dt>U+003B SEMICOLON (;)</dt>
<dd>Switch to the <span>numeric character reference end state</span>.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-semicolon-after-character-reference">missing-semicolon-after-character-reference</span>
<span>parse error</span>. <span>Reconsume</span> in the <span>numeric character reference end
state</span>.</dd>
</dl>
<h5><dfn>Decimal character reference state</dfn></h5>
<p>Consume the <span>next input character</span>:</p>
<dl class="switch">
<dt><span data-x="ASCII digits">ASCII digit</span></dt>
<dd>Multiply the <var data-x="character reference code">character reference code</var> by 10.
Add a numeric version of the <span>current input character</span> (subtract 0x0030 from the
character's code point) to the <var data-x="character reference code">character reference
code</var>.</dd>
<dt>U+003B SEMICOLON (;)</dt>
<dd>Switch to the <span>numeric character reference end state</span>.</dd>
<dt>Anything else</dt>
<dd>This is a <span
data-x="parse-error-missing-semicolon-after-character-reference">missing-semicolon-after-character-reference</span>
<span>parse error</span>. <span>Reconsume</span> in the <span>numeric character reference end
state</span>.</dd>
</dl>
<h5><dfn>Numeric character reference end state</dfn></h5>
<p>Check the <var data-x="character reference code">character reference code</var>:</p>
<ul>
<li><p>If the number is 0x00, then this is a <span
data-x="parse-error-null-character-reference">null-character-reference</span> <span>parse
error</span>. Set the <var data-x="character reference code">character reference code</var> to
0xFFFD.</p></li>
<li><p>If the number is greater than 0x10FFFF, then this is a <span
data-x="parse-error-character-reference-outside-unicode-range">character-reference-outside-unicode-range</span>
<span>parse error</span>. Set the <var data-x="character reference code">character reference
code</var> to 0xFFFD.</p></li>
<li><p>If the number is a <span data-x="surrogate">surrogate</span>, then this is a <span
data-x="parse-error-surrogate-character-reference">surrogate-character-reference</span>
<span>parse error</span>. Set the <var data-x="character reference code">character reference
code</var> to 0xFFFD.</p></li>
<li><p>If the number is a <span data-x="noncharacter">noncharacter</span>, then this is a
<span data-x="parse-error-noncharacter-character-reference">noncharacter-character-reference</span>
<span>parse error</span>.</p></li>
<li><p>If the number is 0x0D<!-- CR is not allowed -->, or a
<span data-x="control">control</span> that's not <span>ASCII whitespace</span>, then this is a
<span data-x="parse-error-control-character-reference">control-character-reference</span>
<span>parse error</span>. If the number is one of the numbers in the first column of the
following table, then find the row with that number in the first column, and set the <var
data-x="character reference code">character reference code</var> to the number in the second
column of that row.</p>
<!-- these are Unicode C1 control characters -->
<table id="table-charref-overrides">
<thead>
<tr><th>Number <th colspan=2>Code point
<tbody>
<!-- <tr><td>0x0D <td>0x000D <td>CARRIAGE RETURN (CR) -->
<tr><td>0x80 <td>0x20AC <td>EURO SIGN (€)
<!-- <tr><td>0x81 <td>0x0081 <td><control> -->
<tr><td>0x82 <td>0x201A <td>SINGLE LOW-9 QUOTATION MARK (‚)
<tr><td>0x83 <td>0x0192 <td>LATIN SMALL LETTER F WITH HOOK (ƒ)
<tr><td>0x84 <td>0x201E <td>DOUBLE LOW-9 QUOTATION MARK („)
<tr><td>0x85 <td>0x2026 <td>HORIZONTAL ELLIPSIS (…)
<tr><td>0x86 <td>0x2020 <td>DAGGER (†)
<tr><td>0x87 <td>0x2021 <td>DOUBLE DAGGER (‡)
<tr><td>0x88 <td>0x02C6 <td>MODIFIER LETTER CIRCUMFLEX ACCENT (ˆ)
<tr><td>0x89 <td>0x2030 <td>PER MILLE SIGN (‰)
<tr><td>0x8A <td>0x0160 <td>LATIN CAPITAL LETTER S WITH CARON (Š)
<tr><td>0x8B <td>0x2039 <td>SINGLE LEFT-POINTING ANGLE QUOTATION MARK (‹)
<tr><td>0x8C <td>0x0152 <td>LATIN CAPITAL LIGATURE OE (Œ)
<!-- <tr><td>0x8D <td>0x008D <td><control> -->
<tr><td>0x8E <td>0x017D <td>LATIN CAPITAL LETTER Z WITH CARON (Ž)
<!-- <tr><td>0x8F <td>0x008F <td><control> -->
<!-- <tr><td>0x90 <td>0x0090 <td><control> -->
<tr><td>0x91 <td>0x2018 <td>LEFT SINGLE QUOTATION MARK (‘)
<tr><td>0x92 <td>0x2019 <td>RIGHT SINGLE QUOTATION MARK (’)
<tr><td>0x93 <td>0x201C <td>LEFT DOUBLE QUOTATION MARK (“)
<tr><td>0x94 <td>0x201D <td>RIGHT DOUBLE QUOTATION MARK (”)
<tr><td>0x95 <td>0x2022 <td>BULLET (•)
<tr><td>0x96 <td>0x2013 <td>EN DASH (–)
<tr><td>0x97 <td>0x2014 <td>EM DASH (—)
<tr><td>0x98 <td>0x02DC <td>SMALL TILDE (˜)
<tr><td>0x99 <td>0x2122 <td>TRADE MARK SIGN (™)
<tr><td>0x9A <td>0x0161 <td>LATIN SMALL LETTER S WITH CARON (š)
<tr><td>0x9B <td>0x203A <td>SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (›)
<tr><td>0x9C <td>0x0153 <td>LATIN SMALL LIGATURE OE (œ)
<!-- <tr><td>0x9D <td>0x009D <td><control> -->
<tr><td>0x9E <td>0x017E <td>LATIN SMALL LETTER Z WITH CARON (ž)
<tr><td>0x9F <td>0x0178 <td>LATIN CAPITAL LETTER Y WITH DIAERESIS (Ÿ)
</table></li>
</ul>
<p>Set the <var data-x="temporary buffer">temporary buffer</var> to the empty string. Append a
code point equal to the <var data-x="character reference code">character reference code</var> to
the <var data-x="temporary buffer">temporary buffer</var>. <span>Flush code points consumed as a
character reference</span>. Switch to the <var data-x="return state">return state</var>.</p>
</div>
<div w-nodev>
<!-- v2: One thing that this doesn't define is handling deeply nested documents. There are
compatibility requirements around that: you can't throw away the elements altogether, consider Tux
made only with opening <font> elements, one per character. Seems that the best thing to do is to
close some formatting elements from the middle of the stack when you hit a limit, or something.
-->
<h4><dfn>Tree construction</dfn></h4>
<p>The input to the tree construction stage is a sequence of tokens from the
<span>tokenization</span> stage. The tree construction stage is associated with a DOM
<code>Document</code> object when a parser is created. The "output" of this stage consists of
dynamically modifying or extending that document's DOM tree.</p>
<p>This specification does not define when an interactive user agent has to render the
<code>Document</code> so that it is available to the user, or when it has to begin accepting user
input.</p>
<hr>
<p>As each token is emitted from the tokenizer, the user agent must follow the appropriate steps
from the following list, known as the <dfn>tree construction dispatcher</dfn>:</p>
<dl class="switch">
<dt>If the <span>stack of open elements</span> is empty</dt>
<dt>If the <span>adjusted current node</span> is an element in the <span>HTML namespace</span></dt>
<dt>If the <span>adjusted current node</span> is a <span>MathML text integration point</span> and the token is a start tag whose tag name is neither "mglyph" nor "malignmark"</dt>
<dt>If the <span>adjusted current node</span> is a <span>MathML text integration point</span> and the token is a character token</dt>
<dt>If the <span>adjusted current node</span> is a <span>MathML <code>annotation-xml</code></span> element and the token is a start tag whose tag name is "svg"</dt>
<dt>If the <span>adjusted current node</span> is an <span>HTML integration point</span> and the token is a start tag</dt>
<dt>If the <span>adjusted current node</span> is an <span>HTML integration point</span> and the token is a character token</dt>
<dt>If the token is an end-of-file token</dt>
<dd>Process the token according to the rules given in the section corresponding to the current
<span>insertion mode</span> in HTML content.</dd>
<dt>Otherwise</dt>
<dd>Process the token according to the rules given in the section for parsing tokens <span
data-x="insertion mode: in foreign content">in foreign content</span>.</dd>
</dl>
<p>The <dfn>next token</dfn> is the token that is about to be processed by the <span>tree
construction dispatcher</span> (even if the token is subsequently just ignored).</p>
<p>A node is a <dfn>MathML text integration point</dfn> if it is one of the following
elements:</p>
<ul class="brief">
<li>A <span>MathML <code>mi</code></span> element</li>
<li>A <span>MathML <code>mo</code></span> element</li>
<li>A <span>MathML <code>mn</code></span> element</li>
<li>A <span>MathML <code>ms</code></span> element</li>
<li>A <span>MathML <code>mtext</code></span> element</li>
</ul>
<p>A node is an <dfn>HTML integration point</dfn> if it is one of the following elements:</p>
<ul class="brief">
<li>A <span>MathML <code>annotation-xml</code></span> element whose start tag token had an
attribute with the name "encoding" whose value was an <span>ASCII case-insensitive</span> match
for the string "<code data-x="">text/html</code>"</li>
<li>A <span>MathML <code>annotation-xml</code></span> element whose start tag token had an
attribute with the name "encoding" whose value was an <span>ASCII case-insensitive</span> match
for the string "<code data-x="">application/xhtml+xml</code>"</li>
<li>An <span>SVG <code>foreignObject</code></span> element</li>
<li>An <span>SVG <code>desc</code></span> element</li>
<li>An <span>SVG <code>title</code></span> element</li>
</ul>
<p class="note">If the node in question is the <var
data-x="concept-frag-parse-context">context</var> element passed to the <span>HTML fragment
parsing algorithm</span>, then the start tag token for that element is the "fake" token created
during by that <span>HTML fragment parsing algorithm</span>.</p>
<hr>
<p class="note">Not all of the tag names mentioned below are conformant tag names in this
specification; many are included to handle legacy content. They still form part of the algorithm
that implementations are required to implement to claim conformance.</p>
<p class="note">The algorithm described below places no limit on the depth of the DOM tree
generated, or on the length of tag names, attribute names, attribute values, <code>Text</code>
nodes, etc. While implementers are encouraged to <a
href="https://infra.spec.whatwg.org/#algorithm-limits">avoid arbitrary limits</a>, it is
recognized that practical concerns will likely force user agents to impose nesting depth
constraints.</p>
<h5>Creating and inserting nodes</h5>
<p>While the parser is processing a token, it can enable or disable <dfn data-x="foster
parent">foster parenting</dfn>. This affects the following algorithm.</p>
<p>The <dfn>appropriate place for inserting a node</dfn>, optionally using a particular
<i>override target</i>, is the position in an element returned by running the following steps:</p>
<ol>
<li>
<p>If there was an <i>override target</i> specified, then let <var>target</var> be the
<i>override target</i>.</p>
<p>Otherwise, let <var>target</var> be the <span>current node</span>.</p>
</li>
<li>
<p>Determine the <var>adjusted insertion location</var> using the first matching steps
from the following list:</p>
<dl class="switch">
<dt>If <span data-x="foster parent">foster parenting</span> is enabled and <var>target</var> is a <code>table</code>, <code>tbody</code>, <code>tfoot</code>,
<code>thead</code>, or <code>tr</code> element</dt> <!-- same list as handling of characters
in "in table" mode -->
<dd>
<p class="note">Foster parenting happens when content is misnested in tables.</p>
<p>Run these substeps:</p>
<ol>
<li><p>Let <var>last template</var> be the last <code>template</code> element in the
<span>stack of open elements</span>, if any.</p>
<li><p>Let <var>last table</var> be the last <code>table</code> element in the
<span>stack of open elements</span>, if any.</p>
<li><p>If there is a <var>last template</var> and either there is no <var>last table</var>, or there is one, but <var>last template</var> is lower
(more recently added) than <var>last table</var> in the <span>stack of open
elements</span>, then: let <var>adjusted insertion location</var> be inside <var>last template</var>'s <span>template contents</span>, after its last child (if any),
and abort these steps.</p></li>
<li><p>If there is no <var>last table</var>, <!-- there's also implicitly no last
template, since we didn't hit the previous step --> then let <var>adjusted insertion
location</var> be inside the first element in the <span>stack of open elements</span> (the
<code>html</code> element), after its last child (if any), and abort these steps.
(<span>fragment case</span>)</p>
<!-- if we get here, we know there's a last table, and if there's a last template, it's older
than the last table. -->
<li><p>If <var>last table</var> has a parent node, then let <var>adjusted insertion location</var> be inside <var>last table</var>'s parent
node, immediately before <var>last table</var>, and abort these steps.</p></li>
<!-- if we get here, we know there's a last table, but it has no parent, and if there's a
last template, it's older than the last table. -->
<li><p>Let <var>previous element</var> be the element immediately above <var>last table</var> in the <span>stack of open elements</span>.</p></li>
<li><p>Let <var>adjusted insertion location</var> be inside <var>previous
element</var>, after its last child (if any).</p></li>
</ol>
<p class="note">These steps are involved in part because it's possible for elements, the
<code>table</code> element in this case in particular, to have been moved by a script around
in the DOM, or indeed removed from the DOM entirely, after the element was inserted by the
parser.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>Let <var>adjusted insertion location</var> be inside <var>target</var>,
after its last child (if any).</p>
</dd>
</dl>
</li>
<li>
<p>If the <var>adjusted insertion location</var> is inside a <code>template</code>
element, let it instead be inside the <code>template</code> element's <span>template
contents</span>, after its last child (if any).</p>
</li>
<li>
<p>Return the <var>adjusted insertion location</var>.</p>
</li>
</ol>
<hr>
<p>When the steps below require the UA to <dfn data-x="create an element for the token">create an
element for a token</dfn> in a particular <var>given namespace</var> and with a
particular <var>intended parent</var>, the UA must run the following steps:</p>
<ol>
<li><p>If the <span>active speculative HTML parser</span> is not null, then return the result of
<span data-x="create a speculative mock element">creating a speculative mock element</span>
given <var>given namespace</var>, the tag name of the given token, and the attributes of the
given token.</p></li>
<li>
<p>Otherwise, optionally <span>create a speculative mock element</span> given <var>given
namespace</var>, the tag name of the given token, and the attributes of the given token.</p>
<p class="note">The result is not used. This step allows for a <span>speculative fetch</span> to
be initiated from non-speculative parsing. The fetch is still speculative at this point,
because, for example, by the time the element is inserted, <var>intended parent</var> might
have been removed from the document.</p>
</li>
<li><p>Let <var>document</var> be <var>intended parent</var>'s <span>node document</span>.</li>
<li><p>Let <var>local name</var> be the tag name of the token.</p></li>
<li><p>Let <var>is</var> be the value of the "<code data-x="attr-is">is</code>" attribute in the
given token, if such an attribute exists, or null otherwise.</p></li>
<li><p>Let <var>definition</var> be the result of <span data-x="look up a custom element
definition">looking up a custom element definition</span> given <var>document</var>, <var>given
namespace</var>, <var>local name</var>, and <var>is</var>.</p></li>
<li><p>Let <var>willExecuteScript</var> be true if <var>definition</var> is non-null and the
parser was not created as part of the <span>HTML fragment parsing algorithm</span>; otherwise
false.</p></li>
<li>
<p>If <var>willExecuteScript</var> is true:</p>
<ol>
<li><p>Increment <var>document</var>'s <span>throw-on-dynamic-markup-insertion
counter</span>.</p></li>
<li><p>If the <span>JavaScript execution context stack</span> is empty, then <span>perform a
microtask checkpoint</span>.</p></li>
<li><p>Push a new <span>element queue</span> onto <var>document</var>'s <span>relevant
agent</span>'s <span>custom element reactions stack</span>.</li>
</ol>
</li>
<li>
<p>Let <var>element</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, <var>localName</var>, <var>given namespace</var>,
null, <var>is</var>, and <var>willExecuteScript</var>.</p>
<p class="note">This will cause <span data-x="custom element constructor">custom element
constructors</span> to run, if <var>willExecuteScript</var> is true. However, since we
incremented the <span>throw-on-dynamic-markup-insertion counter</span>, this cannot cause <span
data-x="dom-document-write">new characters to be inserted into the tokenizer</span>, or <span
data-x="dom-document-open">the document to be blown away</span>.</p>
</li>
<li>
<p><span data-x="concept-element-attributes-append">Append</span> each attribute in the given
token to <var>element</var>.</p>
<p class="note">This can <span>enqueue a custom element callback reaction</span> for the
<code data-x="">attributeChangedCallback</code>, which might run immediately (in the next
step).</p>
<p class="note">Even though the <code data-x="attr-is">is</code> attribute governs the <span
data-x="create an element">creation</span> of a <span>customized built-in element</span>, it is
not present during the execution of the relevant <span>custom element constructor</span>; it is
appended in this step, along with all other attributes.</p>
</li>
<li>
<p>If <var>willExecuteScript</var> is true:</p>
<ol>
<li><p>Let <var>queue</var> be the result of popping from <var>document</var>'s <span>relevant
agent</span>'s <span>custom element reactions stack</span>. (This will be the same
<span>element queue</span> as was pushed above.)</p></li>
<li><p><span>Invoke custom element reactions</span> in <var>queue</var>.</p></li>
<li><p>Decrement <var>document</var>'s <span>throw-on-dynamic-markup-insertion
counter</span>.</p></li>
</ol>
</li>
<li><p>If <var>element</var> has an <code data-x="">xmlns</code> attribute <em>in the <span>XMLNS
namespace</span></em> whose value is not exactly the same as the element's namespace, that is a
<span>parse error</span>. Similarly, if <var>element</var> has an <code
data-x="">xmlns:xlink</code> attribute in the <span>XMLNS namespace</span> whose value is not the
<span>XLink Namespace</span>, that is a <span>parse error</span>.</p></li>
<li><p>If <var>element</var> is a <span data-x="category-reset">resettable element</span> and not
a <span>form-associated custom element</span>, then invoke its <span
data-x="concept-form-reset-control">reset algorithm</span>. (This initializes the element's <span
data-x="concept-fe-value">value</span> and <span data-x="concept-fe-checked">checkedness</span>
based on the element's attributes.)</p></li>
<li><p>If <var>element</var> is a <span>form-associated element</span> and not a
<span>form-associated custom element</span>, the
<span><code data-x="">form</code> element pointer</span> is not null, there is no
<code>template</code> element on the <span>stack of open elements</span>, <var>element</var> is
either not <span data-x="category-listed">listed</span> or doesn't have a <code
data-x="attr-fae-form">form</code> attribute, and the <var>intended parent</var> is in the same
<span>tree</span> as the element pointed to by the <span><code data-x="">form</code> element
pointer</span>, then <span data-x="concept-form-association">associate</span> <var>element</var>
with the <code>form</code> element pointed to by the <span><code data-x="">form</code> element
pointer</span> and set <var>element</var>'s <span>parser inserted flag</span>.</p></li>
<li><p>Return <var>element</var>.</p></li>
</ol>
<hr>
<p>To <dfn>insert an element at the adjusted insertion location</dfn> with an element
<var>element</var>:</p>
<ol>
<li><p>Let the <var>adjusted insertion location</var> be the <span>appropriate place for
inserting a node</span>.</p></li>
<li><p>If it is not possible to insert <var>element</var> at the <var>adjusted insertion
location</var>, abort these steps.</p></li>
<li><p>If the parser was not created as part of the <span>HTML fragment parsing
algorithm</span>, then push a new <span>element queue</span> onto <var>element</var>'s
<span>relevant agent</span>'s <span>custom element reactions stack</span>.</p></li>
<li><p>Insert <var>element</var> at the <var>adjusted insertion location</var>.</p></li>
<li><p>If the parser was not created as part of the <span>HTML fragment parsing
algorithm</span>, then pop the <span>element queue</span> from <var>element</var>'s
<span>relevant agent</span>'s <span>custom element reactions stack</span>, and <span>invoke
custom element reactions</span> in that queue.</p></li>
</ol>
<p class="note">If the <var>adjusted insertion location</var> cannot accept more elements, e.g.,
because it's a <code>Document</code> that already has an element child, then <var>element</var> is
dropped on the floor.</p>
<!-- The names of these algorithms are kinda confusing; e.g. see the confusion in
https://www.w3.org/Bugs/Public/show_bug.cgi?id=18367
Not sure what we could call them instead, though... -->
<p>When the steps below require the user agent to <dfn>insert a foreign element</dfn> for a token
in a given namespace and with a boolean <var>onlyAddToElementStack</var>, the user agent must run
these steps:</p>
<ol>
<li><p>Let the <var>adjusted insertion location</var> be the <span>appropriate place for
inserting a node</span>.</p></li>
<!-- this insertion stuff should be cleaned up: https://github.com/whatwg/html/issues/1706 -->
<li><p>Let <var>element</var> be the result of <span data-x="create an element for the
token">creating an element for the token</span> in the given namespace, with the intended
parent being the element in which the <var>adjusted insertion location</var> finds
itself.</p></li>
<li><p>If <var>onlyAddToElementStack</var> is false, then run <span>insert an element at the
adjusted insertion location</span> with <var>element</var>.</p></li>
<li><p>Push <var>element</var> onto the <span>stack of open elements</span> so that it is the new
<span>current node</span>.</p></li>
<li><p>Return <var>element</var>.</p></li>
</ol>
<p>When the steps below require the user agent to <dfn>insert an HTML element</dfn> for a token,
the user agent must <span>insert a foreign element</span> for the token, with the <span>HTML
namespace</span> and false.</p>
<hr>
<p>When the steps below require the user agent to <dfn>adjust MathML attributes</dfn> for a token,
then, if the token has an attribute named <code data-x="">definitionurl</code>, change its name to
<code data-x="">definitionURL</code> (note the case difference).</p>
<p>When the steps below require the user agent to <dfn>adjust SVG attributes</dfn> for a token,
then, for each attribute on the token whose attribute name is one of the ones in the first column
of the following table, change the attribute's name to the name given in the corresponding cell in
the second column. (This fixes the case of SVG attributes that are not all lowercase.)</p>
<table>
<thead>
<tr> <th> Attribute name on token <th> Attribute name on element
<tbody>
<tr> <td> <code data-x="">attributename</code> <td> <code data-x="">attributeName</code>
<tr> <td> <code data-x="">attributetype</code> <td> <code data-x="">attributeType</code>
<tr> <td> <code data-x="">basefrequency</code> <td> <code data-x="">baseFrequency</code>
<tr> <td> <code data-x="">baseprofile</code> <td> <code data-x="">baseProfile</code>
<tr> <td> <code data-x="">calcmode</code> <td> <code data-x="">calcMode</code>
<tr> <td> <code data-x="">clippathunits</code> <td> <code data-x="">clipPathUnits</code>
<tr> <td> <code data-x="">diffuseconstant</code> <td> <code data-x="">diffuseConstant</code>
<tr> <td> <code data-x="">edgemode</code> <td> <code data-x="">edgeMode</code>
<tr> <td> <code data-x="">filterunits</code> <td> <code data-x="">filterUnits</code>
<tr> <td> <code data-x="">glyphref</code> <td> <code data-x="">glyphRef</code>
<tr> <td> <code data-x="">gradienttransform</code> <td> <code data-x="">gradientTransform</code>
<tr> <td> <code data-x="">gradientunits</code> <td> <code data-x="">gradientUnits</code>
<tr> <td> <code data-x="">kernelmatrix</code> <td> <code data-x="">kernelMatrix</code>
<tr> <td> <code data-x="">kernelunitlength</code> <td> <code data-x="">kernelUnitLength</code>
<tr> <td> <code data-x="">keypoints</code> <td> <code data-x="">keyPoints</code>
<tr> <td> <code data-x="">keysplines</code> <td> <code data-x="">keySplines</code>
<tr> <td> <code data-x="">keytimes</code> <td> <code data-x="">keyTimes</code>
<tr> <td> <code data-x="">lengthadjust</code> <td> <code data-x="">lengthAdjust</code>
<tr> <td> <code data-x="">limitingconeangle</code> <td> <code data-x="">limitingConeAngle</code>
<tr> <td> <code data-x="">markerheight</code> <td> <code data-x="">markerHeight</code>
<tr> <td> <code data-x="">markerunits</code> <td> <code data-x="">markerUnits</code>
<tr> <td> <code data-x="">markerwidth</code> <td> <code data-x="">markerWidth</code>
<tr> <td> <code data-x="">maskcontentunits</code> <td> <code data-x="">maskContentUnits</code>
<tr> <td> <code data-x="">maskunits</code> <td> <code data-x="">maskUnits</code>
<tr> <td> <code data-x="">numoctaves</code> <td> <code data-x="">numOctaves</code>
<tr> <td> <code data-x="">pathlength</code> <td> <code data-x="">pathLength</code>
<tr> <td> <code data-x="">patterncontentunits</code> <td> <code data-x="">patternContentUnits</code>
<tr> <td> <code data-x="">patterntransform</code> <td> <code data-x="">patternTransform</code>
<tr> <td> <code data-x="">patternunits</code> <td> <code data-x="">patternUnits</code>
<tr> <td> <code data-x="">pointsatx</code> <td> <code data-x="">pointsAtX</code>
<tr> <td> <code data-x="">pointsaty</code> <td> <code data-x="">pointsAtY</code>
<tr> <td> <code data-x="">pointsatz</code> <td> <code data-x="">pointsAtZ</code>
<tr> <td> <code data-x="">preservealpha</code> <td> <code data-x="">preserveAlpha</code>
<tr> <td> <code data-x="">preserveaspectratio</code> <td> <code data-x="">preserveAspectRatio</code>
<tr> <td> <code data-x="">primitiveunits</code> <td> <code data-x="">primitiveUnits</code>
<tr> <td> <code data-x="">refx</code> <td> <code data-x="">refX</code>
<tr> <td> <code data-x="">refy</code> <td> <code data-x="">refY</code>
<tr> <td> <code data-x="">repeatcount</code> <td> <code data-x="">repeatCount</code>
<tr> <td> <code data-x="">repeatdur</code> <td> <code data-x="">repeatDur</code>
<tr> <td> <code data-x="">requiredextensions</code> <td> <code data-x="">requiredExtensions</code>
<tr> <td> <code data-x="">requiredfeatures</code> <td> <code data-x="">requiredFeatures</code>
<tr> <td> <code data-x="">specularconstant</code> <td> <code data-x="">specularConstant</code>
<tr> <td> <code data-x="">specularexponent</code> <td> <code data-x="">specularExponent</code>
<tr> <td> <code data-x="">spreadmethod</code> <td> <code data-x="">spreadMethod</code>
<tr> <td> <code data-x="">startoffset</code> <td> <code data-x="">startOffset</code>
<tr> <td> <code data-x="">stddeviation</code> <td> <code data-x="">stdDeviation</code>
<tr> <td> <code data-x="">stitchtiles</code> <td> <code data-x="">stitchTiles</code>
<tr> <td> <code data-x="">surfacescale</code> <td> <code data-x="">surfaceScale</code>
<tr> <td> <code data-x="">systemlanguage</code> <td> <code data-x="">systemLanguage</code>
<tr> <td> <code data-x="">tablevalues</code> <td> <code data-x="">tableValues</code>
<tr> <td> <code data-x="">targetx</code> <td> <code data-x="">targetX</code>
<tr> <td> <code data-x="">targety</code> <td> <code data-x="">targetY</code>
<tr> <td> <code data-x="">textlength</code> <td> <code data-x="">textLength</code>
<tr> <td> <code data-x="">viewbox</code> <td> <code data-x="">viewBox</code>
<tr> <td> <code data-x="">viewtarget</code> <td> <code data-x="">viewTarget</code>
<tr> <td> <code data-x="">xchannelselector</code> <td> <code data-x="">xChannelSelector</code>
<tr> <td> <code data-x="">ychannelselector</code> <td> <code data-x="">yChannelSelector</code>
<tr> <td> <code data-x="">zoomandpan</code> <td> <code data-x="">zoomAndPan</code>
</table>
<p>When the steps below require the user agent to <dfn>adjust foreign attributes</dfn> for a
token, then, if any of the attributes on the token match the strings given in the first column of
the following table, let the attribute be a namespaced attribute, with the prefix being the string
given in the corresponding cell in the second column, the local name being the string given in the
corresponding cell in the third column, and the namespace being the namespace given in the
corresponding cell in the fourth column. (This fixes the use of namespaced attributes, in
particular <span data-x="attr-xml-lang"><code data-x="">lang</code> attributes in the <span>XML
namespace</span></span>.)</p>
<table>
<thead>
<tr> <th> Attribute name <th> Prefix <th> Local name <th> Namespace
<tbody>
<tr> <td> <code data-x="">xlink:actuate</code> <td> <code data-x="">xlink</code> <td> <code data-x="">actuate</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:arcrole</code> <td> <code data-x="">xlink</code> <td> <code data-x="">arcrole</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:href</code> <td> <code data-x="">xlink</code> <td> <code data-x="">href</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:role</code> <td> <code data-x="">xlink</code> <td> <code data-x="">role</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:show</code> <td> <code data-x="">xlink</code> <td> <code data-x="">show</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:title</code> <td> <code data-x="">xlink</code> <td> <code data-x="">title</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xlink:type</code> <td> <code data-x="">xlink</code> <td> <code data-x="">type</code> <td> <span>XLink namespace</span>
<tr> <td> <code data-x="">xml:lang</code> <td> <code data-x="">xml</code> <td> <code data-x="">lang</code> <td> <span>XML namespace</span>
<tr> <td> <code data-x="">xml:space</code> <td> <code data-x="">xml</code> <td> <code data-x="">space</code> <td> <span>XML namespace</span>
<tr> <td> <code data-x="">xmlns</code> <td> (none) <td> <code data-x="">xmlns</code> <td> <span>XMLNS namespace</span>
<tr> <td> <code data-x="">xmlns:xlink</code> <td> <code data-x="">xmlns</code> <td> <code data-x="">xlink</code> <td> <span>XMLNS namespace</span>
</table>
<hr>
<p>When the steps below require the user agent to <dfn>insert a character</dfn> while processing a
token, the user agent must run the following steps:</p>
<ol>
<li><p>Let <var>data</var> be the characters passed to the algorithm, or, if no
characters were explicitly specified, the character of the character token being
processed.</p></li>
<li><p>Let the <var>adjusted insertion location</var> be the <span>appropriate
place for inserting a node</span>.</p></li>
<li>
<p>If the <var>adjusted insertion location</var> is in a <code>Document</code> node,
then return.
<p class="note">The DOM will not let <code>Document</code> nodes have <code>Text</code> node
children, so they are dropped on the floor.</p>
</li>
<li>
<p>If there is a <code>Text</code> node immediately before the <var>adjusted insertion
location</var>, then append <var>data</var> to that <code>Text</code> node's <span
data-x="concept-cd-data">data</span>.</p>
<p>Otherwise, create a new <code>Text</code> node whose <span
data-x="concept-cd-data">data</span> is <var>data</var> and
whose <span>node document</span> is the same as that of the
element in which the <var>adjusted insertion location</var> finds itself, and insert
the newly created node at the <var>adjusted insertion location</var>.</p>
</li>
</ol>
<div class="example">
<p>Here are some sample inputs to the parser and the corresponding number of <code>Text</code>
nodes that they result in, assuming a user agent that executes scripts.</p>
<table>
<thead>
<tr>
<th>Input <th>Number of <code>Text</code> nodes
<tbody>
<tr>
<td><pre><code class="html">A<script>
var script = document.getElementsByTagName('script')[0];
document.body.removeChild(script);
</script>B</code></pre>
<td>One <code>Text</code> node in the document, containing "AB".
<tr>
<td><pre><code class="html">A<script>
var text = document.createTextNode('B');
document.body.appendChild(text);
</script>C</code></pre>
<td>Three <code>Text</code> nodes; "A" before the script, the script's contents, and "BC" after the script (the parser appends to the <code>Text</code> node created by the script).
<tr>
<td><pre><code class="html">A<script>
var text = document.getElementsByTagName('script')[0].firstChild;
text.data = 'B';
document.body.appendChild(text);
</script>C</code></pre>
<td>Two adjacent <code>Text</code> nodes in the document, containing "A" and "BC".
<tr>
<td><pre><code class="html">A<table>B<tr>C</tr>D</table></code></pre>
<td>One <code>Text</code> node before the table, containing "ABCD". (This is caused by <span data-x="foster parent">foster parenting</span>.)
<tr>
<td><pre><code class="html">A<table><tr> B</tr> C</table></code></pre>
<td>One <code>Text</code> node before the table, containing "A B C" (A-space-B-space-C). (This is caused by <span data-x="foster parent">foster parenting</span>.)
<tr>
<td><pre><code class="html">A<table><tr> B</tr> </em>C</table></code></pre>
<td>One <code>Text</code> node before the table, containing "A BC" (A-space-B-C), and one <code>Text</code> node inside the table (as a child of a <code>tbody</code>) with a single space character. (Space characters separated from non-space characters by non-character tokens are not affected by <span data-x="foster parent">foster parenting</span>, even if those other tokens then get ignored.)
</table>
</div>
<hr>
<p>When the steps below require the user agent to <dfn>insert a comment</dfn> while processing a
comment token, optionally with an explicit insertion position <var>position</var>, the
user agent must run the following steps:</p>
<ol>
<li><p>Let <var>data</var> be the data given in the comment token being
processed.</p></li>
<li><p>If <var>position</var> was specified, then let the <var>adjusted
insertion location</var> be <var>position</var>. Otherwise, let <var>adjusted
insertion location</var> be the <span>appropriate place for inserting a node</span>.</p></li>
<li><p>Create a <code>Comment</code> node whose <code data-x="">data</code> attribute is set to
<var>data</var> and whose <span>node document</span> is
the same as that of the node in which the <var>adjusted insertion location</var> finds
itself.</p>
<li><p>Insert the newly created node at the <var>adjusted insertion
location</var>.</p></li>
</ol>
<h5>Parsing elements that contain only text</h5>
<p>The <dfn>generic raw text element parsing algorithm</dfn> and the <dfn>generic RCDATA element
parsing algorithm</dfn> consist of the following steps. These algorithms are always invoked in
response to a start tag token.</p>
<ol>
<li><p><span>Insert an HTML element</span> for the token.</p></li>
<li><p>If the algorithm that was invoked is the <span>generic raw text element parsing
algorithm</span>, switch the tokenizer to the <span>RAWTEXT state</span>; otherwise the algorithm
invoked was the <span>generic RCDATA element parsing algorithm</span>, switch the tokenizer to
the <span>RCDATA state</span>.</p></li>
<li><p>Let the <span>original insertion mode</span> be the current <span>insertion
mode</span>.</p>
<li><p>Then, switch the <span>insertion mode</span> to "<span data-x="insertion mode:
text">text</span>".</p></li>
</ol>
<h5>Closing elements that have implied end tags</h5>
<p>When the steps below require the UA to <dfn>generate implied end tags</dfn>, then, while the
<span>current node</span> is a <code>dd</code> element, a <code>dt</code> element, an
<code>li</code> element, an <code>optgroup</code> element, an <code>option</code> element, a
<code>p</code> element, an <code>rb</code> element, an <code>rp</code> element, an <code>rt</code>
element, or an <code>rtc</code> element, the UA must pop the <span>current node</span> off the
<span>stack of open elements</span>.</p>
<p>If a step requires the UA to generate implied end tags but lists an element to exclude from the
process, then the UA must perform the above steps as if that element was not in the above
list.</p>
<p>When the steps below require the UA to <dfn>generate all implied end tags thoroughly</dfn>,
then, while the <span>current node</span> is a <code>caption</code> element, a
<code>colgroup</code> element, a <code>dd</code> element, a <code>dt</code> element, an
<code>li</code> element, an <code>optgroup</code> element, an <code>option</code> element, a
<code>p</code> element, an <code>rb</code> element, an <code>rp</code> element, an <code>rt</code>
element, an <code>rtc</code> element, a <code>tbody</code> element, a <code>td</code> element, a
<code>tfoot</code> element, a <code>th</code> element, a <code>thead</code> element, or a
<code>tr</code> element, the UA must pop the <span>current node</span> off the
<span>stack of open elements</span>.</p>
<h5 id="parsing-main-inhtml">The rules for parsing tokens in HTML content</h5>
<h6>The "<dfn data-x="insertion mode: initial">initial</dfn>" insertion mode</h6>
<p>A <code>Document</code> object has an associated <dfn>parser cannot change the mode flag</dfn>
(a boolean). It is initially false.</p>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode:
initial">initial</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER
TABULATION, U+000A LINE FEED (LF), U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p>Ignore the token.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span> as the last child of the <code>Document</code> object.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p>If the DOCTYPE token's name is not "<code data-x="">html</code>", or the token's public
identifier is not missing, or the token's system identifier is neither missing nor
"<code>about:legacy-compat</code>", then there is a <span>parse error</span>.</p>
<p>Append a <code>DocumentType</code> node to the <code>Document</code> node, with its <span
data-x="concept-doctype-name">name</span> set to the name given in the DOCTYPE token, or the
empty string if the name was missing; its <span data-x="concept-doctype-publicid">public
ID</span> set to the public identifier given in the DOCTYPE token, or the empty string if the
public identifier was missing; and its <span data-x="concept-doctype-systemid">system ID</span>
set to the system identifier given in the DOCTYPE token, or the empty string if the system
identifier was missing.</p>
<p class="note">This also ensures that the <code>DocumentType</code> node is returned as the
value of the <code data-x="dom-Document-doctype">doctype</code> attribute of the
<code>Document</code> object.</p>
<p id="quirks-mode-doctypes">Then, if the document is <em>not</em> <span>an <code>iframe</code>
<code data-x="attr-iframe-srcdoc">srcdoc</code> document</span>, and the <span>parser cannot
change the mode flag</span> is false, and the DOCTYPE token matches one of the conditions in the
following list, then set the <code>Document</code> to <span>quirks mode</span>:</p>
<ul class="brief">
<li> The <i data-x="force-quirks flag">force-quirks flag</i> is set to <i>on</i>. </li>
<li> The name is not "<code data-x="">html</code>". </li>
<li> The public identifier is set to: "<code data-x="">-//W3O//DTD W3 HTML Strict 3.0//EN//</code>" </li>
<li> The public identifier is set to: "<code data-x="">-/W3C/DTD HTML 4.0 Transitional/EN</code>" </li>
<li> The public identifier is set to: "<code data-x="">HTML</code>" </li>
<li> The system identifier is set to: "<code data-x="">http://www.ibm.com/data/dtd/v11/ibmxhtml1-transitional.dtd</code>" </li>
<li> The public identifier starts with: "<code data-x="">+//Silmaril//dtd html Pro v0r11 19970101//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//AS//DTD HTML 3.0 asWedit + extensions//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//AdvaSoft Ltd//DTD HTML 3.0 asWedit + extensions//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0 Level 1//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0 Level 2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0 Strict Level 1//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0 Strict Level 2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0 Strict//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 2.1E//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 3.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 3.2 Final//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 3.2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML 3//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Level 0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Level 1//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Level 2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Level 3//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Strict Level 0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Strict Level 1//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Strict Level 2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Strict Level 3//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML Strict//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//IETF//DTD HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Metrius//DTD Metrius Presentational//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 2.0 HTML Strict//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 2.0 HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 2.0 Tables//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 3.0 HTML Strict//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 3.0 HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Microsoft//DTD Internet Explorer 3.0 Tables//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Netscape Comm. Corp.//DTD HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Netscape Comm. Corp.//DTD Strict HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//O'Reilly and Associates//DTD HTML 2.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//O'Reilly and Associates//DTD HTML Extended 1.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//O'Reilly and Associates//DTD HTML Extended Relaxed 1.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//SQ//DTD HTML 2.0 HoTMetaL + extensions//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//SoftQuad Software//DTD HoTMetaL PRO 6.0::19990601::extensions to HTML 4.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//SoftQuad//DTD HoTMetaL PRO 4.0::19971010::extensions to HTML 4.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Spyglass//DTD HTML 2.0 Extended//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Sun Microsystems Corp.//DTD HotJava HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//Sun Microsystems Corp.//DTD HotJava Strict HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 3 1995-03-24//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 3.2 Draft//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 3.2 Final//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 3.2//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 3.2S Draft//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.0 Frameset//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.0 Transitional//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML Experimental 19960712//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD HTML Experimental 970421//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD W3 HTML//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3O//DTD W3 HTML 3.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//WebTechs//DTD Mozilla HTML 2.0//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//WebTechs//DTD Mozilla HTML//</code>" </li>
<li> The system identifier is missing and the public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.01 Frameset//</code>" </li>
<li> The system identifier is missing and the public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.01 Transitional//</code>" </li>
</ul>
<p>Otherwise, if the document is <em>not</em> <span>an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span>, and the <span>parser cannot change
the mode flag</span> is false, and the DOCTYPE token matches one of the conditions in the
following list, then set the <code>Document</code> to <span>limited-quirks mode</span>:</p>
<ul class="brief">
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD XHTML 1.0 Frameset//</code>" </li>
<li> The public identifier starts with: "<code data-x="">-//W3C//DTD XHTML 1.0 Transitional//</code>" </li>
<li> The system identifier is not missing and the public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.01 Frameset//</code>" </li>
<li> The system identifier is not missing and the public identifier starts with: "<code data-x="">-//W3C//DTD HTML 4.01 Transitional//</code>" </li>
</ul>
<p>The system identifier and public identifier strings must be compared to the values given in
the lists above in an <span>ASCII case-insensitive</span> manner. A system identifier whose
value is the empty string is not considered missing for the purposes of the conditions
above.</p>
<p>Then, switch the <span>insertion mode</span> to "<span data-x="insertion mode: before
html">before html</span>".</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>If the document is <em>not</em> <span>an <code>iframe</code> <code
data-x="attr-iframe-srcdoc">srcdoc</code> document</span>, then this is a <span>parse
error</span>; if the <span>parser cannot change the mode flag</span> is false, set the
<code>Document</code> to <span>quirks mode</span>.</p>
<p>In any case, switch the <span>insertion mode</span> to "<span data-x="insertion mode: before
html">before html</span>", then reprocess the token.</p>
</dd>
</dl>
<h6>The "<dfn data-x="insertion mode: before html">before html</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: before
html">before html</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span> as the last child of the <code>Document</code> object.</p>
</dd>
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p>Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p><span>Create an element for the token</span> in the <span>HTML namespace</span>, with the
<code>Document</code> as the intended parent. Append it to the <code>Document</code> object. Put
this element in the <span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: before head">before
head</span>".</p>
</dd>
<dt>An end tag whose tag name is one of: "head", "body", "html", "br"</dt>
<dd>
<p>Act as described in the "anything else" entry below.</p>
</dd>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Create an <code>html</code> element whose <span>node document</span> is the <code>Document</code> object. Append
it to the <code>Document</code> object. Put this element in the <span>stack of open
elements</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: before head">before
head</span>", then reprocess the token.</p>
</dd>
</dl>
<p>The <span>document element</span> can end up being removed from the <code>Document</code>
object, e.g. by scripts; nothing in particular happens in such cases, content continues being
appended to the nodes as described in the next section.</p>
<h6>The "<dfn data-x="insertion mode: before head">before head</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: before
head">before head</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER
TABULATION, U+000A LINE FEED (LF), U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p>Ignore the token.</p> <!-- :-( -->
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "head"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Set the <span><code data-x="">head</code> element pointer</span> to the newly created
<code>head</code> element.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head">in
head</span>".</p>
</dd>
<dt>An end tag whose tag name is one of: "head", "body", "html", "br"</dt>
<dd>
<p>Act as described in the "anything else" entry below.</p>
</dd>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- fake <head> -->
<p><span>Insert an HTML element</span> for a "head" start tag token with no attributes.</p>
<p>Set the <span><code data-x="">head</code> element pointer</span> to the newly created
<code>head</code> element.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head">in
head</span>".</p>
<!-- end of fake <head> -->
<p>Reprocess the current token.</p>
</dd>
</dl>
<h6 id="parsing-main-inhead">The "<dfn data-x="insertion mode: in head">in head</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in head">in
head</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER
TABULATION, U+000A LINE FEED (LF), U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is one of: "base", "basefont",
"bgsound", "link"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
</dd>
<dt>A start tag whose tag name is "meta"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
<p>If the <span>active speculative HTML parser</span> is null, then:</p>
<ol>
<li><p id="meta-charset-during-parse">If the element has a <code
data-x="attr-meta-charset">charset</code> attribute, and <span>getting an encoding</span> from
its value results in an <span>encoding</span>, and the
<span data-x="concept-encoding-confidence">confidence</span> is currently <i>tentative</i>,
then <span>change the encoding</span> to the resulting encoding.</p></li>
<li><p>Otherwise, if the element has an <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">Content-Type</code>", and the element has a <code
data-x="attr-meta-content">content</code> attribute, and applying the <span>algorithm for
extracting a character encoding from a <code>meta</code> element</span> to that attribute's
value returns an <span>encoding</span>, and the
<span data-x="concept-encoding-confidence">confidence</span> is currently <i>tentative</i>,
then <span>change the encoding</span> to the extracted encoding.</p></li>
</ol>
<p class="note">The <span>speculative HTML parser</span> doesn't speculatively apply character
encoding declarations in order to reduce implementation complexity.</p>
</dd>
<dt>A start tag whose tag name is "title"</dt>
<dd>
<p>Follow the <span>generic RCDATA element parsing algorithm</span>.</p>
</dd>
<dt>A start tag whose tag name is "noscript", if the <span>scripting flag</span> is enabled</dt>
<dt>A start tag whose tag name is one of: "noframes", "style"</dt>
<dd>
<p>Follow the <span>generic raw text element parsing algorithm</span>.</p>
</dd>
<dt>A start tag whose tag name is "noscript", if the <span>scripting flag</span> is disabled</dt>
<dd>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head noscript">in
head noscript</span>".</p>
</dd>
<dt id="scriptTag">A start tag whose tag name is "script"</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p>Let the <var>adjusted insertion location</var> be the <span>appropriate place
for inserting a node</span>.</p></li>
<li><p><span>Create an element for the token</span> in the <span>HTML namespace</span>, with
the intended parent being the element in which the <var>adjusted insertion
location</var> finds itself.</p></li>
<li>
<p>Set the element's <span>parser document</span> to the <code>Document</code>, and set the
element's <span data-x="script-force-async">force async</span> to false.</p>
<p class="note">This ensures that, if the script is external, any <code
data-x="dom-document-write">document.write()</code> calls in the script will execute in-line,
instead of blowing the document away, as would happen in most other cases. It also prevents
the script from executing until the end tag is seen.</p>
</li>
<li><p>If the parser was created as part of the <span>HTML fragment parsing algorithm</span>,
then set the <code>script</code> element's <span>already started</span> to true.
(<span>fragment case</span>)</p></li>
<li id="document-written-scripts-intervention"><p>If the parser was invoked via the <code
data-x="dom-document-write">document.write()</code> or <code
data-x="dom-document-writeln">document.writeln()</code> methods, then optionally set the
<code>script</code> element's <span>already started</span> to true. (For example, the user
agent might use this clause to prevent execution of <span data-x="origin">cross-origin</span>
scripts inserted via <code data-x="dom-document-write">document.write()</code> under slow
network conditions, or when the page has already taken a long time to load.)</p></li>
<li><p>Insert the newly created element at the <var>adjusted insertion
location</var>.</p></li>
<li><p>Push the element onto the <span>stack of open elements</span> so that it is the new
<span>current node</span>.</p></li>
<li><p>Switch the tokenizer to the <span>script data state</span>.</p></li>
<li><p>Let the <span>original insertion mode</span> be the current <span>insertion
mode</span>.</p>
<li><p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode:
text">text</span>".</p></li>
</ol>
</dd>
<dt>An end tag whose tag name is "head"</dt>
<dd>
<p>Pop the <span>current node</span> (which will be the <code>head</code> element) off the
<span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: after head">after
head</span>".</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "html", "br"</dt>
<dd>
<p>Act as described in the "anything else" entry below.</p>
</dd>
<dt>A start tag whose tag name is "template"</dt>
<dd>
<p>Let <var>template start tag</var> be the start tag.</p>
<p>Insert a <span data-x="concept-parser-marker">marker</span> at the end of the <span>list of
active formatting elements</span>.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in template">in
template</span>".</p>
<p>Push "<span data-x="insertion mode: in template">in template</span>" onto the <span>stack of
template insertion modes</span> so that it is the new <span>current template insertion
mode</span>.</p>
<p>Let the <var>adjusted insertion location</var> be the <span>appropriate place for inserting
a node</span>.</p>
<p>Let <var>intended parent</var> be the element in which the <var>adjusted insertion
location</var> finds itself.</p>
<p>Let <var>document</var> be <var>intended parent</var>'s <span>node document</span>.</p>
<p>If any of the following are false:</p>
<ul>
<li><var>template start tag</var>'s
<code data-x="attr-template-shadowrootmode">shadowrootmode</code> is not in
the <span data-x="attr-shadowrootmode-none-state">none</span> state;</li>
<li><var>document</var>'s <span data-x="concept-document-allow-declarative-shadow-roots">allow
declarative shadow roots</span> is true; or</li>
<li>the <span>adjusted current node</span> is not the topmost element in the <span>stack of
open elements</span>,</li>
</ul>
<p>then <span>insert an HTML element</span> for the token.</p>
<p>Otherwise:</p>
<ol>
<li><p>Let <var>declarative shadow host element</var> be <span>adjusted current
node</span>.</p></li>
<li><p>Let <var>template</var> be the result of <span>insert a foreign element</span>
for <var>template start tag</var>, with <span>HTML namespace</span> and true.</p></li>
<li><p>Let <var>mode</var> be <var>template start tag</var>'s <code
data-x="attr-template-shadowrootmode">shadowrootmode</code> attribute's value.</p></li>
<li><p>Let <var>clonable</var> be true if <var>template start tag</var> has a <code
data-x="attr-template-shadowrootclonable">shadowrootclonable</code> attribute; otherwise
false.</p></li>
<li><p>Let <var>serializable</var> be true if <var>template start tag</var> has a <code
data-x="attr-template-shadowrootserializable">shadowrootserializable</code> attribute;
otherwise false.</p></li>
<li><p>Let <var>delegatesFocus</var> be true if <var>template start tag</var> has a <code
data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code> attribute;
otherwise false.</p></li>
<li><p>If <var>declarative shadow host element</var> is a <span>shadow host</span>, then
<span>insert an element at the adjusted insertion location</span> with
<var>template</var>.</p></li>
<li>
<p>Otherwise:
<ol>
<li>
<p><span data-x="concept-attach-a-shadow-root">Attach a shadow root</span> with
<var>declarative shadow host element</var>, <var>mode</var>, <var>clonable</var>,
<var>serializable</var>, <var>delegatesFocus</var>, and "<code data-x="">named</code>".</p>
<p>If an exception is thrown, then catch it and:</p>
<ol>
<li><p><span>Insert an element at the adjusted insertion location</span> with
<var>template</var>.</p></li>
<li><p>The user agent may report an error to the developer console.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p>Let <var>shadow</var> be <var>declarative shadow host element</var>'s
<span data-x="concept-element-shadow-root">shadow root</span>.</p></li>
<li><p>Set <var>shadow</var>'s
<span data-x="concept-shadow-root-declarative">declarative</span> to true.</p></li>
<li><p>Set <span>template</span>'s <span>template contents</span> property to
<var>shadow</var>.</p></li>
<li><p>Set <var>shadow</var>'s <span>available to element internals</span> to true.</p></li>
</ol>
</li>
</ol>
</dd>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>If there is no <code>template</code> element on the <span>stack of open elements</span>, then
this is a <span>parse error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate all implied end tags thoroughly</span>.</p></li>
<li><p>If the <span>current node</span> is not a <code>template</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>template</code>
element has been popped from the stack.</p></li>
<li><span>Clear the list of active formatting elements up to the last marker</span>.</li>
<li><p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<li><p><span>Reset the insertion mode appropriately</span>.</p></li>
</ol>
</dd>
<dt>A start tag whose tag name is "head"</dt>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- can't get here with an EOF and a fragment case -->
<!-- start of fake </head> -->
<p>Pop the <span>current node</span> (which will be the <code>head</code> element) off the
<span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: after head">after
head</span>".</p>
<!-- end of fake </head> -->
<p>Reprocess the token.</p>
</dd>
</dl>
<h6 id="parsing-main-inheadnoscript">The "<dfn data-x="insertion mode: in head noscript">in head noscript</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in head
noscript">in head noscript</span>" <span>insertion mode</span>, the user agent must handle the
token as follows:</p>
<dl class="switch">
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end tag whose tag name is "noscript"</dt>
<dd>
<p>Pop the <span>current node</span> (which will be a <code>noscript</code> element) from the
<span>stack of open elements</span>; the new <span>current node</span> will be a
<code>head</code> element.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head">in
head</span>".</p>
</dd>
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dt>A comment token</dt>
<dt>A start tag whose tag name is one of: "basefont", "bgsound", "link", "meta", "noframes",
"style"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end tag whose tag name is "br"</dt>
<dd>
<p>Act as described in the "anything else" entry below.</p>
</dd>
<dt>A start tag whose tag name is one of: "head", "noscript"</dt>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- can't get here with an EOF and a fragment case -->
<p><span>Parse error</span>.</p>
<!-- fake </noscript> -->
<p>Pop the <span>current node</span> (which will be a <code>noscript</code> element) from the
<span>stack of open elements</span>; the new <span>current node</span> will be a
<code>head</code> element.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in head">in
head</span>".</p>
<!-- end fake </noscript> -->
<p>Reprocess the token.</p>
</dd>
</dl>
<h6>The "<dfn data-x="insertion mode: after head">after head</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: after
head">after head</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER
TABULATION, U+000A LINE FEED (LF), U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "body"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in body">in
body</span>".</p>
</dd>
<dt>A start tag whose tag name is "frameset"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in frameset">in
frameset</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "base", "basefont", "bgsound", "link", "meta",
"noframes", "script", "style", "template", "title"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>Push the node pointed to by the <span><code data-x="">head</code> element pointer</span> onto
the <span>stack of open elements</span>.</p>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
<p>Remove the node pointed to by the <span><code data-x="">head</code> element pointer</span>
from the <span>stack of open elements</span>. (It might not be the <span>current node</span> at
this point.)</p>
<p class="note">The <span><code data-x="">head</code> element pointer</span> cannot be null at
this point.</p>
</dd>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "html", "br"</dt>
<dd>
<p>Act as described in the "anything else" entry below.</p>
</dd>
<dt>A start tag whose tag name is "head"</dt>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- fake <body>, but without resetting frameset-ok -->
<p><span>Insert an HTML element</span> for a "body" start tag token with no attributes.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in body">in
body</span>".</p>
<!-- end fake <body> -->
<p>Reprocess the current token.</p>
</dd>
</dl>
<h6 id="parsing-main-inbody">The "<dfn data-x="insertion mode: in body">in body</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in body">in
body</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is U+0000 NULL</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
<!-- The D-Link DSL-G604T ADSL router has a zero byte in its
configuration UI before a <frameset>, which is why U+0000 is
special-cased here.
refs: https://bugzilla.mozilla.org/show_bug.cgi?id=563526
https://www.w3.org/Bugs/Public/show_bug.cgi?id=9659
-->
</dd>
<dt>A character token that is one of U+0009 CHARACTER TABULATION,
U+000A LINE FEED (LF), U+000C FORM FEED (FF), U+000D CARRIAGE
RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
</dd>
<dt>Any other character token</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>If there is a <code>template</code> element on the <span>stack of open elements</span>, then
ignore the token.</p>
<p>Otherwise, for each attribute on the token, check to see if the attribute is already present
on the top element of the <span>stack of open elements</span>. If it is not, add the attribute
and its corresponding value to that element.</p>
</dd>
<dt>A start tag whose tag name is one of: "base", "basefont", "bgsound", "link", "meta",
"noframes", "script", "style", "template", "title"</dt>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "body"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>If the <span>stack of open elements</span> has only one node on it, if the second element
on the <span>stack of open elements</span> is not a <code>body</code> element, or if there is a
<code>template</code> element on the <span>stack of open elements</span>, then ignore the token.
(<span>fragment case</span> or there is a <code>template</code> element on the stack)</p>
<p>Otherwise, set the <span>frameset-ok flag</span> to "not ok"; then, for each attribute on the
token, check to see if the attribute is already present on the <code>body</code> element (the
second element) on the <span>stack of open elements</span>, and if it is not, add the attribute
and its corresponding value to that element.</p>
</dd>
<dt>A start tag whose tag name is "frameset"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>If the <span>stack of open elements</span> has only one node on it, or if the second element
on the <span>stack of open elements</span> is not a <code>body</code> element, then ignore the
token. (<span>fragment case</span> or there is a <code>template</code> element on the
stack)</p>
<p>If the <span>frameset-ok flag</span> is set to "not ok", ignore the token.</p>
<p>Otherwise, run the following steps:</p>
<ol>
<li><p>Remove the second element on the <span>stack of open elements</span> from its parent
node, if it has one.</p></li>
<li><p>Pop all the nodes from the bottom of the <span>stack of open elements</span>, from the
<span>current node</span> up to, but not including, the root <code>html</code> element.</p>
<li><p><span>Insert an HTML element</span> for the token.</p></li>
<li><p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in frameset">in
frameset</span>".</p>
</ol>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p>If the <span>stack of template insertion modes</span> is not empty, then process the token
<span>using the rules for</span> the "<span data-x="insertion mode: in template">in
template</span>" <span>insertion mode</span>.</p>
<!-- this is needed to handle <head><template>...[EOF] - otherwise we don't construct the <body> element -->
<p>Otherwise, follow these steps:</p>
<ol>
<li><p>If there is a node in the <span>stack of open elements</span> that is not either a
<code>dd</code> element, a <code>dt</code> element, an <code>li</code> element, an
<code>optgroup</code> element, an <code>option</code> element, a <code>p</code> element, an
<code>rb</code> element, an <code>rp</code> element, an <code>rt</code> element, an
<code>rtc</code> element, a <code>tbody</code> element, a <code>td</code> element, a
<code>tfoot</code> element, a <code>th</code> element, a <code>thead</code> element, a
<code>tr</code> element, the <code>body</code> element, or the <code>html</code> element, then
this is a <span>parse error</span>.</p></li> <!-- (some of those are fragment cases) -->
<li><p><span>Stop parsing</span>.</p></li>
</ol>
</dd>
<dt>An end tag whose tag name is "body"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have a <code>body</code> element in scope</span>, this is a <span>parse error</span>;
ignore the token.</p>
<!-- if we get here, the insertion mode here is forcibly "in body". -->
<p>Otherwise, if there is a node in the <span>stack of open elements</span> that is not either a
<code>dd</code> element, a <code>dt</code> element, an <code>li</code> element, an
<code>optgroup</code> element, an <code>option</code> element, a <code>p</code> element, an
<code>rb</code> element, an <code>rp</code> element, an <code>rt</code> element, an
<code>rtc</code> element, a <code>tbody</code> element, a <code>td</code> element, a
<code>tfoot</code> element, a <code>th</code> element, a <code>thead</code> element, a
<code>tr</code> element, the <code>body</code> element, or the <code>html</code> element, then
this is a <span>parse error</span>.</p> <!-- (some of those are fragment cases, e.g., for
<tbody> you'd have hit the first paragraph since the <body> wouldn't be in scope, unless it was
a fragment case) -->
<!-- If we ever change the frameset-ok flag to an insertion mode, then we'd have to somehow keep
track of its state when we switch to after-body. -->
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: after body">after
body</span>".</p>
</dd>
<dt>An end tag whose tag name is "html"</dt>
<dd>
<!-- fake </body> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have a <code>body</code> element in scope</span>, this is a <span>parse error</span>;
ignore the token.</p>
<!-- if we get here, the insertion mode here is forcibly "in body". -->
<p>Otherwise, if there is a node in the <span>stack of open elements</span> that is not either a
<code>dd</code> element, a <code>dt</code> element, an <code>li</code> element, an
<code>optgroup</code> element, an <code>option</code> element, a <code>p</code> element, an
<code>rb</code> element, an <code>rp</code> element, an <code>rt</code> element, an
<code>rtc</code> element, a <code>tbody</code> element, a <code>td</code> element, a
<code>tfoot</code> element, a <code>th</code> element, a <code>thead</code> element, a
<code>tr</code> element, the <code>body</code> element, or the <code>html</code> element, then
this is a <span>parse error</span>.</p> <!-- (some of those are fragment cases, e.g., for
<tbody> you'd have hit the first paragraph since the <body> wouldn't be in scope, unless it was
a fragment case) -->
<!-- If we ever change the frameset-ok flag to an insertion mode, then we'd have to somehow keep
track of its state when we switch to after-body. -->
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: after body">after
body</span>".</p>
<!-- end fake </body> -->
<p>Reprocess the token.</p>
</dd>
<!-- start tags for non-phrasing flow content elements -->
<!-- the normal ones -->
<dt>A start tag whose tag name is one of: "address", "article", "aside", "blockquote", "center",
"details", "dialog", "dir", "div", "dl", "fieldset", "figcaption", "figure", "footer", "header",
"hgroup", "main", "menu", "nav", "ol", "p", "search", "section", "summary", "ul"</dt>
<dd>
<!-- As of May 2008 this doesn't match any browser exactly, but is as close to what IE does as I
can get without doing the non-tree DOM nonsense, and thus should actually afford better
compatibility when implemented by the other browsers. -->
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<!-- as normal, but close h1-h6 if it's the current node -->
<dt>A start tag whose tag name is one of: "h1", "h2", "h3", "h4",
"h5", "h6"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p>If the <span>current node</span> is an <span data-x="HTML elements">HTML element</span> whose
tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is a <span>parse
error</span>; pop the <span>current node</span> off the <span>stack of open elements</span>.</p>
<!-- See https://bugs.webkit.org/show_bug.cgi?id=12646 -->
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<!-- as normal, but drops leading newline -->
<dt>A start tag whose tag name is one of: "pre", "listing"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has
a <code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p>If the <span>next token</span> is a U+000A LINE FEED (LF) character token, then ignore that
token and move on to the next one. (Newlines at the start of <code>pre</code> blocks are ignored
as an authoring convenience.)</p>
<!-- <pre>[CR]X will eat the [CR], <pre>X will eat the
, but <pre>X will not eat the . -->
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<!-- as normal, but interacts with the form element pointer -->
<dt>A start tag whose tag name is "form"</dt>
<dd>
<p>If the <span><code data-x="form">form</code> element pointer</span> is not null, and there is
no <code>template</code> element on the <span>stack of open elements</span>, then this is a
<span>parse error</span>; ignore the token.</p>
<p>Otherwise:</p>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has
a <code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Insert an HTML element</span> for the token, and, if there is no <code>template</code>
element on the <span>stack of open elements</span>, set the <span><code
data-x="form">form</code> element pointer</span> to point to the element created.</p>
</dd>
<!-- as normal, but imply </li> when there's another <li> open in weird cases -->
<dt>A start tag whose tag name is "li"</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p>Set the <span>frameset-ok flag</span> to "not ok".</p></li>
<li><p>Initialize <var>node</var> to be the <span>current
node</span> (the bottommost node of the stack).</p></li>
<li>
<p><i>Loop</i>: If <var>node</var> is an <code>li</code> element, then run these
substeps:</p>
<ol>
<!-- fake </li> -->
<li><p><span>Generate implied end tags</span>, except for <code>li</code> elements.</p></li>
<li><p>If the <span>current node</span> is not an <code>li</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <code>li</code>
element has been popped from the stack.</p></li>
<!-- end of fake </li> -->
<li><p>Jump to the step labeled <i>done</i> below.</p></li>
</ol>
</li>
<li><p>If <var>node</var> is in the <span>special</span> category, but is not an
<code>address</code>, <code>div</code>, or <code>p</code> element, then jump to the step
labeled <i>done</i> below.</p></li>
<!-- an element <foo> is in this list if the following markup:
<!DOCTYPE html><body><ol><li><foo><li>
...results in the second <li> not being (in any way) a descendant of the first <li>, or if
<foo> is a formatting element that gets reopened later. -->
<li><p>Otherwise, set <var>node</var> to the previous entry in the <span>stack of open
elements</span> and return to the step labeled <i>loop</i>.</p></li>
<li><p><i>Done</i>: If the <span>stack of open elements</span> <span data-x="has an element in
button scope">has a <code>p</code> element in button scope</span>, then <span>close a
<code>p</code> element</span>.</p></li>
<li><p>Finally, <span>insert an HTML element</span> for the token.</p></li>
</ol>
</dd>
<!-- as normal, but imply </dt> or </dd> when there's another <dt> or <dd> open in weird cases -->
<dt>A start tag whose tag name is one of: "dd", "dt"</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p>Set the <span>frameset-ok flag</span> to "not ok".</p></li>
<li><p>Initialize <var>node</var> to be the <span>current
node</span> (the bottommost node of the stack).</p></li>
<li>
<p><i>Loop</i>: If <var>node</var> is a <code>dd</code> element, then run these
substeps:</p>
<ol>
<!-- fake </dd> -->
<li><p><span>Generate implied end tags</span>, except for <code>dd</code> elements.</p></li>
<li><p>If the <span>current node</span> is not a <code>dd</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>dd</code>
element has been popped from the stack.</p></li>
<!-- end of fake </dd> -->
<li><p>Jump to the step labeled <i>done</i> below.</p></li>
</ol>
</li>
<li>
<p>If <var>node</var> is a <code>dt</code> element, then run these substeps:</p>
<ol>
<!-- fake </dt> -->
<li><p><span>Generate implied end tags</span>, except for <code>dt</code> elements.</p></li>
<li><p>If the <span>current node</span> is not a <code>dt</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>dt</code>
element has been popped from the stack.</p></li>
<!-- end of fake </dt> -->
<li><p>Jump to the step labeled <i>done</i> below.</p></li>
</ol>
</li>
<li><p>If <var>node</var> is in the <span>special</span> category, but is not an
<code>address</code>, <code>div</code>, or <code>p</code> element, then jump to the step
labeled <i>done</i> below.</p></li>
<!-- an element <foo> is in this list if the following markup:
<!DOCTYPE html><body><dl><dt><foo><dt>
...results in the second <dt> not being (in any way) a descendant of the first <dt>, or if
<foo> is a formatting element that gets reopened later. -->
<li><p>Otherwise, set <var>node</var> to the previous entry in the <span>stack of open
elements</span> and return to the step labeled <i>loop</i>.</p></li>
<li><p><i>Done</i>: If the <span>stack of open elements</span> <span data-x="has an element in
button scope">has a <code>p</code> element in button scope</span>, then <span>close a
<code>p</code> element</span>.</p></li>
<li><p>Finally, <span>insert an HTML element</span> for the token.</p></li>
</ol>
</dd>
<!-- same as normal, but effectively ends parsing -->
<dt>A start tag whose tag name is "plaintext"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Switch the tokenizer to the <span>PLAINTEXT state</span>.</p>
<p class="note">Once a start tag with the tag name "plaintext" has been seen, all remaining
tokens will be character tokens (and a final end-of-file token) because there is no way to
switch the tokenizer out of the <span>PLAINTEXT state</span>. However, as the tree builder
remains in its existing insertion mode, it might <span>reconstruct the active formatting
elements</span> while processing those character tokens. This means that the parser can
insert other elements into the <code>plaintext</code> element.</p>
</dd>
<!-- button is a hybrid -->
<dt>A start tag whose tag name is "button"</dt>
<dd>
<ol>
<li>
<p>If the <span>stack of open elements</span> <span data-x="has an element in scope">has a
<code>button</code> element in scope</span>, then run these substeps:</p>
<ol>
<li><p><span>Parse error</span>.</p></li>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>button</code>
element has been popped from the stack.</p></li>
</ol>
</li>
<li><p><span>Reconstruct the active formatting elements</span>, if any.</p></li>
<li><p><span>Insert an HTML element</span> for the token.</p></li>
<li><p>Set the <span>frameset-ok flag</span> to "not ok".</p></li>
</ol>
</dd>
<!-- end tags for non-phrasing flow content elements (and button) -->
<!-- the normal ones -->
<dt>An end tag whose tag name is one of: "address", "article", "aside", "blockquote", "button",
"center", "details", "dialog", "dir", "div", "dl", "fieldset", "figcaption", "figure", "footer",
"header", "hgroup", "listing", "main", "menu", "nav", "ol", "pre", "search", "section",
"summary", "ul"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have an element in scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not an <span data-x="HTML elements">HTML element</span> with
the same tag name as that of the token, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <span data-x="HTML
elements">HTML element</span> with the same tag name as the token has been popped from the
stack.</p></li>
</ol>
</dd>
<!-- removes the form element pointer instead of the matching node -->
<dt>An end tag whose tag name is "form"</dt>
<dd>
<p>If there is no <code>template</code> element on the <span>stack of open elements</span>, then
run these substeps:</p>
<ol>
<li><p>Let <var>node</var> be the element that the <span><code data-x="">form</code>
element pointer</span> is set to, or null if it is not set to an element.</p></li>
<li><p>Set the <span><code data-x="">form</code> element pointer</span> to null.</p></li>
<li><p>If <var>node</var> is null or if the <span>stack of open elements</span> does
not <span data-x="has an element in scope">have <var>node</var> in scope</span>, then
this is a <span>parse error</span>; return and ignore the token.</p></li>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not <var>node</var>, then this is a
<span>parse error</span>.</p></li>
<li><p>Remove <var>node</var> from the <span>stack of open elements</span>.</p></li>
</ol>
<p>If there <em>is</em> a <code>template</code> element on the <span>stack of open
elements</span>, then run these substeps instead:</p>
<ol>
<li><p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have a <code>form</code> element in scope</span>, then this is a <span>parse
error</span>; return and ignore the token.</p></li>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not a <code>form</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>form</code>
element has been popped from the stack.</p></li>
</ol>
</dd>
<!-- as normal, except </p> implies <p> if there's no <p> in scope, and needs care as the elements have optional tags -->
<dt>An end tag whose tag name is "p"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in button
scope">have a <code>p</code> element in button scope</span>, then this is a <span>parse
error</span>; <span>insert an HTML element</span> for a "p" start tag token with no
attributes.</p>
<p><span>Close a <code>p</code> element</span>.</p>
</dd>
<!-- as normal, but needs care as the elements have optional tags, and are further scoped by <ol>/<ul> -->
<dt>An end tag whose tag name is "li"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in list item
scope">have an <code>li</code> element in list item scope</span>, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate implied end tags</span>, except for <code>li</code> elements.</p></li>
<li><p>If the <span>current node</span> is not an <code>li</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <code>li</code>
element has been popped from the stack.</p></li>
</ol>
</dd>
<!-- as normal, but needs care as the elements have optional tags -->
<dt>An end tag whose tag name is one of: "dd", "dt"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have an element in scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate implied end tags</span>, except for <span>HTML elements</span> with the
same tag name as the token.</p></li>
<li><p>If the <span>current node</span> is not an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <span data-x="HTML
elements">HTML element</span> with the same tag name as the token has been popped from the
stack.</p></li>
</ol>
</dd>
<!-- as normal, except acts as a closer for any of the h1-h6 elements -->
<dt>An end tag whose tag name is one of: "h1", "h2", "h3", "h4", "h5", "h6"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have an element in scope</span> that is an <span data-x="HTML elements">HTML
element</span> and whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is
a <span>parse error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <span data-x="HTML
elements">HTML element</span> whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6"
has been popped from the stack.</p></li>
</ol>
</dd>
<!-- see also applet/marquee/object lower down -->
<dt>An end tag whose tag name is "sarcasm"</dt>
<dd>
<p>Take a deep breath, then act as described in the "any other end
tag" entry below.</p>
</dd>
<!-- ADOPTION AGENCY ELEMENTS
Mozilla-only: bdo blink del ins sub sup q
Safari-only: code dfn kbd nobr samp var wbr
Both: a b big em font i s small strike strong tt u -->
<dt>A start tag whose tag name is "a"</dt>
<dd>
<p>If the <span>list of active formatting elements</span> contains an <code>a</code> element
between the end of the list and the last <span data-x="concept-parser-marker">marker</span> on
the list (or the start of the list if there is no <span
data-x="concept-parser-marker">marker</span> on the list), then this is a <span>parse
error</span>; run the <span>adoption agency algorithm</span> for the token, then remove that
element from the <span>list of active formatting elements</span> and the <span>stack of open
elements</span> if the <span>adoption agency algorithm</span> didn't already remove it (it might
not have if the element is not <span data-x="has an element in table scope">in table
scope</span>).</p>
<p class="example">In the non-conforming stream
<code data-x=""><a href="a">a<table><a href="b">b</table>x</code>, the first
<code>a</code> element would be closed upon seeing the second one, and the "x" character would
be inside a link to "b", not to "a". This is despite the fact that the outer <code>a</code>
element is not in table scope (meaning that a regular <code data-x=""></a></code> end tag at the start
of the table wouldn't close the outer <code>a</code> element). The result is that the two
<code>a</code> elements are indirectly nested inside each other — non-conforming markup
will often result in non-conforming DOMs when parsed.</p>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token. <span>Push onto the list of active
formatting elements</span> that element.</p>
</dd>
<dt>A start tag whose tag name is one of: "b", "big", "code", "em",
"font", "i", "s", "small", "strike", "strong", "tt", "u"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token. <span>Push onto the list of active
formatting elements</span> that element.</p>
</dd>
<dt>A start tag whose tag name is "nobr"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p>If the <span>stack of open elements</span> <span data-x="has an element in scope">has a
<code>nobr</code> element in scope</span>, then this is a <span>parse error</span>; run the
<span>adoption agency algorithm</span> for the token, then once again <span>reconstruct the
active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token. <span>Push onto the list of active
formatting elements</span> that element.</p>
</dd>
<dt>An end tag whose tag name is one of: "a",
"b", "big", "code", "em", "font", "i", "nobr", "s", "small",
"strike", "strong", "tt", "u"</dt>
<dd>
<p>Run the <span>adoption agency algorithm</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "applet", "marquee", "object"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Insert a <span data-x="concept-parser-marker">marker</span> at the end of the <span>list of
active formatting elements</span>.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<dt>An end tag token whose tag name is one of: "applet", "marquee", "object"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in
scope">have an element in scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise, run these steps:</p>
<ol>
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until an <span data-x="HTML
elements">HTML element</span> with the same tag name as the token has been popped from the
stack.</p></li>
<li><span>Clear the list of active formatting elements up to the last marker</span>.</li>
</ol>
</dd>
<dt>A start tag whose tag name is "table"</dt>
<dd>
<p>If the <code>Document</code> is <em>not</em> set to <span>quirks mode</span>, and the
<span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p> <!-- i hate myself (this quirk was basically caused by acid2; if i'd
realized we could change the specs when i wrote acid2, we could have avoided having any
parsing-mode quirks) -Hixie -->
<p><span>Insert an HTML element</span> for the token.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>".</p>
</dd>
<dt>An end tag whose tag name is "br"</dt>
<dd>
<p><span>Parse error</span>. Drop the attributes from the token, and act as described in the
next entry; i.e. act as if this was a "br" start tag token with no attributes, rather than the
end tag token that it actually is.</p>
</dd>
<!-- do not insert things here, since the previous entry refers to the next entry -->
<dt>A start tag whose tag name is one of: "area", "br", "embed",
"img", "keygen", "wbr"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<!-- shouldn't really do this for <area> -->
</dd>
<dt>A start tag whose tag name is "input"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
<p>If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">hidden</code>", then: set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<dt>A start tag whose tag name is one of: "param", "source", "track"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
</dd>
<dt>A start tag whose tag name is "hr"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<dt>A start tag whose tag name is "image"</dt>
<dd>
<!-- As of 2005-12, studies showed that around 0.2% of pages used the <image> element. -->
<p><span>Parse error</span>. Change the token's tag name to "img" and reprocess it. (Don't
ask.)</p>
</dd>
<dt>A start tag whose tag name is "textarea"</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p><span>Insert an HTML element</span> for the token.</p></li>
<li><p>If the <span>next token</span> is a U+000A LINE FEED (LF) character token, then ignore
that token and move on to the next one. (Newlines at the start of <code>textarea</code>
elements are ignored as an authoring convenience.)</p></li>
<!-- see comment in <pre> start tag bit -->
<li><p>Switch the tokenizer to the <span>RCDATA state</span>.</p></li>
<li><p>Let the <span>original insertion mode</span> be the current <span>insertion
mode</span>.</p>
<li><p>Set the <span>frameset-ok flag</span> to "not ok".</p></li>
<li><p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode:
text">text</span>".</p></li>
</ol>
</dd>
<dt>A start tag whose tag name is "xmp"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in button scope">has a
<code>p</code> element in button scope</span>, then <span>close a <code>p</code>
element</span>.</p>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>Follow the <span>generic raw text element parsing algorithm</span>.</p>
</dd>
<dt>A start tag whose tag name is "iframe"</dt>
<dd>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>Follow the <span>generic raw text element parsing algorithm</span>.</p>
</dd>
<dt>A start tag whose tag name is "noembed"</dt>
<dt>A start tag whose tag name is "noscript", if the <span>scripting flag</span> is enabled</dt>
<dd>
<p>Follow the <span>generic raw text element parsing algorithm</span>.</p>
</dd>
<dt>A start tag whose tag name is "select"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
<p>If the <span>insertion mode</span> is one of "<span data-x="insertion mode: in table">in
table</span>", "<span data-x="insertion mode: in caption">in caption</span>", "<span
data-x="insertion mode: in table body">in table body</span>", "<span data-x="insertion mode: in
row">in row</span>", or "<span data-x="insertion mode: in cell">in cell</span>", then switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in select in table">in select in
table</span>". Otherwise, switch the <span>insertion mode</span> to "<span data-x="insertion
mode: in select">in select</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "optgroup", "option"</dt>
<dd>
<p>If the <span>current node</span> is an <code>option</code> element, then pop the
<span>current node</span> off the <span>stack of open elements</span>.</p>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "rb", "rtc"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in scope">has a
<code>ruby</code> element in scope</span>, then <span>generate implied end tags</span>. If the
<span>current node</span> is not now a <code>ruby</code> element, this is a
<span>parse error</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "rp", "rt"</dt>
<dd>
<p>If the <span>stack of open elements</span> <span data-x="has an element in scope">has a
<code>ruby</code> element in scope</span>, then <span>generate implied end tags</span>, except
for <code>rtc</code> elements. If the <span>current node</span> is not now a <code>rtc</code>
element or a <code>ruby</code> element, this is a <span>parse error</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is "math"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Adjust MathML attributes</span> for the token. (This fixes the case of MathML
attributes that are not all lowercase.)</p>
<p><span>Adjust foreign attributes</span> for the token. (This fixes the use of namespaced
attributes, in particular XLink.)</p>
<p><span>Insert a foreign element</span> for the token, with <span>MathML namespace</span>
and false.</p>
<!-- If we ever change the frameset-ok flag to an insertion mode, the following change would be
implied, except we'd have to do it even in the face of a self-closed tag:
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
-->
<p>If the token has its <i data-x="self-closing flag">self-closing flag</i> set, pop the <span>current node</span> off the
<span>stack of open elements</span> and <span data-x="acknowledge self-closing flag">acknowledge
the token's <i data-x="self-closing flag">self-closing flag</i></span>.</p>
</dd>
<dt>A start tag whose tag name is "svg"</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Adjust SVG attributes</span> for the token. (This fixes the case of SVG attributes that
are not all lowercase.)</p>
<p><span>Adjust foreign attributes</span> for the token. (This fixes the use of namespaced
attributes, in particular XLink in SVG.)</p>
<p><span>Insert a foreign element</span> for the token, with <span>SVG namespace</span>
and false.</p>
<!-- If we ever change the frameset-ok flag to an insertion mode, the following change would be
implied, except we'd have to do it even in the face of a self-closed tag:
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
-->
<p>If the token has its <i data-x="self-closing flag">self-closing flag</i> set, pop the <span>current node</span> off the
<span>stack of open elements</span> and <span data-x="acknowledge self-closing flag">acknowledge
the token's <i data-x="self-closing flag">self-closing flag</i></span>.</p>
</dd>
<dt>A start <!--or end--> tag whose tag name is one of: "caption", "col", "colgroup", "frame",
"head", "tbody", "td", "tfoot", "th", "thead", "tr"</dt>
<!--<dt>An end tag whose tag name is one of: "area", "base", "basefont", "bgsound", "embed",
"hr", "iframe", "image", "img", "input", "keygen", "link", "meta", "noembed", "noframes",
"param", "script", "select", "source", "style", "table", "textarea", "title", "track",
"wbr"</dt>-->
<!--<dt>An end tag whose tag name is "noscript", if the <span>scripting flag</span> is
enabled</dt>-->
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
<!-- end tags are commented out because since they can never end up on the stack anyway, the
default end tag clause will automatically handle them. we don't want to have text in the spec
that is just an optimization, as that detracts from the spec itself -->
</dd>
<dt>Any other start tag</dt>
<dd>
<p><span>Reconstruct the active formatting elements</span>, if any.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p class="note">This element will be an <span>ordinary</span> element. With one exception: if
the <span>scripting flag</span> is disabled, it can also be a <code>noscript</code> element.</p>
</dd>
<dt>Any other end tag</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p>Initialize <var>node</var> to be the <span>current node</span> (the bottommost
node of the stack).</p></li>
<li><p><i>Loop</i>: If <var>node</var> is an <span data-x="HTML elements">HTML
element</span> with the same tag name as the token, then:</p>
<ol>
<li><p><span>Generate implied end tags</span>, except for <span>HTML elements</span> with the
same tag name as the token.</p></li>
<li><p>If <var>node</var> is not the <span>current node</span>, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop all the nodes from the <span>current node</span> up to <var>node</var>,
including <var>node</var>, then stop these steps.</p></li>
</ol>
</li>
<li><p>Otherwise, if <var>node</var> is in the <span>special</span> category, then
this is a <span>parse error</span>; ignore the token, and return.</p></li>
<li><p>Set <var>node</var> to the previous entry in the <span>stack of open
elements</span>.</p></li>
<li><p>Return to the step labeled <i>loop</i>.</p></li>
</ol>
</dd>
</dl>
<p>When the steps above say the user agent is to <dfn>close a <code>p</code> element</dfn>, it
means that the user agent must run the following steps:</p>
<ol> <!-- prereq: p in scope -->
<li><p><span>Generate implied end tags</span>, except for <code>p</code> elements.</p></li>
<li><p>If the <span>current node</span> is not a <code>p</code> element, then this is a
<span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>p</code> element
has been popped from the stack.</p></li>
</ol>
<!-- AAA -->
<p id="adoptionAgency">The <dfn>adoption agency algorithm</dfn>, which takes as its only argument
a token <var>token</var> for which the algorithm is being run, consists of the following
steps:</p>
<ol>
<!-- don't forget about the noah's ark clause when looking at this algorithm! -->
<li><p>Let <var>subject</var> be <var>token</var>'s tag name.</p></li>
<li><p>If the <span>current node</span> is an <span data-x="HTML elements">HTML element</span>
whose tag name is <var>subject</var>, and the <span>current node</span> is not in the
<span>list of active formatting elements</span>, then pop the <span>current node</span> off the
<span>stack of open elements</span> and return.</p></li>
<li><p>Let <var>outerLoopCounter</var> be 0.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>If <var>outerLoopCounter</var> is greater than or equal to 8, then return.</p></li>
<li><p>Increment <var>outerLoopCounter</var> by 1.</p></li>
<li>
<p>Let <var>formattingElement</var> be the last element in the <span>list of active
formatting elements</span> that:</p>
<ul>
<li>is between the end of the list and the last <span
data-x="concept-parser-marker">marker</span> in the list, if any, or the start of the list
otherwise, and</li>
<li>has the tag name <var>subject</var>.</li>
</ul>
<p>If there is no such element, then return and instead act as described in the "any other end
tag" entry above.</p>
</li>
<li><p>If <var>formattingElement</var> is not in the <span>stack of open elements</span>, then
this is a <span>parse error</span>; remove the element from the list, and return.</p></li>
<li><p>If <var>formattingElement</var> is in the <span>stack of open elements</span>, but the
element is not <span data-x="has an element in scope">in scope</span>, then this is a
<span>parse error</span>; return.</p></li>
<!-- at this point, <var>formattingElement</var> is in <span data-x="stack of open
elements">the stack</span> and <span data-x="list of active formatting elements">the
list</span>, and is <span data-x="has an element in scope">in scope</span>. -->
<li><p>If <var>formattingElement</var> is not the <span>current node</span>, this is a
<span>parse error</span>. (But do not return.)</p></li>
<li><p>Let <var>furthestBlock</var> be the topmost node in the <span>stack of open
elements</span> that is lower in the stack than <var>formattingElement</var>, and is an
element in the <span>special</span> category. There might not be one.</p></li>
<!-- <html> ... <formattingElement> ... <furthestBlock> ... <currentNode> -->
<li><p>If there is no <var>furthestBlock</var>, then the UA must first pop all the nodes from
the bottom of the <span>stack of open elements</span>, from the <span>current node</span> up to
and including <var>formattingElement</var>, then remove <var>formattingElement</var> from the
<span>list of active formatting elements</span>, and finally return.</p></li>
<!-- the "reconstruct the active formatting elements" algorithm will rebuild them later -->
<li><p>Let <var>commonAncestor</var> be the element immediately above
<var>formattingElement</var> in the <span>stack of open elements</span>.</p></li>
<!-- <html> ... <commonAncestor> <formattingElement> ... <furthestBlock> ... <currentNode> -->
<li><p>Let a bookmark note the position of <var>formattingElement</var> in the <span>list of
active formatting elements</span> relative to the elements on either side of it in the
list.</p></li>
<li><p>Let <var>node</var> and <var>lastNode</var> be <var>furthestBlock</var>.</p></li>
<li><p>Let <var>innerLoopCounter</var> be 0.</p></li>
<li>
<p>While true:</p>
<ol>
<li><p>Increment <var>innerLoopCounter</var> by 1.</p></li>
<li><p>Let <var>node</var> be the element immediately above <var>node</var> in the
<span>stack of open elements</span>, or if <var>node</var> is no longer in the <span>stack of
open elements</span> (e.g. because it got removed by this algorithm<!-- in particular, the
step labeled "removal" below -->), the element that was immediately above <var>node</var> in
the <span>stack of open elements</span> before <var>node</var> was removed.</p></li>
<li><p>If <var>node</var> is <var>formattingElement</var>, then <span>break</span>.</p></li>
<li><p>If <var>innerLoopCounter</var> is greater than 3 and <var>node</var> is in the
<span>list of active formatting elements</span>, then remove <var>node</var> from the
<span>list of active formatting elements</span>.</p></li>
<li><p><!-- "removal" step: -->If <var>node</var> is not in the <span>list of active
formatting elements</span>, then remove <var>node</var> from the <span>stack of open
elements</span> and <span>continue</span>.</p></li>
<li><p><span>Create an element for the token</span> for which the element <var>node</var> was
created, in the <span>HTML namespace</span>, with <var>commonAncestor</var> as the intended
parent; replace the entry for <var>node</var> in the <span>list of active formatting
elements</span> with an entry for the new element, replace the entry for <var>node</var> in
the <span>stack of open elements</span> with an entry for the new element, and let
<var>node</var> be the new element.</p></li>
<li><p>If <var>lastNode</var> is <var>furthestBlock</var>, then move the aforementioned
bookmark to be immediately after the new <var>node</var> in the <span>list of active
formatting elements</span>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>lastNode</var> to
<var>node</var>.</p></li>
<li><p>Set <var>lastNode</var> to <var>node</var>.</p></li>
</ol>
</li>
<li><p>Insert whatever <var>lastNode</var> ended up being in the previous step at the
<span>appropriate place for inserting a node</span>, but using <var>commonAncestor</var>
as the <i>override target</i>.</p></li>
<li><p><span>Create an element for the token</span> for which <var>formattingElement</var> was created,
in the <span>HTML namespace</span>, with <var>furthestBlock</var> as the intended parent.</p></li>
<li><p>Take all of the child nodes of <var>furthestBlock</var> and append them to the
element created in the last step.</p></li>
<li><p>Append that new element to <var>furthestBlock</var>.</p></li>
<li><p>Remove <var>formattingElement</var> from the <span>list of active formatting
elements</span>, and insert the new element into the <span>list of active formatting
elements</span> at the position of the aforementioned bookmark.</p></li>
<li><p>Remove <var>formattingElement</var> from the <span>stack of open
elements</span>, and insert the new element into the <span>stack of open elements</span>
immediately below the position of <var>furthestBlock</var> in that stack.</p></li>
</ol>
</li>
</ol>
<p class="note">This algorithm's name, the "adoption agency algorithm", comes from the way it
causes elements to change parents, and is in contrast with <a
href="https://ln.hixie.ch/?start=1037910467&count=1">other possible algorithms</a> for dealing
with misnested content.</p>
<h6 id="parsing-main-incdata">The "<dfn data-x="insertion mode: text">text</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode:
text">text</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A character token</dt>
<dd>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
<p class="note">This can never be a U+0000 NULL character; the tokenizer converts those to
U+FFFD REPLACEMENT CHARACTER characters.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<!-- can't be the fragment case -->
<p><span>Parse error</span>.</p>
<p>If the <span>current node</span> is a <code>script</code> element, then set its <span>already
started</span> to true.</p>
<p>Pop the <span>current node</span> off the <span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to the <span>original insertion mode</span> and
reprocess the token.</p>
</dd>
<dt id="scriptEndTag">An end tag whose tag name is "script"</dt>
<dd>
<p>If the <span>active speculative HTML parser</span> is null and the <span>JavaScript execution
context stack</span> is empty, then <span>perform a microtask checkpoint</span>.</p>
<p>Let <var>script</var> be the <span>current node</span> (which will be a
<code>script</code> element).</p>
<p>Pop the <span>current node</span> off the <span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to the <span>original insertion mode</span>.</p>
<p>Let the <var>old insertion point</var> have the same value as the current
<span>insertion point</span>. Let the <span>insertion point</span> be just before the <span>next
input character</span>.</p>
<p>Increment the parser's <span>script nesting level</span> by one.</p>
<p>If the <span>active speculative HTML parser</span> is null, then <span>prepare the script
element</span> <var>script</var>. This might cause some script to execute, which might cause
<span data-x="dom-document-write">new characters to be inserted into the tokenizer</span>, and
might cause the tokenizer to output more tokens, resulting in a <a
href="#nestedParsing">reentrant invocation of the parser</a>.</p>
<p>Decrement the parser's <span>script nesting level</span> by one. If the parser's <span>script
nesting level</span> is zero, then set the <span>parser pause flag</span> to false.</p>
<p>Let the <span>insertion point</span> have the value of the <var>old insertion
point</var>. (In other words, restore the <span>insertion point</span> to its previous value.
This value might be the "undefined" value.)</p>
<p id="scriptTagParserResumes">At this stage, if the <span>pending parsing-blocking
script</span> is not null, then:</p>
<dl class="switch">
<dt>If the <span>script nesting level</span> is not zero:</dt>
<dd>
<p>Set the <span>parser pause flag</span> to true, and abort the processing of any nested
invocations of the tokenizer, yielding control back to the caller. (Tokenization will resume
when the caller returns to the "outer" tree construction stage.)</p>
<p class="note">The tree construction stage of this particular parser is <a
href="#nestedParsing">being called reentrantly</a>, say from a call to <code
data-x="dom-document-write">document.write()</code>.</p>
</dd>
<dt>Otherwise:</dt>
<dd>
<p>While the <span>pending parsing-blocking script</span> is not null:</p>
<ol>
<li><p>Let <var>the script</var> be the <span>pending parsing-blocking
script</span>.</p></li>
<li><p>Set the <span>pending parsing-blocking script</span> to null.</p></li>
<li><p><span>Start the speculative HTML parser</span> for this instance of the HTML
parser.</p></li>
<li><p>Block the <span data-x="tokenization">tokenizer</span> for this instance of the
<span>HTML parser</span>, such that the <span>event loop</span> will not run <span
data-x="concept-task">tasks</span> that invoke the <span
data-x="tokenization">tokenizer</span>.</p></li>
<li><p>If the parser's <code>Document</code> <span>has a style sheet that is blocking
scripts</span> or <var>the script</var>'s <span>ready to be parser-executed</span> is false:
<span>spin the event loop</span> until the parser's <code>Document</code> <span>has no style
sheet that is blocking scripts</span> and <var>the script</var>'s <span>ready to be
parser-executed</span> becomes true.</p></li>
<li>
<p>If this <span data-x="abort a parser">parser has been aborted</span> in the meantime,
return.</p>
<p class="note">This could happen if, e.g., while the <span>spin the event loop</span>
algorithm is running, the <code>Document</code> gets <span data-x="destroy a
document">destroyed</span>, or the <code data-x="dom-document-open">document.open()</code>
method gets invoked on the <code>Document</code>.</p>
</li>
<li><p><span>Stop the speculative HTML parser</span> for this instance of the HTML
parser.</p></li>
<li><p>Unblock the <span data-x="tokenization">tokenizer</span> for this instance of the
<span>HTML parser</span>, such that <span data-x="concept-task">tasks</span> that invoke the
<span data-x="tokenization">tokenizer</span> can again be run.</p></li>
<li><p>Let the <span>insertion point</span> be just before the <span>next input
character</span>.</p></li>
<li><p>Increment the parser's <span>script nesting level</span> by one (it should be zero
before this step, so this sets it to one).</p></li>
<li><p><span>Execute the script element</span> <var>the script</var>.</p></li>
<li><p>Decrement the parser's <span>script nesting level</span> by one. If the parser's
<span>script nesting level</span> is zero (which it always should be at this point), then set
the <span>parser pause flag</span> to false.</p>
<li><p>Let the <span>insertion point</span> be undefined again.</p></li>
</ol>
</dd>
</dl>
</dd>
<dt>Any other end tag</dt>
<dd>
<p>Pop the <span>current node</span> off the <span>stack of open elements</span>.</p>
<p>Switch the <span>insertion mode</span> to the <span>original insertion mode</span>.</p>
</dd>
</dl>
<h6 id="parsing-main-intable">The "<dfn data-x="insertion mode: in table">in table</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in table">in
table</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token, if the <span>current node</span> is <code>table</code>, <code>tbody</code>, <code>template</code>, <code>tfoot</code>, <code>thead</code>, or <code>tr</code> element</dt> <!-- same list as foster parenting + template -->
<dd>
<p>Let the <dfn><var data-x="concept-pending-table-char-tokens">pending table character
tokens</var></dfn> be an empty list of tokens.</p>
<p>Let the <span>original insertion mode</span> be the current <span>insertion mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table text">in
table text</span>" and reprocess the token.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "caption"</dt>
<dd>
<p><span>Clear the stack back to a table context</span>. (See below.)</p>
<p>Insert a <span data-x="concept-parser-marker">marker</span> at the end of the <span>list of
active formatting elements</span>.</p>
<p><span>Insert an HTML element</span> for the token, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in caption">in caption</span>".</p>
</dd>
<dt>A start tag whose tag name is "colgroup"</dt>
<dd>
<p><span>Clear the stack back to a table context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for the token, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in column group">in column group</span>".</p>
</dd>
<dt>A start tag whose tag name is "col"</dt>
<dd>
<!-- fake <colgroup> -->
<p><span>Clear the stack back to a table context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for a "colgroup" start tag token with no attributes, then
switch the <span>insertion mode</span> to "<span data-x="insertion mode: in column group">in
column group</span>".</p>
<!-- end of fake <colgroup> -->
<p>Reprocess the current token.</p>
</dd>
<dt>A start tag whose tag name is one of: "tbody", "tfoot", "thead"</dt>
<dd>
<p><span>Clear the stack back to a table context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for the token, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in table body">in table body</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "td", "th", "tr"</dt>
<dd>
<!-- fake <colgroup> -->
<p><span>Clear the stack back to a table context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for a "tbody" start tag token with no attributes, then
switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table body">in table
body</span>".</p>
<!-- end of fake <colgroup> -->
<p>Reprocess the current token.</p>
</dd>
<dt>A start tag whose tag name is "table"</dt>
<dd>
<p><span>Parse error</span>.</p>
<!-- fake </table> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>table</code> element in table scope</span>, ignore the token.</p>
<p>Otherwise:</p>
<p>Pop elements from this stack until a <code>table</code> element has been popped from the
stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </table> -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is "table"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>table</code> element in table scope</span>, this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise:</p>
<p>Pop elements from this stack until a <code>table</code> element has been popped from the
stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "caption", "col", "colgroup", "html", "tbody",
"td", "tfoot", "th", "thead", "tr"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "style", "script", "template"</dt>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span
data-x="insertion mode: in head">in head</span>" <span>insertion
mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "input"</dt>
<dd>
<p>If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">hidden</code>", then: act as described in the "anything else" entry below.</p>
<p>Otherwise:</p>
<p><span>Parse error</span>.</p>
<p><span>Insert an HTML element</span> for the token.</p>
<p>Pop that <code>input</code> element off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
</dd>
<dt>A start tag whose tag name is "form"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>If there is a <code>template</code> element on the <span>stack of open elements</span>, or if
the <span><code data-x="form">form</code> element pointer</span> is not null, ignore the
token.</p> <!-- in a <template>, the <form> would have no effect and thus be a waste of time... -->
<p>Otherwise:</p>
<p><span>Insert an HTML element</span> for the token, and set the <span><code
data-x="form">form</code> element pointer</span> to point to the element created.</p>
<p>Pop that <code>form</code> element off the <span>stack of open elements</span>.</p>
</dd>
<!-- "form" end tag falls through to in-body, which does the right thing -->
<dt>An end-of-file token</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Enable <span data-x="foster parent">foster parenting</span>, process
the token <span>using the rules for</span> the "<span data-x="insertion mode: in body">in
body</span>" <span>insertion mode</span>, and then disable <span data-x="foster parent">foster
parenting</span>.</p>
</dd>
</dl>
<p>When the steps above require the UA to <dfn>clear the stack back to a table context</dfn>, it
means that the UA must, while the <span>current node</span> is not a <code>table</code>,
<code>template</code>, or <code>html</code> element, pop elements from the <span>stack of open
elements</span>.</p>
<p class="note">This is the same list of elements as used in the <i data-x="has an element in
table scope">has an element in table scope</i> steps.</p>
<p class="note">The <span>current node</span> being an <code>html</code> element after this
process is a <span>fragment case</span>.</p>
<h6 id="parsing-main-intabletext">The "<dfn data-x="insertion mode: in table text">in table text</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in table
text">in table text</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A character token that is U+0000 NULL</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Any other character token</dt>
<dd>
<p>Append the character token to the <var data-x="concept-pending-table-char-tokens">pending
table character tokens</var> list.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- this can only be called if the current node is one of the table model elements -->
<p>If any of the tokens in the <var data-x="concept-pending-table-char-tokens">pending table
character tokens</var> list are character tokens that are not <span>ASCII whitespace</span>,
then this is a <span>parse error</span>: reprocess the character tokens in the <var
data-x="concept-pending-table-char-tokens">pending table character tokens</var> list using the
rules given in the "anything else" entry in the "<span data-x="insertion mode: in table">in
table</span>" insertion mode.</p>
<!-- if there's active formatting elements, it'll recreate those and foster parent the top one
and then put the text nodes in the formatting elements; otherwise, it'll foster parent the
character tokens. -->
<p>Otherwise, <span data-x="insert a character">insert the characters</span> given by the <var
data-x="concept-pending-table-char-tokens">pending table character tokens</var> list.</p> <!--
i.e. inter-element whitespace in the table model isn't foster parented -->
<!-- no need to empty the list, we're leaving the insertion mode and the list is always emptied
before we reenter the mode -->
<p>Switch the <span>insertion mode</span> to the <span>original insertion mode</span> and
reprocess the token.</p>
</dd>
</dl>
<h6 id="parsing-main-incaption">The "<dfn data-x="insertion mode: in caption">in caption</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in caption">in
caption</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>An end tag whose tag name is "caption"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>caption</code> element in table scope</span>, this is a <span>parse
error</span>; ignore the token. (<span>fragment case</span>)</p>
<p>Otherwise:</p>
<p><span>Generate implied end tags</span>.</p>
<p>Now, if the <span>current node</span> is not a <code>caption</code> element, then this is a
<span>parse error</span>.</p>
<p>Pop elements from this stack until a <code>caption</code> element has been popped from the
stack.</p>
<p><span>Clear the list of active formatting elements up to the last marker</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "caption", "col", "colgroup", "tbody", "td", "tfoot",
"th", "thead", "tr"</dt> <dt>An end tag whose tag name is "table"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>caption</code> element in table scope</span>, this is a <span>parse
error</span>; ignore the token. (<span>fragment case</span>)</p>
<p>Otherwise:</p>
<!-- fake </caption> -->
<p><span>Generate implied end tags</span>.</p>
<p>Now, if the <span>current node</span> is not a <code>caption</code> element, then this is a
<span>parse error</span>.</p>
<p>Pop elements from this stack until a <code>caption</code> element has been popped from the
stack.</p>
<p><span>Clear the list of active formatting elements up to the last marker</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>".</p>
<!-- end of fake </caption> -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "col", "colgroup", "html", "tbody", "td",
"tfoot", "th", "thead", "tr"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
</dl>
<h6 id="parsing-main-incolgroup">The "<dfn data-x="insertion mode: in column group">in column group</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in column
group">in column group</span>" <span>insertion mode</span>, the user agent must handle the token
as follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "col"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
</dd>
<dt>An end tag whose tag name is "colgroup"</dt>
<dd>
<p>If the <span>current node</span> is not a <code>colgroup</code> element, then this is a
<span>parse error</span>; ignore the token.</p> <!-- e.g. colgroup fragment case, or
<template><col></colgroup> -->
<p>Otherwise, pop the <span>current node</span> from the <span>stack of open elements</span>.
Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>".</p>
</dd>
<dt>An end tag whose tag name is "col"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "template"</dt>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<!-- fake </colgroup> -->
<p>If the <span>current node</span> is not a <code>colgroup</code> element, then this is a
<span>parse error</span>; ignore the token.</p> <!-- e.g. colgroup fragment case, or
<template><col></colgroup> -->
<p>Otherwise, pop the <span>current node</span> from the <span>stack of open
elements</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>".</p>
<!-- end of fake </colgroup> -->
<p>Reprocess the token.</p>
</dd>
</dl>
<h6 id="parsing-main-intbody">The "<dfn data-x="insertion mode: in table body">in table body</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in table
body">in table body</span>" <span>insertion mode</span>, the user agent must handle the token as
follows:</p>
<dl class="switch">
<dt>A start tag whose tag name is "tr"</dt>
<dd>
<p><span>Clear the stack back to a table body context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for the token, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in row">in row</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "th", "td"</dt>
<dd>
<p><span>Parse error</span>.</p>
<!-- fake </tr> -->
<p><span>Clear the stack back to a table body context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for a "tr" start tag token with no attributes, then
switch the <span>insertion mode</span> to "<span data-x="insertion mode: in row">in
row</span>".</p>
<!-- end of fake </tr> -->
<p>Reprocess the current token.</p>
</dd>
<dt>An end tag whose tag name is one of: "tbody", "tfoot",
"thead"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have an element in table scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as the token, this is a <span>parse error</span>;
ignore the token.</p>
<p>Otherwise:</p>
<p><span>Clear the stack back to a table body context</span>. (See below.)</p>
<p>Pop the <span>current node</span> from the <span>stack of open elements</span>. Switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in table">in table</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "caption", "col",
"colgroup", "tbody", "tfoot", "thead"</dt>
<dt>An end tag whose tag name is "table"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>tbody</code>, <code>thead</code>, or <code>tfoot</code> element in table
scope</span>, this is a <span>parse error</span>; ignore the token.</p>
<p>Otherwise:</p>
<p><span>Clear the stack back to a table body context</span>. (See below.)</p>
<!-- fake </tbody>, </tfoot>, or </thead>, whatever is the current node -->
<p>Pop the <span>current node</span> from the <span>stack of open elements</span>. Switch the
<span>insertion mode</span> to "<span data-x="insertion mode: in table">in table</span>".</p>
<!-- end of fake </tbody>, </tfoot>, or </thead>, whatever was the current node -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "caption", "col", "colgroup", "html", "td",
"th", "tr"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
table">in table</span>" <span>insertion mode</span>.</p>
</dd>
</dl>
<p>When the steps above require the UA to <dfn>clear the stack back to a table body context</dfn>,
it means that the UA must, while the <span>current node</span> is not a <code>tbody</code>,
<code>tfoot</code>, <code>thead</code>, <code>template</code>, or <code>html</code> element, pop
elements from the <span>stack of open elements</span>.</p>
<p class="note">The <span>current node</span> being an <code>html</code> element after this
process is a <span>fragment case</span>.</p>
<h6 id="parsing-main-intr">The "<dfn data-x="insertion mode: in row">in row</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in row">in
row</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A start tag whose tag name is one of: "th", "td"</dt>
<dd>
<p><span>Clear the stack back to a table row context</span>. (See below.)</p>
<p><span>Insert an HTML element</span> for the token, then switch the <span>insertion
mode</span> to "<span data-x="insertion mode: in cell">in cell</span>".</p>
<p>Insert a <span data-x="concept-parser-marker">marker</span> at the end of the <span>list of
active formatting elements</span>.</p>
</dd>
<dt>An end tag whose tag name is "tr"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>tr</code> element in table scope</span>, this is a <span>parse error</span>;
ignore the token.</p>
<p>Otherwise:</p>
<p><span>Clear the stack back to a table row context</span>. (See below.)</p>
<p>Pop the <span>current node</span> (which will be a <code>tr</code> element) from the
<span>stack of open elements</span>. Switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in table body">in table body</span>".</p>
</dd>
<dt>A start tag whose tag name is one of: "caption", "col", "colgroup", "tbody", "tfoot",
"thead", "tr"</dt>
<dt>An end tag whose tag name is "table"</dt>
<dd>
<!-- fake <tr> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>tr</code> element in table scope</span>, this is a <span>parse error</span>;
ignore the token.</p>
<p>Otherwise:</p>
<p><span>Clear the stack back to a table row context</span>. (See below.)</p>
<p>Pop the <span>current node</span> (which will be a <code>tr</code> element) from the
<span>stack of open elements</span>. Switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in table body">in table body</span>".</p>
<!-- end of fake </tr> -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "tbody", "tfoot", "thead"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have an element in table scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as the token, this is a <span>parse error</span>;
ignore the token.</p>
<!-- fake <tr> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have a <code>tr</code> element in table scope</span>, ignore the token.</p>
<p>Otherwise:</p>
<p><span>Clear the stack back to a table row context</span>. (See below.)</p>
<p>Pop the <span>current node</span> (which will be a <code>tr</code> element) from the
<span>stack of open elements</span>. Switch the <span>insertion mode</span> to "<span
data-x="insertion mode: in table body">in table body</span>".</p>
<!-- end of fake </tr> -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "caption", "col", "colgroup", "html", "td",
"th"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
table">in table</span>" <span>insertion mode</span>.</p>
</dd>
</dl>
<p>When the steps above require the UA to <dfn>clear the stack back to a table row context</dfn>,
it means that the UA must, while the <span>current node</span> is not a <code>tr</code>,
<code>template</code>, or <code>html</code> element, pop elements from the <span>stack of open
elements</span>.</p>
<p class="note">The <span>current node</span> being an <code>html</code> element after this
process is a <span>fragment case</span>.</p>
<h6 id="parsing-main-intd">The "<dfn data-x="insertion mode: in cell">in cell</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in cell">in cell</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>An end tag whose tag name is one of: "td", "th"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have an element in table scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise:</p>
<p><span>Generate implied end tags</span>.</p>
<p>Now, if the <span>current node</span> is not an <span data-x="HTML elements">HTML
element</span> with the same tag name as the token, then this is a <span>parse error</span>.</p>
<p>Pop elements from the <span>stack of open elements</span> until an <span data-x="HTML
elements">HTML element</span> with the same tag name as the token has been popped from the
stack.</p>
<p><span>Clear the list of active formatting elements up to the last marker</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in row">in
row</span>".</p> <!-- current node here will be a <tr> normally; but could be <html> in the
fragment case, or <template> in the template case -->
</dd>
<dt>A start tag whose tag name is one of: "caption", "col",
"colgroup", "tbody", "td", "tfoot", "th", "thead", "tr"</dt>
<dd>
<p><span>Assert</span>: The <span>stack of open elements</span> <span data-x="has an element in
table scope">has a <code>td</code> or <code>th</code> element in table scope</span>.</p>
<!-- Because "in row" only switches to "in cell" if a td or th element is on the stack
and the rules for resetting the insertion mode only yield "in cell" if last is false
(i.e. not if node is the fragment context). -->
<p><span>Close the cell</span> (see below) and reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "body", "caption",
"col", "colgroup", "html"</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "table", "tbody",
"tfoot", "thead", "tr"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have an element in table scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then this is a <span>parse
error</span>; ignore the token.</p>
<p>Otherwise, <span>close the cell</span> (see below) and reprocess the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
</dl>
<p>Where the steps above say to <dfn>close the cell</dfn>, they mean to run the following
algorithm:</p>
<ol>
<!-- fake </td> or </th> -->
<li><p><span>Generate implied end tags</span>.</p></li>
<li><p>If the <span>current node</span> is not now a <code>td</code> element or a <code>th</code>
element, then this is a <span>parse error</span>.</p></li>
<li><p>Pop elements from the <span>stack of open elements</span> until a <code>td</code>
element or a <code>th</code> element has been popped from the stack.</p></li>
<li><p><span>Clear the list of active formatting elements up to the last marker</span>.</p></li>
<li><p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in row">in
row</span>".</p></li> <!-- current node here will be a <tr> normally; but could be <html> in the
fragment case, or <template> in the template case -->
<!-- end of fake </td> or </th> -->
</ol>
<p class="note">The <span>stack of open elements</span> cannot have both a <code>td</code> and a
<code>th</code> element <span data-x="has an element in table scope">in table scope</span> at the
same time, nor can it have neither when the <span>close the cell</span> algorithm is invoked.</p>
<h6 id="parsing-main-inselect">The "<dfn data-x="insertion mode: in select">in select</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in select">in
select</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is U+0000 NULL</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>Any other character token</dt>
<dd>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "option"</dt>
<dd>
<!-- fake </option> (maybe) -->
<p>If the <span>current node</span> is an <code>option</code> element, pop that node from the
<span>stack of open elements</span>.</p>
<!-- end of fake </option> -->
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is "optgroup"</dt>
<dd>
<!-- fake </option> (maybe) -->
<p>If the <span>current node</span> is an <code>option</code> element, pop that node from the
<span>stack of open elements</span>.</p>
<!-- end of fake </option> -->
<!-- fake </optgroup> (maybe) -->
<p>If the <span>current node</span> is an <code>optgroup</code> element, pop that node from the
<span>stack of open elements</span>.</p>
<!-- end of fake </optgroup> -->
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>A start tag whose tag name is "hr"</dt>
<dd>
<!-- fake </option> (maybe) -->
<p>If the <span>current node</span> is an <code>option</code> element, pop that node from the
<span>stack of open elements</span>.</p>
<!-- end of fake </option> -->
<!-- fake </optgroup> (maybe) -->
<p>If the <span>current node</span> is an <code>optgroup</code> element, pop that node from the
<span>stack of open elements</span>.</p>
<!-- end of fake </optgroup> -->
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing
flag">self-closing flag</i></span>, if it is set.</p>
</dd>
<dt>An end tag whose tag name is "optgroup"</dt>
<dd>
<!-- fake </option> (maybe) -->
<p>First, if the <span>current node</span> is an <code>option</code> element, and the node
immediately before it in the <span>stack of open elements</span> is an <code>optgroup</code>
element, then pop the <span>current node</span> from the <span>stack of open
elements</span>.</p>
<!-- end of fake </option> -->
<p>If the <span>current node</span> is an <code>optgroup</code> element, then pop that node from
the <span>stack of open elements</span>. Otherwise, this is a <span>parse error</span>; ignore
the token.</p>
</dd>
<dt>An end tag whose tag name is "option"</dt>
<dd>
<p>If the <span>current node</span> is an <code>option</code> element, then pop that node from
the <span>stack of open elements</span>. Otherwise, this is a <span>parse error</span>; ignore
the token.</p>
</dd>
<dt>An end tag whose tag name is "select"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in select
scope">have a <code>select</code> element in select scope</span>, this is a <span>parse
error</span>; ignore the token. (<span>fragment case</span>)</p>
<p>Otherwise:</p>
<p>Pop elements from the <span>stack of open elements</span> until a <code>select</code> element
has been popped from the stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
</dd>
<dt>A start tag whose tag name is "select"</dt>
<dd>
<p><span>Parse error</span>.</p>
<!-- fake </select> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in select
scope">have a <code>select</code> element in select scope</span>, ignore the token.
(<span>fragment case</span>)</p>
<p>Otherwise:</p>
<p>Pop elements from the <span>stack of open elements</span> until a <code>select</code> element
has been popped from the stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </select> -->
<p class="note">It just gets treated like an end tag.</p>
</dd>
<dt>A start tag whose tag name is one of: "input", "keygen", "textarea"</dt>
<dd>
<p><span>Parse error</span>.</p>
<!-- fake </select> -->
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in select
scope">have a <code>select</code> element in select scope</span>, ignore the token.
(<span>fragment case</span>)</p>
<p>Otherwise:</p>
<p>Pop elements from the <span>stack of open elements</span> until a <code>select</code> element
has been popped from the stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </select> -->
<p>Reprocess the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "script", "template"</dt>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
</dl>
<h6 id="parsing-main-inselectintable">The "<dfn data-x="insertion mode: in select in table">in select in table</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in select in
table">in select in table</span>" <span>insertion mode</span>, the user agent must handle the
token as follows:</p>
<dl class="switch">
<dt>A start tag whose tag name is one of: "caption", "table", "tbody", "tfoot", "thead", "tr",
"td", "th"</dt>
<dd>
<p><span>Parse error</span>.</p>
<!-- fake </select> -->
<p>Pop elements from the <span>stack of open elements</span> until a <code>select</code> element
has been popped from the stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </select> -->
<p>Reprocess the token.</p>
</dd>
<dt>An end tag whose tag name is one of: "caption", "table", "tbody", "tfoot", "thead", "tr",
"td", "th"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>If the <span>stack of open elements</span> does not <span data-x="has an element in table
scope">have an element in table scope</span> that is an <span data-x="HTML elements">HTML
element</span> with the same tag name as that of the token, then ignore the token.</p>
<p>Otherwise:</p>
<!-- fake </select> -->
<p>Pop elements from the <span>stack of open elements</span> until a <code>select</code> element
has been popped from the stack.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </select> -->
<p>Reprocess the token.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
select">in select</span>" <span>insertion mode</span>.</p>
</dd>
</dl>
<h6 id="parsing-main-intemplate">The "<dfn data-x="insertion mode: in template">in template</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in template">in
template</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<!-- first, tokens we always ignore: -->
<!-- html: ignored in "in body" mode if there's a <template> on the stack -->
<!-- head: ignored in "in body" mode always -->
<!-- body: ignored in "in body" mode if there's a <template> on the stack -->
<!-- frameset: ignored in "in body" mode if frameset-ok is set to not-ok, which <template> sets it to -->
<!-- second, tokens that are ambiguous (allowed in multiple modes), let's just handle them in a generic way and not pick a mode: -->
<dt>A character token</dt>
<dt>A comment token</dt>
<dt>A DOCTYPE token</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is one of: "base", "basefont", "bgsound", "link", "meta", "noframes", "script", "style", "template", "title"</dt>
<dt>An end tag whose tag name is "template"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<!-- now, tokens that imply certain modes -->
<dt>A start tag whose tag name is one of: "caption", "colgroup", "tbody", "tfoot", "thead"</dt>
<dd>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p>Push "<span data-x="insertion mode: in table">in table</span>" onto the <span>stack of
template insertion modes</span> so that it is the new <span>current template insertion
mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table">in
table</span>", and reprocess the token.</p>
</dd>
<dt>A start tag whose tag name is "col"</dt>
<dd>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p>Push "<span data-x="insertion mode: in column group">in column group</span>" onto the
<span>stack of template insertion modes</span> so that it is the new <span>current template
insertion mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in column group">in
column group</span>", and reprocess the token.</p>
</dd>
<dt>A start tag whose tag name is "tr"</dt>
<dd>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p>Push "<span data-x="insertion mode: in table body">in table body</span>" onto the <span>stack
of template insertion modes</span> so that it is the new <span>current template insertion
mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in table body">in
table body</span>", and reprocess the token.</p>
</dd>
<dt>A start tag whose tag name is one of: "td", "th"</dt>
<dd>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p>Push "<span data-x="insertion mode: in row">in row</span>" onto the <span>stack of template
insertion modes</span> so that it is the new <span>current template insertion mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in row">in
row</span>", and reprocess the token.</p>
</dd>
<!-- default to in-body mode -->
<dt>Any other start tag</dt>
<dd>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p>Push "<span data-x="insertion mode: in body">in body</span>" onto the <span>stack of template
insertion modes</span> so that it is the new <span>current template insertion mode</span>.</p>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: in body">in
body</span>", and reprocess the token.</p>
</dd>
<dt>Any other end tag</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<!-- EOF -->
<dt>An end-of-file token</dt>
<dd>
<p>If there is no <code>template</code> element on the <span>stack of open elements</span>, then
<span>stop parsing</span>. (<span>fragment case</span>)</p>
<p>Otherwise, this is a <span>parse error</span>.</p>
<!-- fake </template> -->
<p>Pop elements from the <span>stack of open elements</span> until a <code>template</code>
element has been popped from the stack.</p>
<p><span>Clear the list of active formatting elements up to the last marker</span>.</p>
<p>Pop the <span>current template insertion mode</span> off the <span>stack of template
insertion modes</span>.</p>
<p><span>Reset the insertion mode appropriately</span>.</p>
<!-- end of fake </template> -->
<p>Reprocess the token.</p>
</dd>
</dl>
<h6 id="parsing-main-afterbody">The "<dfn data-x="insertion mode: after body">after body</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: after body">after body</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span> as the last child of the first element in the <span>stack of
open elements</span> (the <code>html</code> element).</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end tag whose tag name is "html"</dt>
<dd>
<p>If the parser was created as part of the <span>HTML fragment parsing algorithm</span>, this
is a <span>parse error</span>; ignore the token. (<span>fragment case</span>)</p>
<p>Otherwise, switch the <span>insertion mode</span> to "<span data-x="insertion mode: after
after body">after after body</span>".</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p><span>Stop parsing</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Switch the <span>insertion mode</span> to "<span data-x="insertion
mode: in body">in body</span>" and reprocess the token.</p>
</dd>
</dl>
<h6 id="parsing-main-inframeset">The "<dfn data-x="insertion mode: in frameset">in frameset</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: in frameset">in
frameset</span>" <span>insertion mode</span>, the user agent must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>A start tag whose tag name is "frameset"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token.</p>
</dd>
<dt>An end tag whose tag name is "frameset"</dt>
<dd>
<p>If the <span>current node</span> is the root <code>html</code> element, then this is a
<span>parse error</span>; ignore the token. (<span>fragment case</span>)</p>
<p>Otherwise, pop the <span>current node</span> from the <span>stack of open
elements</span>.</p>
<p>If the parser was not created as part of the <span>HTML fragment parsing algorithm</span>
(<span>fragment case</span>), and the <span>current node</span> is no longer a
<code>frameset</code> element, then switch the <span>insertion mode</span> to "<span
data-x="insertion mode: after frameset">after frameset</span>".</p>
</dd>
<dt>A start tag whose tag name is "frame"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately pop the <span>current
node</span> off the <span>stack of open elements</span>.</p>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, if it is set.</p>
</dd>
<dt>A start tag whose tag name is "noframes"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p>If the <span>current node</span> is not the root <code>html</code> element, then this is a
<span>parse error</span>.</p>
<p class="note">The <span>current node</span> can only be the root
<code>html</code> element in the <span>fragment case</span>.</p>
<p><span>Stop parsing</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
</dl>
<h6 id="parsing-main-afterframeset">The "<dfn data-x="insertion mode: after frameset">after frameset</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: after
frameset">after frameset</span>" <span>insertion mode</span>, the user agent must handle the token
as follows:</p>
<!-- due to rules in the "in frameset" mode, this can't be entered in the fragment case -->
<dl class="switch">
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the character</span>.</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end tag whose tag name is "html"</dt>
<dd>
<p>Switch the <span>insertion mode</span> to "<span data-x="insertion mode: after after
frameset">after after frameset</span>".</p>
</dd>
<dt>A start tag whose tag name is "noframes"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p><span>Stop parsing</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
</dl>
<h6>The "<dfn data-x="insertion mode: after after body">after after body</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: after after
body">after after body</span>" <span>insertion mode</span>, the user agent must handle the token
as follows:</p>
<dl class="switch">
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span> as the last child of the <code>Document</code> object.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p><span>Stop parsing</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Switch the <span>insertion mode</span> to "<span data-x="insertion
mode: in body">in body</span>" and reprocess the token.</p>
</dd>
</dl>
<h6>The "<dfn data-x="insertion mode: after after frameset">after after frameset</dfn>" insertion mode</h6>
<p>When the user agent is to apply the rules for the "<span data-x="insertion mode: after after
frameset">after after frameset</span>" <span>insertion mode</span>, the user agent must handle the
token as follows:</p>
<dl class="switch">
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span> as the last child of the <code>Document</code> object.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dt>A start tag whose tag name is "html"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
body">in body</span>" <span>insertion mode</span>.</p>
</dd>
<dt>An end-of-file token</dt>
<dd>
<p><span>Stop parsing</span>.</p>
</dd>
<dt>A start tag whose tag name is "noframes"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span data-x="insertion mode: in
head">in head</span>" <span>insertion mode</span>.</p>
</dd>
<dt>Anything else</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
</dl>
<h5 id="parsing-main-inforeign">The rules for parsing tokens <dfn data-x="insertion mode: in foreign content">in foreign content</dfn></h5>
<p>When the user agent is to apply the rules for parsing tokens in foreign content, the user agent
must handle the token as follows:</p>
<dl class="switch">
<dt>A character token that is U+0000 NULL</dt>
<dd>
<p><span>Parse error</span>. <span data-x="insert a character">Insert a U+FFFD REPLACEMENT
CHARACTER character</span>.</p>
</dd>
<dt>A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C
FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE</dt>
<dd>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
</dd>
<dt>Any other character token</dt>
<dd>
<p><span data-x="insert a character">Insert the token's character</span>.</p>
<p>Set the <span>frameset-ok flag</span> to "not ok".</p>
</dd>
<dt>A comment token</dt>
<dd>
<p><span>Insert a comment</span>.</p>
</dd>
<dt>A DOCTYPE token</dt>
<dd>
<p><span>Parse error</span>. Ignore the token.</p>
</dd>
<dt>A start tag whose tag name is one of: <!--"a",--> "b", "big", "blockquote", "body"<!--by
inspection-->, "br", "center", "code", "dd", "div", "dl", "dt"<!-- so that dd and dt can be
handled uniformly throughout the parser -->, "em", "embed", "h1", "h2", "h3", "h4"<!--for
completeness-->, "h5", "h6"<!--for completeness-->, "head"<!--by inspection-->, "hr", "i", "img",
"li", "listing"<!-- so that pre and listing can be handled uniformly throughout the parser -->,
"menu", "meta", "nobr", "ol"<!-- so that dl, ul, and ol can be handled uniformly throughout the
parser -->, "p", "pre", "ruby", "s", <!--"script",--> "small", "span", "strong", "strike"<!-- so
that s and strike can be handled uniformly throughout the parser -->, <!--"style",--> "sub",
"sup", "table"<!--by inspection-->, "tt", "u", "ul", "var"</dt> <!-- this list was determined
empirically by studying over 6,000,000,000 pages that were specifically not XML pages -->
<dt>A start tag whose tag name is "font", if the token has any attributes named "color", "face",
or "size"</dt> <!-- the attributes here are required so that SVG <font> will go through as SVG
but legacy <font>s won't -->
<dt>An end tag whose tag name is "br", "p"</dt>
<dd>
<p><span>Parse error</span>.</p>
<p>While the <span>current node</span> is not a <span>MathML text integration point</span>, an
<span>HTML integration point</span>, or an element in the <span>HTML namespace</span>, pop
elements from the <span>stack of open elements</span>.</p>
<p>Reprocess the token according to the rules given in the section corresponding to the current
<span>insertion mode</span> in HTML content.</p>
</dd>
<dt>Any other start tag</dt>
<dd>
<p>If the <span>adjusted current node</span> is an element in the <span>MathML namespace</span>,
<span>adjust MathML attributes</span> for the token. (This fixes the case of MathML attributes
that are not all lowercase.)</p>
<p>If the <span>adjusted current node</span> is an element in the <span>SVG namespace</span>, and the
token's tag name is one of the ones in the first column of the following table, change the tag
name to the name given in the corresponding cell in the second column. (This fixes the case of
SVG elements that are not all lowercase.)</p>
<table>
<thead>
<tr> <th> Tag name <th> Element name
<tbody>
<tr> <td> <code data-x="">altglyph</code> <td> <code data-x="">altGlyph</code>
<tr> <td> <code data-x="">altglyphdef</code> <td> <code data-x="">altGlyphDef</code>
<tr> <td> <code data-x="">altglyphitem</code> <td> <code data-x="">altGlyphItem</code>
<tr> <td> <code data-x="">animatecolor</code> <td> <code data-x="">animateColor</code>
<tr> <td> <code data-x="">animatemotion</code> <td> <code data-x="">animateMotion</code>
<tr> <td> <code data-x="">animatetransform</code> <td> <code data-x="">animateTransform</code>
<tr> <td> <code data-x="">clippath</code> <td> <code data-x="">clipPath</code>
<tr> <td> <code data-x="">feblend</code> <td> <code data-x="">feBlend</code>
<tr> <td> <code data-x="">fecolormatrix</code> <td> <code data-x="">feColorMatrix</code>
<tr> <td> <code data-x="">fecomponenttransfer</code> <td> <code data-x="">feComponentTransfer</code>
<tr> <td> <code data-x="">fecomposite</code> <td> <code data-x="">feComposite</code>
<tr> <td> <code data-x="">feconvolvematrix</code> <td> <code data-x="">feConvolveMatrix</code>
<tr> <td> <code data-x="">fediffuselighting</code> <td> <code data-x="">feDiffuseLighting</code>
<tr> <td> <code data-x="">fedisplacementmap</code> <td> <code data-x="">feDisplacementMap</code>
<tr> <td> <code data-x="">fedistantlight</code> <td> <code data-x="">feDistantLight</code>
<tr> <td> <code data-x="">fedropshadow</code> <td> <code data-x="">feDropShadow</code>
<tr> <td> <code data-x="">feflood</code> <td> <code data-x="">feFlood</code>
<tr> <td> <code data-x="">fefunca</code> <td> <code data-x="">feFuncA</code>
<tr> <td> <code data-x="">fefuncb</code> <td> <code data-x="">feFuncB</code>
<tr> <td> <code data-x="">fefuncg</code> <td> <code data-x="">feFuncG</code>
<tr> <td> <code data-x="">fefuncr</code> <td> <code data-x="">feFuncR</code>
<tr> <td> <code data-x="">fegaussianblur</code> <td> <code data-x="">feGaussianBlur</code>
<tr> <td> <code data-x="">feimage</code> <td> <code data-x="">feImage</code>
<tr> <td> <code data-x="">femerge</code> <td> <code data-x="">feMerge</code>
<tr> <td> <code data-x="">femergenode</code> <td> <code data-x="">feMergeNode</code>
<tr> <td> <code data-x="">femorphology</code> <td> <code data-x="">feMorphology</code>
<tr> <td> <code data-x="">feoffset</code> <td> <code data-x="">feOffset</code>
<tr> <td> <code data-x="">fepointlight</code> <td> <code data-x="">fePointLight</code>
<tr> <td> <code data-x="">fespecularlighting</code> <td> <code data-x="">feSpecularLighting</code>
<tr> <td> <code data-x="">fespotlight</code> <td> <code data-x="">feSpotLight</code>
<tr> <td> <code data-x="">fetile</code> <td> <code data-x="">feTile</code>
<tr> <td> <code data-x="">feturbulence</code> <td> <code data-x="">feTurbulence</code>
<tr> <td> <code data-x="">foreignobject</code> <td> <code data-x="">foreignObject</code>
<tr> <td> <code data-x="">glyphref</code> <td> <code data-x="">glyphRef</code>
<tr> <td> <code data-x="">lineargradient</code> <td> <code data-x="">linearGradient</code>
<tr> <td> <code data-x="">radialgradient</code> <td> <code data-x="">radialGradient</code>
<!--<tr> <td> <code data-x="">solidcolor</code> <td> <code data-x="">solidColor</code> (SVG 1.2)-->
<tr> <td> <code data-x="">textpath</code> <td> <code data-x="">textPath</code>
</table>
<p>If the <span>adjusted current node</span> is an element in the <span>SVG namespace</span>,
<span>adjust SVG attributes</span> for the token. (This fixes the case of SVG attributes that
are not all lowercase.)</p>
<p><span>Adjust foreign attributes</span> for the token. (This fixes the use of namespaced
attributes, in particular XLink in SVG.)</p>
<p><span>Insert a foreign element</span> for the token, with <span>adjusted current
node</span>'s namespace and false.</p>
<p>If the token has its <i data-x="self-closing flag">self-closing flag</i> set, then run the appropriate steps from the
following list:</p>
<dl class="switch">
<dt>If the token's tag name is "script", and the new <span>current node</span> is in the <span>SVG namespace</span></dt>
<dd>
<p><span data-x="acknowledge self-closing flag">Acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>, and then act as described in the steps for a "script" end tag below.</p>
</dd>
<dt>Otherwise</dt>
<dd>
<p>Pop the <span>current node</span> off the <span>stack of open elements</span> and <span
data-x="acknowledge self-closing flag">acknowledge the token's <i data-x="self-closing flag">self-closing
flag</i></span>.</p>
</dd>
</dl>
</dd>
<dt id="scriptForeignEndTag">An end tag whose tag name is "script", if the <span>current
node</span> is an <span>SVG <code>script</code></span> element</dt>
<dd>
<p>Pop the <span>current node</span> off the <span>stack of open elements</span>.</p>
<p>Let the <var>old insertion point</var> have the same value as the current
<span>insertion point</span>. Let the <span>insertion point</span> be just before the <span>next
input character</span>.</p>
<p>Increment the parser's <span>script nesting level</span> by one. Set the <span>parser pause
flag</span> to true.</p>
<p>If the <span>active speculative HTML parser</span> is null and the user agent supports SVG,
then <a href="https://www.w3.org/TR/SVGMobile12/script.html#ScriptContentProcessing">Process the
SVG <code data-x="">script</code> element</a> according to the SVG rules. <ref>SVG</ref></p>
<p class="note">Even if this causes <span data-x="dom-document-write">new characters to be
inserted into the tokenizer</span>, the parser will not be executed reentrantly, since the
<span>parser pause flag</span> is true.</p>
<p>Decrement the parser's <span>script nesting level</span> by one. If the parser's <span>script
nesting level</span> is zero, then set the <span>parser pause flag</span> to false.</p>
<p>Let the <span>insertion point</span> have the value of the <var>old insertion
point</var>. (In other words, restore the <span>insertion point</span> to its previous value.
This value might be the "undefined" value.)</p>
</dd>
<dt>Any other end tag</dt>
<dd>
<p>Run these steps:</p>
<ol>
<li><p>Initialize <var>node</var> to be the <span>current node</span> (the bottommost
node of the stack).</p></li>
<li><p>If <var>node</var>'s tag name, <span>converted to ASCII lowercase</span>, is
not the same as the tag name of the token, then this is a <span>parse error</span>.</p></li>
<li><p><i>Loop</i>: If <var>node</var> is the topmost element in the <span>stack of
open elements</span>, then return. (<span>fragment case</span>)</p></li>
<li><p>If <var>node</var>'s tag name, <span>converted to ASCII lowercase</span>, is
the same as the tag name of the token, pop elements from the <span>stack of open
elements</span> until <var>node</var> has been popped from the stack, and then return.</p></li>
<li><p>Set <var>node</var> to the previous entry in the <span>stack of open
elements</span>.</p></li>
<li><p>If <var>node</var> is not an element in the <span>HTML namespace</span>, return
to the step labeled <i>loop</i>.</p></li>
<li><p>Otherwise, process the token according to the rules given in the section corresponding
to the current <span>insertion mode</span> in HTML content.</li>
</ol>
</dd>
</dl>
</div>
<div w-nodev>
<h4>The end</h4>
<p>Once the user agent <dfn data-x="stop parsing">stops parsing</dfn> the document, the user agent
must run the following steps:</p>
<ol>
<!-- this happens as part of one of the tasks that runs the parser -->
<li><p>If the <span>active speculative HTML parser</span> is not null, then <span>stop the
speculative HTML parser</span> and return.</p></li>
<li><p>Set the <span>insertion point</span> to undefined.</p></li>
<li><p><span>Update the current document readiness</span> to "<code
data-x="">interactive</code>".</p></li>
<li><p>Pop <em>all</em> the nodes off the <span>stack of open elements</span>.</p></li>
<li><p>While the <span>list of scripts that will execute when the document has finished
parsing</span> is not empty:</p>
<ol>
<li><p><span>Spin the event loop</span> until the first <code>script</code> in the <span>list
of scripts that will execute when the document has finished parsing</span> has its <span>ready
to be parser-executed</span> set to true <em>and</em> the parser's <code>Document</code>
<span>has no style sheet that is blocking scripts</span>.</p></li>
<li><p><span>Execute the script element</span> given by the first <code>script</code> in
the <span>list of scripts that will execute when the document has finished
parsing</span>.</p></li>
<li><p>Remove the first <code>script</code> element from the <span>list of scripts that will
execute when the document has finished parsing</span> (i.e. shift out the first entry in the
list).</p></li>
</ol>
</li>
<li>
<p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given the
<code>Document</code>'s <span>relevant global object</span> to run the following substeps:</p>
<ol>
<li><p>Set the <code>Document</code>'s <span>load timing info</span>'s <span>DOM content loaded
event start time</span> to the <span>current high resolution time</span> given the
<code>Document</code>'s <span>relevant global object</span>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-DOMContentLoaded">DOMContentLoaded</code> at the <code>Document</code>
object, with its <code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to
true.</p></li>
<li><p>Set the <code>Document</code>'s <span>load timing info</span>'s <span>DOM content loaded
event end time</span> to the <span>current high resolution time</span> given the
<code>Document</code>'s <span>relevant global object</span>.</p></li>
<li><p>Enable the <span data-x="dfn-client-message-queue">client message queue</span> of the
<code>ServiceWorkerContainer</code> object whose associated <span
data-x="serviceworkercontainer-service-worker-client">service worker client</span> is the
<code>Document</code> object's <span>relevant settings object</span>.</p></li>
<li><p>Invoke <span>WebDriver BiDi DOM content loaded</span> with the <code>Document</code>'s
<span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver BiDi
navigation status</span> whose <span data-x="navigation-status-id">id</span> is the
<code>Document</code> object's <span data-x="concept-document-navigation-id">during-loading
navigation ID for WebDriver BiDi</span>, <span data-x="navigation-status-status">status</span>
is "<code data-x="navigation-status-pending" >pending</code>", and <span
data-x="navigation-status-url">url</span> is the <code>Document</code> object's <span
data-x="concept-document-url">URL</span>.</p></li>
</ol>
</li>
<li><p><span>Spin the event loop</span> until the <span>set of scripts that will execute as soon
as possible</span> and the <span>list of scripts that will execute in order as soon as
possible</span> are empty.</p></li> <!-- this step is not redundant with the next one, since
<script> nodes delay the load event of the document they are in, but they might change document
between being added to one document's set/list and executing those scripts, so they might be
delaying another document but still be in this document's set/list. -->
<li><p><span>Spin the event loop</span> until there is nothing that <dfn data-x="delay the load
event">delays the load event</dfn> in the <code>Document</code>.</p></li>
<li>
<p><span>Queue a global task</span> on the <span>DOM manipulation task source</span> given the
<code>Document</code>'s <span>relevant global object</span> to run the following steps:</p>
<ol>
<li><p><span>Update the current document readiness</span> to "<code
data-x="">complete</code>".</p></li>
<li><p>If the <code>Document</code> object's <span data-x="concept-document-bc">browsing
context</span> is null, then abort these steps.</p></li>
<li><p>Let <var>window</var> be the <code>Document</code>'s <span>relevant global
object</span>.</p></li>
<li><p>Set the <code>Document</code>'s <span>load timing info</span>'s <span>load event start
time</span> to the <span>current high resolution time</span> given <var>window</var>.</p></li>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at <var>window</var>, with <var>legacy target override
flag</var> set.</p></li>
<li><p>Invoke <span>WebDriver BiDi load complete</span> with the <code>Document</code>'s <span
data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver BiDi
navigation status</span> whose <span data-x="navigation-status-id">id</span> is the
<code>Document</code> object's <span data-x="concept-document-navigation-id">during-loading
navigation ID for WebDriver BiDi</span>, <span data-x="navigation-status-status">status</span>
is "<code data-x="navigation-status-complete">complete</code>", and <span
data-x="navigation-status-url">url</span> is the <code>Document</code> object's <span
data-x="concept-document-url">URL</span>.</p></li>
<li><p>Set the <code>Document</code> object's <span
data-x="concept-document-navigation-id">during-loading navigation ID for WebDriver BiDi</span>
to null.</p></li>
<li><p>Set the <code>Document</code>'s <span>load timing info</span>'s <span>load event end
time</span> to the <span>current high resolution time</span> given <var>window</var>.</p></li>
<li><p><span>Assert</span>: <code>Document</code>'s <span>page showing</span> is
false.</p></li>
<li><p>Set the <code>Document</code>'s <span>page showing</span> to true.</p></li>
<li><p><span>Fire a page transition event</span> named <code
data-x="event-pageshow">pageshow</code> at <var>window</var> with false.</p></li>
<li><p><span>Completely finish loading</span> the <code>Document</code>.</p></li>
<li><p><span>Queue the navigation timing entry</span> for the <code>Document</code>.</p></li>
</ol>
</li>
<li><p>If the <code>Document</code>'s <span>print when loaded</span> flag is set, then run the
<span>printing steps</span>.</p></li>
<li><p>The <code>Document</code> is now <dfn>ready for post-load tasks</dfn>.</p></li>
</ol>
<p>When the user agent is to <dfn>abort a parser</dfn>, it must run the following steps:</p>
<ol>
<li><p>Throw away any pending content in the <span>input stream</span>, and discard any future
content that would have been added to it.</p></li>
<li><p><span>Stop the speculative HTML parser</span> for this HTML parser.</p></li>
<li><p><span>Update the current document readiness</span> to "<code
data-x="">interactive</code>".</p></li>
<li><p>Pop <em>all</em> the nodes off the <span>stack of open elements</span>.</p></li>
<li><p><span>Update the current document readiness</span> to "<code
data-x="">complete</code>".</p></li>
<!-- anything else? this is things that happen when you call document.open() on a document that's
still being parsed, or when you navigate a document that's still parsing, or navigate the parent
of a frame with a document that's still parsing, or the user hits "stop". Should the pending
scripts be blown away or anything? -->
</ol>
</div>
<div w-nodev>
<h4>Speculative HTML parsing</h4>
<p>User agents may implement an optimization, as described in this section, to speculatively fetch
resources that are declared in the HTML markup while the HTML parser is waiting for a
<span>pending parsing-blocking script</span> to be fetched and executed, or during normal parsing,
at the time <span data-x="create an element for the token">an element is created for a token</span>.
While this optimization is not defined in precise detail, there are some rules to consider for
interoperability.</p>
<p>Each <span>HTML parser</span> can have an <dfn export>active speculative HTML parser</dfn>. It
is initially null.</p>
<p>The <dfn export>speculative HTML parser</dfn> must act like the normal HTML parser (e.g., the
tree builder rules apply), with some exceptions:</p>
<ul>
<li>
<p>The state of the normal HTML parser and the document itself must not be affected.</p>
<p class="example">For example, the <span>next input character</span> or the <span>stack of open
elements</span> for the normal HTML parser is not affected by the <span>speculative HTML
parser</span>.</p>
</li>
<li>
<p>Bytes pushed into the HTML parser's <span>input byte stream</span> must also be pushed into
the speculative HTML parser's <span>input byte stream</span>. Bytes read from the streams must
be independent.</p>
</li>
<li>
<p>The result of the speculative parsing is primarily a series of <span data-x="speculative
fetch">speculative fetches</span>. Which kinds of resources to speculatively fetch is
<span>implementation-defined</span>, but user agents must not speculatively fetch resources that
would not be fetched with the normal HTML parser, under the assumption that the script that is
blocking the HTML parser does nothing.</p>
<p class="note">It is possible that the same markup is seen multiple times from the
<span>speculative HTML parser</span> and then the normal HTML parser. It is expected that
duplicated fetches will be prevented by caching rules, which are not yet fully specified.</p>
</li>
</ul>
<p>A <dfn>speculative fetch</dfn> for a <span>speculative mock element</span> <var>element</var>
must follow these rules:</p>
<p class="XXX">Should some of these things be applied to the document "for real", even
though they are found speculatively?</p>
<ul>
<li>
<p>If the <span>speculative HTML parser</span> encounters one of the following elements, then
act as if that element is processed for the purpose of its effect of subsequent speculative
fetches.</p>
<ul class="brief">
<li>A <code>base</code> element.</li>
<li>A <code>meta</code> element whose <code data-x="attr-meta-http-equiv">http-equiv</code>
attribute is in the <span data-x="attr-meta-http-equiv-content-security-policy">Content
security policy</span> state.</li>
<li>A <code>meta</code> element whose <code data-x="attr-meta-name">name</code> attribute is an
<span>ASCII case-insensitive</span> match for "<code
data-x="meta-referrer">referrer</code>".</li>
<li>A <code>meta</code> element whose <code data-x="attr-meta-name">name</code> attribute is an
<span>ASCII case-insensitive</span> match for "<code data-x="">viewport</code>". (This can
affect whether a media query list <span>matches the environment</span>.) <ref>CSSDEVICEADAPT</ref></li>
</ul>
</li>
<li><p>Let <var>url</var> be the <span>URL</span> that <var>element</var> would fetch if it was
processed normally. If there is no such <span>URL</span> or if it is the empty string, then do
nothing. Otherwise, if <span>url</span> is already in the <span>list of speculative fetch
URLs</span>, then do nothing. Otherwise, fetch <span>url</span> as if the element was processed
normally, and add <var>url</var> to the <span>list of speculative fetch URLs</span>.</p></li>
</ul>
<p>Each <code>Document</code> has a <dfn>list of speculative fetch URLs</dfn>, which is a
<span>list</span> of <span data-x="URL">URLs</span>, initially empty.</p>
<p>To <dfn>start the speculative HTML parser</dfn> for an instance of an HTML parser
<var>parser</var>:</p>
<ol>
<li>
<p>Optionally, return.</p>
<p class="note">This step allows user agents to opt out of speculative HTML parsing.</p>
</li>
<li>
<p>If <var>parser</var>'s <span>active speculative HTML parser</span> is not null, then
<span>stop the speculative HTML parser</span> for <var>parser</var>.</p>
<p class="note">This can happen when <code data-x="dom-document-write">document.write()</code>
writes another parser-blocking script. For simplicity, this specification always restarts
speculative parsing, but user agents can implement a more efficient strategy, so long as the end
result is equivalent.</p>
</li>
<li><p>Let <var>speculativeParser</var> be a new <span>speculative HTML parser</span>, with the
same state as <var>parser</var>.</p></li>
<li><p>Let <var>speculativeDoc</var> be a new isomorphic representation of <var>parser</var>'s
<code>Document</code>, where all elements are instead <span data-x="speculative mock
element">speculative mock elements</span>. Let <var>speculativeParser</var> parse into
<var>speculativeDoc</var>.</p></li>
<li><p>Set <var>parser</var>'s <span>active speculative HTML parser</span> to
<var>speculativeParser</var>.</p></li>
<li><p><span>In parallel</span>, run <var>speculativeParser</var> until it is stopped or until it
reaches the end of its <span>input stream</span>.</p></li>
</ol>
<p>To <dfn>stop the speculative HTML parser</dfn> for an instance of an HTML parser
<var>parser</var>:</p>
<ol>
<li><p>Let <var>speculativeParser</var> be <var>parser</var>'s <span>active speculative HTML
parser</span>.</p></li>
<li><p>If <var>speculativeParser</var> is null, then return.</p></li>
<li><p>Throw away any pending content in <var>speculativeParser</var>'s <span>input
stream</span>, and discard any future content that would have been added to it.</p></li>
<li><p>Set <var>parser</var>'s <span>active speculative HTML parser</span> to null.</p></li>
</ol>
<p>The <span>speculative HTML parser</span> will create <span
data-x="speculative mock element">speculative mock elements</span> instead of normal elements. DOM
operations that the tree builder normally does on elements are expected to work appropriately on
speculative mock elements.</p>
<p>A <dfn>speculative mock element</dfn> is a <span>struct</span> with the following <span
data-x="struct item">items</span>:</p>
<ul>
<li><p>A <span>string</span> <dfn data-x="concept-mock-namespace">namespace</dfn>, corresponding
to an element's <span data-x="concept-element-namespace">namespace</span>.</p></li>
<li><p>A <span>string</span> <dfn data-x="concept-mock-local-name">local name</dfn>,
corresponding to an element's <span data-x="concept-element-local-name">local
name</span>.</p></li>
<li><p>A <span>list</span> <dfn data-x="concept-mock-attribute-list">attribute list</dfn>,
corresponding to an element's <span>attribute list</span>.</p></li>
<li><p>A <span>list</span> <dfn data-x="concept-mock-children">children</dfn>, corresponding to
an element's <span data-x="concept-tree-child">children</span>.</p></li>
</ul>
<p>To <dfn>create a speculative mock element</dfn> given a <var>namespace</var>,
<var>tagName</var>, and <var>attributes</var>:</p>
<ol>
<li><p>Let <var>element</var> be a new <span>speculative mock element</span>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-mock-namespace">namespace</span> to
<var>namespace</var>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-mock-local-name">local name</span> to
<var>tagName</var>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-mock-attribute-list">attribute list</span>
to <var>attributes</var>.</p></li>
<li><p>Set <var>element</var>'s <span data-x="concept-mock-children">children</span> to a new
empty <span>list</span>.</p></li>
<li><p>Optionally, perform a <span>speculative fetch</span> for <var>element</var>.</p></li>
<li><p>Return <var>element</var>.</p></li>
</ol>
<p>When the tree builder says to insert an element into a <code>template</code> element's
<span>template contents</span>, if that is a <span>speculative mock element</span>, and the
<code>template</code> element's <span>template contents</span> is not a
<code>ShadowRoot</code> node, instead do nothing. URLs found speculatively inside
non-declarative-shadow-root <code>template</code> elements might themselves be templates, and must
not be speculatively fetched.</p>
</div>
<div w-nodev>
<h4>Coercing an HTML DOM into an infoset</h4>
<p>When an application uses an <span>HTML parser</span> in conjunction with an XML pipeline, it is
possible that the constructed DOM is not compatible with the XML tool chain in certain subtle
ways. For example, an XML toolchain might not be able to represent attributes with the name <code
data-x="">xmlns</code>, since they conflict with the Namespaces in XML syntax. There is also some
data that the <span>HTML parser</span> generates that isn't included in the DOM itself. This
section specifies some rules for handling these issues.</p>
<p>If the XML API being used doesn't support DOCTYPEs, the tool may drop DOCTYPEs altogether.</p>
<p>If the XML API doesn't support attributes in no namespace that are named "<code
data-x="">xmlns</code>", attributes whose names start with "<code data-x="">xmlns:</code>", or
attributes in the <span>XMLNS namespace</span>, then the tool may drop such attributes.</p>
<p>The tool may annotate the output with any namespace declarations required for proper
operation.</p>
<p>If the XML API being used restricts the allowable characters in the local names of elements and
attributes, then the tool may map all element and attribute local names that the API wouldn't
support to a set of names that <em>are</em> allowed, by replacing any character that isn't
supported with the uppercase letter U and the six digits of the character's code point when
expressed in hexadecimal, using digits 0-9 and capital letters A-F as the symbols, in increasing
numeric order.</p>
<p class="example">For example, the element name <code data-x="">foo<bar</code>, which can be
output by the <span>HTML parser</span>, though it is neither a legal HTML element name nor a
well-formed XML element name, would be converted into <code data-x="">fooU00003Cbar</code>, which
<em>is</em> a well-formed XML element name (though it's still not legal in HTML by any means).</p>
<p class="example">As another example, consider the attribute <code data-x="">xlink:href</code>.
Used on a MathML element, it becomes, after being <span data-x="adjust foreign
attributes">adjusted</span>, an attribute with a prefix "<code data-x="">xlink</code>" and a local
name "<code data-x="">href</code>". However, used on an HTML element, it becomes an attribute with
no prefix and the local name "<code data-x="">xlink:href</code>", which is not a valid NCName, and
thus might not be accepted by an XML API. It could thus get converted, becoming "<code
data-x="">xlinkU00003Ahref</code>".</p>
<p class="note">The resulting names from this conversion conveniently can't clash with any
attribute generated by the <span>HTML parser</span>, since those are all either lowercase or those
listed in the <span>adjust foreign attributes</span> algorithm's table.</p>
<p>If the XML API restricts comments from having two consecutive U+002D HYPHEN-MINUS characters
(--), the tool may insert a single U+0020 SPACE character between any such offending
characters.</p>
<p>If the XML API restricts comments from ending in a U+002D HYPHEN-MINUS character (-), the tool
may insert a single U+0020 SPACE character at the end of such comments.</p>
<p>If the XML API restricts allowed characters in character data, attribute values, or comments,
the tool may replace any U+000C FORM FEED (FF) character with a U+0020 SPACE character, and any
other literal non-XML character with a U+FFFD REPLACEMENT CHARACTER.</p>
<p>If the tool has no way to convey out-of-band information, then the tool may drop the following
information:</p>
<ul>
<li>Whether the document is set to <i data-x="no-quirks mode">no-quirks mode</i>, <i data-x="limited-quirks mode">limited-quirks mode</i>, or
<i data-x="quirks mode">quirks mode</i></li>
<li>The association between form controls and forms that aren't their nearest <code>form</code>
element ancestor (use of the <span><code>form</code> element pointer</span> in the parser)</li>
<li>The <span>template contents</span> of any <code>template</code> elements.</li>
</ul>
<p class="note">The mutations allowed by this section apply <em>after</em> the <span>HTML
parser</span>'s rules have been applied. For example, a <code data-x=""><a::></code> start tag
will be closed by a <code data-x=""></a::></code> end tag, and never by a <code
data-x=""></aU00003AU00003A></code> end tag, even if the user agent is using the rules above to
then generate an actual element in the DOM with the name <code data-x="">aU00003AU00003A</code> for
that start tag.</p>
</div>
<div w-nodev>
<h4>An introduction to error handling and strange cases in the parser</h4>
<!-- NON-NORMATIVE SECTION -->
<p>This section examines some erroneous markup and discusses how the <span>HTML parser</span>
handles these cases.</p>
<h5>Misnested tags: <b><i></b></i></h5>
<!-- NON-NORMATIVE SECTION -->
<p>The most-often discussed example of erroneous markup is as follows:</p>
<pre><code class="html"><p>1<b>2<i>3</b>4</i>5</p></code></pre>
<p>The parsing of this markup is straightforward up to the "3". At this point, the DOM looks like
this:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">3</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>Here, the <span>stack of open elements</span> has five elements on it: <code>html</code>,
<code>body</code>, <code>p</code>, <code>b</code>, and <code>i</code>. The <span>list of active
formatting elements</span> just has two: <code>b</code> and <code>i</code>. The <span>insertion
mode</span> is "<span data-x="insertion mode: in body">in body</span>".</p>
<p>Upon receiving the end tag token with the tag name "b", the "<a href="#adoptionAgency">adoption
agency algorithm</a>" is invoked. This is a simple case, in that the <var>formattingElement</var>
is the <code>b</code> element, and there is no <var>furthest block</var>.
Thus, the <span>stack of open elements</span> ends up with just three elements: <code>html</code>,
<code>body</code>, and <code>p</code>, while the <span>list of active formatting elements</span>
has just one: <code>i</code>. The DOM tree is unmodified at this point.</p>
<p>The next token is a character ("4"), triggers the <span data-x="reconstruct the active
formatting elements">reconstruction of the active formatting elements</span>, in this case just
the <code>i</code> element. A new <code>i</code> element is thus created for the "4"
<code>Text</code> node. After the end tag token for the "i" is also received, and the "5"
<code>Text</code> node is inserted, the DOM looks as follows:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">3</span></li></ul></li></ul></li><li class="t1"><code>i</code><ul><li class="t3"><code>#text</code>: <span data-x="">4</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">5</span></li></ul></li></ul></li></ul></li></ul>
<h5>Misnested tags: <b><p></b></p></h5>
<!-- NON-NORMATIVE SECTION -->
<p>A case similar to the previous one is the following:</p>
<pre><code class="html"><b>1<p>2</b>3</p></code></pre>
<p>Up to the "2" the parsing here is straightforward:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The interesting part is when the end tag token with the tag name "b" is parsed.</p>
<p>Before that token is seen, the <span>stack of open elements</span> has four elements on it:
<code>html</code>, <code>body</code>, <code>b</code>, and <code>p</code>. The <span>list of active
formatting elements</span> just has the one: <code>b</code>. The <span>insertion mode</span> is
"<span data-x="insertion mode: in body">in body</span>".</p>
<p>Upon receiving the end tag token with the tag name "b", the "<a href="#adoptionAgency">adoption
agency algorithm</a>" is invoked, as in the previous example. However, in this case, there
<em>is</em> a <var>furthest block</var>, namely the <code>p</code> element. Thus, this
time the adoption agency algorithm isn't skipped over.</p>
<p>The <var>common ancestor</var> is the <code>body</code> element. A conceptual
"bookmark" marks the position of the <code>b</code> in the <span>list of active formatting
elements</span>, but since that list has only one element in it, the bookmark won't have much
effect.</p>
<p>As the algorithm progresses, <var>node</var> ends up set to the formatting element
(<code>b</code>), and <var>last node</var> ends up set to the <var>furthest
block</var> (<code>p</code>).</p>
<p>The <var>last node</var> gets appended (moved) to the <var>common
ancestor</var>, so that the DOM looks like:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li></ul></li><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li></ul></li></ul></li></ul></li></ul>
<p>A new <code>b</code> element is created, and the children of the <code>p</code> element are
moved to it:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li></ul></li><li class="t1"><code>p</code></li></ul></li></ul></li></ul>
<ul class="domTree"><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li></ul></li></ul>
<p>Finally, the new <code>b</code> element is appended to the <code>p</code> element, so that the
DOM looks like:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The <code>b</code> element is removed from the <span>list of active formatting elements</span>
and the <span>stack of open elements</span>, so that when the "3" is parsed, it is appended to the
<code>p</code> element:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">1</span></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">2</span></li></ul></li><li class="t3"><code>#text</code>: <span data-x="">3</span></li></ul></li></ul></li></ul></li></ul>
<h5>Unexpected markup in tables</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Error handling in tables is, for historical reasons, especially strange. For example, consider
the following markup:</p>
<pre><code class="html"><table><strong><b></strong><tr><td>aaa</td></tr><strong>bbb</strong></table>ccc</code></pre>
<p>The highlighted <code>b</code> element start tag is not allowed directly inside a table like
that, and the parser handles this case by placing the element <em>before</em> the table. (This is
called <i data-x="foster parent">foster parenting</i>.) This can be seen by examining the DOM tree
as it stands just after the <code>table</code> element's start tag has been seen:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>table</code></li></ul></li></ul></li></ul>
<p>...and then immediately after the <code>b</code> element start tag has been seen:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>table</code></li></ul></li></ul></li></ul>
<p>At this point, the <span>stack of open elements</span> has on it the elements
<code>html</code>, <code>body</code>, <code>table</code>, and <code>b</code> (in that order,
despite the resulting DOM tree); the <span>list of active formatting elements</span> just has the
<code>b</code> element in it; and the <span>insertion mode</span> is "<span data-x="insertion mode:
in table">in table</span>".</p>
<p>The <code>tr</code> start tag causes the <code>b</code> element to be popped off the stack and
a <code>tbody</code> start tag to be implied; the <code>tbody</code> and <code>tr</code> elements
are then handled in a rather straight-forward manner, taking the parser through the "<span
data-x="insertion mode: in table body">in table body</span>" and "<span data-x="insertion mode: in
row">in row</span>" insertion modes, after which the DOM looks as follows:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>table</code><ul><li class="t1"><code>tbody</code><ul><li class="t1"><code>tr</code></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>Here, the <span>stack of open elements</span> has on it the elements <code>html</code>,
<code>body</code>, <code>table</code>, <code>tbody</code>, and <code>tr</code>; the <span>list of
active formatting elements</span> still has the <code>b</code> element in it; and the
<span>insertion mode</span> is "<span data-x="insertion mode: in row">in row</span>".</p>
<p>The <code>td</code> element start tag token, after putting a <code>td</code> element on the
tree, puts a <span data-x="concept-parser-marker">marker</span> on the <span>list of active
formatting elements</span> (it also switches to the "<span data-x="insertion mode: in cell">in
cell</span>" <span>insertion mode</span>).</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>table</code><ul><li class="t1"><code>tbody</code><ul><li class="t1"><code>tr</code><ul><li class="t1"><code>td</code></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The <span data-x="concept-parser-marker">marker</span> means that when the "aaa" character
tokens are seen, no <code>b</code> element is created to hold the resulting <code>Text</code>
node:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>table</code><ul><li class="t1"><code>tbody</code><ul><li class="t1"><code>tr</code><ul><li class="t1"><code>td</code><ul><li class="t3"><code>#text</code>: <span data-x="">aaa</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The end tags are handled in a straight-forward manner; after handling them, the <span>stack of
open elements</span> has on it the elements <code>html</code>, <code>body</code>,
<code>table</code>, and <code>tbody</code>; the <span>list of active formatting elements</span>
still has the <code>b</code> element in it (the <span data-x="concept-parser-marker">marker</span>
having been removed by the "td" end tag token); and the <span>insertion mode</span> is "<span
data-x="insertion mode: in table body">in table body</span>".</p>
<p>Thus it is that the "bbb" character tokens are found. These trigger the "<span data-x="insertion
mode: in table text">in table text</span>" insertion mode to be used (with the <span>original
insertion mode</span> set to "<span data-x="insertion mode: in table body">in table body</span>").
The character tokens are collected, and when the next token (the <code>table</code> element end
tag) is seen, they are processed as a group. Since they are not all spaces, they are handled as
per the "anything else" rules in the "<span data-x="insertion mode: in table">in table</span>"
insertion mode, which defer to the "<span data-x="insertion mode: in body">in body</span>"
insertion mode but with <span data-x="foster parent">foster parenting</span>.</p>
<p>When <span data-x="reconstruct the active formatting elements">the active formatting elements
are reconstructed</span>, a <code>b</code> element is created and <span data-x="foster
parent">foster parented</span>, and then the "bbb" <code>Text</code> node is appended to it:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">bbb</span></li></ul></li><li class="t1"><code>table</code><ul><li class="t1"><code>tbody</code><ul><li class="t1"><code>tr</code><ul><li class="t1"><code>td</code><ul><li class="t3"><code>#text</code>: <span data-x="">aaa</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The <span>stack of open elements</span> has on it the elements <code>html</code>,
<code>body</code>, <code>table</code>, <code>tbody</code>, and the new <code>b</code> (again, note
that this doesn't match the resulting tree!); the <span>list of active formatting elements</span>
has the new <code>b</code> element in it; and the <span>insertion mode</span> is still "<span
data-x="insertion mode: in table body">in table body</span>".</p>
<p>Had the character tokens been only <span>ASCII whitespace</span> instead of "bbb", then that
<span>ASCII whitespace</span> would just be appended to the <code>tbody</code> element.</p>
<p>Finally, the <code>table</code> is closed by a "table" end tag. This pops all the nodes from
the <span>stack of open elements</span> up to and including the <code>table</code> element, but it
doesn't affect the <span>list of active formatting elements</span>, so the "ccc" character tokens
after the table result in yet another <code>b</code> element being created, this time after the
table:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>b</code></li><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">bbb</span></li></ul></li><li class="t1"><code>table</code><ul><li class="t1"><code>tbody</code><ul><li class="t1"><code>tr</code><ul><li class="t1"><code>td</code><ul><li class="t3"><code>#text</code>: <span data-x="">aaa</span></li></ul></li></ul></li></ul></li></ul></li><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">ccc</span></li></ul></li></ul></li></ul></li></ul>
<h5>Scripts that modify the page as it is being parsed</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Consider the following markup, which for this example we will assume is the document with
<span>URL</span> <code data-x="">https://example.com/inner</code>, being rendered as the content of
an <code>iframe</code> in another document with the <span>URL</span> <code
data-x="">https://example.com/outer</code>:</p>
<pre><code class="html"><div id=a>
<script>
var div = document.getElementById('a');
parent.document.body.appendChild(div);
</script>
<script>
alert(document.URL);
</script>
</div>
<script>
alert(document.URL);
</script></code></pre>
<p>Up to the first "script" end tag, before the script is parsed, the result is relatively
straightforward:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>div</code> <span data-x="" class="t2"><code class="attribute name" data-x="attr-id">id</code>="<code class="attribute value" data-x="">a</code>"</span><ul><li class="t3"><code>#text</code>: <span data-x="">
</span></li><li class="t1"><code>script</code><ul><li class="t3"><code>#text</code>: <span data-x="">var div = document.getElementById('a'); ⏎ parent.document.body.appendChild(div);</span></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>After the script is parsed, though, the <code>div</code> element and its child
<code>script</code> element are gone:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code></li></ul></li></ul>
<p>They are, at this point, in the <code>Document</code> of the aforementioned outer
<span>browsing context</span>. However, the <span>stack of open elements</span> <em>still contains
the <code>div</code> element</em>.</p>
<p>Thus, when the second <code>script</code> element is parsed, it is inserted <em>into the outer
<code>Document</code> object</em>.</p>
<p>Those parsed into different <code>Document</code>s than the one the parser was created for do
not execute, so the first alert does not show.</p>
<p>Once the <code>div</code> element's end tag is parsed, the <code>div</code> element is popped
off the stack, and so the next <code>script</code> element is in the inner
<code>Document</code>:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>script</code><ul><li class="t3"><code>#text</code>: <span data-x="">alert(document.URL);</span></li></ul></li></ul></li></ul></li></ul>
<p>This script does execute, resulting in an alert that says "https://example.com/inner".</p>
<h5>The execution of scripts that are moving across multiple documents</h5>
<!-- NON-NORMATIVE SECTION -->
<p>Elaborating on the example in the previous section, consider the case where the second
<code>script</code> element is an external script (i.e. one with a <code
data-x="attr-script-src">src</code> attribute). Since the element was not in the parser's
<code>Document</code> when it was created, that external script is not even downloaded.</p>
<p>In a case where a <code>script</code> element with a <code data-x="attr-script-src">src</code>
attribute is parsed normally into its parser's <code>Document</code>, but while the external
script is being downloaded, the element is moved to another document, the script continues to
download, but does not execute.</p>
<p class="note">In general, moving <code>script</code> elements between <code>Document</code>s is
considered a bad practice.</p>
<h5>Unclosed formatting elements</h5>
<!-- NON-NORMATIVE SECTION -->
<p>The following markup shows how nested formatting elements (such as <code>b</code>) get
collected and continue to be applied even as the elements they are contained in are closed, but
that excessive duplicates are thrown away.</p>
<pre><code class="html"><!DOCTYPE html>
<p><b class=x><b class=x><b><b class=x><b class=x><b>X
<p>X
<p><b><b class=x><b>X
<p></b></b></b></b></b></b>X</code></pre>
<p>The resulting DOM tree is as follows:</p>
<ul class="domTree"><li class="t10">DOCTYPE: <code data-x="">html</code></li><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>p</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">X⏎</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">X⏎</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t1"><code>b</code><ul><li class="t1"><code>b</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-class">class</code>="<code class="attribute value" data-x="">x</code>"</span><ul><li class="t1"><code>b</code><ul><li class="t3"><code>#text</code>: <span data-x="">X⏎</span></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span data-x="">X⏎</span></li></ul></li></ul></li></ul></li></ul>
<p>Note how the second <code>p</code> element in the markup has no explicit <code>b</code>
elements, but in the resulting DOM, up to three of each kind of formatting element (in this case
three <code>b</code> elements with the class attribute, and two unadorned <code>b</code> elements)
get reconstructed before the element's "X".</p>
<p>Also note how this means that in the final paragraph only six <code>b</code> end tags are
needed to completely clear the <span>list of active formatting elements</span>, even though nine
<code>b</code> start tags have been seen up to this point.</p>
<!--/HTMLPARSER-->
<!--en-GB--><h3 id="serialising-html-fragments">Serializing HTML fragments</h3>
<p>For the purposes of the following algorithm, an element <dfn>serializes as void</dfn> if its
element type is one of the <span>void elements</span>, or is <code>basefont</code>,
<code>bgsound</code>, <code>frame</code>, <code>keygen</code>, or <code>param</code>.</p>
<p>The following steps form the <!--en-GB--><dfn id="html-fragment-serialisation-algorithm"
export>HTML fragment serialization algorithm</dfn>. The algorithm takes as input a DOM
<code>Element</code>, <code>Document</code>, or <code>DocumentFragment</code> referred to as
<var>the node</var>, a boolean <var>serializableShadowRoots</var>, and a
<code data-x="">sequence<ShadowRoot></code> <var>shadowRoots</var>, and returns a string.</p>
<p class="note">This algorithm serializes the <em>children</em> of the node being serialized, not
the node itself.</p>
<ol>
<li><p>If <var>the node</var> <span>serializes as void</span>, then return the empty
string.</p></li>
<li><p>Let <var>s</var> be a string, and initialize it to the empty string.</p></li>
<li><p>If <var>the node</var> is a <code>template</code> element, then let <var>the node</var> instead be the <code>template</code> element's <span>template
contents</span> (a <code>DocumentFragment</code> node).</p></li>
<li>
<p>If <var>current node</var> is a <span>shadow host</span>, then:</p>
<ol>
<li><p>Let <var>shadow</var> be <var>current node</var>'s
<span data-x="concept-element-shadow-root">shadow root</span>.</p></li>
<li>
<p>If one of the following is true:</p>
<ul>
<li><p><var>serializableShadowRoots</var> is true and <var>shadow</var>'s
<span data-x="shadow-serializable">serializable</span> is true; or</p></li>
<li><p><var>shadowRoots</var> contains <var>shadow</var>,</p></li>
</ul>
<p>then:</p>
<ol>
<li><p>Append "<code data-x=""><template shadowrootmode="</code>".</p></li>
<li><p>If <var>shadow</var>'s <span data-x="concept-shadow-root-mode">mode</span>
is "<code data-x="">open</code>", then append "<code data-x="">open</code>".
Otherwise, append "<code data-x="">closed</code>".</p></li>
<li><p>Append "<code data-x="">"</code>".</p></li>
<li><p>If <var>shadow</var>'s <span>delegates focus</span> is set, then append
"<code data-x=""> shadowrootdelegatesfocus=""</code>".</p></li>
<li><p>If <var>shadow</var>'s <span>serializable</span> is set, then append
"<code data-x=""> shadowrootserializable=""</code>".</p></li>
<li><p>If <var>shadow</var>'s <span>clonable</span> is set, then append
"<code data-x=""> shadowrootclonable=""</code>".</p></li>
<li><p>Append "<code data-x="">></code>".</p></li>
<li><p>Append the value of running the <span>HTML fragment serialization algorithm</span> with
<var>shadow</var>, <var>serializableShadowRoots</var>, and <var>shadowRoots</var> (thus recursing
into this algorithm for that element).</p></li>
<li><p>Append "<code data-x=""></template></code>".</p></li>
</ol>
</li>
</ol>
</li>
<li>
<p>For each child node of <var>the node</var>, in <span>tree order</span>, run the
following steps:</p>
<ol>
<li><p>Let <var>current node</var> be the child node being processed.</p></li>
<li>
<p>Append the appropriate string from the following list to <var>s</var>:</p>
<dl class="switch">
<dt>If <var>current node</var> is an <code>Element</code></dt>
<dd>
<p>If <var>current node</var> is an element in the <span>HTML namespace</span>, the
<span>MathML namespace</span>, or the <span>SVG namespace</span>, then let <var>tagname</var> be <var>current node</var>'s local name. Otherwise, let <var>tagname</var> be <var>current node</var>'s qualified name.</p>
<p>Append a U+003C LESS-THAN SIGN character (<), followed by <var>tagname</var>.</p>
<p class="note">For <span>HTML elements</span> created by the <span>HTML parser</span> or
<code data-x="dom-Document-createElement">createElement()</code>, <var>tagname</var> will be
lowercase.</p>
<p>If <var>current node</var>'s <span data-x="concept-element-is-value"><code
data-x="">is</code> value</span> is not null, and the element does not have an <code
data-x="attr-is">is</code> attribute in its attribute list, then append the string "<code
data-x=""> is="</code>", followed by <var>current node</var>'s <span
data-x="concept-element-is-value"><code data-x="">is</code> value</span> <span
data-x="escaping a string">escaped as described below</span> in <i>attribute mode</i>,
followed by a U+0022 QUOTATION MARK character (").</p>
<p>For each attribute that the element has, append a U+0020 SPACE character, the <span
data-x="attribute's serialized name">attribute's serialized name as described below</span>, a
U+003D EQUALS SIGN character (=), a U+0022 QUOTATION MARK character ("), the
attribute's value, <span data-x="escaping a string">escaped as described below</span> in
<i>attribute mode</i>, and a second U+0022 QUOTATION MARK character (").</p>
<p>An <!--en-GB--><dfn id="attribute's-serialised-name">attribute's serialized name</dfn>
for the purposes of the previous paragraph must be determined as follows:</p>
<dl class="switch">
<dt>If the attribute has no namespace</dt>
<dd>
<p>The attribute's serialized name is the attribute's local name.</p>
<p class="note">For attributes on <span>HTML elements</span> set by the <span>HTML
parser</span> or by <code data-x="dom-Element-setAttribute">setAttribute()</code>, the
local name will be lowercase.</p>
</dd>
<dt>If the attribute is in the <span>XML namespace</span></dt>
<dd><p>The attribute's serialized name is the string "<code data-x="">xml:</code>" followed
by the attribute's local name.</p></dd>
<dt>If the attribute is in the <span>XMLNS namespace</span> and the attribute's local name
is <code data-x="">xmlns</code></dt>
<dd><p>The attribute's serialized name is the string "<code
data-x="">xmlns</code>".</p></dd>
<dt>If the attribute is in the <span>XMLNS namespace</span> and the attribute's local name
is not <code data-x="">xmlns</code></dt>
<dd><p>The attribute's serialized name is the string "<code data-x="">xmlns:</code>"
followed by the attribute's local name.</p></dd>
<dt>If the attribute is in the <span>XLink namespace</span></dt>
<dd><p>The attribute's serialized name is the string "<code data-x="">xlink:</code>"
followed by the attribute's local name.</p></dd>
<dt>If the attribute is in some other namespace</dt>
<dd><p>The attribute's serialized name is the attribute's qualified name.</p></dd>
</dl>
<p>While the exact order of attributes is <span>implementation-defined</span>, and may
depend on factors such as the order that the attributes were given in the original markup,
the sort order must be stable, such that consecutive invocations of this algorithm serialize
an element's attributes in the same order.</p>
<p>Append a U+003E GREATER-THAN SIGN character (>).</p>
<p>If <var>current node</var> <span>serializes as void</span>, then <span>continue</span> on to the next
child node at this point.</p>
<p>Append the value of running the <span>HTML fragment serialization algorithm</span> with
<var>current node</var>, <var>serializableShadowRoots</var>, and <var>shadowRoots</var> (thus
recursing into this algorithm for that node), followed by a U+003C LESS-THAN SIGN character (<), a
U+002F SOLIDUS character (/), <var>tagname</var> again, and finally a U+003E GREATER-THAN SIGN
character (>).</p>
</dd>
<dt>If <var>current node</var> is a <code>Text</code> node</dt>
<dd>
<p>If the parent of <var>current node</var> is a <code>style</code>,
<code>script</code>, <code>xmp</code>, <code>iframe</code>, <code>noembed</code>,
<code>noframes</code>, or <code>plaintext</code> element, or if the parent of <var>current node</var> is a <code>noscript</code> element and <span
data-x="concept-n-script">scripting is enabled</span> for the node, then append the value of
<var>current node</var>'s <span data-x="concept-cd-data">data</span> literally.</p>
<p>Otherwise, append the value of <var>current node</var>'s <span
data-x="concept-cd-data">data</span>, <span data-x="escaping a string">escaped as described
below</span>.</p>
</dd>
<dt>If <var>current node</var> is a <code>Comment</code></dt>
<dd>
<p>Append "<code data-x=""><!--</code>" (U+003C LESS-THAN SIGN, U+0021
EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS), followed by the value of
<var>current node</var>'s <span data-x="concept-cd-data">data</span>, followed by the
literal string "<code data-x="">--></code>" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS,
U+003E GREATER-THAN SIGN).</p>
</dd>
<dt>If <var>current node</var> is a <code>ProcessingInstruction</code></dt>
<dd>
<p>Append "<code data-x=""><?</code>" (U+003C LESS-THAN SIGN, U+003F
QUESTION MARK), followed by the value of <var>current node</var>'s <code
data-x="">target</code> IDL attribute, followed by a single U+0020 SPACE character, followed
by the value of <var>current node</var>'s <span data-x="concept-cd-data">data</span>,
followed by a single U+003E GREATER-THAN SIGN character (>).</p>
</dd>
<dt>If <var>current node</var> is a <code>DocumentType</code></dt>
<dd>
<p>Append "<code data-x=""><!DOCTYPE</code>" (U+003C LESS-THAN SIGN, U+0021
EXCLAMATION MARK, U+0044 LATIN CAPITAL LETTER D, U+004F LATIN CAPITAL LETTER O, U+0043 LATIN
CAPITAL LETTER C, U+0054 LATIN CAPITAL LETTER T, U+0059 LATIN CAPITAL LETTER Y, U+0050 LATIN
CAPITAL LETTER P, U+0045 LATIN CAPITAL LETTER E), followed by a space (U+0020 SPACE),
followed by the value of <var>current node</var>'s <span
data-x="concept-doctype-name">name</span>, followed by "<code data-x="">></code>"
(U+003E GREATER-THAN SIGN).</p>
</dd>
</dl>
</li>
</ol>
</li>
<li><p>Return <var>s</var>.</p></li>
</ol>
<p class="warning">It is possible that the output of this algorithm, if parsed with an <span>HTML
parser</span>, will not return the original tree structure. Tree structures that do not roundtrip
a serialize and reparse step can also be produced by the <span>HTML parser</span> itself, although
such cases are typically non-conforming.</p>
<div class="example">
<p>For instance, if a <code>textarea</code> element to which a <code data-x="">Comment</code>
node has been appended is serialized and the output is then reparsed, the comment will end up
being displayed in the text control. Similarly, if, as a result of DOM manipulation, an element
contains a comment that contains "<code data-x="">--></code>", then when
the result of serializing the element is parsed, the comment will be truncated at that point and
the rest of the comment will be interpreted as markup. More examples would be making a
<code>script</code> element contain a <code>Text</code> node with the text string "<code
data-x=""></script></code>", or having a <code>p</code> element that contains a
<code>ul</code> element (as the <code>ul</code> element's <span data-x="syntax-start-tag">start
tag</span> would imply the end tag for the <code>p</code>).</p>
<p>This can enable cross-site scripting attacks. An example of this would be a page that lets the
user enter some font family names that are then inserted into a CSS <code>style</code> block via
the DOM and which then uses the <code data-x="dom-element-innerHTML">innerHTML</code> IDL attribute to get
the HTML serialization of that <code>style</code> element: if the user enters
"<code data-x=""></style><script>attack</script></code>" as a font family name, <code
data-x="dom-element-innerHTML">innerHTML</code> will return markup that, if parsed in a different context,
would contain a <code>script</code> node, even though no <code>script</code> node existed in the
original DOM.</p>
</div>
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><form id="outer"><div></form><form id="inner"><input></code></pre>
<p>This will be parsed into:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>form</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-id">id</code>="<code class="attribute value" data-x="">outer</code>"</span><ul><li class="t1"><code>div</code><ul><li class="t1"><code>form</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-id">id</code>="<code class="attribute value" data-x="">inner</code>"</span><ul><li class="t1"><code>input</code></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul>
<p>The <code>input</code> element will be associated with the inner <code>form</code> element.
Now, if this tree structure is serialized and reparsed, the <code data-x=""><form
id="inner"></code> start tag will be ignored, and so the <code>input</code> element will be
associated with the outer <code>form</code> element instead.</p>
<pre><code class="html"><html><head></head><body><form id="outer"><div><mark><form id="inner"></mark><input></form></div></form></body></html></code></pre>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>form</code> <span class="t2" data-x=""><code class="attribute name" data-x="attr-id">id</code>="<code class="attribute value" data-x="">outer</code>"</span><ul><li class="t1"><code>div</code><ul><li class="t1"><code>input</code></li></ul></li></ul></li></ul></li></ul></li></ul>
</div>
<div class="example">
<p>As another example, consider the following markup:</p>
<pre><code class="html"><a><table><a></code></pre>
<p>This will be parsed into:</p>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>a</code><ul><li class="t1"><code>a</code></li><li class="t1"><code>table</code></li></ul></li></ul></li></ul></li></ul>
<p>That is, the <code>a</code> elements are nested, because the second <code>a</code> element is
<span data-x="foster parent">foster parented</span>. After a serialize-reparse roundtrip, the
<code>a</code> elements and the <code>table</code> element would all be siblings, because the
second <code data-x=""><a></code> start tag implicitly closes the first <code>a</code>
element.</p>
<pre><code class="html"><html><head></head><body><a><mark><a></mark></a><table></table></a></body></html></code></pre>
<ul class="domTree"><li class="t1"><code>html</code><ul><li class="t1"><code>head</code></li><li class="t1"><code>body</code><ul><li class="t1"><code>a</code></li><li class="t1"><code>a</code></li><li class="t1"><code>table</code></li></ul></li></ul></li></ul>
</div>
<p>For historical reasons, this algorithm does not round-trip an initial U+000A LINE FEED (LF)
character in <code>pre</code>, <code>textarea</code>, or <code>listing</code> elements, even
though (in the first two cases) the markup being round-tripped can be conforming. The <span>HTML
parser</span> will drop such a character during parsing, but this algorithm does <em>not</em>
serialize an extra U+000A LINE FEED (LF) character.</p>
<!-- https://github.com/whatwg/html/issues/944 -->
<div class="example">
<p>For example, consider the following markup:</p>
<pre><code class="html"><pre>
Hello.</pre></code></pre>
<p>When this document is first parsed, the <code>pre</code> element's <span>child text
content</span> starts with a single newline character. After a serialize-reparse roundtrip, the
<code>pre</code> element's <span>child text content</span> is simply "<code
data-x="">Hello.</code>".</p>
</div>
<p id="attr-is-during-serialization">Because of the special role of the <code
data-x="attr-is">is</code> attribute in signaling the creation of <span data-x="customized
built-in element">customized built-in elements</span>, in that it provides a mechanism for parsed
HTML to set the element's <span data-x="concept-element-is-value"><code data-x="">is</code>
value</span>, we special-case its handling during serialization. This ensures that an element's
<span data-x="concept-element-is-value"><code data-x="">is</code> value</span> is preserved
through serialize-parse roundtrips.</p>
<div class="example">
<p>When creating a <span>customized built-in element</span> via the parser, a developer uses the <code
data-x="attr-is">is</code> attribute directly; in such cases serialize-parse roundtrips work fine.</p>
<pre><code class="html"><script>
window.SuperP = class extends HTMLParagraphElement {};
customElements.define("super-p", SuperP, { extends: "p" });
</script>
<div id="container"><p is="super-p">Superb!</p></div>
<script>
console.log(container.innerHTML); // <p is="super-p">
container.innerHTML = container.innerHTML;
console.log(container.innerHTML); // <p is="super-p">
console.assert(container.firstChild instanceof SuperP);
</script></code></pre>
<p>But when creating a customized built-in element via its <span data-x="custom element
constructor">constructor</span> or via <code
data-x="dom-Document-createElement">createElement()</code>, the <code data-x="attr-is">is</code>
attribute is not added. Instead, the <span data-x="concept-element-is-value"><code
data-x="">is</code> value</span> (which is what the custom elements machinery uses) is set
without intermediating through an attribute.</p>
<pre><code class="html"><script>
container.innerHTML = "";
const p = document.createElement("p", { is: "super-p" });
container.appendChild(p);
// The is attribute is not present in the DOM:
console.assert(!p.hasAttribute("is"));
// But the element is still a super-p:
console.assert(p instanceof SuperP);
</script></code></pre>
<p>To ensure that serialize-parse roundtrips still work, the serialization process explicitly
writes out the element's <span data-x="concept-element-is-value"><code data-x="">is</code>
value</span> as an <code data-x="attr-is">is</code> attribute:</p>
<pre><code class="html"><script>
console.log(container.innerHTML); // <p is="super-p">
container.innerHTML = container.innerHTML;
console.log(container.innerHTML); // <p is="super-p">
console.assert(container.firstChild instanceof SuperP);
</script></code></pre>
</div>
<p><dfn id="escapingString">Escaping a string</dfn> (for the purposes of the algorithm above)
consists of running the following steps:</p>
<ol>
<li><p>Replace any occurrence of the "<code data-x="">&</code>" character by the string "<code
data-x="">&amp;</code>".</p></li>
<li><p>Replace any occurrences of the U+00A0 NO-BREAK SPACE character by the string "<code
data-x="">&nbsp;</code>".</p></li>
<li><p>If the algorithm was invoked in the <i>attribute mode</i>, replace any occurrences of the
"<code data-x="">"</code>" character by the string "<code
data-x="">&quot;</code>".</p></li>
<li><p>If the algorithm was <em>not</em> invoked in the <i>attribute mode</i>, replace any
occurrences of the "<code data-x=""><</code>" character by the string "<code
data-x="">&lt;</code>", and any occurrences of the "<code data-x="">></code>" character by
the string "<code data-x="">&gt;</code>".</p></li>
</ol>
<h3>Parsing HTML fragments</h3>
<p>The <dfn>HTML fragment parsing algorithm</dfn>, given an <code>Element</code> node <dfn
data-x="concept-frag-parse-context"><var>context</var></dfn>, string <var>input</var>, and an
optional boolean <var>allowDeclarativeShadowRoots</var> (default false) is the following steps.
They return a list of zero or more nodes.</p>
<p class="note">Parts marked <dfn>fragment case</dfn> in algorithms in the <span>HTML
parser</span> section are parts that only occur if the parser was created for the purposes of this
algorithm. The algorithms have been annotated with such markings for informational purposes only;
such markings have no normative weight. If it is possible for a condition described as a
<span>fragment case</span> to occur even when the parser wasn't created for the purposes of
handling this algorithm, then that is an error in the specification.</p>
<ol>
<li><p>Let <var>document</var> be a <code>Document</code> node whose <span
data-x="concept-document-type">type</span> is "<code data-x="">html</code>".</p></li>
<li><p>If <var data-x="concept-frag-parse-context">context</var>'s <span>node document</span> is
in <span>quirks mode</span>, then set <var>document</var>'s <span
data-x="concept-document-mode">mode</span> to "<code data-x="">quirks</code>".</p></li>
<li><p>Otherwise, if <var data-x="concept-frag-parse-context">context</var>'s <span>node
document</span> is in <span>limited-quirks mode</span>, then set <var>document</var>'s <span
data-x="concept-document-mode">mode</span> to "<code data-x="">limited-quirks</code>".</p></li>
<li><p>If <var>allowDeclarativeShadowRoots</var> is true, then set <var>document</var>'s <span
data-x="concept-document-allow-declarative-shadow-roots">allow declarative shadow roots</span> to
true.</p></li>
<li><p>Create a new <span>HTML parser</span>, and associate it with <var>document</var>.</p></li>
<li>
<p>Set the state of the <span>HTML parser</span>'s <span>tokenization</span> stage as
follows, switching on the <var data-x="concept-frag-parse-context">context</var> element:</p>
<dl class="switch">
<dt><code>title</code></dt>
<dt><code>textarea</code></dt>
<dd>Switch the tokenizer to the <span>RCDATA state</span>.</dd>
<dt><code>style</code></dt>
<dt><code>xmp</code></dt>
<dt><code>iframe</code></dt>
<dt><code>noembed</code></dt>
<dt><code>noframes</code></dt>
<dd>Switch the tokenizer to the <span>RAWTEXT state</span>.</dd>
<dt><code>script</code></dt>
<dd>Switch the tokenizer to the <span>script data state</span>.</dd>
<dt><code>noscript</code></dt>
<dd>If the <span>scripting flag</span> is enabled, switch the tokenizer to the <span>RAWTEXT
state</span>. Otherwise, leave the tokenizer in the <span>data state</span>.</dd>
<dt><code>plaintext</code></dt>
<dd>Switch the tokenizer to the <span>PLAINTEXT state</span>.</dd>
<dt>Any other element</dt>
<dd>Leave the tokenizer in the <span>data state</span>.</dd>
</dl>
<p class="note">For performance reasons, an implementation that does not report errors and
that uses the actual state machine described in this specification directly could use the
PLAINTEXT state instead of the RAWTEXT and script data states where those are mentioned in the
list above. Except for rules regarding parse errors, they are equivalent, since there is no
<span>appropriate end tag token</span> in the fragment case, yet they involve far fewer state
transitions.</p>
</li>
<li><p>Let <var>root</var> be the result of <span data-x="create an element">creating an
element</span> given <var>document</var>, "<code data-x="">html</code>", and the <span>HTML
namespace</span>.</p></li>
<li><p><span data-x="concept-node-append">Append</span> <var>root</var> to
<var>document</var>.</p></li>
<li><p>Set up the <span>HTML parser</span>'s <span>stack of open elements</span> so that it
contains just the single element <var>root</var>.</p></li>
<li><p>If <var data-x="concept-frag-parse-context">context</var> is a <code>template</code>
element, then push "<span data-x="insertion mode: in template">in template</span>" onto the
<span>stack of template insertion modes</span> so that it is the new <span>current template
insertion mode</span>.</p></li>
<li>
<p>Create a start tag token whose name is the local name of <var
data-x="concept-frag-parse-context">context</var> and whose attributes are the attributes of
<var data-x="concept-frag-parse-context">context</var>.</p>
<p>Let this start tag token be the start tag token of <var
data-x="concept-frag-parse-context">context</var>; e.g. for the purposes of determining if it is
an <span>HTML integration point</span>.</p>
</li>
<li>
<p><span data-x="reset the insertion mode appropriately">Reset the parser's insertion mode
appropriately</span>.</p>
<p class="note">The parser will reference the <var
data-x="concept-frag-parse-context">context</var> element as part of that algorithm.</p>
</li>
<li><p>Set the <span>HTML parser</span>'s <span><code>form</code> element pointer</span> to the
nearest node to <var data-x="concept-frag-parse-context">context</var> that is a
<code>form</code> element (going straight up the ancestor chain, and including the element
itself, if it is a <code>form</code> element), if any. (If there is no such <code>form</code>
element, the <span><code>form</code> element pointer</span> keeps its initial value,
null.)</p></li>
<li><p>Place the <var>input</var> into the <span>input stream</span> for the <span>HTML
parser</span> just created. The encoding <span
data-x="concept-encoding-confidence">confidence</span> is <i>irrelevant</i>.</p></li>
<li><p>Start the <span>HTML parser</span> and let it run until it has consumed all the characters
just inserted into the input stream.</p></li>
<li><p>Return <var>root</var>'s <span data-x="concept-tree-child">children</span>, in <span>tree
order</span>.</p></li>
</ol>
</div>
<h3 split-filename="named-characters"><dfn>Named character references</dfn></h3>
<p>This table lists the <span data-x="syntax-charref">character reference</span> names that are
supported by HTML, and the code points to which they refer. It is referenced by the previous
sections.</p>
<p class="note">It is intentional, for legacy compatibility, that many code points have multiple
character reference names. For example, some appear both with and without the trailing semicolon,
or with different capitalizations.</p>
<div id="named-character-references-table">
<table>
<thead>
<tr> <th> Name </th> <th> Character(s) </th> <th> Glyph </th> </tr>
</thead>
<!--BOILERPLATE entities.inc-->
</table>
<!--
If we want to add character references, Almorca suggests:
> I would add &sub1; (character U+2081), &sub2; (character U+2082) and &sub3; (character U+2083).
> They would are the equivalent to ¹, ², and ³.
See also: https://www.w3.org/2003/entities/
-->
</div>
<p>This data is also available <a href="/entities.json">as a JSON file</a>.</p>
<p><i>The glyphs displayed above are non-normative. Refer to Unicode for formal definitions of the
characters listed above.</i></p>
<p class="note">The character reference names originate from <cite>XML Entity Definitions for
Characters</cite>, though only the above is considered normative. <ref>XMLENTITY</ref></p>
<p class="note">This list is static and <a
href="https://github.com/whatwg/html/blob/main/FAQ.md#html-should-add-more-named-character-references">will
not be expanded or changed in the future</a>.</p>
<h2 split-filename="xhtml" id="the-xhtml-syntax"><dfn id="xhtml">The XML syntax</dfn></h2>
<p class="note">This section only describes the rules for XML resources. Rules for
<code>text/html</code> resources are discussed in the section above entitled "<span>The HTML
syntax</span>".</p>
<p class="warning" id="xml-syntax-not-recommended">Using the XML syntax is not recommended, for
reasons which include the fact that there is no specification which defines the rules for how an
XML parser must map a string of bytes or characters into a <code>Document</code> object, as well
as the fact that the XML syntax is essentially unmaintained — in that, it’s not expected that any
further features will ever be added to the XML syntax (even when such features have been added to
the <span data-x="the HTML syntax">HTML syntax</span>).</p>
<div w-nodev>
<h3 id="writing-xhtml-documents">Writing documents in the XML syntax</h3>
</div>
<p class="note">The XML syntax for HTML was formerly referred to as "XHTML", but this
specification does not use that term (among other reasons, because no such term is used for the
HTML syntaxes of MathML and SVG).</p>
<p>The syntax for XML is defined in <cite>XML</cite> and <cite>Namespaces in XML</cite>. <ref>XML</ref>
<ref>XMLNS</ref></p>
<p>This specification does not define any syntax-level requirements beyond those defined for XML
proper.</p>
<p>XML documents may contain a <code data-x="">DOCTYPE</code> if desired, but this is not required
to conform to this specification. This specification does not define a public or system
identifier, nor provide a formal DTD.</p>
<p class="note">According to <cite>XML</cite>, XML processors are not guaranteed to process
the external DTD subset referenced in the DOCTYPE. This means, for example, that using <a
href="https://www.w3.org/TR/xml/#dt-entref">entity references</a> for characters in XML documents
is unsafe if they are defined in an external file (except for <code data-x="">&lt;</code>,
<code data-x="">&gt;</code>, <code data-x="">&amp;</code>,
<code data-x="">&quot;</code>, and <code data-x="">&apos;</code>).</p>
<div w-nodev>
<h3 id="parsing-xhtml-documents">Parsing XML documents</h3>
<p>This section describes the relationship between XML and the DOM, with a particular emphasis on
how this interacts with HTML.</p>
<p>An <dfn export>XML parser</dfn>, for the purposes of this specification, is a construct that
follows the rules given in <cite>XML</cite> to map a string of bytes or characters into a
<code>Document</code> object.</p>
<p class="note">At the time of writing, no such rules actually exist.</p><!--XMLPARSE-->
<p>An <span>XML parser</span> is either associated with a <code>Document</code> object when it is
created, or creates one implicitly.</p>
<p>This <code>Document</code> must then be populated with DOM nodes that represent the tree
structure of the input passed to the parser, as defined by <cite>XML</cite>, <cite>Namespaces
in XML</cite>, and <cite>DOM</cite>. When creating DOM nodes representing elements,
the <span data-x="create an element for the token">create an element for a token</span> algorithm
or some equivalent that operates on appropriate XML data structures must be used, to ensure the
proper <span data-x="element interface">element interfaces</span> are created and that <span
data-x="custom element">custom elements</span> are set up correctly.</p>
<p>For the operations that the <span>XML parser</span> performs on the <code>Document</code>'s
tree, the user agent must act as if elements and attributes were individually appended and set
respectively so as to trigger rules in this specification regarding what happens when an element
is inserted into a document or has its attributes set, and <cite>DOM</cite>'s requirements
regarding <span>mutation observers</span> mean that mutation observers <em>are</em> fired.
<ref>XML</ref> <ref>XMLNS</ref> <ref>DOM</ref> <ref>UIEVENTS</ref></p>
<p>Between the time an element's start tag is parsed and the time either the element's end tag is
parsed or the parser detects a well-formedness error, the user agent must act as if the element
was in a <span>stack of open elements</span>.</p>
<p class="note">This is used by various elements to only start certain processes once they are
popped off of the <span>stack of open elements</span>.</p>
<p>This specification provides the following additional information that user agents should use
when retrieving an external entity: the public identifiers given in the following list all
correspond to <a href="<!--BOILERPLATE entities-dtd.url-->">the URL given by this link</a>. (This
URL is a DTD containing the <a href="https://www.w3.org/TR/xml/#sec-entity-decl">entity
declarations</a> for the names listed in the <span>named character references</span> section.) <ref>XML</ref></p>
<ul class="brief">
<li><code data-x="">-//W3C//DTD XHTML 1.0 Transitional//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML 1.1//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML 1.0 Strict//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML 1.0 Frameset//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML Basic 1.0//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN</code></li>
<li><code data-x="">-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN</code></li>
<li><code data-x="">-//W3C//DTD MathML 2.0//EN</code></li>
<li><code data-x="">-//WAPFORUM//DTD XHTML Mobile 1.0//EN</code></li>
</ul>
<p>Furthermore, user agents should attempt to retrieve the above external entity's content when
one of the above public identifiers is used, and should not attempt to retrieve any other external
entity's content.</p>
<p class="note">This is not strictly a <span data-x="willful violation">violation</span> of
<cite>XML</cite>, but it does contradict the spirit of <cite>XML</cite>'s requirements. This is
motivated by a desire for user agents to all handle entities in an interoperable fashion without
requiring any network access for handling external subsets. <ref>XML</ref></p>
<p>XML parsers can be invoked with <dfn export>XML scripting support enabled</dfn> or <dfn
export>XML scripting support disabled</dfn>. Except where otherwise specified, XML parsers are
invoked with <span>XML scripting support enabled</span>.</p>
<p id="scriptTagXML">When an <span>XML parser</span> with <span>XML scripting support
enabled</span> creates a <code>script</code> element, it must have its <span>parser
document</span> set and its <span data-x="script-force-async">force async</span> set to false. If
the parser was created as part of the <span>XML fragment parsing algorithm</span>, then the
element's <span>already started</span> must be set to true. When the element's end tag is
subsequently parsed, the user agent must <span>perform a microtask checkpoint</span>, and then
<span data-x="prepare the script element">prepare</span> the <code>script</code> element. If this
causes there to be a <span>pending parsing-blocking script</span>, then the user agent must run
the following steps:</p>
<ol>
<li><p>Block this instance of the <span>XML parser</span>, such that the <span>event loop</span>
will not run <span data-x="concept-task">tasks</span> that invoke it.</p></li>
<li><p><span>Spin the event loop</span> until the parser's <code>Document</code> <span>has no
style sheet that is blocking scripts</span> and the <span>pending parsing-blocking
script</span>'s <span>ready to be parser-executed</span> is true.</p></li>
<li><p>Unblock this instance of the <span>XML parser</span>, such that <span
data-x="concept-task">tasks</span> that invoke it can again be run.</p></li>
<li><p><span>Execute the script element</span> given by the <span>pending parsing-blocking
script</span>.</p></li>
<li><p>Set the <span>pending parsing-blocking script</span> to null.</p></li>
</ol>
<p class="note">Since the <code data-x="dom-document-write">document.write()</code> API is not
available for <span>XML documents</span>, much of the complexity in the <span>HTML parser</span>
is not needed in the <span>XML parser</span>.</p>
<p class="note">When the <span>XML parser</span> has <span>XML scripting support disabled</span>,
none of this happens.</p>
<p id="templateTagXML">When an <span>XML parser</span> would append a node to a
<code>template</code> element, it must instead append it to the <code>template</code> element's
<span>template contents</span> (a <code>DocumentFragment</code> node).</p>
<p class="note">This is a <span>willful violation</span> of <cite>XML</cite>; unfortunately,
XML is not formally extensible in the manner that is needed for <code>template</code> processing.
<ref>XML</ref></p>
<p>When an <span>XML parser</span> creates a <code>Node</code> object, its <span>node document</span>
must be set to the <span>node document</span> of
the node into which the newly created node is to be inserted.</p>
<p>Certain algorithms in this specification <dfn data-x="feed the parser">spoon-feed the
parser</dfn> characters one string at a time. In such cases, the <span>XML parser</span> must act
as it would have if faced with a single string consisting of the concatenation of all those
characters.</p>
<p>When an <span>XML parser</span> reaches the end of its input, it must <span>stop
parsing</span>, following the same rules as the <span>HTML parser</span>. An <span>XML
parser</span> can also be <span data-x="abort a parser">aborted</span>, which must again be done in
the same way as for an <span>HTML parser</span>.</p>
<p>For the purposes of conformance checkers, if a resource is determined to be in <span>the XML
syntax</span>, then it is an <span data-x="XML documents">XML document</span>.</p>
<!--//HTMLPARSER-->
<!--en-GB--><h3 id="serialising-xhtml-fragments">Serializing XML fragments</h3>
<p>The <!--en-GB--><dfn id="xml-fragment-serialisation-algorithm">XML fragment serialization
algorithm</dfn> for a <code>Document</code> or <code>Element</code> node either returns a fragment
of XML that represents that node or throws an exception.</p>
<p>For <code>Document</code>s, the algorithm must return a string in the form of a <a
href="https://www.w3.org/TR/xml/#sec-well-formed">document entity</a>, if none of the error cases
below apply.</p>
<p>For <code>Element</code>s, the algorithm must return a string in the form of an <a
href="https://www.w3.org/TR/xml/#wf-entities">internal general parsed entity</a>, if none of the
error cases below apply.</p>
<p>In both cases, the string returned must be XML namespace-well-formed and must be an isomorphic
serialization of all of that node's <span>relevant child nodes</span>, in <span>tree order</span>.
User agents may adjust prefixes and namespace declarations in the serialization (and indeed might
be forced to do so in some cases to obtain namespace-well-formed XML). User agents may use a
combination of regular text and character references to represent <code>Text</code> nodes in the
DOM.</p>
<p>A node's <dfn>relevant child nodes</dfn> are those that apply given the following rules:</p>
<dl>
<dt>For <code>template</code> elements</dt>
<dd>The <span>relevant child nodes</span> are the child nodes of the <code>template</code>
element's <span>template contents</span>, if any.</dd>
<dt>For all other nodes</dt>
<dd>The <span>relevant child nodes</span> are the child nodes of node itself, if any.</dd>
</dl>
<p>For <code>Element</code>s, if any of the elements in the serialization are in no namespace, the
default namespace in scope for those elements must be explicitly declared as the empty string.<!--
because otherwise round-tripping might break since it'll pick up the surrounding default ns when
setting --> (This doesn't apply in the <code>Document</code> case.) <ref>XML</ref>
<ref>XMLNS</ref></p>
<p>For the purposes of this section, an internal general parsed entity is considered XML
namespace-well-formed if a document consisting of an element with no namespace declarations whose
contents are the internal general parsed entity would itself be XML namespace-well-formed.</p>
<p>If any of the following error cases are found in the DOM subtree being serialized, then the
algorithm must throw an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code>
instead of returning a string:</p>
<ul>
<li>A <code>Document</code> node with no child element nodes.</li>
<li>A <code>DocumentType</code> node that has an external subset public identifier that contains
characters that are not matched by the XML <code data-x="">PubidChar</code> production. <ref>XML</ref></li>
<li>A <code>DocumentType</code> node that has an external subset system identifier that contains
both a U+0022 QUOTATION MARK (") and a U+0027 APOSTROPHE (') or that contains characters that are
not matched by the XML <code data-x="">Char</code> production. <ref>XML</ref></li>
<li>A node with a <!--prefix or--> local name containing a U+003A COLON (:).</li> <!--(prefixes
can get adjusted, so this isn't an excuse) -->
<li>A node with a <!--prefix or--> local name that does not match the XML <code
data-x="xml-Name">Name</code> production. <ref>XML</ref></li> <!--(again, prefixes can get
adjusted, so this isn't an excuse) -->
<li>An <code>Attr</code> node with no namespace whose local name is the lowercase string "<code
data-x="">xmlns</code>". <ref>XMLNS</ref></li>
<li>An <code>Element</code> node with two or more attributes with the same local name and
namespace.</li>
<li>An <code>Attr</code> node, <code>Text</code> node, <code>Comment</code> node, or
<code>ProcessingInstruction</code> node whose data contains characters that are not matched by
the XML <code data-x="">Char</code> production. <ref>XML</ref></li>
<li>A <code>Comment</code> node whose data contains two adjacent U+002D HYPHEN-MINUS characters
(-) or ends with such a character.</li>
<li>A <code>ProcessingInstruction</code> node whose target name is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">xml</code>".</li>
<li>A <code>ProcessingInstruction</code> node whose target name contains a U+003A COLON (:).</li>
<li>A <code>ProcessingInstruction</code> node whose data contains the string "<code
data-x="">?></code>".</li>
</ul>
<p class="note">These are the only ways to make a DOM unserialisable. The DOM enforces all the
other XML constraints; for example, trying to append two elements to a <code>Document</code> node
will throw a <span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</p>
<h3 id="parsing-xhtml-fragments">Parsing XML fragments</h3>
<p>The <dfn>XML fragment parsing algorithm</dfn> given an <code>Element</code> node <var
data-x="concept-frag-parse-context">context</var> and a string <var>input</var>, runs the
following steps. They return a list of nodes.</p>
<ol>
<li><p>Create a new <span>XML parser</span>.</p></li>
<li>
<p><span>Feed the parser</span> just created the string corresponding to the start tag of <var
data-x="concept-frag-parse-context">context</var>, declaring all the namespace prefixes that are
in scope on that element in the DOM, as well as declaring the default namespace (if any) that is
in scope on that element in the DOM.</p>
<p>A namespace prefix is in scope if the DOM <code data-x="">lookupNamespaceURI()</code> method
on the element would return a non-null value for that prefix.</p>
<p>The default namespace is the namespace for which the DOM <code
data-x="">isDefaultNamespace()</code> method on the element would return true.</p>
<p class="note">No <code data-x="">DOCTYPE</code> is passed to the parser, and therefore no
external subset is referenced, and therefore no entities will be recognized.</p>
</li>
<li><p><span>Feed the parser</span> just created the string <var>input</var>.</p></li>
<li><p><span>Feed the parser</span> just created the string corresponding to the end tag of <var
data-x="concept-frag-parse-context">context</var>.</p></li>
<li><p>If there is an XML well-formedness or XML namespace well-formedness error, then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If the <span>document element</span> of the resulting <code>Document</code> has any
sibling nodes, then throw a <span>"<code>SyntaxError</code>"</span>
<code>DOMException</code>.</p></li>
<!-- This is technically redundant, but apparently it has gone wrong in the past:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1443 -->
<li><p>Return the resulting <code>Document</code> node's <span>document element</span>'s <span
data-x="concept-tree-child">children</span>, in <span>tree order</span>.</p></li>
</ol>
</div>
<div w-nodev>
<h2 split-filename="rendering" id="rendering">Rendering</h2>
<p><i>User agents are not required to present HTML documents in any particular way. However, this
section provides a set of suggestions for rendering HTML documents that, if followed, are likely
to lead to a user experience that closely resembles the experience intended by the documents'
authors. So as to avoid confusion regarding the normativity of this section, "must" has not been
used. Instead, the term "expected" is used to indicate behavior that will lead to this experience.
For the purposes of conformance for user agents designated as <a href="#renderingUA">supporting
the suggested default rendering</a>, the term "expected" in this section has the same conformance
implications as "must".</i></p>
<h3>Introduction</h3>
<p>The suggestions in this section are generally expressed in CSS terms. User agents are expected
to either support CSS, or translate from the CSS rules given in this section to approximations for
other presentation mechanisms.</p>
<p>In the absence of style-layer rules to the contrary (e.g. author style sheets), user agents are
expected to render an element so that it conveys to the user the meaning that the element
<span>represents</span>, as described by this specification.</p>
<p>The suggestions in this section generally assume a visual output medium with a resolution of
96dpi or greater, but HTML is intended to apply to multiple media (it is a
<i>media-independent</i> language). User agent implementers are encouraged to adapt the
suggestions in this section to their target media.</p>
<hr>
<p>An element is <dfn export>being rendered</dfn> if it has any associated CSS layout boxes, SVG
layout boxes, or some equivalent in other styling languages.</p>
<p class="note">Just being off-screen does not mean the element is not <span>being
rendered</span>. The presence of the <code data-x="attr-hidden">hidden</code> attribute normally
means the element is not <span>being rendered</span>, though this might be overridden by the style
sheets.</p>
<p class="note">The <span>fully active</span> state does not affect whether an element is
<span>being rendered</span> or not. Even if a document is not <span>fully active</span> and not
shown at all to the user, elements within it can still qualify as "being rendered".</p>
<p>An element is said to <dfn>intersect the viewport</dfn> when it is <span>being rendered</span>
and its associated CSS layout box intersects the <span>viewport</span>.</p>
<p class="note">Similar to the <span>being rendered</span> state, elements in non-<span>fully
active</span> documents can still <span>intersect the viewport</span>. The <span>viewport</span>
is not shared between documents and might not always be shown to the user, so an element in a
non-<span>fully active</span> document can still intersect the <span>viewport</span> associated
with its document.</p>
<p class="note">This specification does not define the precise timing for when the intersection is
tested, but it is suggested that the timing match that of the Intersection Observer API. <ref>INTERSECTIONOBSERVER</ref></p>
<p>An element is <dfn>delegating its rendering to its children</dfn> if it is not <span>being
rendered</span> but its children (if any) could <span data-x="being rendered">be rendered</span>,
as a result of CSS 'display: contents', or some equivalent in other styling languages.
<ref>CSSDISPLAY</ref></p>
<hr>
<p>User agents that do not honor author-level CSS style sheets are nonetheless expected to act as
if they applied the CSS rules given in these sections in a manner consistent with this
specification and the relevant CSS and Unicode specifications. <ref>CSS</ref> <ref>UNICODE</ref>
<ref>BIDI</ref></p>
<p class="note">This is especially important for issues relating to the <span>'display'</span>,
<span>'unicode-bidi'</span>, and <span>'direction'</span> properties.</p>
<h3>The CSS user agent style sheet and presentational hints</h3>
<p>The CSS rules given in these subsections are, except where otherwise specified, expected to be
used as part of the user-agent level style sheet defaults for all documents that contain
<span>HTML elements</span>.</p>
<p>Some rules are intended for the author-level zero-specificity presentational hints part of the
CSS cascade; these are explicitly called out as <dfn data-lt="presentational hint"
export>presentational hints</dfn>.</p>
<hr>
<p>When the text below says that an attribute <var>attribute</var> on an element
<var>element</var> <dfn>maps to the pixel length property</dfn> (or properties)
<var>properties</var>, it means that if <var>element</var> has an attribute <var>attribute</var>
set, and parsing that attribute's value using the <span>rules for parsing non-negative
integers</span> doesn't generate an error, then the user agent is expected to use the parsed value
as a pixel length for a <span data-x="presentational hints">presentational hint</span> for
<var>properties</var>.</p>
<p>When the text below says that an attribute <var>attribute</var> on an element
<var>element</var> <dfn>maps to the dimension property</dfn> (or properties)
<var>properties</var>, it means that if <var>element</var> has an attribute <var>attribute</var>
set, and parsing that attribute's value using the <span>rules for parsing dimension values</span>
doesn't generate an error, then the user agent is expected to use the parsed dimension as the
value for a <span data-x="presentational hints">presentational hint</span> for
<var>properties</var>, with the value given as a pixel length if the dimension was a length, and
with the value given as a percentage if the dimension was a percentage.</p>
<p>When the text below says that an attribute <var>attribute</var> on an element
<var>element</var> <dfn>maps to the dimension property (ignoring zero)</dfn> (or properties)
<var>properties</var>, it means that if <var>element</var> has an attribute <var>attribute</var>
set, and parsing that attribute's value using the <span>rules for parsing nonzero dimension
values</span> doesn't generate an error, then the user agent is expected to use the parsed
dimension as the value for a <span data-x="presentational hints">presentational hint</span> for
<var>properties</var>, with the value given as a pixel length if the dimension was a length, and
with the value given as a percentage if the dimension was a percentage.</p>
<p>When the text below says that a pair of attributes <var>w</var> and <var>h</var> on an
element <var>element</var> <dfn>map to the aspect-ratio property</dfn>, it means that if
<var>element</var> has both attributes <var>w</var> and <var>h</var>, and parsing those
attributes' values using the <span>rules for parsing non-negative integers</span> doesn't
generate an error for either, then the user agent is expected to use the parsed integers as a
<span data-x="presentational hints">presentational hint</span> for the <span>'aspect-ratio'</span>
property of the form <code data-x="">auto <var>w</var> / <var>h</var></code>.</p>
<p>When the text below says that a pair of attributes <var>w</var> and <var>h</var> on an
element <var>element</var> <dfn>map to the aspect-ratio property (using dimension rules)</dfn>, it
means that if <var>element</var> has both attributes <var>w</var> and <var>h</var>, and parsing
those attributes' values using the <span>rules for parsing dimension values</span> doesn't
generate an error or return a percentage for either, then the user agent is expected to use the
parsed dimensions as a <span data-x="presentational hints">presentational hint</span> for the
<span>'aspect-ratio'</span> property of the form <code data-x="">auto
<var>w</var> / <var>h</var></code>.</p>
<p>When a user agent is to <dfn>align descendants</dfn> of a node, the user agent is expected to
align only those descendants that have both their <span>'margin-inline-start'</span> and
<span>'margin-inline-end'</span> properties computing to a value other than 'auto', that are
over-constrained and that have one of those two margins with a <span>used value</span> forced to a
greater value, and that do not themselves have an applicable <code data-x="">align</code>
attribute. When multiple elements are to <span data-x="align descendants">align</span> a
particular descendant, the most deeply nested such element is expected to override the others.
Aligned elements are expected to be aligned by having the <span data-x="used value">used
values</span> of their margins on the <span>line-left</span> and <span>line-right</span> sides be
set accordingly. <ref>CSSLOGICAL</ref> <ref>CSSWM</ref></p>
<h3>Non-replaced elements</h3>
<h4>Hidden elements</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
area, base, basefont, datalist, head, link, meta, noembed,
noframes, param, rp, script, style, template, title {
display: none;
}
<span id="hiddenCSS" data-x="">[hidden]:not([hidden=until-found i]):not(embed)</span> {
display: none;
}
[hidden=until-found i]:not(embed) {
content-visibility: hidden;
}
embed[hidden] { display: inline; height: 0; width: 0; } <!-- because for legacy reasons it still needs to instantiate the plugin -->
input[type=hidden i] { display: none !important; }
@media (scripting) {
noscript { display: none !important; }
}</code></pre>
<h4>The page</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
html, body { display: block; }</code></pre>
<!-- body { margin: 8px; } -->
<p>For each property in the table below, given a <code>body</code> element, the first attribute
that exists <span>maps to the pixel length property</span> on the <code>body</code> element. If
none of the attributes for a property are found, or if the value of the attribute that was found
cannot be parsed successfully, then a default value of 8px is expected to be used for that
property instead.</p>
<table>
<thead>
<tr>
<th>Property
<th>Source
<tbody>
<tr>
<td rowspan="3"><span>'margin-top'</span>
<td>The <code>body</code> element's <code data-x="attr-body-marginheight">marginheight</code> attribute
<tr>
<td>The <code>body</code> element's <code data-x="attr-body-topmargin">topmargin</code> attribute
<tr>
<td>The <code>body</code> element's <span>container frame element</span>'s <code data-x="attr-iframe-marginheight">marginheight</code> attribute
<tbody>
<tr>
<td rowspan="3"><span>'margin-right'</span>
<td>The <code>body</code> element's <code data-x="attr-body-marginwidth">marginwidth</code> attribute
<tr>
<td>The <code>body</code> element's <code data-x="attr-body-rightmargin">rightmargin</code> attribute
<tr>
<td>The <code>body</code> element's <span>container frame element</span>'s <code data-x="attr-iframe-marginwidth">marginwidth</code> attribute
<tbody>
<tr>
<td rowspan="3"><span>'margin-bottom'</span>
<td>The <code>body</code> element's <code data-x="attr-body-marginheight">marginheight</code> attribute
<tr>
<td>The <code>body</code> element's <code data-x="attr-body-bottommargin">bottommargin</code> attribute
<tr>
<td>The <code>body</code> element's <span>container frame element</span>'s <code data-x="attr-iframe-marginheight">marginheight</code> attribute
<tbody>
<tr>
<td rowspan="3"><span>'margin-left'</span>
<td>The <code>body</code> element's <code data-x="attr-body-marginwidth">marginwidth</code> attribute
<tr>
<td>The <code>body</code> element's <code data-x="attr-body-leftmargin">leftmargin</code> attribute
<tr>
<td>The <code>body</code> element's <span>container frame element</span>'s <code data-x="attr-iframe-marginwidth">marginwidth</code> attribute
</table>
<p>If the <code>body</code> element's <span>node document</span>'s <span>node navigable</span> is
a <span>child navigable</span>, and the <span data-x="nav-container">container</span> of that
<span>navigable</span> is a <code>frame</code> or <code>iframe</code> element, then the
<dfn>container frame element</dfn> of the <code>body</code> element is that <code>frame</code> or
<code>iframe</code> element. Otherwise, there is no <span>container frame element</span>.</p>
<p class="warning">The above requirements imply that a page can change the margins of another page
(including one from another <span>origin</span>) using, for example, an <code>iframe</code>. This
is potentially a security risk, as it might in some cases allow an attack to contrive a situation
in which a page is rendered not as the author intended, possibly for the purposes of phishing or
otherwise misleading the user.</p>
<hr>
<p>If a <code>Document</code>'s <span>node navigable</span> is a <span>child navigable</span>,
then it is expected to be positioned and sized to fit inside the <span>content box</span> of the
<span data-x="nav-container">container</span> of that <span>navigable</span>. If the <span
data-x="nav-container">container</span> is not <span>being rendered</span>, the
<span>navigable</span> is expected to have a <span>viewport</span> with zero width and zero
height.</p>
<p>If a <code>Document</code>'s <span>node navigable</span> is a <span>child navigable</span>,
the <span data-x="nav-container">container</span> of that <span>navigable</span> is a
<code>frame</code> or <code>iframe</code> element, that element has a <code
data-x="">scrolling</code> attribute, and that attribute's value is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">off</code>", "<code
data-x="">noscroll</code>", or "<code data-x="">no</code>", then the user agent is expected to
prevent any scrollbars from being shown for the <span>viewport</span> of the
<code>Document</code>'s <span>node navigable</span>, regardless of the <span>'overflow'</span>
property that applies to that <span>viewport</span>.</p>
<hr>
<p>When a <code>body</code> element has a <code data-x="attr-background">background</code>
attribute set to a non-empty value, the new value is expected to be <span
data-x="encoding-parsing-and-serializing a URL">encoding-parsed-and-serialized</span> relative to
the element's <span>node document</span>, and if that does not return failure, the user agent is
expected to treat the attribute as a <span data-x="presentational hints">presentational
hint</span> setting the element's <span>'background-image'</span> property to the return
value.</p>
<p>When a <code>body</code> element has a <code data-x="attr-body-bgcolor">bgcolor</code>
attribute set, the new value is expected to be parsed using the <span>rules for parsing a legacy
color value</span>, and if that does not return failure, the user agent is expected to treat the
attribute as a <span data-x="presentational hints">presentational hint</span> setting the
element's <span>'background-color'</span> property to the resulting color.</p>
<p>When a <code>body</code> element has a <code data-x="attr-body-text">text</code> attribute, its
value is expected to be parsed using the <span>rules for parsing a legacy color value</span>, and
if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the element's
<span>'color'</span> property to the resulting color.</p>
<p>When a <code>body</code> element has a <code data-x="attr-body-link">link</code> attribute, its
value is expected to be parsed using the <span>rules for parsing a legacy color value</span>, and
if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the <span>'color'</span> property
of any element in the <code>Document</code> matching the <code data-x="selector-link">:link</code>
<span>pseudo-class</span> to the resulting color.</p>
<p>When a <code>body</code> element has a <code data-x="attr-body-vlink">vlink</code> attribute,
its value is expected to be parsed using the <span>rules for parsing a legacy color value</span>,
and if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the <span>'color'</span> property
of any element in the <code>Document</code> matching the <code
data-x="selector-visited">:visited</code> <span>pseudo-class</span> to the resulting color.</p>
<p>When a <code>body</code> element has an <code data-x="attr-body-alink">alink</code> attribute,
its value is expected to be parsed using the <span>rules for parsing a legacy color value</span>,
and if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the <span>'color'</span> property
of any element in the <code>Document</code> matching the
<code data-x="selector-active">:active</code> <span>pseudo-class</span> and either the <code
data-x="selector-link">:link</code> <span>pseudo-class</span> or the <code
data-x="selector-visited">:visited</code> <span>pseudo-class</span> to the resulting color.</p>
<h4>Flow content</h4>
<!-- del, ins, and map are inline. -->
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
address, blockquote, center, dialog, div, figure, figcaption, footer, form,
header, hr, legend, listing, main, p, plaintext, pre, search, xmp {
display: block;<!-- see also unicode-bidi: isolate rules-->
}
blockquote, figure, listing, p, plaintext, pre, xmp {
margin-block: 1em;
}
blockquote, figure { margin-inline: 40px; }
address { font-style: italic; }
listing, plaintext, pre, xmp {
font-family: monospace; white-space: pre;
}
dialog:not([open]) { display: none; }
dialog {
position: absolute;
inset-inline-start: 0; inset-inline-end: 0;
width: fit-content;
height: fit-content;
margin: auto;
border: solid;
padding: 1em;
background-color: Canvas;
color: CanvasText;
}
dialog:modal {
position: fixed;
overflow: auto;
inset-block: 0;
max-width: calc(100% - 6px - 2em);
max-height: calc(100% - 6px - 2em);
}
dialog::backdrop {
background: rgba(0,0,0,0.1);
}
[popover]:not(:popover-open):not(dialog[open]) {
display:none;
}
dialog:popover-open {
display:block;
}
[popover] {
position: fixed;
inset: 0;
width: fit-content;
height: fit-content;
margin: auto;
border: solid;
padding: 0.25em;
overflow: auto;
color: CanvasText;
background-color: Canvas;
}
:popover-open::backdrop {
position: fixed;
inset: 0;
pointer-events: none !important;
background-color: transparent;
}
slot {
display: contents;
}</code></pre>
<p>The following rules are also expected to apply, as <span>presentational hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
pre[wrap] { white-space: pre-wrap; }</code></pre>
<p>In <span>quirks mode</span>, the following rules are also expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
form { margin-block-end: 1em; }</code></pre>
<hr>
<p>The <code>center</code> element, and the <code>div</code> element when it has an <code
data-x="attr-div-align">align</code> attribute whose value is an <span>ASCII
case-insensitive</span> match for either the string "<code data-x="">center</code>" or the string
"<code data-x="">middle</code>", are expected to center text within themselves, as if they had
their <span>'text-align'</span> property set to 'center' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the center.</p>
<p>The <code>div</code> element, when it has an <code data-x="attr-div-align">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">left</code>", is expected to left-align text within itself, as if it had its
<span>'text-align'</span> property set to 'left' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the left.</p>
<p>The <code>div</code> element, when it has an <code data-x="attr-div-align">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">right</code>", is expected to right-align text within itself, as if it had its
<span>'text-align'</span> property set to 'right' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the right.</p>
<p>The <code>div</code> element, when it has an <code data-x="attr-div-align">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">justify</code>", is expected to full-justify text within itself, as if it had its
<span>'text-align'</span> property set to 'justify' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the left.</p>
<h4>Phrasing content</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
cite, dfn, em, i, var { font-style: italic; }
b, strong { font-weight: bolder; }
code, kbd, samp, tt { font-family: monospace; }
big { font-size: larger; }
small { font-size: smaller; }
sub { vertical-align: sub; }
sup { vertical-align: super; }
sub, sup { line-height: normal; font-size: smaller; }
ruby { display: ruby; }
rt { display: ruby-text; }
:link { color: #0000EE; }
:visited { color: #551A8B; }
:link:active, :visited:active { color: #FF0000; }
:link, :visited { text-decoration: underline; cursor: pointer; }
:focus-visible { outline: auto; }
mark { background: yellow; color: black; } /* this color is just a suggestion and can be changed based on implementation feedback */
abbr[title], acronym[title] { text-decoration: dotted underline; }<!-- CSS3 https://drafts.csswg.org/css3-text/#text-decoration-style -->
ins, u { text-decoration: underline; }
del, s, strike { text-decoration: line-through; }
q::before { content: open-quote; }
q::after { content: close-quote; }
<span data-x="" id="br-wbr-content">br { display-outside: newline; } /* <a href="#bidi-rendering">this also has bidi implications</a> */
nobr { white-space: nowrap; }
wbr { display-outside: break-opportunity; } /* <a href="#bidi-rendering">this also has bidi implications</a> */
nobr wbr { white-space: normal; }</span></code></pre>
<p>The following rules are also expected to apply, as
<span>presentational hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
br[clear=left i] { clear: left; }
br[clear=right i] { clear: right; }
br[clear=all i], br[clear=both i] { clear: both; }</code></pre>
<p>For the purposes of the CSS ruby model, runs of children of <code>ruby</code> elements that are
not <code>rt</code> or <code>rp</code> elements are expected to be wrapped in anonymous boxes
whose <span>'display'</span> property has the value <span>'ruby-base'</span>. <ref>CSSRUBY</ref></p>
<p>When a particular part of a ruby has more than one annotation, the annotations should be
distributed on both sides of the base text so as to minimize the stacking of ruby annotations on
one side.</p>
<p class="note">When it becomes possible to do so, the preceding requirement will be updated to be
expressed in terms of CSS ruby. (Currently, CSS ruby does not handle nested <code>ruby</code>
elements or multiple sequential <code>rt</code> elements, which is how this semantic is
expressed.)</p>
<p>User agents that do not support correct ruby rendering are expected to render parentheses
around the text of <code>rt</code> elements in the absence of <code>rp</code> elements.</p>
<hr>
<p>User agents are expected to support the <span>'clear'</span> property on inline elements (in
order to render <code>br</code> elements with <code data-x="attr-br-clear">clear</code>
attributes) in the manner described in the non-normative note to this effect in <cite>CSS</cite>.
</p> <!-- section 9.5.2 of CSS2.1 -->
<p>The initial value for the <span>'color'</span> property is expected to be black. The initial
value for the <span>'background-color'</span> property is expected to be 'transparent'. The
canvas's background is expected to be white.</p>
<hr>
<p>When a <code>font</code> element has a <code data-x="attr-font-color" undefined>color</code>
attribute, its value is expected to be parsed using the <span>rules for parsing a legacy color
value</span>, and if that does not return failure, the user agent is expected to treat the
attribute as a <span data-x="presentational hints">presentational hint</span> setting the
element's <span>'color'</span> property to the resulting color.</p>
<p>When a <code>font</code> element has a <code data-x="attr-font-face" undefined>face</code>
attribute, the user agent is expected to treat the attribute as a <span data-x="presentational
hints">presentational hint</span> setting the element's <span>'font-family'</span> property to the
attribute's value.</p>
<!-- (Apparently only IE supports this?) (Note: if you add this back, make sure to define which of
'size' vs 'pointsize' wins.)
<p>When a <code>font</code> element has a <code data-x="attr-font-pointsize"
undefined>pointsize</code> attribute, the user agent is expected to parse that attribute's value
using the <span>rules for parsing non-negative integers</span>, and if this doesn't generate an
error, then the user agent is expected to use the parsed value as a <em>point</em> length for a
<span data-x="presentational hints">presentational hint</span> for the <span>'font-size'</span>
property on the element.</p>
-->
<p>When a <code>font</code> element has a <code data-x="attr-font-size" undefined>size</code>
attribute, the user agent is expected to use the following steps, known as the <dfn>rules for
parsing a legacy font size</dfn>, to treat the attribute as a <span data-x="presentational
hints">presentational hint</span> setting the element's <span>'font-size'</span> property:</p>
<ol>
<li><p>Let <var>input</var> be the attribute's value.</p></li>
<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially pointing at the
start of the string.</p></li>
<li><p><span>Skip ASCII whitespace</span> within <var>input</var> given
<var>position</var>.</p></li>
<li><p>If <var>position</var> is past the end of <var>input</var>, there is no <span
data-x="presentational hints">presentational hint</span>. Return.</p></li>
<li><p>If the character at <var>position</var> is a U+002B PLUS SIGN character (+), then let
<var>mode</var> be <i>relative-plus</i>, and advance <var>position</var> to the next character.
Otherwise, if the character at <var>position</var> is a U+002D HYPHEN-MINUS character (-), then
let <var>mode</var> be <i>relative-minus</i>, and advance <var>position</var> to the next
character. Otherwise, let <var>mode</var> be <i>absolute</i>.</p></li>
<li><p><span>Collect a sequence of code points</span> that are <span>ASCII digits</span> from
<var>input</var> given <var>position</var>, and let the resulting sequence be
<var>digits</var>.</p></li>
<li><p>If <var>digits</var> is the empty string, there is no <span data-x="presentational
hints">presentational hint</span>. Return.</p></li>
<li><p>Interpret <var>digits</var> as a base-ten integer. Let <var>value</var> be the resulting
number.</p></li>
<li>
<!-- basefont support would go here, but we removed it -->
<p>If <var>mode</var> is <i>relative-plus</i>, then increment <var>value</var> by 3. If
<var>mode</var> is <i>relative-minus</i>, then let <var>value</var> be the result of subtracting
<var>value</var> from 3.</p>
</li>
<li><p>If <var>value</var> is greater than 7, let it be 7.</p></li>
<li><p>If <var>value</var> is less than 1, let it be 1.</p></li>
<li>
<p>Set <span>'font-size'</span> to the keyword corresponding to the value of <var>value</var>
according to the following table:</p>
<table>
<thead>
<tr>
<th><var>value</var>
<th><span>'font-size'</span> keyword
<tbody>
<tr>
<td>1
<td>'x-small'
<tr>
<td>2
<td>'small'
<tr>
<td>3
<td>'medium'
<tr>
<td>4
<td>'large'
<tr>
<td>5
<td>'x-large'
<tr>
<td>6
<td>'xx-large'
<tr>
<td>7
<td>'xxx-large'
</table>
</li>
</ol>
<h4 id="bidi-rendering">Bidirectional text</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
[dir]:dir(ltr), bdi:dir(ltr), input[type=tel i]:dir(ltr) { direction: ltr; }
[dir]:dir(rtl), bdi:dir(rtl) { direction: rtl; }
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, bdi, output,
[dir=ltr i], [dir=rtl i], [dir=auto i] {
unicode-bidi: isolate; <!-- anything that's similar to display:block, plus <bdi>, <output>, and dir="" -->
}
bdo, bdo[dir] { unicode-bidi: isolate-override; } <!-- bdo[dir] rule is to override the otherwise higher-specificity attribute selectors in the previous rule -->
input[dir=auto i]:is([type=search i], [type=tel i], [type=url i],
[type=email i]), textarea[dir=auto i], pre[dir=auto i] {
unicode-bidi: plaintext;
}
/* see prose for input elements whose type attribute is in the Text state */
/* the <a href="#br-wbr-content">rules setting the 'content' property</a> on <code>br</code> and <code>wbr</code> elements also has bidi implications */</code></pre>
<p>When an <code>input</code> element's <code data-x="attr-dir">dir</code> attribute is in the
<span data-x="attr-dir-auto">auto</span> state and its <code data-x="attr-input-type">type</code>
attribute is in the <span data-x="attr-input-type-text">Text</span> state, then the user agent is
expected to act as if it had a user-agent-level style sheet rule setting the
<span>'unicode-bidi'</span> property to 'plaintext'.</p>
<p>Input fields (i.e. <code>textarea</code> elements, and <code>input</code> elements when their
<code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-text">Text</span>, <span data-x="attr-input-type-search">Search</span>,
<span data-x="attr-input-type-tel">Telephone</span>, <span data-x="attr-input-type-url">URL</span>,
or <span data-x="attr-input-type-email">Email</span> state) are expected to present an editing
user interface with a directionality that matches the element's <span>'direction'</span>
property.</p>
<p>When the document's character encoding is <span>ISO-8859-8</span>, the following rules are
additionally expected to apply, following those above: <ref>ENCODING</ref></p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, [dir=ltr i],
[dir=rtl i], [dir=auto i], *|* {
unicode-bidi: bidi-override;
}
input:not([type=submit i]):not([type=reset i]):not([type=button i]),
textarea {
unicode-bidi: normal;
}</code></pre>
<h4>Sections and headings</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
article, aside, h1, h2, h3, h4, h5, h6, hgroup, nav, section {
display: block;<!-- see also unicode-bidi: isolate rules-->
}
h1 { margin-block: 0.67em; font-size: 2.00em; font-weight: bold; }
h2 { margin-block: 0.83em; font-size: 1.50em; font-weight: bold; }
h3 { margin-block: 1.00em; font-size: 1.17em; font-weight: bold; }
h4 { margin-block: 1.33em; font-size: 1.00em; font-weight: bold; }
h5 { margin-block: 1.67em; font-size: 0.83em; font-weight: bold; }
h6 { margin-block: 2.33em; font-size: 0.67em; font-weight: bold; }</code></pre>
<p>In the following CSS block, <var>x</var> is shorthand for the following selector:
<code data-x="">:is(article, aside, nav, section)</code></p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
<var>x</var> h1 { margin-block: 0.83em; font-size: 1.50em; }
<var>x</var> <var>x</var> h1 { margin-block: 1.00em; font-size: 1.17em; }
<var>x</var> <var>x</var> <var>x</var> h1 { margin-block: 1.33em; font-size: 1.00em; }
<var>x</var> <var>x</var> <var>x</var> <var>x</var> h1 { margin-block: 1.67em; font-size: 0.83em; }
<var>x</var> <var>x</var> <var>x</var> <var>x</var> <var>x</var> h1 { margin-block: 2.33em; font-size: 0.67em; }</code></pre>
<p class="note">The shorthand is used to keep this block at least mildly readable.</p>
<h4>Lists</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
dir, dd, dl, dt, menu, ol, ul { display: block; }<!-- see also unicode-bidi:isolate rules -->
li { display: list-item; text-align: match-parent; }<!-- see also unicode-bidi:isolate rules -->
dir, dl, menu, ol, ul { margin-block: 1em; }
:is(dir, dl, menu, ol, ul) :is(dir, dl, menu, ol, ul) {
margin-block: 0;
}
dd { margin-inline-start: 40px; }
dir, menu, ol, ul { padding-inline-start: 40px; }
ol, ul, menu { counter-reset: list-item; }
ol { list-style-type: decimal; }
dir, menu, ul {
list-style-type: disc;
}
:is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type: circle;
}
:is(dir, menu, ol, ul) :is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type: square;
}</code></pre>
<p id="decohints">The following rules are also expected to apply, as <span>presentational
hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
ol[type="1"], li[type="1"] { list-style-type: decimal; }
ol[type=a <!--grammar-check-override-->s], li[type=a <!--grammar-check-override-->s] { list-style-type: lower-alpha; }
ol[type=A <!--grammar-check-override-->s], li[type=A <!--grammar-check-override-->s] { list-style-type: upper-alpha; }
ol[type=i s], li[type=i s] { list-style-type: lower-roman; }
ol[type=I s], li[type=I s] { list-style-type: upper-roman; }
ul[type=none i], li[type=none i] { list-style-type: none; }
ul[type=disc i], li[type=disc i] { list-style-type: disc; }
ul[type=circle i], li[type=circle i] { list-style-type: circle; }
ul[type=square i], li[type=square i] { list-style-type: square; }</code></pre>
<p>In <span>quirks mode</span>, the following rules are also expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
li { list-style-position: inside; }
li :is(dir, menu, ol, ul) { list-style-position: outside; }
:is(dir, menu, ol, ul) :is(dir, menu, ol, ul, li) { list-style-position: unset; }</code></pre>
<p>When rendering <code>li</code> elements, non-CSS user agents are expected to use the
<span>ordinal value</span> of the <code>li</code> element to render the counter in the list item
marker.</p>
<p id="css-list-rendering">For CSS user agents, some aspects of rendering <span
data-x="css-list-item">list items</span> are defined by the <cite>CSS Lists</cite> specification.
Additionally, the following attribute mappings are expected to apply: <ref>CSSLISTS</ref></p>
<p>When an <code>li</code> element has a <code
data-x="attr-li-value">value</code> attribute, and parsing that attribute's value using the
<span>rules for parsing integers</span> doesn't generate an error, the user agent is expected to
use the parsed value <var>value</var> as a <span data-x="presentational hints">presentational
hint</span> for the <span>'counter-set'</span> property of the form <code data-x="">list-item
<var>value</var></code>.</p>
<p>When an <code>ol</code> element has a <code data-x="attr-ol-start">start</code>
attribute or a <code data-x="attr-ol-reversed">reversed</code> attribute, or both, the user agent
is expected to use the following steps to treat the attributes as a <span data-x="presentational
hints">presentational hint</span> for the <span>'counter-reset'</span> property:</p>
<ol>
<li><p>Let <var>value</var> be null.</p></li>
<li><p>If the element has a <code data-x="attr-ol-start">start</code> attribute, then set
<var>value</var> to the result of parsing the attribute's value using the <span>rules for
parsing integers</span>.</p></li>
<li>
<p>If the element has a <code data-x="attr-ol-reversed">reversed</code> attribute, then:</p>
<ol>
<li><p>If <var>value</var> is an integer, then increment <var>value</var> by 1 and return
<code data-x="">reversed(list-item) <var>value</var></code>.</p></li>
<li>
<p>Otherwise, return <code data-x="">reversed(list-item)</code>.</p>
<p class="note">Either the <code data-x="attr-ol-start">start</code> attribute was absent, or
parsing its value resulted in an error.</p>
</li>
</ol>
</li>
<li>
<p>Otherwise:</p>
<ol>
<li><p>If <var>value</var> is an integer, then decrement <var>value</var> by 1 and return
<code data-x="">list-item <var>value</var></code>.</p></li>
<li><p>Otherwise, there is no <span data-x="presentational hints">presentational
hint</span>.</p></li>
</ol>
</li>
</ol>
<h4>Tables</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
table { display: table; }<!-- see also unicode-bidi:isolate rules -->
caption { display: table-caption; }<!-- see also unicode-bidi:isolate rules -->
colgroup, colgroup[hidden] { display: table-column-group; }<!-- see also unicode-bidi:isolate rules -->
col, col[hidden] { display: table-column; }<!-- see also unicode-bidi:isolate rules -->
thead, thead[hidden] { display: table-header-group; }<!-- see also unicode-bidi:isolate rules -->
tbody, tbody[hidden] { display: table-row-group; }<!-- see also unicode-bidi:isolate rules -->
tfoot, tfoot[hidden] { display: table-footer-group; }<!-- see also unicode-bidi:isolate rules -->
tr, tr[hidden] { display: table-row; }<!-- see also unicode-bidi:isolate rules -->
td, th { display: table-cell; }<!-- see also unicode-bidi:isolate rules -->
colgroup[hidden], col[hidden], thead[hidden], tbody[hidden],
tfoot[hidden], tr[hidden] {
visibility: collapse;
}
table {
box-sizing: border-box;
border-spacing: 2px;
border-collapse: separate;
text-indent: initial;
}
td, th { padding: 1px; }
th { font-weight: bold; }
caption { text-align: center; }
thead, tbody, tfoot, table > tr { vertical-align: middle; }
tr, td, th { vertical-align: inherit; }
thead, tbody, tfoot, tr { border-color: inherit; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i], table[frame=void i],
table[frame=above i], table[frame=below i], table[frame=hsides i],
table[frame=lhs i], table[frame=rhs i], table[frame=vsides i],
table[frame=box i], table[frame=border i],
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-color: black;
}</code></pre>
<p>The following rules are also expected to apply, as <span>presentational hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
table[align=left i] { float: left; }
table[align=right i] { float: right; }
table[align=center i] { margin-inline: auto; }
thead[align=absmiddle i], tbody[align=absmiddle i], tfoot[align=absmiddle i],
tr[align=absmiddle i], td[align=absmiddle i], th[align=absmiddle i] {
text-align: center;
}
caption[align=bottom i] { caption-side: bottom; }
p[align=left i], h1[align=left i], h2[align=left i], h3[align=left i],
h4[align=left i], h5[align=left i], h6[align=left i] {
text-align: left;
}
p[align=right i], h1[align=right i], h2[align=right i], h3[align=right i],
h4[align=right i], h5[align=right i], h6[align=right i] {
text-align: right;
}
p[align=center i], h1[align=center i], h2[align=center i], h3[align=center i],
h4[align=center i], h5[align=center i], h6[align=center i] {
text-align: center;
}
p[align=justify i], h1[align=justify i], h2[align=justify i], h3[align=justify i],
h4[align=justify i], h5[align=justify i], h6[align=justify i] {
text-align: justify;
}
thead[valign=top i], tbody[valign=top i], tfoot[valign=top i],
tr[valign=top i], td[valign=top i], th[valign=top i] {
vertical-align: top;
}
thead[valign=middle i], tbody[valign=middle i], tfoot[valign=middle i],
tr[valign=middle i], td[valign=middle i], th[valign=middle i] {
vertical-align: middle;
}
thead[valign=bottom i], tbody[valign=bottom i], tfoot[valign=bottom i],
tr[valign=bottom i], td[valign=bottom i], th[valign=bottom i] {
vertical-align: bottom;
}
thead[valign=baseline i], tbody[valign=baseline i], tfoot[valign=baseline i],
tr[valign=baseline i], td[valign=baseline i], th[valign=baseline i] {
vertical-align: baseline;
}
td[nowrap], th[nowrap] { white-space: nowrap; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i] {
border-style: hidden;
border-collapse: collapse;
}
table[border] { border-style: outset; } /* <span>only if border is not equivalent to zero</span> */
table[frame=void i] { border-style: hidden; }
table[frame=above i] { border-style: outset hidden hidden hidden; }
table[frame=below i] { border-style: hidden hidden outset hidden; }
table[frame=hsides i] { border-style: outset hidden outset hidden; }
table[frame=lhs i] { border-style: hidden hidden hidden outset; }
table[frame=rhs i] { border-style: hidden outset hidden hidden; }
table[frame=vsides i] { border-style: hidden outset; }
table[frame=box i], table[frame=border i] { border-style: outset; }
table[border] > tr > td, table[border] > tr > th,
table[border] > thead > tr > td, table[border] > thead > tr > th,
table[border] > tbody > tr > td, table[border] > tbody > tr > th,
table[border] > tfoot > tr > td, table[border] > tfoot > tr > th {
/* <span>only if border is not equivalent to zero</span> */
border-width: 1px;
border-style: inset;
}
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th {
border-width: 1px;
border-style: none;
}
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th {
border-width: 1px;
border-block-style: none;
border-inline-style: solid;
}
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-width: 1px;
border-style: solid;
}
table[rules=groups i] > colgroup {
border-inline-width: 1px;
border-inline-style: solid;
}
table[rules=groups i] > thead,
table[rules=groups i] > tbody,
table[rules=groups i] > tfoot {
border-block-width: 1px;
border-block-style: solid;
}
table[rules=rows i] > tr, table[rules=rows i] > thead > tr,
table[rules=rows i] > tbody > tr, table[rules=rows i] > tfoot > tr {
border-block-width: 1px;
border-block-style: solid;
}</code></pre>
<!--
Demos that the above (and prose below) must explain:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1191
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1194
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1195
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1196
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1197
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1199
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1200
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1201
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1209
-->
<p>In <span>quirks mode</span>, the following rules are also expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
table {
font-weight: initial;
font-style: initial;
font-variant: initial;
font-size: initial;
line-height: initial;
white-space: initial;
text-align: initial;
}</code></pre>
<hr>
<p>For the purposes of the CSS table model, the <code>col</code> element is expected to be treated
as if it was present as many times as its <code data-x="attr-col-span">span</code> attribute <span
data-x="rules for parsing non-negative integers">specifies</span>.</p>
<p>For the purposes of the CSS table model, the <code>colgroup</code> element, if it contains no
<code>col</code> element, is expected to be treated as if it had as many such children as its
<code data-x="attr-colgroup-span">span</code> attribute <span data-x="rules for parsing non-negative
integers">specifies</span>.</p>
<p>For the purposes of the CSS table model, the <code data-x="attr-tdth-colspan">colspan</code> and
<code data-x="attr-tdth-rowspan">rowspan</code> attributes on <code>td</code> and <code>th</code>
elements are expected to <span data-x="rules for parsing non-negative integers">provide</span> the
<i>special knowledge</i> regarding cells spanning rows and columns.</p>
<p>In <span>HTML documents</span>, the following rules are also expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
:is(table, thead, tbody, tfoot, tr) > form { display: none !important; }</code></pre>
<hr>
<p>The <code>table</code> element's <code data-x="attr-table-cellspacing">cellspacing</code>
attribute <span>maps to the pixel length property</span> <span>'border-spacing'</span> on the
element.</p>
<p>The <code>table</code> element's <code data-x="attr-table-cellpadding">cellpadding</code>
attribute <span data-x="maps to the pixel length property">maps to the pixel length
properties</span> <span>'padding-top'</span>, <span>'padding-right'</span>,
<span>'padding-bottom'</span>, and <span>'padding-left'</span> of any <code>td</code> and
<code>th</code> elements that have corresponding <span data-x="concept-cell">cells</span> in the
<span data-x="concept-table">table</span> corresponding to the <code>table</code> element.</p>
<p>The <code>table</code> element's <code data-x="attr-table-height">height</code> attribute
<span>maps to the dimension property</span> <span>'height'</span> on the <code>table</code>
element.</p>
<p>The <code>table</code> element's <code data-x="attr-table-width">width</code> attribute
<span>maps to the dimension property (ignoring zero)</span> <span>'width'</span> on the
<code>table</code> element.</p>
<p>The <code>col</code> element's <code data-x="attr-col-width">width</code> attribute <span>maps
to the dimension property</span> <span>'width'</span> on the <code>col</code>
element.</p>
<p>The <code>thead</code>, <code>tbody</code>, and <code>tfoot</code> elements' <code
data-x="attr-tbody-height">height</code> attribute <span>maps to the dimension property</span>
<span>'height'</span> on the element.</p>
<p>The <code>tr</code> element's <code data-x="attr-tr-height">height</code> attribute <span>maps
to the dimension property</span> <span>'height'</span> on the <code>tr</code> element.</p>
<p>The <code>td</code> and <code>th</code> elements' <code data-x="attr-tdth-height">height</code>
attributes <span data-x="maps to the dimension property (ignoring zero)">map to the dimension
property (ignoring zero)</span> <span>'height'</span> on the element.</p>
<p>The <code>td</code> and <code>th</code> elements' <code data-x="attr-tdth-width">width</code>
attributes <span data-x="maps to the dimension property (ignoring zero)">map to the dimension
property (ignoring zero)</span> <span>'width'</span> on the element.</p>
<hr>
<p>The <code>thead</code>, <code>tbody</code>, <code>tfoot</code>, <code>tr</code>,
<code>td</code>, and <code>th</code> elements, when they have an <code data-x="">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for either the string "<code
data-x="">center</code>" or the string "<code data-x="">middle</code>", are expected to center
text within themselves, as if they had their <span>'text-align'</span> property set to 'center' in
a <span data-x="presentational hints">presentational hint</span>, and to <span>align
descendants</span> to the center.</p>
<p>The <code>thead</code>, <code>tbody</code>, <code>tfoot</code>, <code>tr</code>,
<code>td</code>, and <code>th</code> elements, when they have an <code data-x="">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">left</code>", are expected to left-align text within themselves, as if they had their
<span>'text-align'</span> property set to 'left' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the left.</p>
<p>The <code>thead</code>, <code>tbody</code>, <code>tfoot</code>, <code>tr</code>,
<code>td</code>, and <code>th</code> elements, when they have an <code data-x="">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">right</code>", are expected to right-align text within themselves, as if they had their
<span>'text-align'</span> property set to 'right' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the right.</p>
<p>The <code>thead</code>, <code>tbody</code>, <code>tfoot</code>, <code>tr</code>,
<code>td</code>, and <code>th</code> elements, when they have an <code data-x="">align</code>
attribute whose value is an <span>ASCII case-insensitive</span> match for the string "<code
data-x="">justify</code>", are expected to full-justify text within themselves, as if they had
their <span>'text-align'</span> property set to 'justify' in a <span data-x="presentational
hints">presentational hint</span>, and to <span>align descendants</span> to the left.</p>
<p>User agents are expected to have a rule in their user agent style sheet that matches
<code>th</code> elements that have a parent node whose <span>computed value</span> for the
<span>'text-align'</span> property is its initial value, whose declaration block consists of just
a single declaration that sets the <span>'text-align'</span> property to the value 'center'.</p>
<!-- q.v. '-moz-center-or-inherit' -->
<hr>
<p>When a <code>table</code>, <code>thead</code>, <code>tbody</code>, <code>tfoot</code>,
<code>tr</code>, <code>td</code>, or <code>th</code> element has a <code
data-x="attr-background">background</code> attribute set to a non-empty value, the new value is
expected to be <span data-x="encoding-parsing-and-serializing a
URL">encoding-parsed-and-serialized</span> relative to the element's <span>node document</span>,
and if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the element's
<span>'background-image'</span> property to the return value.</p>
<p>When a <code>table</code>, <code>thead</code>, <code>tbody</code>, <code>tfoot</code>,
<code>tr</code>, <code>td</code>, or <code>th</code> element has a <code data-x="">bgcolor</code>
attribute set, the new value is expected to be parsed using the <span>rules for parsing a legacy
color value</span>, and if that does not return failure, the user agent is expected to treat the
attribute as a <span data-x="presentational hints">presentational hint</span> setting the element's
<span>'background-color'</span> property to the resulting color.</p>
<p>When a <code>table</code> element has a <code data-x="attr-table-bordercolor">bordercolor</code>
attribute, its value is expected to be parsed using the <span>rules for parsing a legacy color
value</span>, and if that does not return failure, the user agent is expected to treat the
attribute as a <span data-x="presentational hints">presentational hint</span> setting the
element's <span>'border-top-color'</span>, <span>'border-right-color'</span>,
<span>'border-bottom-color'</span>, and <span>'border-left-color'</span> properties to the
resulting color.</p>
<hr>
<p>The <code>table</code> element's <code data-x="attr-table-border">border</code> attribute <span
data-x="maps to the pixel length property">maps to the pixel length properties</span>
<span>'border-top-width'</span>, <span>'border-right-width'</span>,
<span>'border-bottom-width'</span>, <span>'border-left-width'</span> on the element. If the
attribute is present but parsing the attribute's value using the <span>rules for parsing
non-negative integers</span> generates an error, a default value of 1px is expected to be used for
that property instead.</p>
<p>Rules marked "<dfn id="magic-border-selector">only if border is not equivalent to zero</dfn>"
in the CSS block above is expected to only be applied if the <code
data-x="attr-table-border">border</code> attribute mentioned in the selectors for the rule is not
only present but, when parsed using the <span>rules for parsing non-negative integers</span>, is
also found to have a value other than zero or to generate an error.</p>
<hr>
<p>In <span>quirks mode</span>, a <code>td</code> element or a <code>th</code> element that has a
<code data-x="attr-tdth-nowrap">nowrap</code> attribute but also has a <code
data-x="attr-tdth-width">width</code> attribute whose value, when parsed using the <span>rules for
parsing nonzero dimension values</span>, is found to be a length (not an error or a number
classified as a percentage), is expected to have a <span data-x="presentational
hints">presentational hint</span> setting the element's <span>'white-space'</span> property to
'normal', overriding the rule in the CSS block above that sets it to 'nowrap'.</p> <!--
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1793 --> <!-- note that the "rules for
parsing nonzero dimension values" can't return 0, if the value is "0" they treat it as an error
-->
<h4>Margin collapsing quirks</h4>
<p>A node is <dfn data-x="concept-rendering-substantial">substantial</dfn> if it is a text node
that is not <span>inter-element whitespace</span>, or if it is an element node.</p>
<p>A node is <dfn data-x="concept-rendering-blank">blank</dfn> if it is an element that contains no
<span data-x="concept-rendering-substantial">substantial</span> nodes.</p>
<p>The <dfn data-x="concept-rendering-elements-with-margins">elements with default margins</dfn>
are the following elements: <code>blockquote</code>, <code>dir</code>, <code>dl</code>,
<code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>,
<code>h6</code>, <code>listing</code>, <code>menu</code>, <code>ol</code>,
<code>p</code>, <code>plaintext</code>, <code>pre</code>, <code>ul</code>, <code>xmp</code></p>
<p>In <span>quirks mode</span>, any <span data-x="concept-rendering-elements-with-margins">element
with default margins</span> that is the <span data-x="concept-tree-child">child</span> of a
<code>body</code>, <code>td</code>, or <code>th</code> element and has no <span
data-x="concept-rendering-substantial">substantial</span> previous siblings is expected to have a
user-agent level style sheet rule that sets its <span>'margin-block-start'</span> property to
zero.</p>
<p>In <span>quirks mode</span>, any <span data-x="concept-rendering-elements-with-margins">element
with default margins</span> that is the <span data-x="concept-tree-child">child</span> of a
<code>body</code>, <code>td</code>, or <code>th</code> element, has no <span
data-x="concept-rendering-substantial">substantial</span> previous siblings, and is <span
data-x="concept-rendering-blank">blank</span>, is expected to have a user-agent level style sheet
rule that sets its <span>'margin-block-end'</span> property to zero also.</p>
<p>In <span>quirks mode</span>, any <span data-x="concept-rendering-elements-with-margins">element
with default margins</span> that is the <span data-x="concept-tree-child">child</span> of a
<code>td</code> or <code>th</code> element, has no <span
data-x="concept-rendering-substantial">substantial</span> following siblings, and is <span
data-x="concept-rendering-blank">blank</span>, is expected to have a user-agent level style sheet
rule that sets its <span>'margin-block-start'</span> property to zero.</p>
<p>In <span>quirks mode</span>, any <code>p</code> element that is the <span
data-x="concept-tree-child">child</span> of a <code>td</code> or <code>th</code> element and has
no <span data-x="concept-rendering-substantial">substantial</span> following siblings, is expected
to have a user-agent level style sheet rule that sets its <span>'margin-block-end'</span> property
to zero.</p>
<h4>Form controls</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
input, select, button, textarea {
letter-spacing: initial;
word-spacing: initial;
line-height: initial;
text-transform: initial;
text-indent: initial;
text-shadow: initial;
appearance: auto;
}
input:not([type=image i], [type=range i], [type=checkbox i], [type=radio i]) {
overflow: clip !important;
overflow-clip-margin: 0 !important;
}
input, select, textarea {
text-align: initial;
}
:autofill {
field-sizing: fixed !important;
}
input:is([type=reset i], [type=button i], [type=submit i]), button {
text-align: center;
}
input, button {
display: inline-block;
}
input[type=hidden i], input[type=file i], input[type=image i] {
appearance: none;
}
input:is([type=radio i], [type=checkbox i], [type=reset i], [type=button i],
[type=submit i], [type=color i], [type=search i]), select, button {
box-sizing: border-box;
}
textarea { white-space: pre-wrap; }</code></pre>
<p>In <span>quirks mode</span>, the following rules are also expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
input:not([type=image i]), textarea { box-sizing: border-box; }</code></pre>
<p>Each kind of form control is also described in the <a href="#widgets">Widgets</a> section,
which describes the look and feel of the control.</p>
<p>For <code>input</code> elements where the <code data-x="attr-input-type">type</code> attribute
is not in the <span data-x="attr-input-type-hidden">Hidden</span> state or the <span
data-x="attr-input-type-image">Image Button</span> state, and that are <span>being
rendered</span>, are expected to act as follows:</p>
<ul>
<li><p>The <span>inner display type</span> is always 'flow-root'.</p></li>
</ul>
<h4>The <code>hr</code> element</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
hr {
color: gray;
border-style: inset;
border-width: 1px;
margin-block: 0.5em;
margin-inline: auto;
overflow: hidden;
}</code></pre>
<p>The following rules are also expected to apply, as <span>presentational hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
hr[align=left i] { margin-left: 0; margin-right: auto; }
hr[align=right i] { margin-left: auto; margin-right: 0; }
hr[align=center i] { margin-left: auto; margin-right: auto; }
hr[color], hr[noshade] { border-style: solid; }</code></pre>
<p>If an <code>hr</code> element has either a <code data-x="attr-hr-color">color</code> attribute
or a <code data-x="attr-hr-noshade">noshade</code> attribute, and furthermore also has a <code
data-x="attr-hr-size">size</code> attribute, and parsing that attribute's value using the
<span>rules for parsing non-negative integers</span> doesn't generate an error, then the user
agent is expected to use the parsed value divided by two as a pixel length for
<span>presentational hints</span> for the properties <span>'border-top-width'</span>,
<span>'border-right-width'</span>, <span>'border-bottom-width'</span>, and
<span>'border-left-width'</span> on the element.</p>
<p>Otherwise, if an <code>hr</code> element has neither a <code data-x="attr-hr-color">color</code>
attribute nor a <code data-x="attr-hr-noshade">noshade</code> attribute, but does have a <code
data-x="attr-hr-size">size</code> attribute, and parsing that attribute's value using the
<span>rules for parsing non-negative integers</span> doesn't generate an error, then: if the
parsed value is one, then the user agent is expected to use the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the element's
<span>'border-bottom-width'</span> to 0; otherwise, if the parsed value is greater than one, then
the user agent is expected to use the parsed value minus two as a pixel length for
<span>presentational hints</span> for the <span>'height'</span> property on the element.</p>
<p>The <code data-x="attr-hr-width">width</code> attribute on an <code>hr</code> element <span>maps
to the dimension property</span> <span>'width'</span> on the element.</p>
<p>When an <code>hr</code> element has a <code data-x="attr-hr-color">color</code> attribute, its
value is expected to be parsed using the <span>rules for parsing a legacy color value</span>, and
if that does not return failure, the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the element's
<span>'color'</span> property to the resulting color.</p>
<h4>The <code>fieldset</code> and <code>legend</code> elements</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
fieldset {
display: block;
margin-inline: 2px;
border: groove 2px ThreeDFace;
padding-block: 0.35em 0.625em;
padding-inline: 0.75em;
min-inline-size: min-content;
}
legend {
padding-inline: 2px;
}
legend[align=left i] {
justify-self: left;
}
legend[align=center i] {
justify-self: center;
}
legend[align=right i] {
justify-self: right;
}</code></pre>
<p>The <code>fieldset</code> element, when it generates a <span>CSS box</span>, is expected to act
as follows:</p>
<ul>
<li><p>The element is expected to establish a new <span>block formatting context</span>.</p></li>
<li>
<p>The <span>'display'</span> property is expected to act as follows:</p>
<ul>
<li><p>If the computed value of <span>'display'</span> is a value such that the <span>outer
display type</span> is 'inline', then behave as 'inline-block'.</p></li>
<li><p>Otherwise, behave as 'flow-root'.</p></li>
</ul>
<p class="note">This does not change the computed value.</p>
</li>
<li>
<p>If the element's box has a child box that matches the conditions in the list below, then the
first such child box is the 'fieldset' element's <dfn>rendered legend</dfn>:</p>
<ul class="brief">
<li>The child is a <code>legend</code> element.</li>
<li>The child's used value of <span>'float'</span> is 'none'.</li>
<li>The child's used value of <span>'position'</span> is not 'absolute' or 'fixed'.</li>
</ul>
</li>
<li>
<p>If the element has a <span>rendered legend</span>, then the border is expected to not be
painted behind the rectangle defined as follows, using the writing mode of the fieldset:</p>
<ol>
<li><p>The block-start edge of the rectangle is the smaller of the block-start edge of the
<span>rendered legend</span>'s margin rectangle at its static position (ignoring transforms),
and the block-start outer edge of the <code>fieldset</code>'s border.</p></li>
<li><p>The block-end edge of the rectangle is the larger of the block-end edge of the
<span>rendered legend</span>'s margin rectangle at its static position (ignoring transforms),
and the block-end outer edge of the <code>fieldset</code>'s border.</p></li>
<li><p>The inline-start edge of the rectangle is the smaller of the inline-start edge of the
<span>rendered legend</span>'s border rectangle at its static position (ignoring transforms),
and the inline-start outer edge of the <code>fieldset</code>'s border.</p></li>
<li><p>The inline-end edge of the rectangle is the larger of the inline-end edge of the
<span>rendered legend</span>'s border rectangle at its static position (ignoring transforms),
and the inline-end outer edge of the <code>fieldset</code>'s border.</p></li>
</ol>
</li>
<li><p>The space allocated for the element's border on the block-start side is expected to be
the element's <span>'border-block-start-width'</span> or the <span>rendered legend</span>'s
margin box size in the <code>fieldset</code>'s block-flow direction, whichever is
greater.</p></li>
<li><p>For the purpose of calculating the used <span>'block-size'</span>, if the computed
<span>'block-size'</span> is not 'auto', the space allocated for the <span>rendered
legend</span>'s margin box that spills out past the border, if any, is expected to be
subtracted from the <span>'block-size'</span>. If the content box's block-size would be
negative, then let the content box's block-size be zero instead.</p></li>
<li><p>If the element has a <span>rendered legend</span>, then that element is expected to be
the first child box.</p></li>
<li><p>The <span>anonymous fieldset content box</span> is expected to appear after the
<span>rendered legend</span> and is expected to contain the content (including the '::before'
and '::after' pseudo-elements) of the <code>fieldset</code> element except for the
<span>rendered legend</span>, if there is one.</p></li>
<li><p>The used value of the <span>'padding-top'</span>, <span>'padding-right'</span>,
<span>'padding-bottom'</span>, and <span>'padding-left'</span> properties are expected to be
zero.</p></li>
<li><p>For the purpose of calculating the min-content inline size, use the greater of the
min-content inline size of the <span>rendered legend</span> and the min-content inline size of
the <span>anonymous fieldset content box</span>.</p></li>
<li><p>For the purpose of calculating the max-content inline size, use the greater of the
max-content inline size of the <span>rendered legend</span> and the max-content inline size of
the <span>anonymous fieldset content box</span>.</p></li>
</ul>
<p>A <code>fieldset</code> element's <span>rendered legend</span>, if any, is expected to act as
follows:</p>
<ul>
<li><p>The element is expected to establish a new <span>formatting context</span> for its
contents. The type of this <span>formatting context</span> is determined by its
<span>'display'</span> value, as usual.</p></li>
<li>
<p>The <span>'display'</span> property is expected to behave as if its computed value was
blockified.</p>
<p class="note">This does not change the computed value.</p>
</li>
<li><p>If the <span>computed value</span> of <span>'inline-size'</span> is 'auto', then the
<span>used value</span> is the <span>fit-content inline size</span>.</p></li>
<li><p>The element is expected to be positioned in the inline direction as is normal for
blocks (e.g., taking into account margins and the <span>'justify-self'</span>
property).</p></li>
<li>
<p>The element's box is expected to be constrained in the inline direction by the inline
content size of the <code>fieldset</code> as if it had used its computed inline padding.</p>
<div class="example">
<p>For example, if the <code>fieldset</code> has a specified padding of 50px, then the
<span>rendered legend</span> will be positioned 50px in from the <code>fieldset</code>'s
border. The padding will further apply to the <span>anonymous fieldset content box</span>
instead of the <code>fieldset</code> element itself.</p>
</div>
</li>
<li><p>The element is expected to be positioned in the block-flow direction such that its border
box is centered over the border on the block-start side of the <code>fieldset</code>
element.</p></li>
</ul>
<p>A <code>fieldset</code> element's <dfn>anonymous fieldset content box</dfn> is expected to
act as follows:</p>
<ul>
<li>
<p>The <span>'display'</span> property is expected to act as follows:</p>
<ul>
<li><p>If the computed value of <span>'display'</span> on the <code>fieldset</code> element
is 'grid' or 'inline-grid', then set the used value to 'grid'.</p></li>
<li><p>If the computed value of <span>'display'</span> on the <code>fieldset</code> element
is 'flex' or 'inline-flex', then set the used value to 'flex'.</p></li>
<li><p>Otherwise, set the used value to 'flow-root'.</p></li>
</ul>
</li>
<li>
<p>The following properties are expected to inherit from the <code>fieldset</code> element:</p>
<ul class="brief">
<li><span>'align-content'</span></li>
<li><span>'align-items'</span></li>
<li><span>'border-radius'</span></li>
<li><span>'column-count'</span></li>
<li><span>'column-fill'</span></li>
<li><span>'column-gap'</span></li>
<li><span>'column-rule'</span></li>
<li><span>'column-width'</span></li>
<li><span>'flex-direction'</span></li>
<li><span>'flex-wrap'</span></li>
<li><span>'grid-auto-columns'</span></li>
<li><span>'grid-auto-flow'</span></li>
<li><span>'grid-auto-rows'</span></li>
<li><span>'grid-column-gap'</span></li>
<li><span>'grid-row-gap'</span></li>
<li><span>'grid-template-areas'</span></li>
<li><span>'grid-template-columns'</span></li>
<li><span>'grid-template-rows'</span></li>
<li><span>'justify-content'</span></li>
<li><span>'justify-items'</span></li>
<li><span>'overflow'</span></li>
<li><span>'padding-bottom'</span></li>
<li><span>'padding-left'</span></li>
<li><span>'padding-right'</span></li>
<li><span>'padding-top'</span></li>
<li><span>'text-overflow'</span></li>
<li><span>'unicode-bidi'</span></li>
</ul>
</li>
<li><p>The <span>'block-size'</span> property is expected to be set to '100%'.</p></li>
<li><p>For the purpose of calculating percentage padding, act as if the padding was calculated
for the <code>fieldset</code> element.</p></li>
</ul>
<div class="note" id="fieldset-layout-model">
<figure>
<svg viewBox="0 0 400 270" width="480" height="324" role="img" aria-label="Fieldset layout
model">
<defs>
<marker id='arrow-red' orient='auto' markerWidth='5' markerHeight='4'
refX='0.1' refY='2'>
<path d='M0,0 V4 L5,2 Z' fill='red' />
</marker>
<marker id='arrow-blue' orient='auto' markerWidth='5' markerHeight='4'
refX='0.1' refY='2'>
<path d='M0,0 V4 L5,2 Z' fill='blue' />
</marker>
</defs>
<!-- outer outline -->
<rect stroke-dasharray="6" stroke-width="1" stroke="black" width="304" height="176" x="48"
y="48" fill="none"/>
<line marker-end="url(#arrow-blue)" x1="200" x2="200" y1="48" y2="20" stroke-width="2"
stroke="blue"/>
<line marker-end="url(#arrow-blue)" x1="48" x2="20" y1="136" y2="136" stroke-width="2"
stroke="blue"/>
<line marker-end="url(#arrow-blue)" x1="352" x2="380" y1="136" y2="136" stroke-width="2"
stroke="blue"/>
<line marker-end="url(#arrow-blue)" x1="200" x2="200" y1="224" y2="250" stroke-width="2"
stroke="blue"/>
<text x="210" y="35" font-size="12" font-family="sans-serif" font-style="normal"
fill="blue">fieldset's margin</text>
<!-- fieldset -->
<rect stroke-width="2" stroke="blue" width="300" height="116.5" x="50" y="105" fill="white"/>
<!-- rendered legend -->
<rect stroke-width="2" stroke="red" width="85" height="60" x="100" y="75" fill="white"/>
<text x="120" y="105" dominant-baseline="central" fill="red" font-family="serif"
font-style="normal">legend</text>
<!-- legend padding -->
<rect x="110" y="85" width="65" height="40" fill="none" stroke="#eee" stroke-width="18"/>
<text x="133" y="88" font-size="12" font-family="sans-serif" font-style="normal"
fill="gray">padding</text>
<line marker-end="url(#arrow-red)" x1="185" x2="325" y1="90" y2="90" stroke-width="2"
stroke="red"/>
<text x="210" y="85" font-size="12" font-family="sans-serif" font-style="normal"
fill="red">legend's margin</text>
<line marker-end="url(#arrow-red)" x1="100" x2="75" y1="90" y2="90" stroke-width="2"
stroke="red"/>
<line marker-end="url(#arrow-red)" x1="143" x2="143" y1="75" y2="60" stroke-width="2"
stroke="red"/>
<line marker-end="url(#arrow-red)" x1="143" x2="143" y1="135" y2="150" stroke-width="2"
stroke="red"/>
<!-- fieldset padding -->
<rect x="60" y="171" width="280" height="40" fill="none" stroke="#eee" stroke-width="18"/>
<text x="297" y="174" font-size="12" font-family="sans-serif" font-style="normal"
fill="gray">padding</text>
<!-- anonymous fieldset content box outline -->
<rect stroke-dasharray="6" stroke-width="1" stroke="black" width="296" height="58" x="52"
y="161" fill="none"/>
<text x="170" y="156" font-size="12" font-family="sans-serif" font-style="normal">anonymous
fieldset content box</text>
<text x="70" y="191" dominant-baseline="central" fill="blue" font-family="serif"
font-style="normal">content</text>
</svg>
<figcaption>The legend is rendered over the top border, and the top border area reserves
vertical space for the legend. The fieldset's top margin starts at the top margin edge of the
legend. The legend's horizontal margins, or the <span>'justify-self'</span> property, gives
its horizontal position. The <span>anonymous fieldset content box</span> appears below the
legend.</figcaption>
</figure>
</div>
<h3>Replaced elements</h3>
<p class="note">The following elements can be <span data-x="replaced element">replaced
elements</span>: <code>audio</code>, <code>canvas</code>, <code>embed</code>, <code>iframe</code>,
<code>img</code>, <code>input</code>, <code>object</code>, and <code>video</code>.</p>
<h4 id="embedded-content-rendering-rules">Embedded content</h4>
<p>The <code>embed</code>, <code>iframe</code>, and <code>video</code> elements are expected to be
treated as <span data-x="replaced element">replaced elements</span>.</p>
<p>A <code>canvas</code> element that <span>represents</span> <span>embedded content</span> is
expected to be treated as a <span>replaced element</span>; the contents of such elements are the
element's bitmap, if any, or else a <span>transparent black</span> bitmap with the same
<span>natural dimensions</span> as the element. Other <code>canvas</code> elements are expected
to be treated as ordinary elements in the rendering model.</p>
<p>An <code>object</code> element that <span>represents</span> an image, plugin, or its
<span>content navigable</span> is expected to be treated as a <span>replaced element</span>.
Other <code>object</code> elements are expected to be treated as ordinary elements in the
rendering model.</p>
<p>The <code>audio</code> element, when it is <span data-x="expose a user interface to the
user">exposing a user interface</span>, is expected to be treated as a
<span>replaced element</span> about one line high, as wide as is necessary to expose the user
agent's user interface features. When an <code>audio</code> element is not <span data-x="expose a
user interface to the user">exposing a user interface</span>, the user agent is expected to force
its <span>'display'</span> property to compute to 'none', irrespective of CSS rules.</p>
<p>Whether a <code>video</code> element is <span data-x="expose a user interface to the
user">exposing a user interface</span> is not expected to affect the size of the rendering;
controls are expected to be overlaid above the page content without causing any layout changes,
and are expected to disappear when the user does not need them.</p>
<p>When a <code>video</code> element represents a poster frame or frame of video, the poster frame
or frame of video is expected to be rendered at the largest size that maintains the aspect ratio
of that poster frame or frame of video without being taller or wider than the <code>video</code>
element itself, and is expected to be centered in the <code>video</code> element.</p>
<p>Any subtitles or captions are expected to be overlaid directly on top of their
<code>video</code> element, as defined by the relevant rendering rules; for WebVTT, those are the
<span>rules for updating the display of WebVTT text tracks</span>. <ref>WEBVTT</ref></p>
<p>When the user agent starts <span data-x="expose a user interface to the user">exposing a user
interface</span> for a <code>video</code> element, the user agent should run the <span>rules for
updating the text track rendering</span> of each of the <span data-x="text track">text
tracks</span> in the <code>video</code> element's <span>list of text tracks</span> that are <span
data-x="text track showing">showing</span> and whose <span>text track kind</span> is one of <code
data-x="dom-TextTrack-kind-subtitles">subtitles</code> or <code
data-x="dom-TextTrack-kind-captions">captions</code> (e.g., for <span data-x="text track">text
tracks</span> based on WebVTT, the <span>rules for updating the display of WebVTT text
tracks</span>). <ref>WEBVTT</ref></p>
<p class="note">Resizing <code>video</code> and <code>canvas</code> elements does not interrupt
video playback or clear the canvas.</p>
<hr>
<p>The following CSS rules are expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
iframe { border: 2px inset; }
<span id="video-object-fit">video { object-fit: contain; }</span></code></pre>
<h4>Images</h4>
<p>User agents are expected to render <code>img</code> elements and <code>input</code> elements
whose <code data-x="attr-input-type">type</code> attributes are in the <span
data-x="attr-input-type-image">Image Button</span> state, according to the first applicable rules
from the following list:</p>
<dl class="switch">
<dt>If the element <span>represents</span> an image</dt>
<dd>The user agent is expected to treat the element as a <span>replaced element</span> and
render the image according to the rules for doing so defined in CSS.</dd>
<dt>
If the element does not <span data-x="represents">represent</span> an image and either:
<ul>
<li>the user agent has reason to believe that the image will become <i
data-x="img-available">available</i><!--input-img-available also--> and be rendered in due
course, or
<li>the element has no <code data-x="">alt</code> attribute<!-- attr-img-alt, attr-input-alt -->, or
<li>the <code>Document</code> is in <span>quirks mode</span>, and the element already has
<span>natural dimensions</span> (e.g., from the <span>dimension attributes</span> or CSS
rules)
</ul>
</dt>
<dd>The user agent is expected to treat the element as a <span>replaced element</span> whose
content is the text that the element represents, if any, optionally alongside an icon indicating
that the image is being obtained (if applicable). For <code>input</code> elements, the element
is expected to appear button-like to indicate that the element is a <span
data-x="concept-button">button</span>.</dd>
<!-- no-quirks and limited-quirks modes only-->
<dt>If the element is an <code>img</code> element that <span>represents</span> some text and the
user agent does not expect this to change</dt>
<dd>The user agent is expected to treat the element as a non-replaced phrasing element whose
content is the text, optionally with an icon indicating that an image is missing, so that the
user can request the image be displayed or investigate why it is not rendering. In non-graphical
contexts, such an icon should be omitted.</dd>
<!-- no-quirks and limited-quirks modes only-->
<dt>If the element is an <code>img</code> element that <span>represents</span> nothing and the
user agent does not expect this to change</dt>
<dd>The user agent is expected to treat the element as a <span>replaced element</span> whose
<span>natural dimensions</span> are 0. (In the absence of further styles, this will cause the
element to essentially not be rendered.)</dd>
<!-- no-quirks and limited-quirks modes only-->
<dt>If the element is an <code>input</code> element that does not <span
data-x="represents">represent</span> an image and the user agent does not expect this to change</dt>
<dd>The user agent is expected to treat the element as a <span>replaced element</span>
consisting of a button whose content is the element's alternative text. The <span>natural
dimensions</span> of the button are expected to be about one line in height and whatever width
is necessary to render the text on one line.</dd>
</dl>
<p>The icons mentioned above are expected to be relatively small so as not to disrupt most text
but be easily clickable. In a visual environment, for instance, icons could be 16 pixels by 16
pixels square, or 1em by 1em if the images are scalable. In an audio environment, the icon could
be a short bleep. The icons are intended to indicate to the user that they can be used to get to
whatever options the UA provides for images, and, where appropriate, are expected to provide
access to the context menu that would have come up if the user interacted with the actual
image.</p>
<hr>
<p>All animated images with the same <span>absolute URL</span> and the same image data are
expected to be rendered synchronized to the same timeline as a group, with the timeline starting
at the time of the least recent addition to the group.</p>
<p class="note">In other words, when a second image with the same <span>absolute URL</span> and
animated image data is inserted into a document, it jumps to the point in the animation cycle that
is currently being displayed by the first image.</p>
<p>When a user agent is to <dfn>restart the animation</dfn> for an <code>img</code> element
showing an animated image, all animated images with the same <span>absolute URL</span> and the
same image data in that <code>img</code> element's <span>node document</span> are expected to restart
their animation from the beginning.</p>
<hr>
<p>The following CSS rules are expected to apply:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
<span id="img-contain-size">img:is([sizes="auto" i], [sizes^="auto," i]) {
contain: size !important;
contain-intrinsic-size: 300px 150px;
}</span></code></pre>
<p>The following CSS rules are expected to apply when the <code>Document</code> is in <span>quirks
mode</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
img[align=left i] { margin-right: 3px; }
img[align=right i] { margin-left: 3px; }</code></pre>
</div>
<div w-nodev>
<h4>Attributes for embedded content and images</h4>
<p>The following CSS rules are expected to apply as <span>presentational hints</span>:</p>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
embed[align=left i], iframe[align=left i], img[align=left i],
input[type=image i][align=left i], object[align=left i] {
float: left;
}
embed[align=right i], iframe[align=right i], img[align=right i],
input[type=image i][align=right i], object[align=right i] {
float: right;
}
embed[align=top i], iframe[align=top i], img[align=top i],
input[type=image i][align=top i], object[align=top i] {
vertical-align: top;
}
embed[align=baseline i], iframe[align=baseline i], img[align=baseline i],
input[type=image i][align=baseline i], object[align=baseline i] {
vertical-align: baseline;
}
embed[align=texttop i], iframe[align=texttop i], img[align=texttop i],
input[type=image i][align=texttop i], object[align=texttop i] {
vertical-align: text-top;
}
embed[align=absmiddle i], iframe[align=absmiddle i], img[align=absmiddle i],
input[type=image i][align=absmiddle i], object[align=absmiddle i],
embed[align=abscenter i], iframe[align=abscenter i], img[align=abscenter i],
input[type=image i][align=abscenter i], object[align=abscenter i] {
vertical-align: middle;
}
embed[align=bottom i], iframe[align=bottom i], img[align=bottom i],
input[type=image i][align=bottom i], object[align=bottom i] {
vertical-align: bottom;
}</code></pre>
<p>When an <code>embed</code>, <code>iframe</code>, <code>img</code>, or <code>object</code>
element, or an <code>input</code> element whose <code data-x="attr-input-type">type</code>
attribute is in the <span data-x="attr-input-type-image">Image Button</span> state, has an <code
data-x="">align</code> attribute whose value is an <span>ASCII case-insensitive</span> match for
the string "<code data-x="">center</code>" or the string "<code data-x="">middle</code>", the user
agent is expected to act as if the element's <span>'vertical-align'</span> property was set to a
value that aligns the vertical middle of the element with the parent element's baseline.</p>
<p>The <code data-x="">hspace</code> attribute of <code>embed</code>,
<code>img</code>, or <code>object</code> elements, and <code>input</code> elements with a <code
data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-image">Image
Button</span> state, <span data-x="maps to the dimension property">maps to the dimension
properties</span> <span>'margin-left'</span> and <span>'margin-right'</span> on the element.</p>
<p>The <code data-x="">vspace</code> attribute of <code>embed</code>,
<code>img</code>, or <code>object</code> elements, and <code>input</code> elements with a <code
data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-image">Image
Button</span> state, <span data-x="maps to the dimension property">maps to the dimension
properties</span> <span>'margin-top'</span> and <span>'margin-bottom'</span> on the element.</p>
<p>When an <code>iframe</code> element has a <code
data-x="attr-iframe-frameborder">frameborder</code> attribute whose value, when parsed using the
<span>rules for parsing integers</span>, is zero or an error, the user agent is expected to have
<span>presentational hints</span> setting the element's <span>'border-top-width'</span>,
<span>'border-right-width'</span>, <span>'border-bottom-width'</span>, and
<span>'border-left-width'</span> properties to zero.</p>
<p>When an <code>img</code> element, <code>object</code> element, or <code>input</code> element
with a <code data-x="attr-input-type">type</code> attribute in the <span
data-x="attr-input-type-image">Image Button</span> state has a <code
data-x="">border</code> attribute whose value, when parsed using the <span>rules for
parsing non-negative integers</span>, is found to be a number greater than zero, the user agent is
expected to use the parsed value for eight <span>presentational hints</span>: four setting the
parsed value as a pixel length for the element's <span>'border-top-width'</span>,
<span>'border-right-width'</span>, <span>'border-bottom-width'</span>, and
<span>'border-left-width'</span> properties, and four setting the element's
<span>'border-top-style'</span>, <span>'border-right-style'</span>,
<span>'border-bottom-style'</span>, and <span>'border-left-style'</span> properties to the value
'solid'.</p>
<p id="dimRendering">The <code data-x="attr-dim-width">width</code> and <code
data-x="attr-dim-height">height</code> attributes on an <code>img</code> element's <span
data-x="concept-img-dimension-attribute-source">dimension attribute source</span> <span
data-x="maps to the dimension property">map to the dimension properties</span>
<span>'width'</span> and <span>'height'</span> on the <code>img</code> element respectively. They
similarly <span>map to the aspect-ratio property (using dimension rules)</span> of the
<code>img</code> element.</p>
<p>The <code data-x="attr-dim-width">width</code> and <code data-x="attr-dim-height">height</code>
attributes on <code>embed</code>, <code>iframe</code>, <code>object</code>, and <code>video</code>
elements, and <code>input</code> elements with a <code data-x="attr-input-type">type</code>
attribute in the <span data-x="attr-input-type-image">Image Button</span> state and that either
represents an image or that the user expects will eventually represent an image, <span
data-x="maps to the dimension property">map to the dimension properties</span>
<span>'width'</span> and <span>'height'</span> on the element respectively.</p>
<p>The <code data-x="attr-dim-width">width</code> and <code data-x="attr-dim-height">height</code>
attributes <span>map to the aspect-ratio property (using dimension rules)</span> on
<code>img</code> and <code>video</code> elements, and <code>input</code> elements with a <code
data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-image">Image
Button</span> state.</p>
<p>The <code data-x="attr-canvas-width">width</code> and <code
data-x="attr-canvas-height">height</code> attributes <span>map to the aspect-ratio property</span>
on <code>canvas</code> elements.</p>
</div>
<div w-nodev>
<h4>Image maps</h4>
<p>Shapes on an <span>image map</span> are expected to act, for the purpose of the CSS cascade, as
elements independent of the original <code>area</code> element that happen to match the same style
rules but inherit from the <code>img</code> or <code>object</code> element.</p>
<p>For the purposes of the rendering, only the <span>'cursor'</span> property is expected to have
any effect on the shape.</p>
<p class="example">Thus, for example, if an <code>area</code> element has a <code
data-x="attr-style">style</code> attribute that sets the <span>'cursor'</span> property to 'help',
then when the user designates that shape, the cursor would change to a Help cursor.</p>
<p class="example">Similarly, if an <code>area</code> element had a CSS rule that set its
<span>'cursor'</span> property to 'inherit' (or if no rule setting the <span>'cursor'</span>
property matched the element at all), the shape's cursor would be inherited from the
<code>img</code> or <code>object</code> element of the <span>image map</span>, not from the parent
of the <code>area</code> element.</p>
</div>
<div w-nodev>
<h3 id="widgets"><span id="bindings"></span>Widgets</h3>
<h4>Native appearance</h4>
<p>The <cite>CSS Basic User Interface</cite> specification calls elements that can have a
<span>native appearance</span> <span data-x="widget">widgets</span>, and defines whether to use that <span>native
appearance</span> depending on the <span>'appearance'</span> property. That logic, in
turn, depends on whether each the element is classified as a <span>devolvable
widget</span> or <span>non-devolvable widget</span>. This section defines which elements match
these concepts for HTML, what their <span>native appearance</span> is, and any particularity of
their <span data-x="devolved widget">devolved</span> state or <span>primitive appearance</span>.
<ref>CSSUI</ref></p>
<p>The following elements can have a <span>native appearance</span> for the purpose of the CSS
<span>'appearance'</span> property.</p>
<ul class="brief">
<li><code>button</code></li>
<li><code>input</code></li>
<li><code>meter</code></li>
<li><code>progress</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
</ul>
</div>
<div w-nodev>
<h4>Writing mode</h4>
<p>Several widgets have their rendering controlled by the <span>'writing-mode'</span> CSS
property. For the purposes of those widgets, we have the following definitions.</p>
<p>A <dfn>horizontal writing mode</dfn> is when resolving the <span>'writing-mode'</span>
property of the control results in a computed value of 'horizontal-tb'.</p>
<p>A <dfn>vertical writing mode</dfn> is when resolving the <span>'writing-mode'</span> property
of the control results in a computed value of either 'vertical-rl', 'vertical-lr', 'sideways-rl'
or 'sideways-lr'.</p>
</div>
<div w-nodev>
<h4>Button layout</h4>
<p>When an element uses <span>button layout</span>, it is a <span>devolvable widget</span>, and
it's <span>native appearance</span> is that of a button.</p>
<p><dfn>Button layout</dfn> is as follows:</p>
<ul>
<li>
<p>If the element is a <code>button</code> element, then the <span>'display'</span> property is
expected to act as follows:</p>
<ul>
<li><p>If the computed value of <span>'display'</span> is 'inline-grid', 'grid',
'inline-flex', 'flex', 'none', or 'contents', then behave as the computed value.</p></li>
<li><p>Otherwise, if the computed value of <span>'display'</span> is a value such that the
<span>outer display type</span> is 'inline', then behave as 'inline-block'.</p></li>
<li><p>Otherwise, behave as 'flow-root'.</p></li>
</ul>
</li>
<li><p>The element is expected to establish a new <span>formatting context</span> for its
contents. The type of this formatting context is determined by its <span>'display'</span> value,
as usual.</p></li>
<li><p>If the element is <span>absolutely-positioned</span>, then for the purpose of the
<a href="https://drafts.csswg.org/css2/#visuren">CSS visual formatting model</a>, act as if
the element is a <span>replaced element</span>. <ref>CSS</ref></p></li>
<li><p>If the <span>computed value</span> of <span>'inline-size'</span> is 'auto', then the
<span>used value</span> is the <span>fit-content inline size</span>.</p></li>
<li><p>For the purpose of the 'normal' keyword of the <span>'align-self'</span> property, act
as if the element is a replaced element.</p></li>
<li>
<p>If the element is an <code>input</code> element, or if it is a <code>button</code> element
and its computed value for <span>'display'</span> is not 'inline-grid', 'grid', 'inline-flex',
or 'flex', then the element's box has a child <dfn>anonymous button content box</dfn> with the
following behaviors:</p>
<ul>
<li><p>The box is a <span>block-level</span> <span>block container</span> that establishes a
new <span>block formatting context</span> (i.e., <span>'display'</span> is
'flow-root').</p></li>
<li><p>If the box does not overflow in the horizontal axis, then it is centered
horizontally.</p></li>
<li><p>If the box does not overflow in the vertical axis, then it is centered
vertically.</p></li>
</ul>
<p>Otherwise, there is no <span>anonymous button content box</span>.</p>
</li>
</ul>
<p class="XXX">Need to define the expected <span>primitive appearance</span>.</p>
<h4>The <code>button</code> element</h4>
<p>The <code>button</code> element, when it generates a <span>CSS box</span>, is expected to
depict a button and to use <span>button layout</span> whose <span>anonymous button content
box</span>'s contents (if there is an <span>anonymous button content box</span>) are the child
boxes the element's box would otherwise have.</p>
</div>
<div w-nodev>
<h4>The <code>details</code> and <code>summary</code> elements</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
details, summary {
display: block;
}
details > summary:first-of-type {
display: list-item;
counter-increment: list-item 0;
list-style: disclosure-closed inside;
}
details[open] > summary:first-of-type {
list-style-type: disclosure-open;
}</code></pre>
<p>The <code>details</code> element is expected to have an internal <span>shadow tree</span> with
three child elements:</p>
<ol>
<li>
<p>The first child element is a <code>slot</code> that is expected to take the
<code>details</code> element's first <code>summary</code> element child, if any. This element
has a single child <code>summary</code> element called the <dfn>default summary</dfn> which has
text content that is <span>implementation-defined</span> (and probably locale-specific).</p>
<p>The <code>summary</code> element that this slot <span>represents</span> is expected to allow
the user to request the details be shown or hidden.</p>
</li>
<li>
<p>The second child element is a <code>slot</code> that is expected to take the
<code>details</code> element's remaining descendants, if any. This element has no contents.</p>
<p>This element is expected to match the <span>'::details-content'</span> pseudo-element.</p>
<p>This element is expected to have its <code data-x="attr-style">style</code> attribute set to
"<code data-x="">display: block; content-visibility: hidden;</code>" when the
<code>details</code> element does not have an <code data-x="attr-details-open">open</code>
attribute. When it does have the <code data-x="attr-details-open">open</code> attribute, the
<code data-x="attr-style">style</code> attribute is expected to be set to
"<code data-x="">display: block;</code>".</p>
<p class="note">Because the slots are hidden inside a shadow tree, this <code
data-x="attr-style">style</code> attribute is not directly visible to author code. Its impacts,
however, are visible. Notably, the choice of <code data-x="">content-visibility: hidden</code>
instead of, e.g., <code data-x="">display: none</code>, impacts the results of various APIs that
query layout information.</p>
</li>
<li>
<p>The third child element is either a <code>link</code> or <code>style</code>
element with the following styles for the <span>default summary</span>:</p>
<pre><code class="css">:host summary {
display: list-item;
counter-increment: list-item 0;
list-style: disclosure-closed inside;
}
:host([open]) summary {
list-style-type: disclosure-open;
}</code></pre>
<p class="note">The position of this child element relative to the other two is not observable.
This means that implementations might have it in a different order relative to its siblings.
Implementations might even associate the style with the shadow tree using a mechanism that is
not an element.</p>
</li>
</ol>
<p class="note">The structure of this shadow tree is observable through the ways that the children
of the <code>details</code> element and the '::details-content' pseudo-element respond to CSS
styles.</p>
<!-- https://mail.gnome.org/archives/usability/2006-June/msg00015.html -->
</div>
<div w-nodev>
<h4>The <code>input</code> element as a text entry widget</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-text">Text</span>, <span
data-x="attr-input-type-tel">Telephone</span>, <span data-x="attr-input-type-url">URL</span>, or
<span data-x="attr-input-type-email">Email</span> state, is a <span>devolvable widget</span>. Its
expected <span>native appearance</span> is to render as an <span>'inline-block'</span> box depicting
a one-line text control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-search">Search</span> state is a <span>devolvable widget</span>.
Its expected <span>native appearance</span> is to render as an <span>'inline-block'</span> box
depicting a one-line text control. If the <span>computed value</span> of the element's
<span>'appearance'</span> property is not <code>'textfield'</code>, it may have a distinct style
indicating that it is a search field.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-password">Password</span> state is a <span>devolvable
widget</span>. Its expected <span>native appearance</span> is to render as an
<span>'inline-block'</span> box depicting a one-line text control that obscures data entry.</p>
<p>For <code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute is
in one of the above states, the <span>used value</span> of the <span>'line-height'</span> property
must be a length value that is no smaller than what the <span>used value</span> would be for
'line-height: normal'.</p>
<p class="note">The <span>used value</span> will not be the actual keyword 'normal'. Also, this
rule does not affect the <span>computed value</span>.</p>
<p>If these text controls provide a text selection, then, when the user changes the current
selection, the user agent is expected to <span>queue an element task</span> on the <span>user
interaction task source</span> given the <code>input</code> element to <span
data-x="concept-event-fire">fire an event</span> named <code data-x="event-select">select</code>
at the element, with the <code data-x="dom-Event-bubbles">bubbles</code> attribute initialized to
true.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is
in one of the above states is an <span>element with default preferred size</span>, and user
agents are expected to apply the <span>'field-sizing'</span> CSS property to the element. User
agents are expected to determine the <span>inline size</span> of its <span>intrinsic size</span>
by the following steps:</p>
<ol>
<li>
<p>If the <span>'field-sizing'</span> property on the element has a <span>computed value</span>
of <span data-x="field-sizing-content">'content'</span>, the <span>inline size</span> is
determined by the text which the element shows. The text is either a
<span data-x="concept-fe-value">value</span> or a short hint specified by the
<code data-x="attr-input-placeholder">placeholder</code> attribute. User agents may take the
text caret size into account in the <span>inline size</span>.</p>
</li>
<li>
<p>If the element has a <code data-x="attr-input-size">size</code> attribute, and parsing that
attribute's value using the <span>rules for parsing non-negative integers</span> doesn't
generate an error, return the value obtained from applying the <span>converting a character
width to pixels</span> algorithm to the value of the attribute.</p>
</li>
<li>
<p>Otherwise, return the value obtained from applying the <span>converting a character width to
pixels</span> algorithm to the number 20.</p>
</li>
</ol>
<p>The <dfn>converting a character width to pixels</dfn> algorithm returns <span data-x="">(<var>size</var>-1)×<var>avg</var> + <var>max</var></span>,
where <var>size</var> is the character width to convert, <var>avg</var> is the
average character width of the primary font for the element for which the algorithm is being run,
in pixels, and <var>max</var> is the maximum character width of that same font, also in
pixels. (The element's <span>'letter-spacing'</span> property does not affect the result.)</p>
<p>These text controls are expected to be <span data-x="scroll container">scroll
containers</span> and support scrolling in the <span>inline axis</span>, but not the <span>block
axis</span>.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>input</code> element as domain-specific widgets</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-date">Date</span> state is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box depicting a date control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-month">Month</span> state is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box depicting a month control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-week">Week</span> state is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box depicting a week control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-time">Time</span> state is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box depicting a time control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-datetime-local">Local Date and Time</span> state is a
<span>devolvable widget</span> expected to render as an <span>'inline-block'</span> box depicting
a local date and time control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-number">Number</span> state is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box depicting a number control.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-number">Number</span> state is an
<span>element with default preferred size</span>, and user agents are expected to apply the
<span>'field-sizing'</span> CSS property to the element. The <span>block size</span> of the
<span>intrinsic size</span> is about one line high. If the <span>'field-sizing'</span> property
on the element has a <span>computed value</span> of
<span data-x="field-sizing-content">'content'</span>, the <span>inline size</span> of the
<span>intrinsic size</span> is expected to be about as wide as necessary to show the current
<span data-x="concept-fe-value">value</span>. Otherwise, the <span>inline size</span> of the
<span>intrinsic size</span> is expected to be about as wide as necessary to show the widest
possible value.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-date">Date</span>,
<span data-x="attr-input-type-month">Month</span>,
<span data-x="attr-input-type-week">Week</span>, <span data-x="attr-input-type-time">Time</span>,
or <span data-x="attr-input-type-datetime-local">Local Date and Time</span> state, is expected to
be about one line high, and about as wide as necessary to show the widest possible value.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>input</code> element as a range control</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-range">Range</span> state is a <span>non-devolvable
widget</span>. Its expected <span>native appearance</span> is to render as an
<span>'inline-block'</span> box depicting a slider control.</p>
<p>When this control has a <span>horizontal writing mode</span>, the control is expected to be a
horizontal slider. Its lowest value is on the right if the <span>'direction'</span> property has a
<span>computed value</span> of 'rtl', and on the left otherwise. When this control has a
<span>vertical writing mode</span>, it is expected to be a vertical slider. Its lowest value is on
the bottom if the <span>'direction'</span> property has a <span>computed value</span> of 'rtl', and
on the top otherwise.</p>
<p>Predefined suggested values (provided by the <code data-x="attr-input-list">list</code>
attribute) are expected to be shown as tick marks on the slider, which the slider can snap to.</p>
<p class="XXX">Need to detail the expected <span>primitive appearance</span>.</p>
</div>
<div w-nodev>
<!--en-GB--><h4 id="the-input-element-as-a-colour-well">The <code>input</code> element as a color
well</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-color">Color</span> state is expected to depict a color well,
which, when activated, provides the user with a color picker (e.g. a color wheel or color
palette) from which the color can be changed. The element, when it generates a <span>CSS
box</span>, is expected to use <span>button layout</span>, that has no child boxes of the
<span>anonymous button content box</span>. The <span>anonymous button content box</span> is
expected to have a <span data-x="presentational hints">presentational hint</span> setting the
<span>'background-color'</span> property to the element's <span
data-x="concept-fe-value">value</span>.</p>
<p>Predefined suggested values (provided by the <code data-x="attr-input-list">list</code>
attribute) are expected to be shown in the color picker interface, not on the color well
itself.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>input</code> element as a checkbox and radio button widgets</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-checkbox">Checkbox</span> state is a <span>non-devolvable
widget</span> expected to render as an <span>'inline-block'</span> box containing a single
checkbox control, with no label.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-radio">Radio Button</span> state is a <span>non-devolvable
widget</span> expected to render as an <span>'inline-block'</span> box containing a single radio
button control, with no label.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>input</code> element as a file upload control</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-file">File Upload</span> state, when it generates a <span>CSS
box</span>, is expected to render as an <span>'inline-block'</span> box containing a span of text
giving the filename(s) of the <span data-x="concept-input-type-file-selected">selected
files</span>, if any, followed by a button that, when activated, provides the user with a file
picker from which the selection can be changed. The button is expected to use <span>button
layout</span> and match the <span>'::file-selector-button'</span> pseudo-element. The contents of
its <span>anonymous button content box</span> are expected to be
<span>implementation-defined</span> (and possibly locale-specific) text, for example "Choose
file".</p>
<p>User agents may handle an <code>input</code> element whose
<code data-x="attr-input-type">type</code> attribute is in the
<span data-x="attr-input-type-file">File Upload</span> state as an
<span>element with default preferred size</span>, and user agents may apply the
<span>'field-sizing'</span> CSS property to the element. If the <span>'field-sizing'</span>
property on the element has a <span>computed value</span> of
<span data-x="field-sizing-content">'content'</span>, the <span>intrinsic size</span> of the
element is expected to depend on its content such as the <span>'::file-selector-button'</span>
pseudo-element and chosen file names.</p>
</div>
<div w-nodev>
<h4>The <code>input</code> element as a button</h4>
<p>An <code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in
the <span data-x="attr-input-type-submit">Submit Button</span>, <span
data-x="attr-input-type-reset">Reset Button</span>, or <span
data-x="attr-input-type-button">Button</span> state, when it generates a <span>CSS box</span>, is
expected to depict a button and use <span>button layout</span> and the contents of the
<span>anonymous button content box</span> are expected to be the text of the element's <code
data-x="attr-input-value">value</code> attribute, if any, or text derived from the element's <code
data-x="attr-input-type">type</code> attribute in an <span>implementation-defined</span> (and
probably locale-specific) fashion, if not.</p>
</div>
<div w-nodev>
<h4>The <code>marquee</code> element</h4>
<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";
marquee {
display: inline-block;
text-align: initial;
overflow: hidden !important;
}</code></pre>
<p>The <code>marquee</code> element, while <span data-x="concept-marquee-on">turned on</span>, is
expected to render in an animated fashion according to its attributes as follows:</p>
<dl>
<dt>If the element's <code data-x="attr-marquee-behavior">behavior</code> attribute is in the
<span data-x="attr-marquee-behavior-scroll">scroll</span> state</dt>
<dd>
<p>Slide the contents of the element in the direction described by the <code
data-x="attr-marquee-direction">direction</code> attribute as defined below, such that it begins
off the start side of the <code>marquee</code>, and ends flush with the inner end side.</p>
<p class="example">For example, if the <code data-x="attr-marquee-direction">direction</code>
attribute is <span data-x="attr-marquee-direction-left">left</span> (the default), then the
contents would start such that their left edge are off the side of the right edge of the
<code>marquee</code>'s <span>content area</span>, and the contents would then slide up to the
point where the left edge of the contents are flush with the left inner edge of the
<code>marquee</code>'s <span>content area</span>.</p>
<p>Once the animation has ended, the user agent is expected to <span>increment the marquee
current loop index</span>. If the element is still <span data-x="concept-marquee-on">turned
on</span> after this, then the user agent is expected to restart the animation.</p>
</dd>
<dt>If the element's <code data-x="attr-marquee-behavior">behavior</code> attribute is in the
<span data-x="attr-marquee-behavior-slide">slide</span> state</dt>
<dd>
<p>Slide the contents of the element in the direction described by the <code
data-x="attr-marquee-direction">direction</code> attribute as defined below, such that it begins
off the start side of the <code>marquee</code>, and ends off the end side of the
<code>marquee</code>.</p>
<p class="example">For example, if the <code data-x="attr-marquee-direction">direction</code>
attribute is <span data-x="attr-marquee-direction-left">left</span> (the default), then the
contents would start such that their left edge are off the side of the right edge of the
<code>marquee</code>'s <span>content area</span>, and the contents would then slide up to the
point where the <em>right</em> edge of the contents are flush with the left inner edge of the
<code>marquee</code>'s <span>content area</span>.</p>
<p>Once the animation has ended, the user agent is expected to <span>increment the marquee
current loop index</span>. If the element is still <span data-x="concept-marquee-on">turned
on</span> after this, then the user agent is expected to restart the animation.</p>
</dd>
<dt>If the element's <code data-x="attr-marquee-behavior">behavior</code> attribute is in the
<span data-x="attr-marquee-behavior-alternate">alternate</span> state</dt>
<dd>
<p>When the <span>marquee current loop index</span> is even (or zero), slide the contents of the
element in the direction described by the <code data-x="attr-marquee-direction">direction</code>
attribute as defined below, such that it begins flush with the start side of the
<code>marquee</code>, and ends flush with the end side of the <code>marquee</code>.</p>
<p>When the <span>marquee current loop index</span> is odd, slide the contents of the element in
the opposite direction than that described by the <code
data-x="attr-marquee-direction">direction</code> attribute as defined below, such that it begins
flush with the end side of the <code>marquee</code>, and ends flush with the start side of the
<code>marquee</code>.</p>
<p class="example">For example, if the <code data-x="attr-marquee-direction">direction</code>
attribute is <span data-x="attr-marquee-direction-left">left</span> (the default), then the
contents would with their right edge flush with the right inner edge of the
<code>marquee</code>'s <span>content area</span>, and the contents would then slide up to the
point where the <em>left</em> edge of the contents are flush with the left inner edge of the
<code>marquee</code>'s <span>content area</span>.</p>
<p>Once the animation has ended, the user agent is expected to <span>increment the marquee
current loop index</span>. If the element is still <span data-x="concept-marquee-on">turned
on</span> after this, then the user agent is expected to continue the animation.</p>
</dd>
</dl>
<p>The <code data-x="attr-marquee-direction">direction</code> attribute has the meanings described
in the following table:</p>
<table>
<thead>
<tr>
<th><code data-x="attr-marquee-direction">direction</code> attribute state
<th>Direction of animation
<th>Start edge
<th>End edge
<th>Opposite direction
<tbody>
<tr>
<td><span data-x="attr-marquee-direction-left">left</span>
<td>← Right to left
<td>Right
<td>Left
<td>→ Left to Right
<tr>
<td><span data-x="attr-marquee-direction-right">right</span>
<td>→ Left to Right
<td>Left
<td>Right
<td>← Right to left
<tr>
<td><span data-x="attr-marquee-direction-up">up</span>
<td>↑ Up (Bottom to Top)
<td>Bottom
<td>Top
<td>↓ Down (Top to Bottom)
<tr>
<td><span data-x="attr-marquee-direction-down">down</span>
<td>↓ Down (Top to Bottom)
<td>Top
<td>Bottom
<td>↑ Up (Bottom to Top)
</table>
<p>In any case, the animation should proceed such that there is a delay given by the <span>marquee
scroll interval</span> between each frame, and such that the content moves at most the distance
given by the <span>marquee scroll distance</span> with each frame.</p>
<p>When a <code>marquee</code> element has a <code undefined data-x="attr-marquee-bgcolor">bgcolor</code>
attribute set, the value is expected to be parsed using the <span>rules for parsing a legacy color
value</span>, and if that does not return failure, the user agent is expected to treat the
attribute as a <span data-x="presentational hints">presentational hint</span> setting the element's
<span>'background-color'</span> property to the resulting color.</p>
<p>The <code undefined data-x="attr-marquee-width">width</code> and <code
undefined data-x="attr-marquee-height">height</code> attributes on a <code>marquee</code> element
<span data-x="maps to the dimension property">map to the dimension properties</span>
<span>'width'</span> and <span>'height'</span> on the element respectively.</p>
<p>The <span>natural height</span> of a <code>marquee</code> element with its <code
data-x="attr-marquee-direction">direction</code> attribute in the <span
data-x="attr-marquee-direction-up">up</span> or <span
data-x="attr-marquee-direction-down">down</span> states is 200 <span data-x="'px'">CSS
pixels</span>.</p>
<p>The <code undefined data-x="attr-marquee-vspace">vspace</code> attribute of a
<code>marquee</code> element <span data-x="maps to the dimension property">maps to the dimension
properties</span> <span>'margin-top'</span> and <span>'margin-bottom'</span> on the element. The
<code undefined data-x="attr-marquee-hspace">hspace</code> attribute of a <code>marquee</code>
element <span data-x="maps to the dimension property">maps to the dimension properties</span>
<span>'margin-left'</span> and <span>'margin-right'</span> on the element.</p>
</div>
<div w-nodev>
<h4>The <code>meter</code> element</h4>
<pre><code class="css" data-x="">@namespace "http://www.w3.org/1999/xhtml";
meter { appearance: auto; }</code></pre>
<p>The <code>meter</code> element is a <span>devolvable widget</span>. Its expected <span>native
appearance</span> is to render as an <span>'inline-block'</span> box with a <span>'block-size'</span>
of '1em' and a <span>'inline-size'</span> of '5em', a <span>'vertical-align'</span> of '-0.2em', and
with its contents depicting a gauge.</p>
<p>When this element has a <span>horizontal writing mode</span>, the depiction is expected to be of
a horizontal gauge. Its minimum value is on the right if the <span>'direction'</span> property has
a <span>computed value</span> of 'rtl', and on the left otherwise. When this element has a
<span>vertical writing mode</span>, it is expected to depict a vertical gauge. Its minimum value is
on the bottom if the <span>'direction'</span> property has a <span>computed value</span> of 'rtl',
and on the top otherwise.</p>
<p>User agents are expected to use a presentation consistent with platform conventions for gauges,
if any.</p>
<p class="note">Requirements for what <!--non-normative-->must be depicted in the gauge are
included in the definition of the <code>meter</code> element.</p>
<p class="XXX">Need to detail the expected <span>primitive appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>progress</code> element</h4>
<pre><code class="css" data-x="">@namespace "http://www.w3.org/1999/xhtml";
progress { appearance: auto; }</code></pre>
<p>The <code>progress</code> element is a <span>devolvable widget</span>. Its expected
<span>native appearance</span> is to render as an <span>'inline-block'</span> box with a
<span>'block-size'</span> of '1em' and a <span>'inline-size'</span> of '10em', and a
<span>'vertical-align'</span> of '-0.2em'.</p>
<!-- https://software.hixie.ch/utilities/js/canvas/?c.clearRect(0%2C%200%2C%20640%2C%20480)%3B%0Ac.save()%3B%0Atry%20%7B%0A%20%20c.fillStyle%20%3D%20%27black%27%3B%0A%20%20c.font%20%3D%20%278px%20sans-serif%27%3B%0A%20%20c.fillText(%27Horizontal%20ltr%27%2C%2030%2C105)%3B%0A%20%20c.fillText(%27Horizontal%20rtl%27%2C125%2C105)%3B%0A%20%20c.fillText(%27Vertical%20ltr%27%2C%20192%2C105)%3B%0A%20%20c.fillText(%27Vertical%20rtl%27%2C%20233%2C105)%3B%0A%20%20c.font%20%3D%20%27700%2010px%20sans-serif%27%3B%0A%20%20c.fillText(%27Progress%20Bars%27%2C%2013%2C30)%3B%0A%20%20c.font%20%3D%20%27100%2010px%20sans-serif%27%3B%0A%20%20c.fillText(%27(80%25)%27%2C%2037%2C45)%3B%0A%0A%20%20c.beginPath()%3B%0A%20%20var%20g%20%3D%20c.createLinearGradient(10%2C0%2C80%2C0)%3B%0A%20%20g.addColorStop(0%2C%20%27%2300FF00%27)%3B%0A%20%20g.addColorStop(0.8%2C%20%27%2300FF00%27)%3B%0A%20%20g.addColorStop(0.9%2C%20%27%23FFFF00%27)%3B%0A%20%20c.fillStyle%20%3D%20g%3B%0A%20%20c.rect(10%2C80%2C80%2C15)%3B%0A%20%20c.fill()%3B%0A%20%20c.strokeStyle%20%3D%20%27black%27%3B%0A%20%20c.stroke()%3B%0A%0A%20%20c.beginPath()%3B%0A%20%20var%20g%20%3D%20c.createLinearGradient(105%2C0%2C175%2C0)%3B%0A%20%20g.addColorStop(0%2C%20%27%23FFFF00%27)%3B%0A%20%20g.addColorStop(0.2%2C%20%27%23FFFF00%27)%3B%0A%20%20g.addColorStop(0.4%2C%20%27%2300FF00%27)%3B%0A%20%20c.fillStyle%20%3D%20g%3B%0A%20%20c.rect(105%2C80%2C80%2C15)%3B%0A%20%20c.fill()%3B%0A%20%20c.strokeStyle%20%3D%20%27black%27%3B%0A%20%20c.stroke()%3B%0A%0A%20%20c.beginPath()%3B%0A%20%20var%20g%20%3D%20c.createLinearGradient(0%2C80%2C0%2C20)%3B%0A%20%20g.addColorStop(0%2C%20%27%2300FF00%27)%3B%0A%20%20g.addColorStop(0.75%2C%20%27%2300FF00%27)%3B%0A%20%20g.addColorStop(0.85%2C%20%27%23FFFF00%27)%3B%0A%20%20c.fillStyle%20%3D%20g%3B%0A%20%20c.rect(203%2C15%2C15%2C80)%3B%0A%20%20c.fill()%3B%0A%20%20c.strokeStyle%20%3D%20%27black%27%3B%0A%20%20c.stroke()%3B%0A%0A%20%20c.beginPath()%3B%0A%20%20var%20g%20%3D%20c.createLinearGradient(0%2C80%2C0%2C20)%3B%0A%20%20g.addColorStop(0%2C%20%27%23FFFF00%27)%3B%0A%20%20g.addColorStop(0.15%2C%20%27%2300FF00%27)%3B%0A%20%20c.fillStyle%20%3D%20g%3B%0A%20%20c.rect(242%2C15%2C15%2C80)%3B%0A%20%20c.fill()%3B%0A%20%20c.strokeStyle%20%3D%20%27black%27%3B%0A%20%20c.stroke()%3B%0A%7D%20finally%20%7B%0A%20%20c.restore()%3B%0A%7D%0A -->
<p> <img src="/images/sample-progress.png" alt="" width=276 height=115 class="extra"> When the this
element has a <span>horizontal writing mode</span>, the element is expected to be depicted as a
horizontal progress bar. The start is on the right and the end is on the left if the
<span>'direction'</span> property on this element has a <span>computed value</span> of 'rtl', and
with the start on the left and the end on the right otherwise. When this element has a
<span>vertical writing mode</span>, it is expected to be depicted as a vertical progress bar. The
start is on the bottom and the end is on the top if the <span>'direction'</span> property on this
element has a <span>computed value</span> of 'rtl', and with the start on the top and the end on
the bottom otherwise.</p>
<p>User agents are expected to use a presentation consistent with platform conventions for
progress bars. In particular, user agents are expected to use different presentations for
determinate and indeterminate progress bars. User agents are also expected to vary the
presentation based on the dimensions of the element.</p>
<p class="note">Requirements for how to determine if the progress bar is determinate or
indeterminate, and what progress a determinate progress bar is to show, are included in the
definition of the <code>progress</code> element.</p>
<p class="XXX">Need to detail the expected <span>primitive appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>select</code> element</h4>
<p>The <code>select</code> element is an <span>element with default preferred size</span>, and
user agents are expected to apply the <span>'field-sizing'</span> CSS property to
<code>select</code> elements.
<p>A <code>select</code> element is either a <dfn export for="select">list box</dfn> or a <dfn
export for="select">drop-down box</dfn>, depending on its attributes.</p>
<p>A <code>select</code> element whose <code data-x="attr-select-multiple">multiple</code>
attribute is present is expected to render as a multi-select <span>list box</span>.</p>
<p>A <code>select</code> element whose <code data-x="attr-select-multiple">multiple</code>
attribute is absent, and whose <span data-x="concept-select-size">display size</span> is greater
than 1, is expected to render as a single-select <span>list box</span>.</p>
<p>When the element renders as a <span>list box</span>, it is a <span>devolvable widget</span>
expected to render as an <span>'inline-block'</span> box. The <span>inline size</span> of its
<span>intrinsic size</span> is the <span>width of the <code>select</code>'s labels</span> plus
the width of a scrollbar. The <span>block size</span> of its <span>intrinsic size</span> is
determined by the following steps:</p>
<ol>
<li>
<p>If the <span>'field-sizing'</span> property on the element has a <span>computed value</span>
of <span data-x="field-sizing-content">'content'</span>, return the height necessary to contain
all rows for items.</p>
</li>
<li>
<p>If the <code data-x="attr-select-size">size</code> attribute is absent or it has no valid
value, return the height necessary to contain four rows.</p>
</li>
<li>
<p>Otherwise, return the height necessary to contain as many rows for items as given by the
element's <span data-x="concept-select-size">display size</span>.</p>
</li>
</ol>
<p>A <code>select</code> element whose <code data-x="attr-select-multiple">multiple</code>
attribute is absent, and whose <span data-x="concept-select-size">display size</span> is 1, is
expected to render as an <span>'inline-block'</span> one-line <span>drop-down box</span>.
The <span>inline size</span> of its <span>intrinsic size</span> is the
<span>width of the <code>select</code>'s labels</span>. If the <span>'field-sizing'</span>
property on the element has a <span>computed value</span> of
<span data-x="field-sizing-content">'content'</span>, the <span>inline size</span> of the
<span>intrinsic size</span> depends on the shown text. The shown text is typically the label of
an <code>option</code> of which <span data-x="concept-option-selectedness">selectedness</span> is
set to true.</p>
<p>When the element renders as a <span>drop-down box</span>, it is a <span>devolvable
widget</span>. Its appearance in the devolved state, as well as its appearance when the
<span>computed value</span> of the element's <span>'appearance'</span> property is
<code>'menulist-button'</code>, is that of a drop-down box, including a "drop-down button",
but not necessarily rendered using a native control of the host operating system. In such a state,
CSS properties such as <span>'color'</span>, <span>'background-color'</span>, and 'border' should
not be disregarded (as is generally permissible when rendering an element according to its
<span>native appearance</span>).</p>
<p>In either case (<span>list box</span> or <span>drop-down box</span>), the element's items are
expected to be the element's <span data-x="concept-select-option-list">list of options</span>,
with the element's <code>optgroup</code> element <span data-x="concept-tree-child">children</span>
providing headers for groups of options where applicable.</p>
<p>An <code>optgroup</code> element is expected to be rendered by displaying the element's <code
data-x="attr-optgroup-label">label</code> attribute.</p>
<p>An <code>option</code> element is expected to be rendered by displaying the element's <span
data-x="concept-option-label">label</span>, indented under its <code>optgroup</code> element if it
has one.</p>
<p>Each sequence of one or more child <code>hr</code> element siblings may be rendered as a single
separator.</p>
<p>The <dfn>width of the <code>select</code>'s labels</dfn> is the wider of the width necessary to
render the widest <code>optgroup</code>, and the width necessary to render the widest
<code>option</code> element in the element's <span data-x="concept-select-option-list">list of
options</span> (including its indent, if any).</p>
<p>If a <code>select</code> element contains a <span>placeholder label option</span>, the user
agent is expected to render that <code>option</code> in a manner that conveys that it is a label,
rather than a valid option of the control. This can include preventing the <span>placeholder label
option</span> from being explicitly selected by the user. When the <span>placeholder label
option</span>'s <span data-x="concept-option-selectedness">selectedness</span> is true, the control
is expected to be displayed in a fashion that indicates that no valid option is currently
selected.</p>
<p>User agents are expected to render the labels in a <code>select</code> in such a manner that
any alignment remains consistent whether the label is being displayed as part of the page or in a
menu control.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h4>The <code>textarea</code> element</h4>
<p>The <code>textarea</code> element is a <span>devolvable widget</span> expected to render as an
<span>'inline-block'</span> box depicting a multiline text control. If this multiline text control
provides a selection, then, when the user changes the current selection, the user agent is
expected to <span>queue an element task</span> on the <span>user interaction task source</span>
given the <code>textarea</code> element to <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-select">select</code> at the element, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p>
<p>The <code>textarea</code> element is an <span>element with default preferred size</span>, and
user agents are expected to apply the <span>'field-sizing'</span> CSS property to
<code>textarea</code> elements.
<p>If the <span>'field-sizing'</span> property on the element has a <span>computed value</span>
of <span data-x="field-sizing-content">'content'</span>, the <span>intrinsic size</span> is
determined from the text which the element shows. The text is either a
<span data-x="concept-textarea-raw-value">raw value</span> or a short hint specified by the
<code data-x="attr-textarea-placeholder">placeholder</code> attribute. User agents may take the
text caret size into account in the <span>intrinsic size</span>. Otherwise, its
<span>intrinsic size</span> is computed from <span>textarea effective width</span> and
<span>textarea effective height</span> (as defined below).</p>
<p>The <dfn>textarea effective width</dfn> of a <code>textarea</code> element is <span
data-x=""><var>size</var>×<var>avg</var> + <var>sbw</var></span>, where
<var>size</var> is the element's <span data-x="attr-textarea-cols-value">character width</span>,
<var>avg</var> is the average character width of the primary font of the element, in <span
data-x="'px'">CSS pixels</span>, and <var>sbw</var> is the width of a scrollbar, in <span
data-x="'px'">CSS pixels</span>. (The element's <span>'letter-spacing'</span> property does not
affect the result.)</p>
<p>The <dfn>textarea effective height</dfn> of a <code>textarea</code> element is the height in
<span data-x="'px'">CSS pixels</span> of the number of lines specified the element's <span
data-x="attr-textarea-rows-value">character height</span>, plus the height of a scrollbar in <span
data-x="'px'">CSS pixels</span>.</p>
<p>User agents are expected to apply the <span>'white-space'</span> CSS property to
<code>textarea</code> elements. For historical reasons, if the element has a <code
data-x="attr-textarea-wrap">wrap</code> attribute whose value is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="attr-textarea-wrap-off"
undefined>off</code>", then the user agent is expected to treat the attribute as a <span
data-x="presentational hints">presentational hint</span> setting the element's
<span>'white-space'</span> property to 'pre'.</p>
<p class="XXX">Need to detail the expected <span>native appearance</span> and <span>primitive
appearance</span>.</p>
</div>
<div w-nodev>
<h3>Frames and framesets</h3>
<p>User agents are expected to render <code>frameset</code> elements as a box with the height and
width of the <span>viewport</span>, with a surface rendered according to the following layout
algorithm:</p>
<ol>
<li>
<p>The <var>cols</var> and <var>rows</var> variables are lists of zero or more pairs consisting
of a number and a unit, the unit being one of <i>percentage</i>, <i>relative</i>, and
<i>absolute</i>.</p>
<p>Use the <span>rules for parsing a list of dimensions</span> to parse the value of the
element's <code undefined data-x="attr-frameset-cols">cols</code> attribute, if there is one.
Let <var>cols</var> be the result, or an empty list if there is no such attribute.</p>
<p>Use the <span>rules for parsing a list of dimensions</span> to parse the value of the
element's <code undefined data-x="attr-frameset-rows">rows</code> attribute, if there is one.
Let <var>rows</var> be the result, or an empty list if there is no such attribute.</p>
</li>
<li>
<p>For any of the entries in <var>cols</var> or <var>rows</var> that have the number zero and
the unit <i>relative</i>, change the entry's number to one.</p>
</li>
<li>
<p>If <var>cols</var> has no entries, then add a single entry consisting of the value 1 and the
unit <i>relative</i> to <var>cols</var>.</p>
<p>If <var>rows</var> has no entries, then add a single entry consisting of the value 1 and the
unit <i>relative</i> to <var>rows</var>.</p>
</li>
<li>
<p>Invoke the algorithm defined below to <span>convert a list of dimensions to a list of pixel
values</span> using <var>cols</var> as the input list, and the width of the surface that the
<code>frameset</code> is being rendered into, in <span data-x="'px'">CSS pixels</span>, as the
input dimension. Let <var>sized cols</var> be the resulting list.</p>
<p>Invoke the algorithm defined below to <span>convert a list of dimensions to a list of pixel
values</span> using <var>rows</var> as the input list, and the height of the surface that the
<code>frameset</code> is being rendered into, in <span data-x="'px'">CSS pixels</span>, as the
input dimension. Let <var>sized rows</var> be the resulting list.</p>
</li>
<li>
<p>Split the surface into a grid of <var>w</var>×<var>h</var>
rectangles, where <var>w</var> is the number of entries in <var>sized cols</var> and
<var>h</var> is the number of entries in <var>sized rows</var>.</p>
<p>Size the columns so that each column in the grid is as many <span data-x="'px'">CSS
pixels</span> wide as the corresponding entry in the <var>sized cols</var> list.</p>
<p>Size the rows so that each row in the grid is as many <span data-x="'px'">CSS pixels</span>
high as the corresponding entry in the <var>sized rows</var> list.</p>
</li>
<li>
<p>Let <var>children</var> be the list of <code>frame</code> and <code>frameset</code> elements
that are <span data-x="concept-tree-child">children</span> of the <code>frameset</code> element
for which the algorithm was invoked.</p>
</li>
<li>
<p>For each row of the grid of rectangles created in the previous step, from top to bottom, run
these substeps:</p>
<ol>
<li>
<p>For each rectangle in the row, from left to right, run these substeps:</p>
<ol>
<li>
<p>If there are any elements left in <var>children</var>, take the first element in the
list, and assign it to the rectangle.</p>
<p>If this is a <code>frameset</code> element, then recurse the entire <code>frameset</code>
layout algorithm for that <code>frameset</code> element, with the rectangle as the
surface.</p>
<p>Otherwise, it is a <code>frame</code> element; render its <span>content
navigable</span>, positioned and sized to fit the rectangle.</p>
</li>
<li>
<p>If there are any elements left in <var>children</var>, remove the first element from
<var>children</var>.</p>
</li>
</ol>
</li>
</ol>
</li>
<li>
<p>If the <code>frameset</code> element <span>has a border</span>, draw an outer set of borders
around the rectangles, using the element's <span>frame border color</span>.</p>
<p>For each rectangle, if there is an element assigned to that rectangle, and that element
<span>has a border</span>, draw an inner set of borders around that rectangle, using the
element's <span>frame border color</span>.</p>
<p>For each (visible) border that does not abut a rectangle that is assigned a
<code>frame</code> element with a <code undefined data-x="attr-frame-noresize">noresize</code>
attribute (including rectangles in further nested <code>frameset</code> elements), the user
agent is expected to allow the user to move the border, resizing the rectangles within, keeping
the proportions of any nested <code>frameset</code> grids.</p>
<p>A <code>frameset</code> or <code>frame</code> element <dfn>has a border</dfn> if the
following algorithm returns true:</p>
<ol>
<li><p>If the element has a <code data-x="">frameborder</code> attribute whose value is not the
empty string and whose first character is either a U+0031 DIGIT ONE (1) character, a U+0079
LATIN SMALL LETTER Y character (y), or a U+0059 LATIN CAPITAL LETTER Y character (Y), then
return true.</p></li>
<li><p>Otherwise, if the element has a <code data-x="">frameborder</code> attribute, return
false.</p></li>
<li><p>Otherwise, if the element has a parent element that is a <code>frameset</code> element,
then return true if <em>that</em> element <span>has a border</span>, and false if it does
not.</p></li>
<li><p>Otherwise, return true.</p></li>
</ol>
<p>The <!--en-GB--><dfn id="frame-border-colour">frame border color</dfn> of a
<code>frameset</code> or <code>frame</code> element is the color obtained from the following
algorithm:</p>
<ol>
<li><p>If the element has a <code data-x="">bordercolor</code> attribute, and applying the
<span>rules for parsing a legacy color value</span> to that attribute's value does not return
failure, then return the color so obtained.</p></li>
<li><p>Otherwise, if the element has a parent element that is a <code>frameset</code> element,
then return the <span>frame border color</span> of that element.</p>
<li><p>Otherwise, return gray.</p></li>
</ol>
</li>
</ol>
<p>The algorithm to <dfn>convert a list of dimensions to a list of pixel values</dfn> consists of
the following steps:</p>
<ol>
<li>
<p>Let <var>input list</var> be the list of numbers and units passed to the algorithm.</p>
<p>Let <var>output list</var> be a list of numbers the same length as <var>input list</var>, all
zero.</p>
<p>Entries in <var>output list</var> correspond to the entries in <var>input list</var> that
have the same position.</p>
</li>
<li><p>Let <var>input dimension</var> be the size passed to the algorithm.</p>
<li>
<p>Let <var>total percentage</var> be the sum of all the numbers in <var>input list</var> whose
unit is <i>percentage</i>.</p>
<p>Let <var>total relative</var> be the sum of all the numbers in <var>input list</var> whose
unit is <i>relative</i>.</p>
<p>Let <var>total absolute</var> be the sum of all the numbers in <var>input list</var> whose
unit is <i>absolute</i>.</p>
<p>Let <var>remaining space</var> be the value of <var>input dimension</var>.</p>
</li>
<li>
<p>If <var>total absolute</var> is greater than <var>remaining space</var>, then for each entry
in <var>input list</var> whose unit is <i>absolute</i>, set the corresponding value in
<var>output list</var> to the number of the entry in <var>input list</var> multiplied by
<var>remaining space</var> and divided by <var>total absolute</var>. Then, set <var>remaining
space</var> to zero.</p>
<p>Otherwise, for each entry in <var>input list</var> whose unit is <i>absolute</i>, set the
corresponding value in <var>output list</var> to the number of the entry in <var>input
list</var>. Then, decrement <var>remaining space</var> by <var>total absolute</var>.</p>
</li>
<li>
<p>If <var>total percentage</var> multiplied by the <var>input dimension</var> and divided by
100 is greater than <var>remaining space</var>, then for each entry in <var>input list</var>
whose unit is <i>percentage</i>, set the corresponding value in <var>output list</var> to the
number of the entry in <var>input list</var> multiplied by <var>remaining space</var> and
divided by <var>total percentage</var>. Then, set <var>remaining space</var> to zero.</p>
<p>Otherwise, for each entry in <var>input list</var> whose unit is <i>percentage</i>, set the
corresponding value in <var>output list</var> to the number of the entry in <var>input
list</var> multiplied by the <var>input dimension</var> and divided by 100. Then, decrement
<var>remaining space</var> by <var>total percentage</var> multiplied by the <var>input
dimension</var> and divided by 100.</p>
</li>
<li>
<p>For each entry in <var>input list</var> whose unit is <i>relative</i>, set the corresponding
value in <var>output list</var> to the number of the entry in <var>input list</var> multiplied
by <var>remaining space</var> and divided by <var>total relative</var>.</p>
</li>
<li><p>Return <var>output list</var>.</p></li>
</ol>
<p>User agents working with integer values for frame widths (as opposed to user agents that can
lay frames out with subpixel accuracy) are expected to distribute the remainder first to the last
entry whose unit is <i>relative</i>, then equally (not proportionally) to each entry whose unit is
<i>percentage</i>, then equally (not proportionally) to each entry whose unit is <i>absolute</i>,
and finally, failing all else, to the last entry.</p>
<hr>
<!--
<p>The user agent is expected to force the <span>'display'</span> property of <code>frame</code>
elements to 'block', the <span>'height'</span> property of <code>frame</code> elements to 0, and
the <span>'width'</span> property of <code>frame</code> elements to 0, irrespective of CSS rules.
(This only matters for when a <code>frame</code> element is rendered outside a
<code>frameset</code>.)</p>
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2722 - as of Jan 2014, Chrome did this, but Firefox did not
-->
<p>The contents of a <code>frame</code> element that does not have a <code>frameset</code> parent
are expected to be rendered as <span>transparent black</span>; the user agent is expected to not
render its <span>content navigable</span> in this case, and its <span>content navigable</span> is
expected to have a <span>viewport</span> with zero width and zero height.</p>
</div>
<div w-nodev>
<h3>Interactive media</h3>
<h4>Links, forms, and navigation</h4>
<p>User agents are expected to allow the user to control aspects of <span>hyperlink</span>
activation and <span>form submission</span>, such as which <span>navigable</span> is to be used
for the subsequent <span data-x="navigate">navigation</span>.</p>
<p>User agents are expected to allow users to discover the destination of <span
data-x="hyperlink">hyperlinks</span> and of <span data-x="form">forms</span> before triggering their
<span data-x="navigate">navigation</span>.</p>
<p>User agents are expected to inform the user of whether a <span>hyperlink</span> includes
<span>hyperlink auditing</span>, and to let them know at a minimum which domains will be contacted
as part of such auditing.</p>
<p>User agents may allow users to <span>navigate</span><!--DONAV cite=""--> <span
data-x="navigable">navigables</span> to the URLs <span data-x="encoding-parsing a
URL">indicated</span> by the <code data-x="">cite</code> attributes on <code>q</code>,
<code>blockquote</code>, <code>ins</code>, and <code>del</code> elements.</p>
<p>User agents may surface <span data-x="hyperlink">hyperlinks</span> created by <code>link</code>
elements in their user interface, as discussed <a
href="#providing-users-with-a-means-to-follow-hyperlinks-created-using-the-link-element">previously</a>.</p>
<h4>The <code data-x="attr-title">title</code> attribute</h4>
<p>User agents are expected to expose the <span>advisory information</span> of elements upon user
request, and to make the user aware of the presence of such information.</p>
<p>On interactive graphical systems where the user can use a pointing device, this could take the
form of a tooltip. When the user is unable to use a pointing device, then the user agent is
expected to make the content available in some other fashion, e.g. by making the element a
<span>focusable area</span> and always displaying the <span>advisory information</span> of the
currently <span>focused</span> element, or by showing the <span>advisory information</span> of the
elements under the user's finger on a touch device as the user pans around the screen.</p>
<p>U+000A LINE FEED (LF) characters are expected to cause line breaks in the tooltip; U+0009
CHARACTER TABULATION (tab) characters are expected to render as a nonzero horizontal shift that
lines up the next glyph with the next tab stop, with tab stops occurring at points that are
multiples of 8 times the width of a U+0020 SPACE character.</p>
<div class="example">
<p>For example, a visual user agent could make elements with a <code
data-x="attr-title">title</code> attribute <span>focusable</span>, and could make
any <span>focused</span> element with a <code data-x="attr-title">title</code> attribute
show its tooltip under the element while the element has focus. This would allow a user to tab
around the document to find all the advisory text.</p>
</div>
<div class="example">
<p>As another example, a screen reader could provide an audio cue when reading an element with a
tooltip, with an associated key to read the last tooltip for which a cue was played.</p>
</div>
<h4>Editing hosts</h4>
<p>The current text editing caret (i.e. the <span>active range</span>, if it is empty and in an
<span>editing host</span>), if any, is expected to act like an inline
<span>replaced element</span> with the vertical dimensions of the caret and with zero width for
the purposes of the CSS rendering model.</p>
<p class="note">This means that even an empty block can have the caret inside it, and that when
the caret is in such an element, it prevents <span data-x="collapsing margins">margins from
collapsing</span> through the element.</p>
<h4>Text rendered in native user interfaces</h4>
<p>User agents are expected to honor the Unicode semantics of text that is exposed in user
interfaces, for example supporting the bidirectional algorithm in text shown in dialogs, title
bars, popup menus, and tooltips. Text from the contents of elements is expected to be rendered in
a manner that honors <span>the directionality</span> of the element from which the text was
obtained. Text from attributes is expected to be rendered in a manner that honours the
<span>directionality of the attribute</span>.</p>
<div class="example">
<p>Consider the following markup, which has Hebrew text asking for a programming language, the
languages being text for which a left-to-right direction is important given the punctuation in
some of their names:</p>
<pre><code class="html"><p dir="rtl" lang="he">
<label>
<span data-x="" dir="rtl" lang="he">בחר שפת תכנות:</span>
<select>
<option dir="ltr">C++</option>
<option dir="ltr">C#</option>
<option dir="ltr">FreePascal</option>
<option dir="ltr">F#</option>
</select>
</label>
</p></code></pre>
<p>If the <code>select</code> element was rendered as a drop down box, a correct rendering would
ensure that the punctuation was the same both in the drop down, and in the box showing the
current selection.</p>
<p><img src="/images/bidiselect.png" width="206" height="105" alt=""></p> <!-- no need for alt
text, the previous paragraph describes it completely -->
</div>
<div class="example">
<p>The directionality of attributes depends on the attribute and on the element's <code
data-x="attr-dir">dir</code> attribute, as the following example demonstrates. Consider this
markup:</p>
<pre><code class="html"><bdo dir=ltr><table>
<tr>
<th abbr="(א" dir=ltr>A
<th abbr="(א" dir=rtl>A
<th abbr="(א" dir=auto>A
</table></bdo></code></pre>
<p>If the <code data-x="attr-th-abbr">abbr</code> attributes are rendered, e.g. in a tooltip or
other user interface, the first will have a left parenthesis (because the direction is 'ltr'),
the second will have a right parenthesis (because the direction is 'rtl'), and the third will
have a right parenthesis (because the direction is determined <em>from the attribute value</em>
to be 'rtl').</p>
<p>However, if instead the attribute was not a <span>directionality-capable attribute</span>, the
results would be different:</p>
<pre><code class="html"><bdo dir=ltr><table>
<tr>
<th data-abbr="(א" dir=ltr>A
<th data-abbr="(א" dir=rtl>A
<th data-abbr="(א" dir=auto>A
</table></bdo></code></pre>
<p>In this case, if the user agent were to expose the <code data-x="">data-abbr</code> attribute
in the user interface (e.g. in a debugging environment), the last case would be rendered with a
<em>left</em> parenthesis, because the direction would be determined from the element's
contents.</p>
</div>
<p>A string provided by a script (e.g. the argument to <code
data-x="dom-alert">window.alert()</code>) is expected to be treated as an independent set of one or
more bidirectional algorithm paragraphs when displayed, as defined by the bidirectional algorithm,
including, for instance, supporting the paragraph-breaking behavior of U+000A LINE FEED (LF)
characters. For the purposes of determining the paragraph level of such text in the bidirectional
algorithm, this specification does <em>not</em> provide a higher-level override of rules P2 and
P3. <ref>BIDI</ref></p>
<p>When necessary, authors can enforce a particular direction for a given paragraph by starting it
with the Unicode U+200E LEFT-TO-RIGHT MARK or U+200F RIGHT-TO-LEFT MARK characters.</p>
<div class="example">
<p>Thus, the following script:</p>
<pre><code class="js">alert('\u05DC\u05DE\u05D3 HTML \u05D4\u05D9\u05D5\u05DD!')</code></pre>
<p>...would always result in a message reading
"<bdo lang="" dir=rtl>למד LMTH היום!</bdo>"
(not "<bdo lang="" dir=ltr>דמל HTML םויה!</bdo>"),
regardless of the language of the user agent interface or the
direction of the page or any of its elements.</p>
</div>
<div class="example">
<p>For a more complex example, consider the following script:</p>
<pre class="bad"><code class="js">/* Warning: this script does not handle right-to-left scripts correctly */
var s;
if (s = prompt('What is your name?')) {
alert(s + '! Ok, Fred, ' + s + ', and Wilma will get the car.');
}</code></pre>
<p>When the user enters "<kbd>Kitty</kbd>", the user agent would alert "<samp>Kitty! Ok, Fred,
Kitty, and Wilma will get the car.</samp>". However, if the user enters "<kbd dir="rtl"
lang="ar">لا أفهم</kbd>", then the bidirectional
algorithm will determine that the direction of the paragraph is right-to-left, and so the output
will be the following unintended mess: "<samp lang=""><bdo
dir="rtl">لا أفهم! derF ,kO, لا أفهم, rac eht teg lliw amliW dna.</bdo></samp>"</p>
<p>To force an alert that starts with user-provided text (or other text of unknown
directionality) to render left-to-right, the string can be prefixed with a U+200E LEFT-TO-RIGHT
MARK character:</p>
<pre><code class="js">var s;
if (s = prompt('What is your name?')) {
alert('<strong>\u200E</strong>' + s + '! Ok, Fred, ' + s + ', and Wilma will get the car.');
}</code></pre>
</div>
<h3>Print media</h3>
<p>User agents are expected to allow the user to request the opportunity to <dfn>obtain a physical
form</dfn> (or a representation of a physical form) of a <code>Document</code>. For example,
selecting the option to print a page or convert it to PDF format. <ref>PDF</ref></p>
<p>When the user actually <span data-x="obtain a physical form">obtains a physical form</span> (or
a representation of a physical form) of a <code>Document</code>, the user agent is expected to
create a new rendering of the <code>Document</code> for the print media.</p>
<h3>Unstyled XML documents</h3>
<!-- https://hixie.ch/tests/evil/xml/ -->
<p>HTML user agents may, in certain circumstances, find themselves rendering non-HTML documents
that use vocabularies for which they lack any built-in knowledge. This section provides for a way
for user agents to handle such documents in a somewhat useful manner.</p>
<p>While a <code>Document</code> is an <span>unstyled document</span>, the user agent is expected
to render <span>an unstyled document view</span>.</p>
<p>A <code>Document</code> is an <dfn>unstyled document</dfn> while it matches the following
conditions:</p>
<ul>
<li>The <code>Document</code> has no author style sheets (whether referenced by HTTP headers, processing instructions, elements like <code>link</code>, inline elements like <code>style</code>, or any other mechanism).
<li>None of the elements in the <code>Document</code> have any <span>presentational hints</span>.
<li>None of the elements in the <code>Document</code> have any <span data-x="css-styling-attribute">style attributes</span>.
<li>None of the elements in the <code>Document</code> are in any of the following namespaces: <span>HTML namespace</span>, <span>SVG namespace</span>, <span>MathML namespace</span>
<li>The <code>Document</code> has no <span>focusable area</span> (e.g. from XLink) other than the <span>viewport</span>.
<li>The <code>Document</code> has no <span data-x="hyperlink">hyperlinks</span> (e.g. from XLink).
<li>There exists no <span data-x="concept-script">script</span> whose <span
data-x="concept-script-settings-object">settings object</span>'s <span
data-x="concept-settings-object-global">global object</span> is a <code>Window</code> object with
this <code>Document</code> as its <span data-x="concept-document-window">associated
<code>Document</code></span>.
<li>None of the elements in the <code>Document</code> have any registered event listeners.
</ul>
<p><dfn>An unstyled document view</dfn> is one where the DOM is not rendered according to CSS
(which would, since there are no applicable styles in this context, just result in a wall of
text), but is instead rendered in a manner that is useful for a developer. This could consist of
just showing the <code>Document</code> object's source, maybe with syntax highlighting, or it
could consist of displaying just the DOM tree, or simply a message saying that the page is not a
styled document.</p>
<p class="note">If a <code>Document</code> stops being an <span>unstyled document</span>, then the
conditions above stop applying, and thus a user agent following these requirements will switch to
using the regular CSS rendering.</p>
</div>
<h2 split-filename="obsolete" id="obsolete">Obsolete features</h2>
<h3>Obsolete but conforming features</h3>
<p>Features listed in this section will trigger warnings in conformance checkers.</p>
<p>Authors should not specify a <code data-x="attr-img-border">border</code> attribute on an
<code>img</code> element. If the attribute is present, its value must be the string "<code
data-x="">0</code>". CSS should be used instead.</p>
<p>Authors should not specify a <code data-x="attr-script-charset">charset</code> attribute on a
<code>script</code> element. If the attribute is present, its value must be an <span>ASCII
case-insensitive</span> match for "<code data-x="">utf-8</code>". (This has no effect in a
document that conforms to the requirements elsewhere in this standard of being encoded as
<span>UTF-8</span>.)</p>
<p>Authors should not specify a <code data-x="attr-script-language">language</code> attribute on a
<code>script</code> element. If the attribute is present, its value must be an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">JavaScript</code>" and either the
<code data-x="attr-script-type">type</code> attribute must be omitted or its value must be an
<span>ASCII case-insensitive</span> match for the string "<code data-x="">text/javascript</code>".
The attribute should be entirely omitted instead (with the value "<code
data-x="">JavaScript</code>", it has no effect), or replaced with use of the <code
data-x="attr-script-type">type</code> attribute.</p>
<p>Authors should not specify a value for the <code data-x="attr-script-type">type</code>
attribute on <code>script</code> elements that is the empty string or a <span>JavaScript MIME type
essence match</span>. Instead, they should omit the attribute, which has the same effect.</p>
<p>Authors should not specify a <code data-x="attr-style-type">type</code> attribute on a
<code>style</code> element. If the attribute is present, its value must be an <span>ASCII
case-insensitive</span> match for "<code>text/css</code>".</p>
<p>Authors should not specify the <code data-x="attr-a-name">name</code> attribute on
<code>a</code> elements. If the attribute is present, its value must not be the empty string and
must neither be equal to the value of any of the <span data-x="concept-id">IDs</span> in the
element's <span>tree</span> other than the element's own <span data-x="concept-id">ID</span>, if
any, nor be equal to the value of any of the other <code data-x="attr-a-name">name</code>
attributes on <code>a</code> elements in the element's <span>tree</span>. If this attribute is
present and the element has an <span data-x="concept-id">ID</span>, then the attribute's value
must be equal to the element's <span data-x="concept-id">ID</span>. In earlier versions of the
language, this attribute was intended as a way to specify possible targets for <span
data-x="concept-url-fragment">fragments</span> in <span data-x="URL">URLs</span>. The <code
data-x="attr-id">id</code> attribute should be used instead.</p>
<!-- remove this once type=number is widely supported -->
<p>Authors should not, but may despite requirements to the contrary elsewhere in this
specification, specify the <code data-x="attr-input-maxlength">maxlength</code> and <code
data-x="attr-input-size">size</code> attributes on <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attributes are in the <span
data-x="attr-input-type-number">Number</span> state. One valid reason for using these attributes
regardless is to help legacy user agents that do not support <code>input</code> elements with
<code data-x="">type="number"</code> to still render the text control with a useful width.</p>
<div w-nodev>
<h4>Warnings for obsolete but conforming features</h4>
<p>To ease the transition from HTML4 Transitional documents to the language defined in
<em>this</em> specification, and to discourage certain features that are only allowed in very few
circumstances, conformance checkers must warn the user when the following features are used in a
document. These are generally old obsolete features that have no effect, and are allowed only to
distinguish between likely mistakes (regular conformance errors) and mere vestigial markup or
unusual and discouraged practices (these warnings).</p>
<p>The following features must be categorized as described
above:</p>
<ul><!-- downplayed list -->
<li><p>The presence of a <code data-x="attr-img-border">border</code> attribute on an
<code>img</code> element if its value is the string "<code data-x="">0</code>".</p></li>
<li><p>The presence of a <code data-x="attr-script-charset">charset</code> attribute on a
<code>script</code> element if its value is an <span>ASCII case-insensitive</span> match for
"<code data-x="">utf-8</code>".</p></li>
<li><p>The presence of a <code data-x="attr-script-language">language</code> attribute on a
<code>script</code> element if its value is an <span>ASCII case-insensitive</span> match for the
string "<code data-x="">JavaScript</code>" and if there is no <code
data-x="attr-script-type">type</code> attribute or there is and its value is an <span>ASCII
case-insensitive</span> match for the string "<code data-x="">text/javascript</code>".</p></li>
<li><p>The presence of a <code data-x="attr-style-type">type</code> attribute on a
<code>script</code> element if its value is a <span>JavaScript MIME type essence
match</span>.</p></li>
<li><p>The presence of a <code data-x="attr-style-type">type</code> attribute on a
<code>style</code> element if its value is an <span>ASCII case-insensitive</span> match for
"<code>text/css</code>".</p></li>
<li><p>The presence of a <code data-x="attr-a-name">name</code> attribute on an <code>a</code>
element, if its value is not the empty string.</p></li>
<li><p>The presence of a <code data-x="attr-input-maxlength">maxlength</code> attribute on an
<code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in the
<span data-x="attr-input-type-number">Number</span> state.</p></li>
<li><p>The presence of a <code data-x="attr-input-size">size</code> attribute on an
<code>input</code> element whose <code data-x="attr-input-type">type</code> attribute is in the
<span data-x="attr-input-type-number">Number</span> state.</p></li>
</ul>
<p>Conformance checkers must distinguish between pages that have no conformance errors and have
none of these obsolete features, and pages that have no conformance errors but do have some of
these obsolete features.</p>
<p class="example">For example, a validator could report some pages as "Valid HTML" and others as
"Valid HTML with warnings".</p>
</div>
<h3>Non-conforming features</h3>
<p>Elements in the following list are entirely obsolete, and must not be used by authors:</p>
<dl><!-- alphabetical by first element in the group, except CSS goes last -->
<dt><dfn element><code>applet</code></dfn></dt>
<dd><p>Use <code>embed</code> or <code>object</code> instead.</p></dd>
<dt><dfn element><code>acronym</code></dfn></dt>
<dd><p>Use <code>abbr</code> instead.</p></dd>
<dt><dfn element><code>bgsound</code></dfn></dt>
<dd><p>Use <code>audio</code> instead.</p></dd>
<dt><dfn element><code>dir</code></dfn></dt>
<dd><p>Use <code>ul</code> instead.</p></dd>
<dt><code>frame</code></dt>
<dt><code>frameset</code></dt>
<dt><dfn element><code>noframes</code></dfn></dt>
<dd><p>Either use <code>iframe</code> and CSS instead, or use server-side includes to generate complete pages with the various invariant parts merged in.</p></dd>
<dt><dfn element><code>isindex</code></dfn></dt>
<dd><p>Use an explicit <code>form</code> and <span data-x="attr-input-type-text">text control</span> combination instead.</p></dd>
<dt><dfn element><code>keygen</code></dfn></dt>
<dd>
<p>For enterprise device management use cases, use native on-device management capabilities.</p>
<p>For certificate enrollment use cases, use the Web Cryptography API to generate a keypair for
the certificate, and then export the certificate and key to allow the user to install them
manually. <ref>WEBCRYPTO</ref></p>
</dd>
<dt><dfn element><code>listing</code></dfn></dt>
<dd><p>Use <code>pre</code> and <code>code</code> instead.</p></dd>
<dt><dfn element><code>menuitem</code></dfn></dt>
<dd><p>To implement a custom context menu, use script to handle the <code
data-x="event-contextmenu">contextmenu</code> event.</p></dd>
<dt><dfn element><code>nextid</code></dfn></dt>
<dd><p>Use GUIDs instead.</p></dd>
<dt><dfn element><code>noembed</code></dfn></dt>
<dd><p>Use <code>object</code> instead of <code>embed</code> when fallback is necessary.</p></dd>
<dt id="the-param-element"><dfn element><code>param</code></dfn></dt>
<dd><p>Use the <code data-x="attr-object-data">data</code> attribute of the <code>object</code> element to set the
URL of the external resource.</p></dd>
<dt><dfn element><code>plaintext</code></dfn></dt>
<dd><p>Use the "<code>text/plain</code>" <span>MIME type</span> instead.</p></dd>
<dt><dfn element><code>rb</code></dfn></dt>
<dt><dfn element><code>rtc</code></dfn></dt>
<dd><p>Providing the ruby base directly inside the <code>ruby</code> element or using nested
<code>ruby</code> elements is sufficient.</p></dd>
<dt><dfn element><code>strike</code></dfn></dt>
<dd><p>Use <code>del</code> instead if the element is marking an edit, otherwise use <code>s</code> instead.</p></dd>
<dt><dfn element><code>xmp</code></dfn></dt>
<dd><p>Use <code>pre</code> and <code>code</code> instead, and escape "<code data-x=""><</code>" and "<code data-x="">&</code>" characters as "<code data-x="">&lt;</code>" and "<code data-x="">&amp;</code>" respectively.</p></dd>
<dt><dfn element><code>basefont</code></dfn></dt>
<dt><dfn element><code>big</code></dfn></dt>
<dt><dfn element><code>blink</code></dfn></dt>
<dt><dfn element><code>center</code></dfn></dt>
<dt><dfn element><code>font</code></dfn></dt>
<dt><code>marquee</code></dt>
<dt><dfn element><code>multicol</code></dfn></dt>
<dt><dfn element><code>nobr</code></dfn></dt>
<dt><dfn element><code>spacer</code></dfn></dt>
<dt><dfn element><code>tt</code></dfn></dt>
<dd>
<p>Use appropriate elements or CSS instead.</p>
<p>Where the <code>tt</code> element would have been used for marking up keyboard input,
consider the <code>kbd</code> element; for variables, consider the <code>var</code> element; for
computer code, consider the <code>code</code> element; and for computer output, consider the
<code>samp</code> element.</p>
<p>Similarly, if the <code>big</code> element is being used to denote a heading, consider using
the <code>h1</code> element; if it is being used for marking up important passages, consider the
<code>strong</code> element; and if it is being used for highlighting text for reference
purposes, consider the <code>mark</code> element.</p>
<p>See also the <a href="#usage-summary">text-level semantics usage summary</a> for more
suggestions with examples.</p>
</dd>
</dl>
<hr>
<p>The following attributes are obsolete (though the elements are still part of the language), and
must not be used by authors:</p>
<dl><!-- alphabetical by element then attribute of first item in group, except CSS goes last -->
<dt><dfn element-attr for="a"><code data-x="attr-a-charset">charset</code></dfn> on <code>a</code> elements</dt>
<dt><dfn element-attr for="link"><code data-x="attr-link-charset">charset</code></dfn> on <code>link</code> elements</dt>
<dd><p>Use an HTTP `<code>Content-Type</code>` header on the linked resource instead.</p></dd>
<dt><dfn element-attr for="script"><code data-x="attr-script-charset">charset</code></dfn> on <code>script</code>
elements (except as noted in the previous section)</dt>
<dd><p>Omit the attribute. Both documents and scripts are required to use <span>UTF-8</span>, so
it is redundant to specify it on the <code>script</code> element since it inherits from the
document.</p></dd>
<dt><dfn element-attr for="a"><code data-x="attr-a-coords">coords</code></dfn> on <code>a</code> elements</dt>
<dt><dfn element-attr for="a"><code data-x="attr-a-shape">shape</code></dfn> on <code>a</code> elements</dt>
<dd><p>Use <code>area</code> instead of <code>a</code> for image maps.</p></dd>
<dt><dfn element-attr for="a"><code data-x="attr-a-methods">methods</code></dfn> on <code>a</code> elements</dt>
<dt><dfn element-attr for="link"><code data-x="attr-link-methods">methods</code></dfn> on <code>link</code> elements</dt>
<dd><p>Use the HTTP OPTIONS feature instead.</p></dd>
<dt><dfn element-attr for="a"><code data-x="attr-a-name">name</code></dfn> on <code>a</code> elements (except as noted in the previous section)</dt>
<dt><dfn element-attr for="embed"><code data-x="attr-embed-name">name</code></dfn> on <code>embed</code> elements</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-name">name</code></dfn> on <code>img</code> elements</dt>
<dt><dfn element-attr for="option"><code data-x="attr-option-name">name</code></dfn> on <code>option</code> elements</dt>
<dd><p>Use the <code data-x="attr-id">id</code> attribute instead.</p></dd>
<dt><dfn element-attr for="a"><code data-x="attr-a-rev">rev</code></dfn> on <code>a</code> elements</dt>
<dt><dfn element-attr for="link"><code data-x="attr-link-rev">rev</code></dfn> on <code>link</code> elements</dt>
<dd><p>Use the <code data-x="attr-hyperlink-rel">rel</code>
attribute instead, with an opposite term. (For example, instead of
<code data-x="">rev="made"</code>, use <code
data-x="">rel="author"</code>.)</p></dd>
<dt><dfn element-attr for="a"><code data-x="attr-a-urn">urn</code></dfn> on <code>a</code> elements</dt>
<dt><dfn element-attr for="link"><code data-x="attr-link-urn">urn</code></dfn> on <code>link</code> elements</dt>
<dd><p>Specify the preferred persistent identifier using the <code data-x="attr-hyperlink-href">href</code> attribute instead.</p></dd>
<dt><dfn element-attr for="form"><code data-x="attr-form-accept">accept</code></dfn> on <code>form</code> elements</dt>
<dd><p>Use the <code data-x="attr-input-accept">accept</code> attribute directly on the <code>input</code> elements instead.</p></dd>
<dt><dfn element-attr for="area"><code data-x="attr-area-hreflang">hreflang</code></dfn> on <code>area</code>
elements</dt>
<dt><dfn element-attr for="area"><code data-x="attr-area-type">type</code></dfn> on <code>area</code> elements</dt>
<dd><p>These attributes do not do anything useful, and for historical reasons there are no
corresponding IDL attributes on <code>area</code> elements. Omit them altogether.</p></dd>
<dt><dfn element-attr for="area"><code data-x="attr-area-nohref">nohref</code></dfn> on <code>area</code> elements</dt>
<dd><p>Omitting the <code data-x="attr-hyperlink-href">href</code>
attribute is sufficient; the <code
data-x="attr-area-nohref">nohref</code> attribute is
unnecessary. Omit it altogether.</p></dd>
<dt><dfn element-attr for="head"><code data-x="attr-head-profile">profile</code></dfn> on <code>head</code> elements</dt>
<dd><p>Unnecessary. Omit it altogether.</p></dd>
<dt><dfn element-attr for="html"><code data-x="attr-html-manifest">manifest</code></dfn> on <code>html</code> elements</dt>
<dd><p>Use service workers instead. <ref>SW</ref></p></dd>
<dt><dfn element-attr for="html"><code data-x="attr-html-version">version</code></dfn> on <code>html</code> elements</dt>
<dd><p>Unnecessary. Omit it altogether.</p></dd>
<dt><dfn element-attr for="input"><code data-x="attr-input-ismap">ismap</code></dfn> on <code>input</code> elements</dt>
<dd><p>Unnecessary. Omit it altogether. All <code>input</code> elements with a <code
data-x="attr-input-type">type</code> attribute in the <span data-x="attr-input-type-image">Image
Button</span> state are processed as server-side image maps.</p></dd>
<dt><dfn element-attr for="input"><code data-x="attr-input-usemap">usemap</code></dfn> on <code>input</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-usemap">usemap</code></dfn> on <code>object</code> elements</dt>
<dd><p>Use the <code>img</code> element for image maps.</p></dd>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-longdesc">longdesc</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-longdesc">longdesc</code></dfn> on <code>img</code> elements</dt>
<dd><p>Use a regular <code>a</code> element to link to the
description, or (in the case of images) use an <span>image
map</span> to provide a link from the image to the image's
description.</p></dd>
<dt><dfn element-attr for="img"><code data-x="attr-img-lowsrc">lowsrc</code></dfn> on <code>img</code> elements</dt>
<dd><p>Use a progressive JPEG image (given in the <code data-x="attr-img-src">src</code> attribute),
instead of using two separate images.</p></dd>
<dt><dfn element-attr for="link"><code data-x="attr-link-target">target</code></dfn> on <code>link</code> elements</dt>
<dd><p>Unnecessary. Omit it altogether.</p></dd>
<dt><dfn element-attr for="menu"><code data-x="attr-menu-type">type</code></dfn> on <code>menu</code> elements</dt>
<dd><p>To implement a custom context menu, use script to handle the <code
data-x="event-contextmenu">contextmenu</code> event. For toolbar menus, omit the
attribute.</p></dd>
<dt><dfn element-attr for="menu"><code data-x="attr-menu-label">label</code></dfn> on <code>menu</code> elements</dt>
<dt><dfn element-attr><code data-x="attr-contextmenu">contextmenu</code></dfn> on all elements</dt>
<dt><dfn element-attr><code data-x="handler-onshow">onshow</code></dfn> on all elements</dt>
<dd><p>To implement a custom context menu, use script to handle the <code
data-x="event-contextmenu">contextmenu</code> event.</p></dd>
<dt><dfn element-attr for="meta"><code data-x="attr-meta-scheme">scheme</code></dfn> on <code>meta</code> elements</dt>
<dd><p>Use only one scheme per field, or make the scheme declaration part of the value.</p></dd>
<dt><dfn element-attr for="object"><code data-x="attr-object-archive">archive</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-classid">classid</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-code">code</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-codebase">codebase</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-codetype">codetype</code></dfn> on <code>object</code> elements</dt>
<dd><p>Use the <code data-x="attr-object-data">data</code> and <code
data-x="attr-object-type">type</code> attributes to invoke <span
data-x="plugin">plugins</span>.</p></dd>
<dt><dfn element-attr for="object"><code data-x="attr-object-declare">declare</code></dfn> on <code>object</code> elements</dt>
<dd><p>Repeat the <code>object</code> element completely each time the resource is to be reused.</p></dd>
<dt><dfn element-attr for="object"><code data-x="attr-object-standby">standby</code></dfn> on <code>object</code> elements</dt>
<dd><p>Optimize the linked resource so that it loads quickly or, at least, incrementally.</p></dd>
<dt><dfn element-attr for="object"><code data-x="attr-object-typemustmatch">typemustmatch</code></dfn> on <code>object</code> elements</dt>
<dd><p>Avoid using <code>object</code> elements with untrusted resources.</p></dd>
<dt><dfn element-attr for="script"><code data-x="attr-script-language">language</code></dfn> on <code>script</code> elements (except as noted in the previous section)</dt>
<dd><p>Omit the attribute for JavaScript; for <span data-x="data block">data blocks</span>, use
the <code data-x="attr-script-type">type</code> attribute instead.</p></dd>
<dt><dfn element-attr for="script"><code data-x="attr-script-event">event</code></dfn> on <code>script</code> elements</dt>
<dt><dfn element-attr for="script"><code data-x="attr-script-for">for</code></dfn> on <code>script</code> elements</dt>
<dd><p>Use DOM events mechanisms to register event listeners. <ref>DOM</ref></p></dd>
<dt><dfn element-attr for="style"><code data-x="attr-style-type">type</code></dfn> on <code>style</code> elements (except as noted in the previous section)</dt>
<dd><p>Omit the attribute for CSS; for <span data-x="data block">data blocks</span>, use
<code>script</code> as the container instead of <code>style</code>.</p></dd>
<dt><dfn element-attr for="table"><code data-x="attr-table-datapagesize">datapagesize</code></dfn> on <code>table</code> elements</dt>
<dd><p>Unnecessary. Omit it altogether.</p></dd>
<dt><dfn element-attr for="table"><code data-x="attr-table-summary">summary</code></dfn> on <code>table</code> elements</dt><!-- 2.65% pages -->
<dd><p>Use one of the <a href="#table-descriptions-techniques">techniques for describing
tables</a> given in the <code>table</code> section instead.</p></dd>
<dt><dfn element-attr for="td"><code data-x="attr-td-abbr">abbr</code></dfn> on <code>td</code> elements</dt>
<dd><p>Use text that begins in an unambiguous and terse manner, and include any more elaborate text after that. The <code data-x="attr-title">title</code> attribute can also be useful in including more detailed text, so that the cell's contents can be made terse. If it's a heading, use <code>th</code> (which has an <code data-x="attr-th-abbr">abbr</code> attribute).</p>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-axis">axis</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dd><p>Use the <code data-x="attr-th-scope">scope</code> attribute on the relevant <code>th</code>.</p>
<dt><dfn element-attr for="td"><code data-x="attr-td-scope">scope</code></dfn> on <code>td</code> elements</dt>
<dd><p>Use <code>th</code> elements for heading cells.</p>
<dt><dfn element-attr><code data-x="attr-datasrc">datasrc</code></dfn> on <code>a</code>, <code>button</code>, <code>div</code>, <code>frame</code>, <code>iframe</code>, <code>img</code>, <code>input</code>, <code>label</code>, <code>legend</code>, <code>marquee</code>, <code>object</code>, <code>option</code>, <code>select</code>, <code>span</code>, <code>table</code>, and <code>textarea</code> elements</dt>
<dt><dfn element-attr><code data-x="attr-datafld">datafld</code></dfn> on <code>a</code>, <code>button</code>, <code>div</code>, <code>fieldset</code>, <code>frame</code>, <code>iframe</code>, <code>img</code>, <code>input</code>, <code>label</code>, <code>legend</code>, <code>marquee</code>, <code>object</code>, <code>select</code>, <code>span</code>, and <code>textarea</code> elements</dt>
<dt><dfn element-attr><code data-x="attr-dataformatas">dataformatas</code></dfn> on <code>button</code>, <code>div</code>, <code>input</code>, <code>label</code>, <code>legend</code>, <code>marquee</code>, <code>object</code>, <code>option</code>, <code>select</code>, <code>span</code>, and <code>table</code> elements</dt>
<dd><p>Use script and a mechanism such as <code>XMLHttpRequest</code> to populate the page dynamically. <ref>XHR</ref></p></dd>
<dt><dfn element-attr><code data-x="attr-dropzone">dropzone</code></dfn> on all elements</dt>
<dd><p>Use script to handle the <code data-x="event-dnd-dragenter">dragenter</code> and <code
data-x="event-dnd-dragover">dragover</code> events instead.</p></dd>
<dt><dfn element-attr for="body"><code data-x="attr-body-alink">alink</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-bgcolor">bgcolor</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-bottommargin">bottommargin</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-leftmargin">leftmargin</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-link">link</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-marginheight">marginheight</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-marginwidth">marginwidth</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-rightmargin">rightmargin</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-text">text</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-topmargin">topmargin</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="body"><code data-x="attr-body-vlink">vlink</code></dfn> on <code>body</code> elements</dt>
<dt><dfn element-attr for="br"><code data-x="attr-br-clear">clear</code></dfn> on <code>br</code> elements</dt>
<dt><dfn element-attr for="caption"><code data-x="attr-caption-align">align</code></dfn> on <code>caption</code> elements</dt>
<dt><dfn element-attr for="col"><code data-x="attr-col-align">align</code></dfn> on <code>col</code> elements</dt>
<dt><dfn element-attr for="col"><code data-x="attr-col-char">char</code></dfn> on <code>col</code> elements</dt>
<dt><dfn element-attr for="col"><code data-x="attr-col-charoff">charoff</code></dfn> on <code>col</code> elements</dt>
<dt><dfn element-attr for="col"><code data-x="attr-col-valign">valign</code></dfn> on <code>col</code> elements</dt>
<dt><dfn element-attr for="col"><code data-x="attr-col-width">width</code></dfn> on <code>col</code> elements</dt>
<dt><dfn element-attr for="div"><code data-x="attr-div-align">align</code></dfn> on <code>div</code> elements</dt>
<dt><dfn element-attr for="dl"><code data-x="attr-dl-compact">compact</code></dfn> on <code>dl</code> elements</dt>
<dt><dfn element-attr for="embed"><code data-x="attr-embed-align">align</code></dfn> on <code>embed</code> elements</dt>
<dt><dfn element-attr for="embed"><code data-x="attr-embed-hspace">hspace</code></dfn> on <code>embed</code> elements</dt>
<dt><dfn element-attr for="embed"><code data-x="attr-embed-vspace">vspace</code></dfn> on <code>embed</code> elements</dt>
<dt><dfn element-attr for="hr"><code data-x="attr-hr-align">align</code></dfn> on <code>hr</code> elements</dt>
<dt><dfn element-attr for="hr"><code data-x="attr-hr-color">color</code></dfn> on <code>hr</code> elements</dt>
<dt><dfn element-attr for="hr"><code data-x="attr-hr-noshade">noshade</code></dfn> on <code>hr</code> elements</dt>
<dt><dfn element-attr for="hr"><code data-x="attr-hr-size">size</code></dfn> on <code>hr</code> elements</dt>
<dt><dfn element-attr for="hr"><code data-x="attr-hr-width">width</code></dfn> on <code>hr</code> elements</dt>
<dt><dfn element-attr for="h1,h2,h3,h4,h5,h6"><code data-x="attr-hx-align">align</code></dfn> on <code>h1</code>—<code>h6</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-align">align</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-allowtransparency">allowtransparency</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-frameborder">frameborder</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-framespacing">framespacing</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-hspace">hspace</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-marginheight">marginheight</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-marginwidth">marginwidth</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-scrolling">scrolling</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="iframe"><code data-x="attr-iframe-vspace">vspace</code></dfn> on <code>iframe</code> elements</dt>
<dt><dfn element-attr for="input"><code data-x="attr-input-align">align</code></dfn> on <code>input</code> elements</dt>
<dt><dfn element-attr for="input"><code data-x="attr-input-border">border</code></dfn> on <code>input</code> elements</dt>
<dt><dfn element-attr for="input"><code data-x="attr-input-hspace">hspace</code></dfn> on <code>input</code> elements</dt>
<dt><dfn element-attr for="input"><code data-x="attr-input-vspace">vspace</code></dfn> on <code>input</code> elements</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-align">align</code></dfn> on <code>img</code> elements</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-border">border</code></dfn> on <code>img</code> elements (except as noted in the previous section)</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-hspace">hspace</code></dfn> on <code>img</code> elements</dt>
<dt><dfn element-attr for="img"><code data-x="attr-img-vspace">vspace</code></dfn> on <code>img</code> elements</dt>
<dt><dfn element-attr for="legend"><code data-x="attr-legend-align">align</code></dfn> on <code>legend</code> elements</dt>
<dt><dfn element-attr for="li"><code data-x="attr-li-type">type</code></dfn> on <code>li</code> elements</dt>
<dt><dfn element-attr for="menu"><code data-x="attr-menu-compact">compact</code></dfn> on <code>menu</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-align">align</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-border">border</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-hspace">hspace</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="object"><code data-x="attr-object-vspace">vspace</code></dfn> on <code>object</code> elements</dt>
<dt><dfn element-attr for="ol"><code data-x="attr-ol-compact">compact</code></dfn> on <code>ol</code> elements</dt>
<dt><dfn element-attr for="p"><code data-x="attr-p-align">align</code></dfn> on <code>p</code> elements</dt>
<dt><dfn element-attr for="pre"><code data-x="attr-pre-width">width</code></dfn> on <code>pre</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-align">align</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-bgcolor">bgcolor</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-border">border</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-bordercolor">bordercolor</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-cellpadding">cellpadding</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-cellspacing">cellspacing</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-frame">frame</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-height">height</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-rules">rules</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="table"><code data-x="attr-table-width">width</code></dfn> on <code>table</code> elements</dt>
<dt><dfn element-attr for="tbody"><code data-x="attr-tbody-align">align</code></dfn> on <code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements</dt>
<dt><dfn element-attr for="tbody"><code data-x="attr-tbody-char">char</code></dfn> on <code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements</dt>
<dt><dfn element-attr for="tbody"><code data-x="attr-tbody-charoff">charoff</code></dfn> on <code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements</dt>
<dt><dfn element-attr for="tbody"><code data-x="attr-tbody-height">height</code></dfn> on <code>thead</code>, <code>tbody</code>, and <code>tfoot</code> elements</dt>
<dt><dfn element-attr for="tbody"><code data-x="attr-tbody-vAlign">valign</code></dfn> on <code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-align">align</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-bgcolor">bgcolor</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-char">char</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-charoff">charoff</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-height">height</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-nowrap">nowrap</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-valign">valign</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="td,th"><code data-x="attr-tdth-width">width</code></dfn> on <code>td</code> and <code>th</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-align">align</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-bgcolor">bgcolor</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-char">char</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-charoff">charoff</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-height">height</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="tr"><code data-x="attr-tr-valign">valign</code></dfn> on <code>tr</code> elements</dt>
<dt><dfn element-attr for="ul"><code data-x="attr-ul-compact">compact</code></dfn> on <code>ul</code> elements</dt>
<dt><dfn element-attr for="ul"><code data-x="attr-ul-type">type</code></dfn> on <code>ul</code> elements</dt>
<dt><dfn element-attr><code data-x="attr-background">background</code></dfn> on <code>body</code>, <code>table</code>, <code>thead</code>, <code>tbody</code>, <code>tfoot</code>, <code>tr</code>, <code>td</code>, and <code>th</code> elements</dt>
<dd><p>Use CSS instead.</p></dd>
</dl>
<div w-nodev>
<h3>Requirements for implementations</h3>
<h4 id="the-marquee-element">The <dfn element><code>marquee</code></dfn> element</h4>
<p>The <code>marquee</code> element is a presentational element that animates content. CSS
transitions and animations are a more appropriate mechanism. <ref>CSSANIMATIONS</ref> <ref>CSSTRANSITIONS</ref></p>
<p>The <code>marquee</code> element must implement the <code>HTMLMarqueeElement</code>
interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLMarqueeElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-marquee-behavior">behavior</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-marquee-bgColor">bgColor</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-marquee-direction">direction</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-marquee-height">height</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-marquee-hspace">hspace</span>;
[<span>CEReactions</span>] attribute long <span data-x="dom-marquee-loop">loop</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-marquee-scrollamount">scrollAmount</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-marquee-scrollDelay">scrollDelay</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-marquee-trueSpeed">trueSpeed</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-marquee-vspace">vspace</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-marquee-width">width</span>;
undefined <span data-x="dom-marquee-start">start</span>();
undefined <span data-x="dom-marquee-stop">stop</span>();
};</code></pre>
<p>A <code>marquee</code> element can be <dfn data-x="concept-marquee-on">turned on</dfn> or <dfn
data-x="concept-marquee-off">turned off</dfn>. When it is created, it is <span
data-x="concept-marquee-on">turned on</span>.</p>
<p>When the <dfn method for="HTMLMarqueeElement"><code
data-x="dom-marquee-start">start()</code></dfn> method is called, the <code>marquee</code> element
must be <span data-x="concept-marquee-on">turned on</span>.</p>
<p>When the <dfn method for="HTMLMarqueeElement"><code
data-x="dom-marquee-stop">stop()</code></dfn> method is called, the <code>marquee</code> element
must be <span data-x="concept-marquee-off">turned off</span>.</p>
<hr>
<p>The <dfn element-attr for="marquee"><code data-x="attr-marquee-behavior">behavior</code></dfn>
content attribute on <code>marquee</code> elements is an <span>enumerated attribute</span> with
the following keywords and states (all non-conforming):</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<tbody>
<tr>
<td><code data-x="">scroll</code>
<td><dfn data-x="attr-marquee-behavior-scroll">scroll</dfn>
<tr>
<td><code data-x="">slide</code>
<td><dfn data-x="attr-marquee-behavior-slide">slide</dfn>
<tr>
<td><code data-x="">alternate</code>
<td><dfn data-x="attr-marquee-behavior-alternate">alternate</dfn>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-marquee-behavior-scroll">scroll</span> state.</p>
<hr>
<p>The <dfn element-attr for="marquee"><code
data-x="attr-marquee-direction">direction</code></dfn> content attribute on <code>marquee</code>
elements is an <span>enumerated attribute</span> with the following keywords and states (all
non-conforming):</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<tbody>
<tr>
<td><code data-x="">left</code>
<td><dfn data-x="attr-marquee-direction-left">left</dfn>
<tr>
<td><code data-x="">right</code>
<td><dfn data-x="attr-marquee-direction-right">right</dfn>
<tr>
<td><code data-x="">up</code>
<td><dfn data-x="attr-marquee-direction-up">up</dfn>
<tr>
<td><code data-x="">down</code>
<td><dfn data-x="attr-marquee-direction-down">down</dfn>
</table>
<p>The attribute's <i data-x="missing value default">missing value default</i> and <i
data-x="invalid value default">invalid value default</i> are both the <span
data-x="attr-marquee-direction-left">left</span> state.</p>
<hr>
<p>The <dfn element-attr for="marquee"><code
data-x="attr-marquee-truespeed">truespeed</code></dfn> content attribute on <code>marquee</code>
elements is a <span>boolean attribute</span>.</p>
<hr>
<p>A <code>marquee</code> element has a <dfn>marquee scroll interval</dfn>, which is obtained as
follows:</p>
<ol>
<li><p>If the element has a <code undefined data-x="attr-marquee-scrolldelay">scrolldelay</code> attribute,
and parsing its value using the <span>rules for parsing non-negative integers</span> does not
return an error, then let <var>delay</var> be the parsed value. Otherwise, let <var>delay</var>
be 85.</p></li>
<li><p>If the element does not have a <code data-x="attr-marquee-truespeed">truespeed</code>
attribute, and the <var>delay</var> value is less than 60, then let <var>delay</var> be 60
instead.</p></li>
<li><p>The <span>marquee scroll interval</span> is <var>delay</var>, interpreted in
milliseconds.</p></li>
</ol>
<hr>
<p>A <code>marquee</code> element has a <dfn>marquee scroll distance</dfn>, which, if the element
has a <code undefined data-x="attr-marquee-scrollamount">scrollamount</code> attribute, and
parsing its value using the <span>rules for parsing non-negative integers</span> does not return
an error, is the parsed value interpreted in <span data-x="'px'">CSS pixels</span>, and otherwise
is 6 <span data-x="'px'">CSS pixels</span>.</p>
<hr>
<p>A <code>marquee</code> element has a <dfn>marquee loop count</dfn>, which, if the element has a
<dfn element-attr for="marquee"><code data-x="attr-marquee-loop">loop</code></dfn> attribute, and
parsing its value using the <span>rules for parsing integers</span> does not return an error or a
number less than 1, is the parsed value, and otherwise is −1.</p>
<p>The <dfn attribute for="HTMLMarqueeElement"><code data-x="dom-marquee-loop">loop</code></dfn>
IDL attribute, on getting, must return the element's <span>marquee loop count</span>; and on
setting, if the new value is different than the element's <span>marquee loop count</span> and
either greater than zero or equal to −1, must set the element's <code
data-x="attr-marquee-loop">loop</code> content attribute (adding it if necessary) to the
<span>valid integer</span> that represents the new value. (Other values are ignored.)</p>
<p>A <code>marquee</code> element also has a <dfn>marquee current loop index</dfn>, which is zero
when the element is created.</p>
<p>The rendering layer will occasionally <dfn>increment the marquee current loop index</dfn>,
which must cause the following steps to be run:</p>
<ol>
<li><p>If the <span>marquee loop count</span> is −1, then return.</p>
<li><p>Increment the <span>marquee current loop index</span> by one.</p></li>
<li><p>If the <span>marquee current loop index</span> is now greater than or equal to the
element's <span>marquee loop count</span>, <span data-x="concept-marquee-off">turn off</span> the
<code>marquee</code> element.</p></li>
</ol>
<hr>
<p>The <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-behavior">behavior</code></dfn>, <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-direction">direction</code></dfn>, <dfn attribute
for="HTMLMarqueeElement"><code data-x="dom-marquee-height">height</code></dfn>, <dfn attribute
for="HTMLMarqueeElement"><code data-x="dom-marquee-hspace">hspace</code></dfn>, <dfn attribute
for="HTMLMarqueeElement"><code data-x="dom-marquee-vspace">vspace</code></dfn>, and <dfn attribute
for="HTMLMarqueeElement"><code data-x="dom-marquee-width">width</code></dfn> IDL attributes must
<span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-bgColor">bgColor</code></dfn> IDL attribute must <span>reflect</span> the
<code undefined data-x="attr-marquee-bgcolor">bgcolor</code> content attribute.</p>
<p>The <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-scrollAmount">scrollAmount</code></dfn> IDL attribute must
<span>reflect</span> the <code undefined data-x="attr-marquee-scrollamount">scrollamount</code>
content attribute. The <span>default value</span> is 6.</p>
<p>The <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-scrollDelay">scrollDelay</code></dfn> IDL attribute must <span>reflect</span>
the <code undefined data-x="attr-marquee-scrolldelay">scrolldelay</code> content attribute. The
<span>default value</span> is 85.</p>
<p>The <dfn attribute for="HTMLMarqueeElement"><code
data-x="dom-marquee-trueSpeed">trueSpeed</code></dfn> IDL attribute must <span>reflect</span> the
<code data-x="attr-marquee-truespeed">truespeed</code> content attribute.</p>
<h4>Frames</h4>
<p>The <dfn element><code>frameset</code></dfn> element acts as <span>the body element</span> in
documents that use frames.</p>
<p>The <code>frameset</code> element must implement the <code>HTMLFrameSetElement</code>
interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLFrameSetElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-frameset-cols">cols</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-frameset-rows">rows</span>;
};
<span>HTMLFrameSetElement</span> includes <span>WindowEventHandlers</span>;</code></pre>
<p>The <dfn attribute for="HTMLFrameSetElement"><code data-x="dom-frameset-cols">cols</code></dfn>
and <dfn attribute for="HTMLFrameSetElement"><code data-x="dom-frameset-rows">rows</code></dfn>
IDL attributes of the <code>frameset</code> element must <span>reflect</span> the respective
content attributes of the same name.</p>
<p>The <code>frameset</code> element exposes as <span>event handler content attributes</span> a
number of the <span>event handlers</span> of the <code>Window</code> object. It also mirrors their
<span>event handler IDL attributes</span>.</p>
<p>The <span>event handlers</span> of the <code>Window</code> object named by the
<span><code>Window</code>-reflecting body element event handler set</span>, exposed on the
<code>frameset</code> element, replace the generic <span>event handlers</span> with the same names
normally supported by <span>HTML elements</span>.</p>
<hr>
<p>The <dfn element><code>frame</code></dfn> element has a <span>content navigable</span> similar
to the <code>iframe</code> element, but rendered within a <code>frameset</code> element.</p>
<!-- START of section that's very similar to <iframe> -->
<p>The <code>frame</code> <span>HTML element insertion steps</span>, given
<var>insertedNode</var>, are:</p>
<ol>
<li><p>If <var>insertedNode</var> is not <span>in a document tree</span>, then return.</p></li>
<li><p>If <var>insertedNode</var>'s <span>root</span>'s <span
data-x="concept-document-bc">browsing context</span> is null, then return.</p></li>
<li><p><span>Create a new child navigable</span> for <var>insertedNode</var>.</p></li>
<li><p><span>Process the <code>frame</code> attributes</span> for <var>insertedNode</var>, with
<var data-x="process-frame-initial-insertion">initialInsertion</var> set to true.</p></li>
</ol>
<p>The <code>frame</code> <span>HTML element removing steps</span>, given <var>removedNode</var>,
are to <span>destroy a child navigable</span> given <var>removedNode</var>.</p>
<p>Whenever a <code>frame</code> element with a non-null <span>content navigable</span> has its
<code undefined data-x="attr-frame-src">src</code> attribute set, changed, or removed, the user
agent must <span>process the <code>frame</code> attributes</span>.</p> <!-- It doesn't happen
when the base URL is changed, though. -->
<p>To <dfn>process the <code>frame</code> attributes</dfn> for an element <var>element</var>, with
an optional boolean <dfn
data-x="process-frame-initial-insertion"><var>initialInsertion</var></dfn>:</p>
<ol>
<li><p>Let <var>url</var> be the result of running the <span>shared attribute processing steps
for <code>iframe</code> and <code>frame</code> elements</span> given <var>element</var> and
<var>initialInsertion</var>.</p></li>
<li><p>If <var>url</var> is null, then return.</p></li>
<li>
<p>If <var>url</var> <span>matches <code>about:blank</code></span> and
<var>initialInsertion</var> is true, then:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-load">load</code> at <var>element</var>.</p></li>
<li><p>Return.</p></li>
</ol>
</li>
<li><p><span>Navigate an <code>iframe</code> or <code>frame</code></span> given
<var>element</var>, <var>url</var>, and the empty string.</p></li>
</ol>
<p>The <code>frame</code> element <span>potentially delays the load event</span>.</p>
<!-- END of section that's very similar to <iframe> -->
<p>The <code>frame</code> element must implement the <code>HTMLFrameElement</code> interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLFrameElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-frame-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-frame-scrolling">scrolling</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-frame-src">src</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-frame-frameBorder">frameBorder</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-frame-longDesc">longDesc</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-frame-noResize">noResize</span>;
readonly attribute <span>Document</span>? <span data-x="dom-frame-contentDocument">contentDocument</span>;
readonly attribute <span>WindowProxy</span>? <span data-x="dom-frame-contentWindow">contentWindow</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-frame-marginHeight">marginHeight</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-frame-marginWidth">marginWidth</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLFrameElement"><code data-x="dom-frame-name">name</code></dfn>, <dfn
attribute for="HTMLFrameElement"><code data-x="dom-frame-scrolling">scrolling</code></dfn>, and
<dfn attribute for="HTMLFrameElement"><code data-x="dom-frame-src">src</code></dfn> IDL attributes
of the <code>frame</code> element must <span>reflect</span> the respective content attributes of
the same name. For the purposes of reflection, the <code>frame</code> element's <code undefined
data-x="attr-frame-src">src</code> content attribute is defined as containing a
<span>URL</span>.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-frameBorder">frameBorder</code></dfn> IDL attribute of the <code>frame</code>
element must <span>reflect</span> the element's <code undefined
data-x="attr-frame-frameborder">frameborder</code> content attribute.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-longDesc">longDesc</code></dfn> IDL attribute of the <code>frame</code> element
must <span>reflect</span> the element's <code undefined
data-x="attr-frame-longdesc">longdesc</code> content attribute, which for the purposes of
reflection is defined as containing a <span>URL</span>.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-noResize">noResize</code></dfn> IDL attribute of the <code>frame</code> element
must <span>reflect</span> the element's <code undefined
data-x="attr-frame-noresize">noresize</code> content attribute.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-marginHeight">marginHeight</code></dfn> IDL attribute of the <code>frame</code>
element must <span>reflect</span> the element's <code undefined
data-x="attr-frame-marginheight">marginheight</code> content attribute.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-marginWidth">marginWidth</code></dfn> IDL attribute of the <code>frame</code>
element must <span>reflect</span> the element's <code undefined
data-x="attr-frame-marginwidth">marginwidth</code> content attribute.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-contentDocument">contentDocument</code></dfn> getter steps are to return
<span>this</span>'s <span>content document</span>.</p>
<p>The <dfn attribute for="HTMLFrameElement"><code
data-x="dom-frame-contentWindow">contentWindow</code></dfn> getter steps are to return
<span>this</span>'s <span>content window</span>.</p>
<h4>Other elements, attributes and APIs</h4> <!-- alphabetical by name and attribute -->
<p>User agents must treat <code>acronym</code> elements in a manner
equivalent to <code>abbr</code> elements in terms of semantics and
for purposes of rendering.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLAnchorElement-partial">HTMLAnchorElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-coords">coords</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-charset">charset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-rev">rev</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-a-shape">shape</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLAnchorElement"><code data-x="dom-a-coords">coords</code></dfn>,
<dfn attribute for="HTMLAnchorElement"><code data-x="dom-a-charset">charset</code></dfn>, <dfn
attribute for="HTMLAnchorElement"><code data-x="dom-a-name">name</code></dfn>, <dfn attribute
for="HTMLAnchorElement"><code data-x="dom-a-rev">rev</code></dfn>, and <dfn attribute
for="HTMLAnchorElement"><code data-x="dom-a-shape">shape</code></dfn> IDL attributes of the
<code>a</code> element must <span>reflect</span> the respective content attributes of the same
name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLAreaElement-partial">HTMLAreaElement</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-area-noHref">noHref</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLAreaElement"><code data-x="dom-area-noHref">noHref</code></dfn> IDL
attribute of the <code>area</code> element must <span>reflect</span> the element's <code
data-x="attr-area-nohref">nohref</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLBodyElement-partial">HTMLBodyElement</span> {
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-body-text">text</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-body-link">link</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-body-vLink">vLink</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-body-aLink">aLink</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-body-bgColor">bgColor</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-body-background">background</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLBodyElement"><code data-x="dom-body-text">text</code></dfn> IDL
attribute of the <code>body</code> element must <span>reflect</span> the element's <code
data-x="attr-body-text">text</code> content attribute.</p>
<p>The <dfn attribute for="HTMLBodyElement"><code data-x="dom-body-link">link</code></dfn> IDL
attribute of the <code>body</code> element must <span>reflect</span> the element's <code
data-x="attr-body-link">link</code> content attribute.</p>
<p>The <dfn attribute for="HTMLBodyElement"><code data-x="dom-body-aLink">aLink</code></dfn> IDL
attribute of the <code>body</code> element must <span>reflect</span> the element's <code
data-x="attr-body-alink">alink</code> content attribute.</p>
<p>The <dfn attribute for="HTMLBodyElement"><code data-x="dom-body-vLink">vLink</code></dfn> IDL
attribute of the <code>body</code> element must <span>reflect</span> the element's <code
data-x="attr-body-vlink">vlink</code> content attribute.</p>
<p>The <dfn attribute for="HTMLBodyElement"><code data-x="dom-body-bgColor">bgColor</code></dfn>
IDL attribute of the <code>body</code> element must <span>reflect</span> the element's <code
data-x="attr-body-bgcolor">bgcolor</code> content attribute.</p>
<p>The <dfn attribute for="HTMLBodyElement"><code
data-x="dom-body-background">background</code></dfn> IDL attribute of the <code>body</code>
element must <span>reflect</span> the element's <code data-x="attr-background">background</code>
content attribute. (The <code data-x="attr-background">background</code> content is <em>not</em>
defined to contain a <span>URL</span>, despite rules regarding its handling in the Rendering
section above.)</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLBRElement-partial">HTMLBRElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-br-clear">clear</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLBRElement"><code data-x="dom-br-clear">clear</code></dfn> IDL
attribute of the <code>br</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableCaptionElement-partial">HTMLTableCaptionElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-caption-align">align</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableCaptionElement"><code
data-x="dom-caption-align">align</code></dfn> IDL attribute of the <code>caption</code> element
must <span>reflect</span> the content attribute of the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableColElement-partial">HTMLTableColElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-col-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-col-ch">ch</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-col-chOff">chOff</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-col-vAlign">vAlign</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-col-width">width</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableColElement"><code data-x="dom-col-align">align</code></dfn>
and <dfn attribute for="HTMLTableColElement"><code data-x="dom-col-width">width</code></dfn> IDL
attributes of the <code>col</code> element must <span>reflect</span> the respective content
attributes of the same name.</p>
<p>The <dfn attribute for="HTMLTableColElement"><code data-x="dom-col-ch">ch</code></dfn> IDL
attribute of the <code>col</code> element must <span>reflect</span> the element's <code
data-x="attr-col-char">char</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableColElement"><code data-x="dom-col-chOff">chOff</code></dfn>
IDL attribute of the <code>col</code> element must <span>reflect</span> the element's <code
data-x="attr-col-charoff">charoff</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableColElement"><code data-x="dom-col-vAlign">vAlign</code></dfn>
IDL attribute of the <code>col</code> element must <span>reflect</span> the element's <code
data-x="attr-col-valign">valign</code> content attribute.</p>
<hr>
<p>User agents must treat <code>dir</code> elements in a manner equivalent to <code>ul</code>
elements in terms of semantics and for purposes of rendering.</p>
<p>The <code>dir</code> element must implement the <code>HTMLDirectoryElement</code>
interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLDirectoryElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute boolean <span data-x="dom-dir-compact">compact</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLDirectoryElement"><code
data-x="dom-dir-compact">compact</code></dfn> IDL attribute of the <code>dir</code> element must
<span>reflect</span> the content attribute of the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLDivElement-partial">HTMLDivElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-div-align">align</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLDivElement"><code data-x="dom-div-align">align</code></dfn> IDL
attribute of the <code>div</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLDListElement-partial">HTMLDListElement</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-dl-compact">compact</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLDListElement"><code data-x="dom-dl-compact">compact</code></dfn>
IDL attribute of the <code>dl</code> element must <span>reflect</span> the content attribute of
the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLEmbedElement-partial">HTMLEmbedElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-embed-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-embed-name">name</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLEmbedElement"><code data-x="dom-embed-name">name</code></dfn> and
<dfn attribute for="HTMLEmbedElement"><code data-x="dom-embed-align">align</code></dfn> IDL
attributes of the <code>embed</code> element must <span>reflect</span> the respective content
attributes of the same name.</p>
<hr>
<p>The <code>font</code> element must implement the <code>HTMLFontElement</code> interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLFontElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-font-color">color</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-font-face">face</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-font-size">size</span>; <!-- yes, DOMString, not long (so says DOM2 HTML) -->
};</code></pre>
<p>The <dfn attribute for="HTMLFontElement"><code data-x="dom-font-color">color</code></dfn>, <dfn
attribute for="HTMLFontElement"><code data-x="dom-font-face">face</code></dfn>, and <dfn attribute
for="HTMLFontElement"><code data-x="dom-font-size">size</code></dfn> IDL attributes of the
<code>font</code> element must <span>reflect</span> the respective content attributes of the same
name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLHeadingElement-partial">HTMLHeadingElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-hx-align">align</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLHeadingElement"><code data-x="dom-hx-align">align</code></dfn> IDL
attribute of the <code>h1</code>–<code>h6</code> elements must <span>reflect</span> the
content attribute of the same name.</p>
<hr>
<p class="note">The <dfn attribute for="HTMLHeadElement"><code
data-x="dom-head-profile">profile</code></dfn> IDL attribute on <code>head</code> elements (with
the <code>HTMLHeadElement</code> interface) is intentionally omitted. Unless so required by <span
data-x="other applicable specifications">another applicable specification</span>, implementations
would therefore not support this attribute. (It is mentioned here as it was defined in a previous
version of <cite>DOM</cite>.)</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLHRElement-partial">HTMLHRElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-hr-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-hr-color">color</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-hr-noShade">noShade</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-hr-size">size</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-hr-width">width</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLHRElement"><code data-x="dom-hr-align">align</code></dfn>, <dfn
attribute for="HTMLHRElement"><code data-x="dom-hr-color">color</code></dfn>, <dfn attribute
for="HTMLHRElement"><code data-x="dom-hr-size">size</code></dfn>, and <dfn attribute
for="HTMLHRElement"><code data-x="dom-hr-width">width</code></dfn> IDL attributes of the
<code>hr</code> element must <span>reflect</span> the respective content attributes of the same
name.</p>
<p>The <dfn attribute for="HTMLHRElement"><code data-x="dom-hr-noShade">noShade</code></dfn> IDL
attribute of the <code>hr</code> element must <span>reflect</span> the element's <code
data-x="attr-hr-noshade">noshade</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLHtmlElement-partial">HTMLHtmlElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-html-version">version</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLHtmlElement"><code data-x="dom-html-version">version</code></dfn>
IDL attribute of the <code>html</code> element must <span>reflect</span> the content attribute of
the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLIFrameElement-partial">HTMLIFrameElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-scrolling">scrolling</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-frameBorder">frameBorder</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-iframe-longDesc">longDesc</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-iframe-marginHeight">marginHeight</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-iframe-marginWidth">marginWidth</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLIFrameElement"><code data-x="dom-iframe-align">align</code></dfn>
and <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-scrolling">scrolling</code></dfn> IDL attributes of the <code>iframe</code>
element must <span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-frameBorder">frameBorder</code></dfn> IDL attribute of the <code>iframe</code>
element must <span>reflect</span> the element's <code
data-x="attr-iframe-frameborder">frameborder</code> content attribute.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-longDesc">longDesc</code></dfn> IDL attribute of the <code>iframe</code>
element must <span>reflect</span> the element's <code
data-x="attr-iframe-longdesc">longdesc</code> content attribute, which for the purposes of
reflection is defined as containing a <span>URL</span>.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-marginHeight">marginHeight</code></dfn> IDL attribute of the
<code>iframe</code> element must <span>reflect</span> the element's <code
data-x="attr-iframe-marginheight">marginheight</code> content attribute.</p>
<p>The <dfn attribute for="HTMLIFrameElement"><code
data-x="dom-iframe-marginWidth">marginWidth</code></dfn> IDL attribute of the <code>iframe</code>
element must <span>reflect</span> the element's <code
data-x="attr-iframe-marginwidth">marginwidth</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLImageElement-partial">HTMLImageElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-name">name</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-img-lowsrc">lowsrc</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-align">align</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-img-hspace">hspace</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-img-vspace">vspace</span>;
[<span>CEReactions</span>] attribute USVString <span data-x="dom-img-longDesc">longDesc</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-img-border">border</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLImageElement"><code data-x="dom-img-name">name</code></dfn>, <dfn
attribute for="HTMLImageElement"><code data-x="dom-img-align">align</code></dfn>, <dfn attribute
for="HTMLImageElement"><code data-x="dom-img-border">border</code></dfn>, <dfn attribute
for="HTMLImageElement"><code data-x="dom-img-hspace">hspace</code></dfn>, and <dfn attribute
for="HTMLImageElement"><code data-x="dom-img-vspace">vspace</code></dfn> IDL attributes of the
<code>img</code> element must <span>reflect</span> the respective content attributes of the same
name.</p>
<p>The <dfn attribute for="HTMLImageElement"><code data-x="dom-img-longDesc">longDesc</code></dfn>
IDL attribute of the <code>img</code> element must <span>reflect</span> the element's <code
data-x="attr-img-longdesc">longdesc</code> content attribute, which for the purposes of reflection
is defined as containing a <span>URL</span>.</p>
<p>The <dfn attribute for="HTMLImageElement"><code data-x="dom-img-lowsrc">lowsrc</code></dfn> IDL
attribute of the <code>img</code> element must <span>reflect</span> the element's <code
data-x="attr-img-lowsrc">lowsrc</code> content attribute, which for the purposes of reflection is
defined as containing a <span>URL</span>.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLInputElement-partial">HTMLInputElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-input-useMap">useMap</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-align">align</code></dfn> IDL
attribute of the <code>input</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<p>The <dfn attribute for="HTMLInputElement"><code data-x="dom-input-useMap">useMap</code></dfn>
IDL attribute of the <code>input</code> element must <span>reflect</span> the element's <code
data-x="attr-input-usemap">usemap</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLLegendElement-partial">HTMLLegendElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-legend-align">align</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLLegendElement"><code data-x="dom-legend-align">align</code></dfn>
IDL attribute of the <code>legend</code> element must <span>reflect</span> the content attribute
of the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLLIElement-partial">HTMLLIElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-li-type">type</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLLIElement"><code data-x="dom-li-type">type</code></dfn> IDL
attribute of the <code>li</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLLinkElement-partial">HTMLLinkElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-charset">charset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-rev">rev</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-link-target">target</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLLinkElement"><code data-x="dom-link-charset">charset</code></dfn>,
<dfn attribute for="HTMLLinkElement"><code data-x="dom-link-rev">rev</code></dfn>, and <dfn
attribute for="HTMLLinkElement"><code data-x="dom-link-target">target</code></dfn> IDL attributes
of the <code>link</code> element must <span>reflect</span> the respective content attributes of
the same name.</p>
<hr>
<p>User agents must treat <code>listing</code> elements in a manner equivalent to <code>pre</code>
elements in terms of semantics and for purposes of rendering.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLMenuElement-partial">HTMLMenuElement</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-menu-compact">compact</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLMenuElement"><code data-x="dom-menu-compact">compact</code></dfn>
IDL attribute of the <code>menu</code> element must <span>reflect</span> the content attribute of
the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLMetaElement-partial">HTMLMetaElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-meta-scheme">scheme</span>;
};</code></pre>
<p>User agents may treat the <code data-x="attr-meta-scheme">scheme</code> content attribute on the
<code>meta</code> element as an extension of the element's <code
data-x="attr-meta-name">name</code> content attribute when processing a <code>meta</code> element
with a <code data-x="attr-meta-name">name</code> attribute whose value is one that the user agent
recognizes as supporting the <code data-x="attr-meta-scheme">scheme</code> attribute.</p>
<p>User agents are encouraged to ignore the <code data-x="attr-meta-scheme">scheme</code> attribute
and instead process the value given to the metadata name as if it had been specified for each
expected value of the <code data-x="attr-meta-scheme">scheme</code> attribute.</p>
<div class="example">
<p>For example, if the user agent acts on <code>meta</code> elements with <code
data-x="attr-meta-name">name</code> attributes having the value "eGMS.subject.keyword", and knows
that the <code data-x="attr-meta-scheme">scheme</code> attribute is used with this metadata name,
then it could take the <code data-x="attr-meta-scheme">scheme</code> attribute into account,
acting as if it was an extension of the <code data-x="attr-meta-name">name</code> attribute. Thus
the following two <code>meta</code> elements could be treated as two elements giving values for
two different metadata names, one consisting of a combination of "eGMS.subject.keyword" and
"LGCL", and the other consisting of a combination of "eGMS.subject.keyword" and "ORLY":</p>
<pre class="bad"><code class="html"><!-- this markup is invalid -->
<meta name="eGMS.subject.keyword" scheme="LGCL" content="Abandoned vehicles">
<meta name="eGMS.subject.keyword" scheme="ORLY" content="Mah car: kthxbye"></code></pre>
<p>The suggested processing of this markup, however, would be equivalent to the following:</p>
<pre><code class="html"><meta name="eGMS.subject.keyword" content="Abandoned vehicles">
<meta name="eGMS.subject.keyword" content="Mah car: kthxbye"></code></pre>
</div>
<p>The <dfn attribute for="HTMLMetaElement"><code data-x="dom-meta-scheme">scheme</code></dfn> IDL
attribute of the <code>meta</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLObjectElement-partial">HTMLObjectElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-archive">archive</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-code">code</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-object-declare">declare</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-object-hspace">hspace</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-standby">standby</span>;
[<span>CEReactions</span>] attribute unsigned long <span data-x="dom-object-vspace">vspace</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-codeBase">codeBase</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-codeType">codeType</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-object-useMap">useMap</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-object-border">border</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLObjectElement"><code data-x="dom-object-align">align</code></dfn>,
<dfn attribute for="HTMLObjectElement"><code data-x="dom-object-archive">archive</code></dfn>,
<dfn attribute for="HTMLObjectElement"><code data-x="dom-object-border">border</code></dfn>, <dfn
attribute for="HTMLObjectElement"><code data-x="dom-object-code">code</code></dfn>, <dfn attribute
for="HTMLObjectElement"><code data-x="dom-object-declare">declare</code></dfn>, <dfn attribute
for="HTMLObjectElement"><code data-x="dom-object-hspace">hspace</code></dfn>, <dfn attribute
for="HTMLObjectElement"><code data-x="dom-object-standby">standby</code></dfn>, and <dfn attribute
for="HTMLObjectElement"><code data-x="dom-object-vspace">vspace</code></dfn> IDL attributes of the
<code>object</code> element must <span>reflect</span> the respective content attributes of the
same name.</p>
<p>The <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-codeBase">codeBase</code></dfn> IDL attribute of the <code>object</code>
element must <span>reflect</span> the element's <code
data-x="attr-object-codebase">codebase</code> content attribute, which for the purposes of
reflection is defined as containing a <span>URL</span>.</p>
<p>The <dfn attribute for="HTMLObjectElement"><code
data-x="dom-object-codeType">codeType</code></dfn> IDL attribute of the <code>object</code>
element must <span>reflect</span> the element's <code
data-x="attr-object-codetype">codetype</code> content attribute.</p>
<p>The <dfn attribute for="HTMLObjectElement"><code data-x="dom-object-useMap">useMap</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-hyperlink-usemap">usemap</code>
content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLOListElement-partial">HTMLOListElement</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-ol-compact">compact</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLOListElement"><code data-x="dom-ol-compact">compact</code></dfn>
IDL attribute of the <code>ol</code> element must <span>reflect</span> the content attribute of
the same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLParagraphElement-partial">HTMLParagraphElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-p-align">align</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLParagraphElement"><code data-x="dom-p-align">align</code></dfn> IDL
attribute of the <code>p</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<p>The <code>param</code> element must implement the <code>HTMLParamElement</code> interface.</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>HTMLParamElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-param-name">name</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-param-value">value</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-param-type">type</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-param-valueType">valueType</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLParamElement"><code data-x="dom-param-name">name</code></dfn>,
<dfn attribute for="HTMLParamElement"><code data-x="dom-param-value">value</code></dfn>, and <dfn
attribute for="HTMLParamElement"><code data-x="dom-param-type">type</code></dfn> IDL attributes
of the <code>param</code> element must <span>reflect</span> the respective content attributes of
the same name.</p>
<p>The <dfn attribute for="HTMLParamElement"><code
data-x="dom-param-valueType">valueType</code></dfn> IDL attribute of the <code>param</code>
element must <span>reflect</span> the element's <code data-x="">valuetype</code> content
attribute.</p>
<hr>
<p>User agents must treat <code>plaintext</code> elements in a manner equivalent to
<code>pre</code> elements in terms of semantics and for purposes of rendering. (The parser has
special behavior for this element, though.)</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLPreElement-partial">HTMLPreElement</span> {
[<span>CEReactions</span>] attribute long <span data-x="dom-pre-width">width</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLPreElement"><code data-x="dom-pre-width">width</code></dfn> IDL
attribute of the <code>pre</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLStyleElement-partial">HTMLStyleElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-style-type">type</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLStyleElement"><code data-x="dom-style-type">type</code></dfn> IDL
attribute of the <code>style</code> element must <span>reflect</span> the element's <code
data-x="attr-style-type">type</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLScriptElement-partial">HTMLScriptElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-charset">charset</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-event">event</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-script-htmlFor">htmlFor</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-charset">charset</code></dfn> and <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-event">event</code></dfn> IDL attributes of the <code>script</code> element
must <span>reflect</span> the respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLScriptElement"><code
data-x="dom-script-htmlFor">htmlFor</code></dfn> IDL attribute of the <code>script</code> element
must <span>reflect</span> the element's <code data-x="attr-script-for">for</code> content
attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableElement-partial">HTMLTableElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-border">border</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-frame">frame</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-rules">rules</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-summary">summary</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-table-width">width</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-table-bgColor">bgColor</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-table-cellPadding">cellPadding</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-table-cellSpacing">cellSpacing</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-align">align</code></dfn>,
<dfn attribute for="HTMLTableElement"><code data-x="dom-table-border">border</code></dfn>, <dfn
attribute for="HTMLTableElement"><code data-x="dom-table-frame">frame</code></dfn>, <dfn attribute
for="HTMLTableElement"><code data-x="dom-table-summary">summary</code></dfn>, <dfn attribute
for="HTMLTableElement"><code data-x="dom-table-rules">rules</code></dfn>, and <dfn attribute
for="HTMLTableElement"><code data-x="dom-table-width">width</code></dfn> IDL attributes of the
<code>table</code> element must <span>reflect</span> the respective content attributes of the same
name.</p>
<p>The <dfn attribute for="HTMLTableElement"><code data-x="dom-table-bgColor">bgColor</code></dfn>
IDL attribute of the <code>table</code> element must <span>reflect</span> the element's <code
data-x="attr-table-bgcolor">bgcolor</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableElement"><code
data-x="dom-table-cellPadding">cellPadding</code></dfn> IDL attribute of the <code>table</code>
element must <span>reflect</span> the element's <code
data-x="attr-table-cellpadding">cellpadding</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableElement"><code
data-x="dom-table-cellSpacing">cellSpacing</code></dfn> IDL attribute of the <code>table</code>
element must <span>reflect</span> the element's <code
data-x="attr-table-cellspacing">cellspacing</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableSectionElement-partial">HTMLTableSectionElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tbody-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tbody-ch">ch</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tbody-chOff">chOff</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tbody-vAlign">vAlign</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableSectionElement"><code
data-x="dom-tbody-align">align</code></dfn> IDL attribute of the <code>tbody</code>,
<code>thead</code>, and <code>tfoot</code> elements must <span>reflect</span> the content
attribute of the same name.</p>
<p>The <dfn attribute for="HTMLTableSectionElement"><code data-x="dom-tbody-ch">ch</code></dfn>
IDL attribute of the <code>tbody</code>, <code>thead</code>, and <code>tfoot</code> elements must
<span>reflect</span> the elements' <code data-x="attr-tbody-char">char</code> content
attributes.</p>
<p>The <dfn attribute for="HTMLTableSectionElement"><code
data-x="dom-tbody-chOff">chOff</code></dfn> IDL attribute of the <code>tbody</code>,
<code>thead</code>, and <code>tfoot</code> elements must <span>reflect</span> the elements' <code
data-x="attr-tbody-charoff">charoff</code> content attributes.</p>
<p>The <dfn attribute for="HTMLTableSectionElement"><code
data-x="dom-tbody-vAlign">vAlign</code></dfn> IDL attribute of the <code>tbody</code>,
<code>thead</code>, and <code>tfoot</code> elements must <span>reflect</span> the elements' <code
data-x="attr-tbody-valign">valign</code> content attributes.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableCellElement-partial">HTMLTableCellElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-axis">axis</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-height">height</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-width">width</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-ch">ch</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-chOff">chOff</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-tdth-noWrap">noWrap</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tdth-vAlign">vAlign</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-tdth-bgColor">bgColor</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableCellElement"><code data-x="dom-tdth-align">align</code></dfn>,
<dfn attribute for="HTMLTableCellElement"><code data-x="dom-tdth-axis">axis</code></dfn>, <dfn
attribute for="HTMLTableCellElement"><code data-x="dom-tdth-height">height</code></dfn>, and <dfn
attribute for="HTMLTableCellElement"><code data-x="dom-tdth-width">width</code></dfn> IDL
attributes of the <code>td</code> and <code>th</code> elements must <span>reflect</span> the
respective content attributes of the same name.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code data-x="dom-tdth-ch">ch</code></dfn> IDL
attribute of the <code>td</code> and <code>th</code> elements must <span>reflect</span> the
elements' <code data-x="attr-tdth-char">char</code> content attributes.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code data-x="dom-tdth-chOff">chOff</code></dfn>
IDL attribute of the <code>td</code> and <code>th</code> elements must <span>reflect</span> the
elements' <code data-x="attr-tdth-charoff">charoff</code> content attributes.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-noWrap">noWrap</code></dfn> IDL attribute of the <code>td</code> and
<code>th</code> elements must <span>reflect</span> the elements' <code
data-x="attr-tdth-nowrap">nowrap</code> content attributes.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-vAlign">vAlign</code></dfn> IDL attribute of the <code>td</code> and
<code>th</code> elements must <span>reflect</span> the elements' <code
data-x="attr-tdth-valign">valign</code> content attributes.</p>
<p>The <dfn attribute for="HTMLTableCellElement"><code
data-x="dom-tdth-bgColor">bgColor</code></dfn> IDL attribute of the <code>td</code> and
<code>th</code> elements must <span>reflect</span> the elements' <code
data-x="attr-tdth-bgcolor">bgcolor</code> content attributes.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLTableRowElement-partial">HTMLTableRowElement</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tr-align">align</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tr-ch">ch</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tr-chOff">chOff</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-tr-vAlign">vAlign</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-tr-bgColor">bgColor</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-align">align</code></dfn> IDL
attribute of the <code>tr</code> element must <span>reflect</span> the content attribute of the
same name.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-ch">ch</code></dfn> IDL
attribute of the <code>tr</code> element must <span>reflect</span> the element's <code
data-x="attr-tr-char">char</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-chOff">chOff</code></dfn> IDL
attribute of the <code>tr</code> element must <span>reflect</span> the element's <code
data-x="attr-tr-charoff">charoff</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-vAlign">vAlign</code></dfn>
IDL attribute of the <code>tr</code> element must <span>reflect</span> the element's <code
data-x="attr-tr-valign">valign</code> content attribute.</p>
<p>The <dfn attribute for="HTMLTableRowElement"><code data-x="dom-tr-bgColor">bgColor</code></dfn>
IDL attribute of the <code>tr</code> element must <span>reflect</span> the element's <code
data-x="attr-tr-bgcolor">bgcolor</code> content attribute.</p>
<hr>
<pre><code class="idl">partial interface <span id="HTMLUListElement-partial">HTMLUListElement</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-ul-compact">compact</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-ul-type">type</span>;
};</code></pre>
<p>The <dfn attribute for="HTMLUListElement"><code data-x="dom-ul-compact">compact</code></dfn>
and <dfn attribute for="HTMLUListElement"><code data-x="dom-ul-type">type</code></dfn> IDL
attributes of the <code>ul</code> element must <span>reflect</span> the respective content
attributes of the same name.</p>
<hr>
<p>User agents must treat <code>xmp</code> elements in a manner equivalent to <code>pre</code>
elements in terms of semantics and for purposes of rendering. (The parser has special behavior for
this element though.)</p>
<hr>
<pre><code class="idl">partial interface <span id="Document-partial">Document</span> {
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-document-fgColor">fgColor</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-document-linkColor">linkColor</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-document-vlinkColor">vlinkColor</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-document-alinkColor">alinkColor</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] DOMString <span data-x="dom-document-bgColor">bgColor</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-anchors">anchors</span>;
[SameObject] readonly attribute <span>HTMLCollection</span> <span data-x="dom-document-applets">applets</span>;
undefined <span data-x="dom-document-clear">clear</span>();
undefined <span data-x="dom-document-captureEvents">captureEvents</span>();
undefined <span data-x="dom-document-releaseEvents">releaseEvents</span>();
[SameObject] readonly attribute <span>HTMLAllCollection</span> <span data-x="dom-document-all">all</span>;
};</code></pre>
<p>The attributes of the <code>Document</code> object listed in the first column of the following
table must <span>reflect</span> the content attribute on <span>the body element</span> with the
name given in the corresponding cell in the second column on the same row, if <span>the body
element</span> is a <code>body</code> element (as opposed to a <code>frameset</code> element).
When there is no <span data-x="the body element">body element</span> or if it is a
<code>frameset</code> element, the attributes must instead return the empty string on getting and
do nothing on setting.</p>
<table>
<thead>
<tr>
<th> IDL attribute
<th> Content attribute
<tbody>
<tr>
<td><dfn attribute for="Document"><code data-x="dom-document-fgColor">fgColor</code></dfn>
<td><code data-x="attr-body-text">text</code>
<tr>
<td><dfn attribute for="Document"><code data-x="dom-document-linkColor">linkColor</code></dfn>
<td><code data-x="attr-body-link">link</code>
<tr>
<td><dfn attribute for="Document"><code data-x="dom-document-vlinkColor">vlinkColor</code></dfn>
<td><code data-x="attr-body-vlink">vlink</code>
<tr>
<td><dfn attribute for="Document"><code data-x="dom-document-alinkColor">alinkColor</code></dfn>
<td><code data-x="attr-body-alink">alink</code>
<tr>
<td><dfn attribute for="Document"><code data-x="dom-document-bgColor">bgColor</code></dfn>
<td><code data-x="attr-body-bgcolor">bgcolor</code>
</table>
<hr>
<p>The <dfn attribute for="Document"><code data-x="dom-document-anchors">anchors</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches only <code>a</code> elements with <code data-x="attr-a-name">name</code>
attributes.</p>
<p>The <dfn attribute for="Document"><code data-x="dom-document-applets">applets</code></dfn>
attribute must return an <code>HTMLCollection</code> rooted at the <code>Document</code> node,
whose filter matches nothing. (It exists for historical reasons.)</p>
<p>The <dfn method for="Document"><code data-x="dom-document-clear">clear()</code></dfn>,
<dfn method for="Document"><code data-x="dom-document-captureEvents">captureEvents()</code></dfn>,
and <dfn method for="Document"><code
data-x="dom-document-releaseEvents">releaseEvents()</code></dfn> methods must do nothing.</p>
<hr>
<p>The <dfn attribute for="Document"><code data-x="dom-document-all">all</code></dfn> attribute
must return an <code>HTMLAllCollection</code> rooted at the <code>Document</code> node, whose
filter matches all elements.</p>
<hr>
<pre><code class="idl">partial interface <span id="Window-partial">Window</span> {
undefined <span data-x="dom-window-captureEvents">captureEvents</span>();
undefined <span data-x="dom-window-releaseEvents">releaseEvents</span>();
[Replaceable, SameObject] readonly attribute <span>External</span> <span data-x="dom-external">external</span>;
};</code></pre>
<p>The <dfn method for="Window"><code
data-x="dom-window-captureEvents">captureEvents()</code></dfn> and <dfn method for="Window"><code
data-x="dom-window-releaseEvents">releaseEvents()</code></dfn> methods must do nothing.</p>
<p>The <dfn attribute for="Window"><code data-x="dom-external">external</code></dfn> attribute of
the <code>Window</code> interface must return an instance of the <code>External</code>
interface:</p>
<pre><code class="idl">[Exposed=Window]
interface <dfn interface>External</dfn> {
undefined <span data-x="dom-external-AddSearchProvider">AddSearchProvider</span>();
undefined <span data-x="dom-external-IsSearchProviderInstalled">IsSearchProviderInstalled</span>();
};</code></pre>
<p>The <dfn method for="External"><code
data-x="dom-external-AddSearchProvider">AddSearchProvider()</code></dfn> and <dfn method
for="External"><code
data-x="dom-external-IsSearchProviderInstalled">IsSearchProviderInstalled()</code></dfn> methods
must do nothing.</p>
</div>
<div w-nodev>
<h2 split-filename="iana" id="iana">IANA considerations</h2>
<!-- https://www.w3.org/2002/06/registering-mediatype.html -->
<h3><dfn><code>text/html</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type text/html
-->
<!--
Obsoletes:
https://www.rfc-editor.org/rfc/rfc2854
Include a request to retire RFC 2854 pursuant to section 6.4 of RFC 2026.
-->
<dl>
<dt>Type name:</dt>
<dd>text</dd>
<dt>Subtype name:</dt>
<dd>html</dd>
<dt>Required parameters:</dt>
<dd>No required parameters</dd>
<dt>Optional parameters:</dt>
<dd>
<dl>
<dt><code data-x="">charset</code></dt>
<dd>
<p>The <code data-x="">charset</code> parameter may be provided to specify the
<span>document's character encoding</span>, overriding any <span data-x="character encoding
declaration">character encoding declarations</span> in the document other than a Byte Order
Mark (BOM). The parameter's value must be an <span>ASCII case-insensitive</span> match for the
string "<code data-x="">utf-8</code>". <ref>ENCODING</ref></p>
</dd>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>
8bit (see the section on <span data-x="character encoding declaration">character encoding
declarations</span>)
</dd>
<dt>Security considerations:</dt>
<dd>
<p>Entire novels have been written about the security considerations that apply to HTML
documents. Many are listed in this document, to which the reader is referred for more details.
Some general concerns bear mentioning here, however:</p>
<p>HTML is scripted language, and has a large number of APIs (some of which are described in
this document). Script can expose the user to potential risks of information leakage, credential
leakage, cross-site scripting attacks, cross-site request forgeries, and a host of other
problems. While the designs in this specification are intended to be safe if implemented
correctly, a full implementation is a massive undertaking and, as with any software, user agents
are likely to have security bugs.</p>
<p>Even without scripting, there are specific features in HTML which, for historical reasons,
are required for broad compatibility with legacy content but that expose the user to unfortunate
security problems. In particular, the <code>img</code> element can be used in conjunction with
some other features as a way to effect a port scan from the user's location on the Internet.
This can expose local network topologies that the attacker would otherwise not be able to
determine.</p>
<p>HTML relies on a compartmentalization scheme sometimes known as the <i>same-origin
policy</i>. An <span>origin</span> in most cases consists of all the pages served from the same
host, on the same port, using the same protocol.</p>
<p>It is critical, therefore, to ensure that any untrusted content that forms part of a site be
hosted on a different <span>origin</span> than any sensitive content on that site. Untrusted
content can easily spoof any other page on the same origin, read data from that origin, cause
scripts in that origin to execute, submit forms to and from that origin even if they are
protected from cross-site request forgery attacks by unique tokens, and make use of any
third-party resources exposed to or rights granted to that origin.</p>
</dd>
<dt>Interoperability considerations:</dt>
<dd>
Rules for processing both conforming and non-conforming content
are defined in this specification.
</dd>
<dt>Published specification:</dt>
<dd id="authors-using-html">
This document is the relevant specification. Labeling a resource
with the <code>text/html</code> type asserts that the resource is
an <span data-x="HTML documents">HTML document</span> using
<span>the HTML syntax</span>.
</dd>
<dt>Applications that use this media type:</dt>
<dd>
Web browsers, tools for processing web content, HTML authoring
tools, search engines, validators.
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>No sequence of bytes can uniquely identify an HTML
document. More information on detecting HTML documents is
available in <cite>MIME Sniffing</cite>. <ref>MIMESNIFF</ref></dd>
<dt>File extension(s):</dt>
<dd>"<code data-x="">html</code>" and "<code data-x="">htm</code>"
are commonly, but certainly not exclusively, used as the
extension for HTML documents.</dd>
<dt>Macintosh file type code(s):</dt>
<dd><code data-x="">TEXT</code></dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>No restrictions apply.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> used with <code>text/html</code> resources
either refer to the <span>indicated part</span> of the corresponding <code>Document</code>, or
provide state information for in-page scripts.</p>
<h3><dfn><code>multipart/x-mixed-replace</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type multipart/x-mixed-replace
-->
<dl>
<dt>Type name:</dt>
<dd>multipart</dd>
<dt>Subtype name:</dt>
<dd>x-mixed-replace</dd>
<dt>Required parameters:</dt>
<dd>
<ul class="brief">
<li><code data-x="">boundary</code> (defined in RFC2046) <ref>RFC2046</ref>
</ul>
</dd>
<dt>Optional parameters:</dt>
<dd>No optional parameters.</dd>
<dt>Encoding considerations:</dt>
<dd>binary</dd>
<dt>Security considerations:</dt>
<dd>
Subresources of a <code>multipart/x-mixed-replace</code>
resource can be of any type, including types with non-trivial
security implications such as <code>text/html</code>.
</dd>
<dt>Interoperability considerations:</dt>
<dd>
None.
</dd>
<dt>Published specification:</dt>
<dd>
This specification describes processing rules for web browsers.
Conformance requirements for generating resources with this type are the same as for <code>multipart/mixed</code>. <ref>RFC2046</ref>
</dd>
<dt>Applications that use this media type:</dt>
<dd>
This type is intended to be used in resources generated by web servers, for consumption by web browsers.
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>No sequence of bytes can uniquely identify a <code>multipart/x-mixed-replace</code> resource.</dd>
<dt>File extension(s):</dt>
<dd>No specific file extensions are recommended for this type.</dd>
<dt>Macintosh file type code(s):</dt>
<dd>No specific Macintosh file type codes are recommended for this type.</dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>No restrictions apply.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> used with
<code>multipart/x-mixed-replace</code> resources apply to each body part as defined by the type
used by that body part.</p>
<h3><dfn><code>application/xhtml+xml</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type application/xhtml+xml
-->
<!--
Obsoletes:
https://www.rfc-editor.org/rfc/rfc3236
-->
<dl>
<dt>Type name:</dt>
<dd>application</dd>
<dt>Subtype name:</dt>
<dd>xhtml+xml</dd>
<dt>Required parameters:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>Optional parameters:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>Encoding considerations:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>Security considerations:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>Interoperability considerations:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt id="authors-using-xhtml">Published specification:</dt>
<dd>Labeling a resource with the <code>application/xhtml+xml</code> type asserts that the
resource is an XML document that likely has a <span>document element</span> from the <span>HTML
namespace</span>. Thus, the relevant specifications are <cite>XML</cite>, <cite>Namespaces in
XML</cite>, and this specification. <ref>XML</ref> <ref>XMLNS</ref></dd>
<dt>Applications that use this media type:</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>Same as for <code>application/xml</code> <ref>RFC7303</ref></dd>
<dt>File extension(s):</dt>
<dd>"<code data-x="">xhtml</code>" and "<code data-x="">xht</code>" are sometimes used as
extensions for XML resources that have a <span>document element</span> from the <span>HTML
namespace</span>.</dd>
<dt>Macintosh file type code(s):</dt>
<dd><code data-x="">TEXT</code></dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>No restrictions apply.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> used with
<code>application/xhtml+xml</code> resources have the same semantics as with any
<span>XML MIME type</span>. <ref>RFC7303</ref></p>
<h3><dfn><code>text/ping</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type text/ping
-->
<dl>
<dt>Type name:</dt>
<dd>text</dd>
<dt>Subtype name:</dt>
<dd>ping</dd>
<dt>Required parameters:</dt>
<dd>No parameters</dd>
<dt>Optional parameters:</dt>
<dd>
<dl>
<dt><code data-x="">charset</code></dt>
<dd>
<p>The <code data-x="">charset</code> parameter may be provided. The parameter's value must be
"<code data-x="">utf-8</code>". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.</p>
</dd>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>Not applicable.</dd>
<dt>Security considerations:</dt>
<dd>
<p>If used exclusively in the fashion described in the context of
<span>hyperlink auditing</span>, this type introduces no new
security concerns.</p>
</dd>
<dt>Interoperability considerations:</dt>
<dd>
Rules applicable to this type are defined in this specification.
</dd>
<dt>Published specification:</dt>
<dd>
This document is the relevant specification.
</dd>
<dt>Applications that use this media type:</dt>
<dd>
Web browsers.
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd><code>text/ping</code> resources always consist of the four
bytes 0x50 0x49 0x4E 0x47 (`<code data-x="">PING</code>`).</dd>
<dt>File extension(s):</dt>
<dd>No specific file extension is recommended for this type.</dd>
<dt>Macintosh file type code(s):</dt>
<dd>No specific Macintosh file type codes are recommended for this type.</dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>Only intended for use with HTTP POST requests generated as part
of a web browser's processing of the <code
data-x="attr-hyperlink-ping">ping</code> attribute.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> have no meaning with
<code>text/ping</code> resources.</p>
<h3><dfn><code>application/microdata+json</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type application/microdata+json
-->
<dl>
<dt>Type name:</dt>
<dd>application</dd>
<dt>Subtype name:</dt>
<dd>microdata+json</dd>
<dt>Required parameters:</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>Optional parameters:</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>Encoding considerations:</dt>
<dd>8bit (always UTF-8)</dd>
<dt>Security considerations:</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>Interoperability considerations:</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>Published specification:</dt>
<dd>
Labeling a resource with the <code>application/microdata+json</code> type asserts that the
resource is a JSON text that consists of an object with a single entry called "<code
data-x="">items</code>" consisting of an array of entries, each of which consists of an object
with an entry called "<code data-x="">id</code>" whose value is a string, an entry called "<code
data-x="">type</code>" whose value is another string, and an entry called "<code
data-x="">properties</code>" whose value is an object whose entries each have a value consisting
of an array of either objects or strings, the objects being of the same form as the objects in
the aforementioned "<code data-x="">items</code>" entry. Thus, the relevant specifications are
<cite>JSON</cite> and this specification. <ref>JSON</ref>
</dd>
<dt>Applications that use this media type:</dt>
<dd>
<p>Applications that transfer data intended for use with HTML's microdata feature, especially in
the context of drag-and-drop, are the primary application class for this type.</p>
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>File extension(s):</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
<dt>Macintosh file type code(s):</dt>
<dd>Same as for <code>application/json</code> <ref>JSON</ref></dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>No restrictions apply.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> used with
<code>application/microdata+json</code> resources have the same semantics as when used with
<code>application/json</code> (namely, at the time of writing, no semantics at all).
<ref>JSON</ref></p>
<h3><dfn><code>text/event-stream</code></dfn></h3>
<p>This registration is for community review and will be submitted to the IESG for review,
approval, and registration with IANA.</p>
<!--
To: ietf-types@iana.org
Subject: Registration of media type text/event-stream
-->
<dl>
<dt>Type name:</dt>
<dd>text</dd>
<dt>Subtype name:</dt>
<dd>event-stream</dd>
<dt>Required parameters:</dt>
<dd>No parameters</dd>
<dt>Optional parameters:</dt>
<dd>
<dl>
<dt><code data-x="">charset</code></dt>
<dd>
<p>The <code data-x="">charset</code> parameter may be provided. The parameter's value must be
"<code data-x="">utf-8</code>". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.</p>
</dd>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>8bit (always UTF-8)</dd>
<dt>Security considerations:</dt>
<dd>
<p>An event stream from an origin distinct from the origin of the content consuming the event
stream can result in information leakage. To avoid this, user agents are required to apply CORS
semantics. <ref>FETCH</ref></p>
<p>Event streams can overwhelm a user agent; a user agent is expected to apply suitable
restrictions to avoid depleting local resources because of an overabundance of information from
an event stream.</p>
<p>Servers can be overwhelmed if a situation develops in which the server is causing clients to
reconnect rapidly. Servers should use a 5xx status code to indicate capacity problems, as this
will prevent conforming clients from reconnecting automatically.</p>
</dd>
<dt>Interoperability considerations:</dt>
<dd>
Rules for processing both conforming and non-conforming content are defined in this
specification.
</dd>
<dt>Published specification:</dt>
<dd>
This document is the relevant specification.
</dd>
<dt>Applications that use this media type:</dt>
<dd>
Web browsers and tools using web services.
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>No sequence of bytes can uniquely identify an event stream.</dd>
<dt>File extension(s):</dt>
<dd>No specific file extensions are recommended for this type.</dd>
<dt>Macintosh file type code(s):</dt>
<dd>No specific Macintosh file type codes are recommended for this type.</dd>
</dl>
</dd>
<dt>Person & email address to contact for further information:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>This format is only expected to be used by dynamic open-ended streams served using HTTP or a
similar protocol. Finite resources are not expected to be labeled with this type.</dd>
<dt>Author:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>
<p><span data-x="concept-url-fragment">Fragments</span> have no meaning with
<code>text/event-stream</code> resources.</p>
<h3><dfn><code data-x="scheme-web">web+</code> scheme prefix</dfn></h3>
<p>This section describes a convention for use with the IANA URI scheme registry. It does not
itself register a specific scheme. <ref>RFC7595</ref></p>
<dl>
<dt>Scheme name:</dt>
<dd>
Schemes starting with the four characters "<code
data-x="">web+</code>" followed by one or more letters in the range
<code data-x="">a</code>-<code data-x="">z</code>.
</dd>
<dt>Status:</dt>
<dd>Permanent</dd>
<dt>Scheme syntax:</dt>
<dd>Scheme-specific.</dd>
<dt>Scheme semantics:</dt>
<dd>Scheme-specific.</dd>
<dt>Encoding considerations:</dt>
<dd>All "<code data-x="">web+</code>" schemes should use UTF-8 encodings where relevant.</dd>
<dt>Applications/protocols that use this scheme name:</dt>
<dd>Scheme-specific.</dd>
<dt>Interoperability considerations:</dt>
<dd>The scheme is expected to be used in the context of web applications.</dd>
<dt>Security considerations:</dt>
<dd>
Any web page is able to register a handler for all "<code data-x="">web+</code>" schemes. As
such, these schemes must not be used for features intended to be core platform features (e.g.,
HTTP). Similarly, such schemes must not store confidential information in their URLs, such as
usernames, passwords, personal information, or confidential project names.
</dd>
<dt>Contact:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>Change controller:</dt>
<dd>Ian Hickson <ian@hixie.ch></dd>
<dt>References:</dt>
<dd>
<cite>Custom scheme handlers</cite>, HTML Living Standard:
<a href="#custom-handlers">https://html.spec.whatwg.org/#custom-handlers</a>
</dd>
</dl>
</div>
<h2 split-filename="indices" id="index" class="no-num">Index</h2>
<div w-nodev>
<p>The following sections only cover conforming elements and features.</p>
</div>
<h3 class="no-num">Elements</h3>
<!-- NON-NORMATIVE SECTION -->
<table>
<caption>List of elements</caption>
<thead>
<tr>
<th> Element
<th> Description
<th> Categories
<th> Parents†
<th> Children
<th> Attributes
<th> Interface
<tbody>
<tr>
<th><code>a</code></th>
<td>Hyperlink</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>*;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-hyperlink-href">href</code>;
<code data-x="attr-hyperlink-target">target</code>;
<code data-x="attr-hyperlink-download">download</code>;
<code data-x="attr-hyperlink-ping">ping</code>;
<code data-x="attr-hyperlink-rel">rel</code>;
<code data-x="attr-hyperlink-hreflang">hreflang</code>;
<code data-x="attr-hyperlink-type">type</code>;
<code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code></td>
<td><code>HTMLAnchorElement</code></td>
</tr>
<tr>
<th><code>abbr</code></th>
<td>Abbreviation</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>address</code></th>
<td>Contact information for a page or <code>article</code> element</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>area</code></th>
<td>Hyperlink or dead area on an image map</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-area-alt">alt</code>;
<code data-x="attr-area-coords">coords</code>;
<code data-x="attr-area-shape">shape</code>;
<code data-x="attr-hyperlink-href">href</code>;
<code data-x="attr-hyperlink-target">target</code>;
<code data-x="attr-hyperlink-download">download</code>;
<code data-x="attr-hyperlink-ping">ping</code>;
<code data-x="attr-hyperlink-rel">rel</code>;
<code data-x="attr-hyperlink-referrerpolicy">referrerpolicy</code></td>
<td><code>HTMLAreaElement</code></td>
</tr>
<tr>
<th><code>article</code></th>
<td>Self-contained syndicatable or reusable composition</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Sectioning content">sectioning</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>aside</code></th>
<td>Sidebar for tangentially related content</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Sectioning content">sectioning</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>audio</code></th>
<td>Audio player</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span>*</td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><code>source</code>*;
<code>track</code>*;
<span>transparent</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-media-src">src</code>;
<code data-x="attr-media-crossorigin">crossorigin</code>;
<code data-x="attr-media-preload">preload</code>;
<code data-x="attr-media-autoplay">autoplay</code>;
<code data-x="attr-media-loop">loop</code>;
<code data-x="attr-media-muted">muted</code>;
<code data-x="attr-media-controls">controls</code></td>
<td><code>HTMLAudioElement</code></td>
</tr>
<tr>
<th><code>b</code></th>
<td>Keywords</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>base</code></th>
<td>Base URL and default target <span>navigable</span> for <span data-x="attr-hyperlink-target">hyperlinks</span> and <span data-x="attr-fs-target">forms</span></td>
<td><span data-x="Metadata content">metadata</span></td>
<td><code>head</code></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-base-href">href</code>;
<code data-x="attr-base-target">target</code></td>
<td><code>HTMLBaseElement</code></td>
</tr>
<tr>
<th><code>bdi</code></th>
<td>Text directionality isolation</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>bdo</code></th>
<td>Text directionality formatting</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>blockquote</code></th>
<td>A section quoted from another source</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-blockquote-cite">cite</code></td>
<td><code>HTMLQuoteElement</code></td>
</tr>
<tr>
<th><code>body</code></th>
<td>Document body</td>
<td>none</td>
<td><code>html</code></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="handler-window-onafterprint">onafterprint</code>;
<code data-x="handler-window-onbeforeprint">onbeforeprint</code>;
<code data-x="handler-window-onbeforeunload">onbeforeunload</code>;
<code data-x="handler-window-onhashchange">onhashchange</code>;
<code data-x="handler-window-onlanguagechange">onlanguagechange</code>;
<code data-x="handler-window-onmessage">onmessage</code>;
<code data-x="handler-window-onmessageerror">onmessageerror</code>;
<code data-x="handler-window-onoffline">onoffline</code>;
<code data-x="handler-window-ononline">ononline</code>;
<code data-x="handler-window-onpageswap">onpageswap</code>;
<code data-x="handler-window-onpagehide">onpagehide</code>;
<code data-x="handler-window-onpagereveal">onpagereveal</code>;
<code data-x="handler-window-onpageshow">onpageshow</code>;
<code data-x="handler-window-onpopstate">onpopstate</code>;
<code data-x="handler-window-onrejectionhandled">onrejectionhandled</code>;
<code data-x="handler-window-onstorage">onstorage</code>;
<code data-x="handler-window-onunhandledrejection">onunhandledrejection</code>;
<code data-x="handler-window-onunload">onunload</code></td>
<td><code>HTMLBodyElement</code></td>
</tr>
<tr>
<th><code>br</code></th>
<td>Line break, e.g. in poem or postal address</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLBRElement</code></td>
</tr>
<tr>
<th><code>button</code></th>
<td>Button control</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="category-listed">listed</span>;
<span data-x="category-label">labelable</span>;
<span data-x="category-submit">submittable</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-button-command">command</code>;
<code data-x="attr-button-commandfor">commandfor</code>;
<code data-x="attr-fe-disabled">disabled</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-fs-formaction">formaction</code>;
<code data-x="attr-fs-formenctype">formenctype</code>;
<code data-x="attr-fs-formmethod">formmethod</code>;
<code data-x="attr-fs-formnovalidate">formnovalidate</code>;
<code data-x="attr-fs-formtarget">formtarget</code>;
<code data-x="attr-fe-name">name</code>;
<code data-x="attr-popovertarget">popovertarget</code>;
<code data-x="attr-popovertargetaction">popovertargetaction</code>;
<code data-x="attr-button-type">type</code>;
<code data-x="attr-button-value">value</code></td>
<td><code>HTMLButtonElement</code></td>
</tr>
<tr>
<th><code>canvas</code></th>
<td>Scriptable bitmap canvas</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-canvas-width">width</code>;
<code data-x="attr-canvas-height">height</code></td>
<td><code>HTMLCanvasElement</code></td>
</tr>
<tr>
<th><code>caption</code></th>
<td>Table caption</td>
<td>none</td>
<td><code>table</code></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableCaptionElement</code></td>
</tr>
<tr>
<th><code>cite</code></th>
<td>Title of a work</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>code</code></th>
<td>Computer code</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>col</code></th>
<td>Table column</td>
<td>none</td>
<td><code>colgroup</code></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-col-span">span</code></td>
<td><code>HTMLTableColElement</code></td>
</tr>
<tr>
<th><code>colgroup</code></th>
<td>Group of columns in a table</td>
<td>none</td>
<td><code>table</code></td>
<td><code>col</code>*;
<code>template</code>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-colgroup-span">span</code></td>
<td><code>HTMLTableColElement</code></td>
</tr>
<tr>
<th><code>data</code></th>
<td>Machine-readable equivalent</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-data-value">value</code></td>
<td><code>HTMLDataElement</code></td>
</tr>
<tr>
<th><code>datalist</code></th>
<td>Container for options for <span data-x="attr-input-list">combo box control</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*;
<code>option</code>*;
<span>script-supporting elements</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLDataListElement</code></td>
</tr>
<tr>
<th><code>dd</code></th>
<td>Content for corresponding <code>dt</code> element(s)</td>
<td>none</td>
<td><code>dl</code>;
<code>div</code>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>del</code></th>
<td>A removal from the document</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>*;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-mod-cite">cite</code>;
<code data-x="attr-mod-datetime">datetime</code></td>
<td><code>HTMLModElement</code></td>
</tr>
<tr>
<th><code>details</code></th>
<td>Disclosure control for hiding details</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><code>summary</code>*;
<span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-details-name">name</code>;
<code data-x="attr-details-open">open</code></td>
<td><code>HTMLDetailsElement</code></td>
</tr>
<tr>
<th><code>dfn</code></th>
<td>Defining instance</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>dialog</code></th>
<td>Dialog box or window</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-dialog-open">open</code></td>
<td><code>HTMLDialogElement</code></td>
</tr>
<tr>
<th><code>div</code></th>
<td>Generic flow container, or container for name-value groups in <code>dl</code> elements</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span>;
<code>dl</code></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLDivElement</code></td>
</tr>
<tr>
<th><code>dl</code></th>
<td>Association list consisting of zero or more name-value groups</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><code>dt</code>*;
<code>dd</code>*;
<code>div</code>*;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLDListElement</code></td>
</tr>
<tr>
<th><code>dt</code></th>
<td>Legend for corresponding <code>dd</code> element(s)</td>
<td>none</td>
<td><code>dl</code>;
<code>div</code>*</td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>em</code></th>
<td>Stress emphasis</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>embed</code></th>
<td><span>Plugin</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-embed-src">src</code>;
<code data-x="attr-embed-type">type</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code>;
any*</td>
<td><code>HTMLEmbedElement</code></td>
</tr>
<tr>
<th><code>fieldset</code></th>
<td>Group of form controls</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="category-listed">listed</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><code>legend</code>*;
<span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-fieldset-disabled">disabled</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-fe-name">name</code></td>
<td><code>HTMLFieldSetElement</code></td>
</tr>
<tr>
<th><code>figcaption</code></th>
<td>Caption for <code>figure</code></td>
<td>none</td>
<td><code>figure</code></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>figure</code></th>
<td>Figure with optional caption</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><code>figcaption</code>*;
<span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>footer</code></th>
<td>Footer for a page or section</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>form</code></th>
<td>User-submittable form</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-form-accept-charset">accept-charset</code>;
<code data-x="attr-fs-action">action</code>;
<code data-x="attr-form-autocomplete">autocomplete</code>;
<code data-x="attr-fs-enctype">enctype</code>;
<code data-x="attr-fs-method">method</code>;
<code data-x="attr-form-name">name</code>;
<code data-x="attr-fs-novalidate">novalidate</code>;
<code data-x="attr-form-rel">rel</code>;
<code data-x="attr-fs-target">target</code></td>
<td><code>HTMLFormElement</code></td>
</tr>
<tr>
<th><code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code></th>
<td>Heading</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Heading content">heading</span>;
<span data-x="Palpable content">palpable</span></td>
<td><code>legend</code>;
<code>summary</code>;
<span data-x="Flow content">flow</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLHeadingElement</code></td>
</tr>
<tr>
<th><code>head</code></th>
<td>Container for document metadata</td>
<td>none</td>
<td><code>html</code></td>
<td><span data-x="Metadata content">metadata content</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLHeadElement</code></td>
</tr>
<tr>
<th><code>header</code></th>
<td>Introductory or navigational aids for a page or section</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>hgroup</code></th>
<td>Heading container</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td>
<code>legend</code>;
<code>summary</code>;
<span data-x="Flow content">flow</span></td>
<td><code>h1</code>;
<code>h2</code>;
<code>h3</code>;
<code>h4</code>;
<code>h5</code>;
<code>h6</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>hr</code></th>
<td>Thematic break</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLHRElement</code></td>
</tr>
<tr>
<th><code>html</code></th>
<td>Root element</td>
<td>none</td>
<td>none*</td>
<td><code>head</code>*;
<code>body</code>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLHtmlElement</code></td>
</tr>
<tr>
<th><code>i</code></th>
<td>Alternate voice</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>iframe</code></th>
<td><span>Child navigable</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-iframe-src">src</code>;
<code data-x="attr-iframe-srcdoc">srcdoc</code>;
<code data-x="attr-iframe-name">name</code>;
<code data-x="attr-iframe-sandbox">sandbox</code>;
<code data-x="attr-iframe-allow">allow</code>;
<code data-x="attr-iframe-allowfullscreen">allowfullscreen</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code>;
<code data-x="attr-iframe-referrerpolicy">referrerpolicy</code>;
<code data-x="attr-iframe-loading">loading</code></td>
<td><code>HTMLIFrameElement</code></td>
</tr>
<tr>
<th><code>img</code></th>
<td>Image</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>*;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span>;
<code>picture</code></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-img-alt">alt</code>;
<code data-x="attr-img-src">src</code>;
<code data-x="attr-img-srcset">srcset</code>;
<code data-x="attr-img-sizes">sizes</code>;
<code data-x="attr-img-crossorigin">crossorigin</code>;
<code data-x="attr-hyperlink-usemap">usemap</code>;
<code data-x="attr-img-ismap">ismap</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code>;
<code data-x="attr-img-referrerpolicy">referrerpolicy</code>;
<code data-x="attr-img-decoding">decoding</code>;
<code data-x="attr-img-loading">loading</code>;
<code data-x="attr-img-fetchpriority">fetchpriority</code></td>
<td><code>HTMLImageElement</code></td>
</tr>
<tr>
<th><code>input</code></th>
<td>Form control</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Interactive content">interactive</span>*;
<span data-x="category-listed">listed</span>;
<span data-x="category-label">labelable</span>;
<span data-x="category-submit">submittable</span>;
<span data-x="category-reset">resettable</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span>*</td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-input-accept">accept</code>;
<code data-x="attr-input-alpha">alpha</code>;
<code data-x="attr-input-alt">alt</code>;
<code data-x="attr-fe-autocomplete">autocomplete</code>;
<code data-x="attr-input-checked">checked</code>;
<code data-x="attr-input-colorspace">colorspace</code>;
<code data-x="attr-fe-dirname">dirname</code>;
<code data-x="attr-fe-disabled">disabled</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-fs-formaction">formaction</code>;
<code data-x="attr-fs-formenctype">formenctype</code>;
<code data-x="attr-fs-formmethod">formmethod</code>;
<code data-x="attr-fs-formnovalidate">formnovalidate</code>;
<code data-x="attr-fs-formtarget">formtarget</code>;
<code data-x="attr-dim-height">height</code>;
<code data-x="attr-input-list">list</code>;
<code data-x="attr-input-max">max</code>;
<code data-x="attr-input-maxlength">maxlength</code>;
<code data-x="attr-input-min">min</code>;
<code data-x="attr-input-minlength">minlength</code>;
<code data-x="attr-input-multiple">multiple</code>;
<code data-x="attr-fe-name">name</code>;
<code data-x="attr-input-pattern">pattern</code>;
<code data-x="attr-input-placeholder">placeholder</code>;
<code data-x="attr-popovertarget">popovertarget</code>;
<code data-x="attr-popovertargetaction">popovertargetaction</code>;
<code data-x="attr-input-readonly">readonly</code>;
<code data-x="attr-input-required">required</code>;
<code data-x="attr-input-size">size</code>;
<code data-x="attr-input-src">src</code>;
<code data-x="attr-input-step">step</code>;
<code data-x="attr-input-type">type</code>;
<code data-x="attr-input-value">value</code>;
<code data-x="attr-dim-width">width</code></td>
<td><code>HTMLInputElement</code></td>
</tr>
<tr>
<th><code>ins</code></th>
<td>An addition to the document</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>*;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-mod-cite">cite</code>;
<code data-x="attr-mod-datetime">datetime</code></td>
<td><code>HTMLModElement</code></td>
</tr>
<tr>
<th><code>kbd</code></th>
<td>User input</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>label</code></th>
<td>Caption for a form control</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-label-for">for</code></td>
<td><code>HTMLLabelElement</code></td>
</tr>
<tr>
<th><code>legend</code></th>
<td>Caption for <code>fieldset</code></td>
<td>none</td>
<td><code>fieldset</code></td>
<td><span data-x="Phrasing content">phrasing</span>;
<span data-x="heading content">heading content</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLLegendElement</code></td>
</tr>
<tr>
<th><code>li</code></th>
<td>List item</td>
<td>none</td>
<td><code>ol</code>;
<code>ul</code>;
<code>menu</code>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-li-value">value</code>*</td>
<td><code>HTMLLIElement</code></td>
</tr>
<tr>
<th><code>link</code></th>
<td>Link metadata</td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Flow content">flow</span>*;
<span data-x="Phrasing content">phrasing</span>*</td>
<td><code>head</code>;
<code>noscript</code>*;
<span data-x="phrasing content">phrasing</span>*</td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-link-href">href</code>;
<code data-x="attr-link-crossorigin">crossorigin</code>;
<code data-x="attr-link-rel">rel</code>;
<code data-x="attr-link-as">as</code>;
<code data-x="attr-link-media">media</code>;
<code data-x="attr-link-hreflang">hreflang</code>;
<code data-x="attr-link-type">type</code>;
<code data-x="attr-link-sizes">sizes</code>;
<code data-x="attr-link-imagesrcset">imagesrcset</code>;
<code data-x="attr-link-imagesizes">imagesizes</code>;
<code data-x="attr-link-referrerpolicy">referrerpolicy</code>;
<code data-x="attr-link-integrity">integrity</code>;
<code data-x="attr-link-blocking">blocking</code>;
<code data-x="attr-link-color">color</code>;
<code data-x="attr-link-disabled">disabled</code>;
<code data-x="attr-link-fetchpriority">fetchpriority</code></td>
<td><code>HTMLLinkElement</code></td>
</tr>
<tr>
<th><code>main</code></th>
<td>Container for the dominant contents of the document</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>map</code></th>
<td><span>Image map</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>*;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span>;
<code>area</code>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-map-name">name</code></td>
<td><code>HTMLMapElement</code></td>
</tr>
<tr>
<th><code>mark</code></th>
<td>Highlight</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><span>MathML <code>math</code></span></th>
<td>MathML root</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>per <ref>MATHML</ref></td>
<td>per <ref>MATHML</ref></td>
<td><code>Element</code></td>
</tr>
<tr>
<th><code>menu</code></th>
<td>Menu of commands</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><code>li</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLMenuElement</code></td>
</tr>
<tr>
<th><code>meta</code></th>
<td>Text metadata</td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Flow content">flow</span>*;
<span data-x="Phrasing content">phrasing</span>*</td>
<td><code>head</code>;
<code>noscript</code>*;
<span data-x="phrasing content">phrasing</span>*</td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-meta-name">name</code>;
<code data-x="attr-meta-http-equiv">http-equiv</code>;
<code data-x="attr-meta-content">content</code>;
<code data-x="attr-meta-charset">charset</code>;
<code data-x="attr-meta-media">media</code></td>
<td><code>HTMLMetaElement</code></td>
</tr>
<tr>
<th><code>meter</code></th>
<td>Gauge</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="category-label">labelable</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-meter-value">value</code>;
<code data-x="attr-meter-min">min</code>;
<code data-x="attr-meter-max">max</code>;
<code data-x="attr-meter-low">low</code>;
<code data-x="attr-meter-high">high</code>;
<code data-x="attr-meter-optimum">optimum</code></td>
<td><code>HTMLMeterElement</code></td>
</tr>
<tr>
<th><code>nav</code></th>
<td>Section with navigational links</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Sectioning content">sectioning</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>noscript</code></th>
<td>Fallback content for script</td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><code>head</code>*;
<span data-x="Phrasing content">phrasing</span>*</td>
<td>varies*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>object</code></th>
<td>Image, <span>child navigable</span>, or <span>plugin</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>*;
<span data-x="category-listed">listed</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-object-data">data</code>;
<code data-x="attr-object-type">type</code>;
<code data-x="attr-object-name">name</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code></td>
<td><code>HTMLObjectElement</code></td>
</tr>
<tr>
<th><code>ol</code></th>
<td>Ordered list</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><code>li</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-ol-reversed">reversed</code>;
<code data-x="attr-ol-start">start</code>;
<code data-x="attr-ol-type">type</code></td>
<td><code>HTMLOListElement</code></td>
</tr>
<tr>
<th><code>optgroup</code></th>
<td>Group of options in a list box</td>
<td>none</td>
<td><code>select</code></td>
<td><code>option</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-optgroup-disabled">disabled</code>;
<code data-x="attr-optgroup-label">label</code></td>
<td><code>HTMLOptGroupElement</code></td>
</tr>
<tr>
<th><code>option</code></th>
<td>Option in a list box or combo box control</td>
<td>none</td>
<td><code>select</code>;
<code>datalist</code>;
<code>optgroup</code></td>
<td><span data-x="text content">text</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-option-disabled">disabled</code>;
<code data-x="attr-option-label">label</code>;
<code data-x="attr-option-selected">selected</code>;
<code data-x="attr-option-value">value</code></td>
<td><code>HTMLOptionElement</code></td>
</tr>
<tr>
<th><code>output</code></th>
<td>Calculated output value</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="category-listed">listed</span>;
<span data-x="category-label">labelable</span>;
<span data-x="category-reset">resettable</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-output-for">for</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-fe-name">name</code></td>
<td><code>HTMLOutputElement</code></td>
</tr>
<tr>
<th><code>p</code></th>
<td>Paragraph</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLParagraphElement</code></td>
</tr>
<tr>
<th><code>picture</code></th>
<td>Image</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><code>source</code>*;
one <code>img</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLPictureElement</code></td>
</tr>
<tr>
<th><code>pre</code></th>
<td>Block of preformatted text</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLPreElement</code></td>
</tr>
<tr>
<th><code>progress</code></th>
<td>Progress bar</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="category-label">labelable</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-progress-value">value</code>;
<code data-x="attr-progress-max">max</code></td>
<td><code>HTMLProgressElement</code></td>
</tr>
<tr>
<th><code>q</code></th>
<td>Quotation</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-q-cite">cite</code></td>
<td><code>HTMLQuoteElement</code></td>
</tr>
<tr>
<th><code>rp</code></th>
<td>Parenthesis for ruby annotation text</td>
<td>none</td>
<td><code>ruby</code></td>
<td><span data-x="text content">text</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>rt</code></th>
<td>Ruby annotation text</td>
<td>none</td>
<td><code>ruby</code></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>ruby</code></th>
<td>Ruby annotation(s)</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span>;
<code>rt</code>;
<code>rp</code>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>s</code></th>
<td>Inaccurate text</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>samp</code></th>
<td>Computer output</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>script</code></th>
<td>Embedded script</td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Script-supporting elements">script-supporting</span></td>
<td><code>head</code>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Script-supporting elements">script-supporting</span></td>
<td>script, data, or script documentation*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-script-src">src</code>;
<code data-x="attr-script-type">type</code>;
<code data-x="attr-script-nomodule">nomodule</code>;
<code data-x="attr-script-async">async</code>;
<code data-x="attr-script-defer">defer</code>;
<code data-x="attr-script-crossorigin">crossorigin</code>;
<code data-x="attr-script-integrity">integrity</code>;
<code data-x="attr-script-referrerpolicy">referrerpolicy</code>;
<code data-x="attr-script-blocking">blocking</code>;
<code data-x="attr-script-fetchpriority">fetchpriority</code></td>
<td><code>HTMLScriptElement</code></td>
</tr>
<tr>
<th><code>search</code></th>
<td>Container for search controls</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>section</code></th>
<td>Generic document or application section</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Sectioning content">sectioning</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>select</code></th>
<td>List box control</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="category-listed">listed</span>;
<span data-x="category-label">labelable</span>;
<span data-x="category-submit">submittable</span>;
<span data-x="category-reset">resettable</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><code>option</code>;
<code>optgroup</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-fe-autocomplete">autocomplete</code>;
<code data-x="attr-fe-disabled">disabled</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-select-multiple">multiple</code>;
<code data-x="attr-fe-name">name</code>;
<code data-x="attr-select-required">required</code>;
<code data-x="attr-select-size">size</code></td>
<td><code>HTMLSelectElement</code></td>
</tr>
<tr>
<th><code>slot</code></th>
<td>Shadow tree slot</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-slot-name">name</code></td>
<td><code>HTMLSlotElement</code></td>
</tr>
<tr>
<th><code>small</code></th>
<td>Side comment</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>source</code></th>
<td>Image source for <code>img</code> or media source for <code>video</code> or <code>audio</code></td>
<td>none</td>
<td><code>picture</code>;
<code>video</code>;
<code>audio</code></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-source-type">type</code>;
<code data-x="attr-source-media">media</code>;
<code data-x="attr-source-src">src</code>;
<code data-x="attr-source-srcset">srcset</code>;
<code data-x="attr-source-sizes">sizes</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code></td>
<td><code>HTMLSourceElement</code></td>
</tr>
<tr>
<th><code>span</code></th>
<td>Generic phrasing container</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLSpanElement</code></td>
</tr>
<tr>
<th><code>strong</code></th>
<td>Importance</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>style</code></th>
<td>Embedded styling information</td>
<td><span data-x="Metadata content">metadata</span></td>
<td><code>head</code>;
<code>noscript</code>*</td>
<td>text*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-style-media">media</code>;
<code data-x="attr-style-blocking">blocking</code></td>
<td><code>HTMLStyleElement</code></td>
</tr>
<tr>
<th><code>sub</code></th>
<td>Subscript</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>summary</code></th>
<td>Caption for <code>details</code></td>
<td>none</td>
<td><code>details</code></td>
<td><span data-x="Phrasing content">phrasing</span>;
<span data-x="Heading content">heading content</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>sup</code></th>
<td>Superscript</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><span>SVG <code>svg</code></span></th>
<td>SVG root</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>per <ref>SVG</ref></td>
<td>per <ref>SVG</ref></td>
<td><code>SVGSVGElement</code></td>
</tr>
<tr>
<th><code>table</code></th>
<td>Table</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><code>caption</code>*;
<code>colgroup</code>*;
<code>thead</code>*;
<code>tbody</code>*;
<code>tfoot</code>*;
<code>tr</code>*;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableElement</code></td>
</tr>
<tr>
<th><code>tbody</code></th>
<td>Group of rows in a table</td>
<td>none</td>
<td><code>table</code></td>
<td><code>tr</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableSectionElement</code></td>
</tr>
<tr>
<th><code>td</code></th>
<td>Table cell</td>
<td>none</td>
<td><code>tr</code></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-tdth-colspan">colspan</code>;
<code data-x="attr-tdth-rowspan">rowspan</code>;
<code data-x="attr-tdth-headers">headers</code></td>
<td><code>HTMLTableCellElement</code></td>
</tr>
<tr>
<th><code>template</code></th>
<td>Template</td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Script-supporting elements">script-supporting</span></td>
<td><span data-x="Metadata content">metadata</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Script-supporting elements">script-supporting</span>;
<code>colgroup</code>*</td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-template-shadowrootmode">shadowrootmode</code>;
<code data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code>;
<code data-x="attr-template-shadowrootclonable">shadowrootclonable</code>;
<code data-x="attr-template-shadowrootserializable">shadowrootserializable</code></td>
<td><code>HTMLTemplateElement</code></td>
</tr>
<tr>
<th><code>textarea</code></th>
<td>Multiline text controls</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="category-listed">listed</span>;
<span data-x="category-label">labelable</span>;
<span data-x="category-submit">submittable</span>;
<span data-x="category-reset">resettable</span>;
<span data-x="Form-associated element">form-associated</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="text content">text</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-fe-autocomplete">autocomplete</code>;
<code data-x="attr-textarea-cols">cols</code>;
<code data-x="attr-fe-dirname">dirname</code>;
<code data-x="attr-fe-disabled">disabled</code>;
<code data-x="attr-fae-form">form</code>;
<code data-x="attr-textarea-maxlength">maxlength</code>;
<code data-x="attr-textarea-minlength">minlength</code>;
<code data-x="attr-fe-name">name</code>;
<code data-x="attr-textarea-placeholder">placeholder</code>;
<code data-x="attr-textarea-readonly">readonly</code>;
<code data-x="attr-textarea-required">required</code>;
<code data-x="attr-textarea-rows">rows</code>;
<code data-x="attr-textarea-wrap">wrap</code></td>
<td><code>HTMLTextAreaElement</code></td>
</tr>
<tr>
<th><code>tfoot</code></th>
<td>Group of footer rows in a table</td>
<td>none</td>
<td><code>table</code></td>
<td><code>tr</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableSectionElement</code></td>
</tr>
<tr>
<th><code>th</code></th>
<td>Table header cell</td>
<td><span data-x="Interactive content">interactive</span>*</td>
<td><code>tr</code></td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-tdth-colspan">colspan</code>;
<code data-x="attr-tdth-rowspan">rowspan</code>;
<code data-x="attr-tdth-headers">headers</code>;
<code data-x="attr-th-scope">scope</code>;
<code data-x="attr-th-abbr">abbr</code></td>
<td><code>HTMLTableCellElement</code></td>
</tr>
<tr>
<th><code>thead</code></th>
<td>Group of heading rows in a table</td>
<td>none</td>
<td><code>table</code></td>
<td><code>tr</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableSectionElement</code></td>
</tr>
<tr>
<th><code>time</code></th>
<td>Machine-readable equivalent of date- or time-related data</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-time-datetime">datetime</code></td>
<td><code>HTMLTimeElement</code></td>
</tr>
<tr>
<th><code>title</code></th>
<td>Document title</td>
<td><span data-x="Metadata content">metadata</span></td>
<td><code>head</code></td>
<td><span data-x="text content">text</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTitleElement</code></td>
</tr>
<tr>
<th><code>tr</code></th>
<td>Table row</td>
<td>none</td>
<td><code>table</code>;
<code>thead</code>;
<code>tbody</code>;
<code>tfoot</code></td>
<td><code>th</code>*;
<code>td</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLTableRowElement</code></td>
</tr>
<tr>
<th><code>track</code></th>
<td>Timed text track</td>
<td>none</td>
<td><code>audio</code>;
<code>video</code></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-track-default">default</code>;
<code data-x="attr-track-kind">kind</code>;
<code data-x="attr-track-label">label</code>;
<code data-x="attr-track-src">src</code>;
<code data-x="attr-track-srclang">srclang</code></td>
<td><code>HTMLTrackElement</code></td>
</tr>
<tr>
<th><code>u</code></th>
<td>Unarticulated annotation</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>ul</code></th>
<td>List</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><code>li</code>;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLUListElement</code></td>
</tr>
<tr>
<th><code>var</code></th>
<td>Variable</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><code>video</code></th>
<td>Video player</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Embedded content">embedded</span>;
<span data-x="Interactive content">interactive</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td><code>source</code>*;
<code>track</code>*;
<span>transparent</span>*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-media-src">src</code>;
<code data-x="attr-media-crossorigin">crossorigin</code>;
<code data-x="attr-video-poster">poster</code>;
<code data-x="attr-media-preload">preload</code>;
<code data-x="attr-media-autoplay">autoplay</code>;
<code data-x="attr-video-playsinline">playsinline</code>;
<code data-x="attr-media-loop">loop</code>;
<code data-x="attr-media-muted">muted</code>;
<code data-x="attr-media-controls">controls</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code></td>
<td><code>HTMLVideoElement</code></td>
</tr>
<tr>
<th><code>wbr</code></th>
<td>Line breaking opportunity</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span data-x="Phrasing content">phrasing</span></td>
<td>empty</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
</tr>
<tr>
<th><span data-x="autonomous custom element">autonomous custom elements</span></th>
<td>Author-defined elements</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span></td>
<td><span>transparent</span></td>
<td><span data-x="global attributes">globals</span>; any, as decided by the element's author</td>
<td>Supplied by the element's author (inherits from <code>HTMLElement</code>)</td>
</tr>
</table>
<p class="tablenote"><small>An asterisk (*) in a cell indicates that the actual rules are more
complicated than indicated in the table above.</small></p>
<p class="tablenote"><small>† Categories in the "Parents" column refer to parents that list
the given categories in their content model, not to elements that themselves are in those
categories. For example, the <code>a</code> element's "Parents" column says "phrasing", so any
element whose content model contains the "phrasing" category could be a parent of an
<code>a</code> element. Since the "flow" category includes all the "phrasing" elements, that means
the <code>th</code> element could be a parent to an <code>a</code> element.</small></p>
<h3 class="no-num">Element content categories</h3>
<!-- NON-NORMATIVE SECTION -->
<!-- when updating this also check the category-list <ul>s -->
<table>
<caption>List of element content categories</caption>
<thead>
<tr>
<th> Category
<th> Elements
<th> Elements with exceptions
<tbody>
<tr>
<td> <span>Metadata content</span>
<td>
<code>base</code>;
<code>link</code>;
<code>meta</code>;
<code>noscript</code>;
<code>script</code>;
<code>style</code>;
<code>template</code>;
<code>title</code>
<td>
—
<tr>
<td> <span>Flow content</span>
<td>
<code>a</code>;
<code>abbr</code>;
<code>address</code>;
<code>article</code>;
<code>aside</code>;
<code>audio</code>;
<code>b</code>;
<code>bdi</code>;
<code>bdo</code>;
<code>blockquote</code>;
<code>br</code>;
<code>button</code>;
<code>canvas</code>;
<code>cite</code>;
<code>code</code>;
<code>data</code>;
<code>datalist</code>;
<code>del</code>;
<code>details</code>;
<code>dfn</code>;
<code>dialog</code>;
<code>div</code>;
<code>dl</code>;
<code>em</code>;
<code>embed</code>;
<code>fieldset</code>;
<code>figure</code>;
<code>footer</code>;
<code>form</code>;
<code>h1</code>;
<code>h2</code>;
<code>h3</code>;
<code>h4</code>;
<code>h5</code>;
<code>h6</code>;
<code>header</code>;
<code>hgroup</code>;
<code>hr</code>;
<code>i</code>;
<code>iframe</code>;
<code>img</code>;
<code>input</code>;
<code>ins</code>;
<code>kbd</code>;
<code>label</code>;
<code>map</code>;
<code>mark</code>;
<span>MathML <code>math</code></span>;
<code>menu</code>;
<code>meter</code>;
<code>nav</code>;
<code>noscript</code>;
<code>object</code>;
<code>ol</code>;
<code>output</code>;
<code>p</code>;
<code>picture</code>;
<code>pre</code>;
<code>progress</code>;
<code>q</code>;
<code>ruby</code>;
<code>s</code>;
<code>samp</code>;
<code>script</code>;
<code>search</code>;
<code>section</code>;
<code>select</code>;
<code>slot</code>;
<code>small</code>;
<code>span</code>;
<code>strong</code>;
<code>sub</code>;
<code>sup</code>;
<span>SVG <code>svg</code></span>;
<code>table</code>;
<code>template</code>;
<code>textarea</code>;
<code>time</code>;
<code>u</code>;
<code>ul</code>;
<code>var</code>;
<code>video</code>;
<code>wbr</code>;
<span data-x="autonomous custom element">autonomous custom elements</span>;
<span data-x="text content">Text</span>
<td>
<code>area</code> (if it is a descendant of a <code>map</code> element);
<code>link</code> (if it is <span>allowed in the body</span>);
<code>main</code> (if it is a <span>hierarchically correct <code>main</code> element</span>);
<code>meta</code> (if the <code data-x="attr-itemprop">itemprop</code> attribute is present)
<tr>
<td> <span>Sectioning content</span>
<td>
<code>article</code>;
<code>aside</code>;
<code>nav</code>;
<code>section</code>
<td>
—
<tr>
<td> <span>Heading content</span>
<td>
<code>h1</code>;
<code>h2</code>;
<code>h3</code>;
<code>h4</code>;
<code>h5</code>;
<code>h6</code>;
<code>hgroup</code>
<td>
—
<tr>
<td> <span>Phrasing content</span>
<td>
<code>a</code>;
<code>abbr</code>;
<code>audio</code>;
<code>b</code>;
<code>bdi</code>;
<code>bdo</code>;
<code>br</code>;
<code>button</code>;
<code>canvas</code>;
<code>cite</code>;
<code>code</code>;
<code>data</code>;
<code>datalist</code>;
<code>del</code>;
<code>dfn</code>;
<code>em</code>;
<code>embed</code>;
<code>i</code>;
<code>iframe</code>;
<code>img</code>;
<code>input</code>;
<code>ins</code>;
<code>kbd</code>;
<code>label</code>;
<code>map</code>;
<code>mark</code>;
<span>MathML <code>math</code></span>;
<code>meter</code>;
<code>noscript</code>;
<code>object</code>;
<code>output</code>;
<code>picture</code>;
<code>progress</code>;
<code>q</code>;
<code>ruby</code>;
<code>s</code>;
<code>samp</code>;
<code>script</code>;
<code>select</code>;
<code>slot</code>;
<code>small</code>;
<code>span</code>;
<code>strong</code>;
<code>sub</code>;
<code>sup</code>;
<span>SVG <code>svg</code></span>;
<code>template</code>;
<code>textarea</code>;
<code>time</code>;
<code>u</code>;
<code>var</code>;
<code>video</code>;
<code>wbr</code>;
<span data-x="autonomous custom element">autonomous custom elements</span>;
<span data-x="text content">Text</span>
<td>
<code>area</code> (if it is a descendant of a <code>map</code> element);
<code>link</code> (if it is <span>allowed in the body</span>);
<code>meta</code> (if the <code data-x="attr-itemprop">itemprop</code> attribute is present)
<tr>
<td> <span>Embedded content</span>
<td>
<code>audio</code>;
<code>canvas</code>;
<code>embed</code>;
<code>iframe</code>;
<code>img</code>;
<span>MathML <code>math</code></span>;
<code>object</code>;
<code>picture</code>;
<span>SVG <code>svg</code></span>;
<code>video</code>
<td>
—
<tr>
<td> <span>Interactive content</span>
<td>
<code>button</code>;
<code>details</code>;
<code>embed</code>;
<code>iframe</code>;
<code>label</code>;
<code>select</code>;
<code>textarea</code>
<td>
<code>a</code> (if the <code data-x="attr-hyperlink-href">href</code> attribute is present);
<code>audio</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present);
<code>img</code> (if the <code data-x="attr-hyperlink-usemap">usemap</code> attribute is present);
<code>input</code> (if the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state);
<code>video</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present)
<tr>
<td> <span data-x="form-associated element">Form-associated elements</span>
<td>
<code>button</code>;
<code>fieldset</code>;
<code>input</code>;
<code>label</code>;
<code>object</code>;
<code>output</code>;
<code>select</code>;
<code>textarea</code>;
<code>img</code>;
<span data-x="form-associated custom element">form-associated custom elements</span>
<td>
—
<tr>
<td> <span data-x="category-listed">Listed elements</span>
<td>
<code>button</code>;
<code>fieldset</code>;
<code>input</code>;
<code>object</code>;
<code>output</code>;
<code>select</code>;
<code>textarea</code>;
<span data-x="form-associated custom element">form-associated custom elements</span>
<td>
—
<tr>
<td> <span data-x="category-submit">Submittable elements</span>
<td>
<code>button</code>;
<code>input</code>;
<code>select</code>;
<code>textarea</code>;
<span data-x="form-associated custom element">form-associated custom elements</span>
<td>
—
<tr>
<td> <span data-x="category-reset">Resettable elements</span>
<td>
<code>input</code>;
<code>output</code>;
<code>select</code>;
<code>textarea</code>;
<span data-x="form-associated custom element">form-associated custom elements</span>
<td>
—
<tr>
<td> <span data-x="category-autocapitalize-and-autocorrect">Autocapitalize-and-autocorrect
inheriting elements</span>
<td>
<code>button</code>;
<code>fieldset</code>;
<code>input</code>;
<code>output</code>;
<code>select</code>;
<code>textarea</code>
<td>
—
<tr>
<td> <span data-x="category-label">Labelable elements</span>
<td>
<code>button</code>;
<code>input</code>;
<code>meter</code>;
<code>output</code>;
<code>progress</code>;
<code>select</code>;
<code>textarea</code>;
<span data-x="form-associated custom element">form-associated custom elements</span>
<td>
—
<tr>
<td> <span>Palpable content</span>
<td>
<code>a</code>;
<code>abbr</code>;
<code>address</code>;
<code>article</code>;
<code>aside</code>;
<code>b</code>;
<code>bdi</code>;
<code>bdo</code>;
<code>blockquote</code>;
<code>button</code>;
<code>canvas</code>;
<code>cite</code>;
<code>code</code>;
<code>data</code>;
<code>del</code>;
<code>details</code>;
<code>dfn</code>;
<code>div</code>;
<code>em</code>;
<code>embed</code>;
<code>fieldset</code>;
<code>figure</code>;
<code>footer</code>;
<code>form</code>;
<code>h1</code>;
<code>h2</code>;
<code>h3</code>;
<code>h4</code>;
<code>h5</code>;
<code>h6</code>;
<code>header</code>;
<code>hgroup</code>;
<code>i</code>;
<code>iframe</code>;
<code>img</code>;
<code>ins</code>;
<code>kbd</code>;
<code>label</code>;
<code>main</code>;
<code>map</code>;
<code>mark</code>;
<span>MathML <code>math</code></span>;
<code>meter</code>;
<code>nav</code>;
<code>object</code>;
<code>output</code>;
<code>p</code>;
<code>picture</code>;
<code>pre</code>;
<code>progress</code>;
<code>q</code>;
<code>ruby</code>;
<code>s</code>;
<code>samp</code>;
<code>search</code>;
<code>section</code>;
<code>select</code>;
<code>small</code>;
<code>span</code>;
<code>strong</code>;
<code>sub</code>;
<code>sup</code>;
<span>SVG <code>svg</code></span>;
<code>table</code>;
<code>textarea</code>;
<code>time</code>;
<code>u</code>;
<code>var</code>;
<code>video</code>;
<span data-x="autonomous custom element">autonomous custom elements</span>
<td>
<code>audio</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present);
<code>dl</code> (if the element's children include at least one name-value group);
<code>input</code> (if the <code data-x="attr-input-type">type</code> attribute is <em>not</em> in the <span data-x="attr-input-type-hidden">Hidden</span> state);
<code>menu</code> (if the element's children include at least one <code>li</code> element);
<code>ol</code> (if the element's children include at least one <code>li</code> element);
<code>ul</code> (if the element's children include at least one <code>li</code> element);
<span data-x="text content">Text</span> that is not <span>inter-element whitespace</span>
<tr>
<td> <span>Script-supporting elements</span>
<td>
<code>script</code>;
<code>template</code>
<td>
—
</table>
<h3 class="no-num">Attributes</h3>
<!-- NON-NORMATIVE SECTION -->
<table id="attributes-1">
<caption>List of attributes (excluding event handler content attributes)</caption>
<thead>
<tr>
<th> Attribute
<th> Element(s)
<th> Description
<th> Value
<tbody>
<tr>
<th> <code data-x="">abbr</code>
<td> <code data-x="attr-th-abbr">th</code>
<td> Alternative label to use for the header cell when referencing the cell in other contexts
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">accept</code>
<td> <code data-x="attr-input-accept">input</code>
<td> Hint for expected file type in <span data-x="attr-input-type-file">file upload controls</span>
<td> <span>Set of comma-separated tokens</span>* consisting of <span data-x="valid MIME type string with no parameters">valid MIME type strings with no parameters</span> or <code data-x="">audio/*</code>, <code data-x="">video/*</code>, or <code data-x="">image/*</code>
<tr>
<th> <code data-x="">accept-charset</code>
<td> <code data-x="attr-form-accept-charset">form</code>
<td> Character encodings to use for <span>form submission</span>
<td> <span>ASCII case-insensitive</span> match for "<code data-x="">UTF-8</code>"
<tr>
<th> <code data-x="">accesskey</code>
<td> <span data-x="attr-accesskey">HTML elements</span>
<td> Keyboard shortcut to activate or focus element
<td> <span>Ordered set of unique space-separated tokens</span>, none of which are <span>identical to</span> another, each consisting of one code point in length
<tr>
<th> <code data-x="">action</code>
<td> <code data-x="attr-fs-action">form</code>
<td> <span>URL</span> to use for <span>form submission</span>
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">allow</code>
<td> <code data-x="attr-iframe-allow">iframe</code>
<td> <span data-x="concept-permissions-policy">Permissions policy</span> to be applied to the <code>iframe</code>'s contents
<td> <span data-x="concept-serialized-permissions-policy">Serialized permissions policy</span>
<tr>
<th> <code data-x="">allowfullscreen</code>
<td> <code data-x="attr-iframe-allowfullscreen">iframe</code>
<td> Whether to allow the <code>iframe</code>'s contents to use <code data-x="dom-element-requestFullscreen">requestFullscreen()</code>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">alpha</code>
<td> <code data-x="attr-input-alpha">input</code>
<td> Allow the color's alpha component to be set
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">alt</code>
<td> <code data-x="attr-area-alt">area</code>;
<code data-x="attr-img-alt">img</code>;
<code data-x="attr-input-alt">input</code>
<td> Replacement text for use when images are not available
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">as</code>
<td> <code data-x="attr-link-as">link</code>
<td> <span data-x="concept-potential-destination">Potential destination</span> for a preload request (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>" and <code data-x="attr-link-rel">rel</code>="<code data-x="rel-modulepreload">modulepreload</code>")
<td> <span data-x="concept-potential-destination">Potential destination</span>, for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>"; <span data-x="concept-script-like-destination">script-like destination</span>, for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-modulepreload">modulepreload</code>"
<tr>
<th> <code data-x="">async</code>
<td> <code data-x="attr-script-async">script</code>
<td> Execute script when available, without blocking while fetching
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">autocapitalize</code>
<td> <span data-x="attr-autocapitalize">HTML elements</span>
<td> Recommended autocapitalization behavior (for supported input methods)
<td> "<code data-x="attr-autocapitalize-on">on</code>";
"<code data-x="attr-autocapitalize-off">off</code>";
"<code data-x="attr-autocapitalize-none">none</code>";
"<code data-x="attr-autocapitalize-sentences">sentences</code>";
"<code data-x="attr-autocapitalize-words">words</code>";
"<code data-x="attr-autocapitalize-characters">characters</code>"
<tr>
<th> <code data-x="">autocomplete</code>
<td> <code data-x="attr-form-autocomplete">form</code>
<td> Default setting for autofill feature for controls in the form
<td> "<code data-x="">on</code>"; "<code data-x="">off</code>"
<tr>
<th> <code data-x="">autocomplete</code>
<td> <code data-x="attr-fe-autocomplete">input</code>;
<code data-x="attr-fe-autocomplete">select</code>;
<code data-x="attr-fe-autocomplete">textarea</code>
<td> Hint for form autofill feature
<td> <span data-x="autofill field">Autofill field</span> name and related tokens*
<tr>
<th> <code data-x="">autocorrect</code>
<td> <span data-x="attr-autocorrect">HTML elements</span>
<td> Recommended autocorrection behavior (for supported input methods)
<td> "<code data-x="attr-autocorrect-on">on</code>";
"<code data-x="attr-autocorrect-off">off</code>"
<tr>
<th> <code data-x="">autofocus</code>
<td> <span data-x="attr-fe-autofocus">HTML elements</span>
<td> Automatically focus the element when the page is loaded
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">autoplay</code>
<td> <code data-x="attr-media-autoplay">audio</code>;
<code data-x="attr-media-autoplay">video</code>
<td> Hint that the <span>media resource</span> can be started automatically when the page is loaded
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">blocking</code>
<td> <code data-x="attr-link-blocking">link</code>;
<code data-x="attr-script-blocking">script</code>;
<code data-x="attr-style-blocking">style</code>
<td> Whether the element is <span>potentially render-blocking</span>
<td> <span>Unordered set of unique space-separated tokens</span>*
<tr>
<th> <code data-x="">charset</code>
<td> <code data-x="attr-meta-charset">meta</code>
<td> <span>Character encoding declaration</span>
<td> "<code data-x="">utf-8</code>"
<tr>
<th> <code data-x="">checked</code>
<td> <code data-x="attr-input-checked">input</code>
<td> Whether the control is checked
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">cite</code>
<td> <code data-x="attr-blockquote-cite">blockquote</code>;
<code data-x="attr-mod-cite">del</code>;
<code data-x="attr-mod-cite">ins</code>;
<code data-x="attr-q-cite">q</code>
<td> Link to the source of the quotation or more information about the edit
<td> <span>Valid URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">class</code>
<td> <span data-x="attr-class">HTML elements</span>
<td> Classes to which the element belongs
<td> <span>Set of space-separated tokens</span>
<tr>
<th> <code data-x="">closedby</code>
<td> <code data-x="attr-dialog-closedby">dialog</code>
<td> Which user actions will close the dialog
<td> "<code data-x="attr-dialog-closedby-any">any</code>";
"<code data-x="attr-dialog-closedby-closerequest">closerequest</code>";
"<code data-x="attr-dialog-closedby-none">none</code>";
<tr>
<th> <code data-x="">color</code>
<td> <code data-x="attr-link-color">link</code>
<td> Color to use when customizing a site's icon (for <code data-x="attr-link-rel">rel</code>="<code data-x="">mask-icon</code>")
<td> CSS <span><color></span>
<tr>
<th> <code data-x="">colorspace</code>
<td> <code data-x="attr-input-colorspace">input</code>
<td> The color space of the serialized color
<td> "<code data-x="attr-input-colorspace-limited-srgb">limited-srgb</code>";
"<code data-x="attr-input-colorspace-display-p3">display-p3</code>"
<tr>
<th> <code data-x="">cols</code>
<td> <code data-x="attr-textarea-cols">textarea</code>
<td> Maximum number of characters per line
<td> <span>Valid non-negative integer</span> greater than zero
<tr>
<th> <code data-x="">colspan</code>
<td> <code data-x="attr-tdth-colspan">td</code>;
<code data-x="attr-tdth-colspan">th</code>
<td> Number of columns that the cell is to span
<td> <span>Valid non-negative integer</span> greater than zero
<tr>
<th> <code data-x="">command</code>
<td> <code data-x="attr-button-command">button</code>
<td> Indicates to the targeted element which action to take.
<td> "<code data-x="attr-button-command-toggle-popover">toggle-popover</code>";
"<code data-x="attr-button-command-show-popover">show-popover</code>";
"<code data-x="attr-button-command-hide-popover">hide-popover</code>";
"<code data-x="attr-button-command-close">close</code>";
"<code data-x="attr-button-command-show-modal">show-modal</code>";
a <span data-x="attr-button-command-custom">custom command keyword</span>
<tr>
<th> <code data-x="">commandfor</code>
<td> <code data-x="attr-button-commandfor">button</code>
<td> Targets another element to be invoked.
<td> <span data-x="concept-id">ID</span>*
<tr>
<th> <code data-x="">content</code>
<td> <code data-x="attr-meta-content">meta</code>
<td> Value of the element
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">contenteditable</code>
<td> <span data-x="attr-contenteditable">HTML elements</span>
<td> Whether the element is editable
<td> "<code data-x="">true</code>"; "<code data-x="">plaintext-only</code>";
"<code data-x="">false</code>"
<tr>
<th> <code data-x="">controls</code>
<td> <code data-x="attr-media-controls">audio</code>;
<code data-x="attr-media-controls">video</code>
<td> Show user agent controls
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">coords</code>
<td> <code data-x="attr-area-coords">area</code>
<td> Coordinates for the shape to be created in an <span>image map</span>
<td> <span>Valid list of floating-point numbers</span>*
<tr>
<th> <code data-x="">crossorigin</code>
<td> <code data-x="attr-media-crossorigin">audio</code>;
<code data-x="attr-img-crossorigin">img</code>;
<code data-x="attr-link-crossorigin">link</code>;
<code data-x="attr-script-crossorigin">script</code>;
<code data-x="attr-media-crossorigin">video</code>
<td> How the element handles crossorigin requests
<td> "<code data-x="attr-crossorigin-anonymous-keyword">anonymous</code>"; "<code data-x="attr-crossorigin-use-credentials-keyword">use-credentials</code>"
<tr>
<th> <code data-x="">data</code>
<td> <code data-x="attr-object-data">object</code>
<td> Address of the resource
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">datetime</code>
<td> <code data-x="attr-mod-datetime">del</code>;
<code data-x="attr-mod-datetime">ins</code>
<td> Date and (optionally) time of the change
<td> <span>Valid date string with optional time</span>
<tr>
<th> <code data-x="">datetime</code>
<td> <code data-x="attr-time-datetime">time</code>
<td> Machine-readable value
<td> <span>Valid month string</span>,
<span>valid date string</span>,
<span>valid yearless date string</span>,
<span>valid time string</span>,
<span>valid local date and time string</span>,
<span>valid time-zone offset string</span>,
<span>valid global date and time string</span>,
<span>valid week string</span>,
<span>valid non-negative integer</span>, or
<span>valid duration string</span>
<tr>
<th> <code data-x="">decoding</code>
<td> <code data-x="attr-img-decoding">img</code>
<td> Decoding hint to use when processing this image for presentation
<td> "<code data-x="attr-img-decoding-sync">sync</code>";
"<code data-x="attr-img-decoding-async">async</code>";
"<code data-x="attr-img-decoding-auto">auto</code>"
<tr>
<th> <code data-x="">default</code>
<td> <code data-x="attr-track-default">track</code>
<td> Enable the track if no other <span>text track</span> is more suitable
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">defer</code>
<td> <code data-x="attr-script-defer">script</code>
<td> Defer script execution
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">dir</code>
<td> <span data-x="attr-dir">HTML elements</span>
<td> <span data-x="the directionality">The text directionality</span> of the element
<td> "<code data-x="attr-dir-ltr">ltr</code>"; "<code data-x="attr-dir-rtl">rtl</code>"; "<code data-x="attr-dir-auto">auto</code>"
<tr>
<th> <code data-x="">dir</code>
<td> <code>bdo</code>
<td> <span data-x="the directionality">The text directionality</span> of the element
<td> "<code data-x="attr-dir-ltr">ltr</code>"; "<code data-x="attr-dir-rtl">rtl</code>"
<tr>
<th> <code data-x="">dirname</code>
<td> <code data-x="attr-fe-dirname">input</code>;
<code data-x="attr-fe-dirname">textarea</code>
<td> Name of form control to use for sending the element's <span data-x="the directionality">directionality</span> in <span>form submission</span>
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">disabled</code>
<td> <code data-x="attr-fe-disabled">button</code>;
<code data-x="attr-fe-disabled">input</code>;
<code data-x="attr-optgroup-disabled">optgroup</code>;
<code data-x="attr-option-disabled">option</code>;
<code data-x="attr-fe-disabled">select</code>;
<code data-x="attr-fe-disabled">textarea</code>;
<span data-x="attr-fe-disabled">form-associated custom elements</span>
<td> Whether the form control is disabled
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">disabled</code>
<td> <code data-x="attr-fieldset-disabled">fieldset</code>
<td> Whether the descendant form controls, except any inside <code>legend</code>, are disabled
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">disabled</code>
<td> <code data-x="attr-link-disabled">link</code>
<td> Whether the link is disabled
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">download</code>
<td> <code data-x="attr-hyperlink-download">a</code>;
<code data-x="attr-hyperlink-download">area</code>
<td> Whether to download the resource instead of navigating to it, and its filename if so
<td> Text
<tr>
<th> <code data-x="">draggable</code>
<td> <span data-x="attr-draggable">HTML elements</span>
<td> Whether the element is draggable
<td> "<code data-x="">true</code>"; "<code data-x="">false</code>"
<tr>
<th> <code data-x="">enctype</code>
<td> <code data-x="attr-fs-enctype">form</code>
<td> <span>Entry list</span> encoding type to use for <span>form submission</span>
<td> "<code data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code>"; "<code data-x="attr-fs-enctype-formdata">multipart/form-data</code>"; "<code data-x="attr-fs-enctype-text">text/plain</code>"
<tr>
<th> <code data-x="">enterkeyhint</code>
<td> <span data-x="attr-enterkeyhint">HTML elements</span>
<td> Hint for selecting an enter key action
<td> "<code data-x="attr-enterkeyhint-keyword-enter">enter</code>";
"<code data-x="attr-enterkeyhint-keyword-done">done</code>";
"<code data-x="attr-enterkeyhint-keyword-go">go</code>";
"<code data-x="attr-enterkeyhint-keyword-next">next</code>";
"<code data-x="attr-enterkeyhint-keyword-previous">previous</code>";
"<code data-x="attr-enterkeyhint-keyword-search">search</code>";
"<code data-x="attr-enterkeyhint-keyword-send">send</code>"
<tr>
<th> <code data-x="">fetchpriority</code>
<td> <code data-x="attr-img-fetchpriority">img</code>;
<code data-x="attr-link-fetchpriority">link</code>;
<code data-x="attr-script-fetchpriority">script</code>
<td> Sets the <span data-x="concept-request-priority">priority</span> for <span data-x="concept-fetch">fetches</span> initiated by the element
<td> "<code data-x="attr-fetchpriority-auto">auto</code>";
"<code data-x="attr-fetchpriority-high">high</code>";
"<code data-x="attr-fetchpriority-low">low</code>"
<tr>
<th> <code data-x="">for</code>
<td> <code data-x="attr-label-for">label</code>
<td> Associate the label with form control
<td> <span data-x="concept-id">ID</span>*
<tr>
<th> <code data-x="">for</code>
<td> <code data-x="attr-output-for">output</code>
<td> Specifies controls from which the output was calculated
<td> <span>Unordered set of unique space-separated tokens</span> consisting of IDs*
<tr>
<th> <code data-x="">form</code>
<td> <code data-x="attr-fae-form">button</code>;
<code data-x="attr-fae-form">fieldset</code>;
<code data-x="attr-fae-form">input</code>;
<code data-x="attr-fae-form">object</code>;
<code data-x="attr-fae-form">output</code>;
<code data-x="attr-fae-form">select</code>;
<code data-x="attr-fae-form">textarea</code>;
<span data-x="attr-fae-form">form-associated custom elements</span>
<td> Associates the element with a <code>form</code> element
<td> <span data-x="concept-id">ID</span>*
<tr>
<th> <code data-x="">formaction</code>
<td> <code data-x="attr-fs-formaction">button</code>;
<code data-x="attr-fs-formaction">input</code>
<td> <span>URL</span> to use for <span>form submission</span>
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">formenctype</code>
<td> <code data-x="attr-fs-formenctype">button</code>;
<code data-x="attr-fs-formenctype">input</code>
<td> <span>Entry list</span> encoding type to use for <span>form submission</span>
<td> "<code data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code>"; "<code data-x="attr-fs-enctype-formdata">multipart/form-data</code>"; "<code data-x="attr-fs-enctype-text">text/plain</code>"
<tr>
<th> <code data-x="">formmethod</code>
<td> <code data-x="attr-fs-formmethod">button</code>;
<code data-x="attr-fs-formmethod">input</code>
<td> Variant to use for <span>form submission</span>
<td> "<code data-x="">GET</code>";
"<code data-x="">POST</code>";
"<code data-x="">dialog</code>"
<tr>
<th> <code data-x="">formnovalidate</code>
<td> <code data-x="attr-fs-formnovalidate">button</code>;
<code data-x="attr-fs-formnovalidate">input</code>
<td> Bypass form control validation for <span>form submission</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">formtarget</code>
<td> <code data-x="attr-fs-formtarget">button</code>;
<code data-x="attr-fs-formtarget">input</code>
<td> <span>Navigable</span> for <span>form submission</span>
<td> <span>Valid navigable target name or keyword</span>
<tr>
<th> <code data-x="">headers</code>
<td> <code data-x="attr-tdth-headers">td</code>;
<code data-x="attr-tdth-headers">th</code>
<td> The header cells for this cell
<td> <span>Unordered set of unique space-separated tokens</span> consisting of IDs*
<tr>
<th> <code data-x="">height</code>
<td> <code data-x="attr-canvas-height">canvas</code>;
<code data-x="attr-dim-height">embed</code>;
<code data-x="attr-dim-height">iframe</code>;
<code data-x="attr-dim-height">img</code>;
<code data-x="attr-dim-height">input</code>;
<code data-x="attr-dim-height">object</code>;
<code data-x="attr-dim-height">source</code> (in <code>picture</code>);
<code data-x="attr-dim-height">video</code>
<td> Vertical dimension
<td> <span>Valid non-negative integer</span>
<tr>
<th> <code data-x="">hidden</code>
<td> <span data-x="attr-hidden">HTML elements</span>
<td> Whether the element is relevant
<td> "<code data-x="attr-hidden-until-found">until-found</code>";
"<code data-x="attr-hidden">hidden</code>";
the empty string
<tr>
<th> <code data-x="">high</code>
<td> <code data-x="attr-meter-high">meter</code>
<td> Low limit of high range
<td> <span>Valid floating-point number</span>*
<tr>
<th> <code data-x="">href</code>
<td> <code data-x="attr-hyperlink-href">a</code>;
<code data-x="attr-hyperlink-href">area</code>
<td> Address of the <span>hyperlink</span>
<td> <span>Valid URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">href</code>
<td> <code data-x="attr-link-href">link</code>
<td> Address of the <span>hyperlink</span>
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">href</code>
<td> <code data-x="attr-base-href">base</code>
<td> <span>Document base URL</span>
<td> <span>Valid URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">hreflang</code>
<td> <code data-x="attr-hyperlink-hreflang">a</code>;
<code data-x="attr-link-hreflang">link</code>
<td> Language of the linked resource
<td> Valid BCP 47 language tag
<tr>
<th> <code data-x="">http-equiv</code>
<td> <code data-x="attr-meta-http-equiv">meta</code>
<td> Pragma directive
<td> "<code data-x="attr-meta-http-equiv-keyword-content-type">content-type</code>";
"<code data-x="attr-meta-http-equiv-keyword-default-style">default-style</code>";
"<code data-x="attr-meta-http-equiv-keyword-refresh">refresh</code>";
"<code data-x="attr-meta-http-equiv-keyword-x-ua-compatible">x-ua-compatible</code>";
"<code data-x="attr-meta-http-equiv-keyword-content-security-policy">content-security-policy</code>"
<tr>
<th> <code data-x="">id</code>
<td> <span data-x="attr-id">HTML elements</span>
<td> The element's <span data-x="concept-id">ID</span>
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">imagesizes</code>
<td> <code data-x="attr-link-imagesizes">link</code>
<td> Image sizes for different page layouts (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>")
<td> <span>Valid source size list</span>
<tr>
<th> <code data-x="">imagesrcset</code>
<td> <code data-x="attr-link-imagesrcset">link</code>
<td> Images to use in different situations, e.g., high-resolution displays, small monitors, etc. (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-preload">preload</code>")
<td> Comma-separated list of <span data-x="image candidate string">image candidate strings</span>
<tr>
<th> <code data-x="">inert</code>
<td> <span data-x="attr-inert">HTML elements</span>
<td> Whether the element is <span>inert</span>.
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">inputmode</code>
<td> <span data-x="attr-inputmode">HTML elements</span>
<td> Hint for selecting an input modality
<td> "<code data-x="attr-inputmode-keyword-none">none</code>";
"<code data-x="attr-inputmode-keyword-text">text</code>";
"<code data-x="attr-inputmode-keyword-tel">tel</code>";
"<code data-x="attr-inputmode-keyword-email">email</code>";
"<code data-x="attr-inputmode-keyword-url">url</code>";
"<code data-x="attr-inputmode-keyword-numeric">numeric</code>";
"<code data-x="attr-inputmode-keyword-decimal">decimal</code>";
"<code data-x="attr-inputmode-keyword-search">search</code>"
<tr>
<th> <code data-x="">integrity</code>
<td> <code data-x="attr-link-integrity">link</code>;
<code data-x="attr-script-integrity">script</code>
<td> Integrity metadata used in <cite>Subresource Integrity</cite> checks <ref>SRI</ref>
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">is</code>
<td> <span data-x="attr-is">HTML elements</span>
<td> Creates a <span>customized built-in element</span>
<td> <span>Valid custom element name</span> of a defined <span>customized built-in element</span>
<tr>
<th> <code data-x="">ismap</code>
<td> <code data-x="attr-img-ismap">img</code>
<td> Whether the image is a server-side image map
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">itemid</code>
<td> <span data-x="attr-itemid">HTML elements</span>
<td> <span>Global identifier</span> for a microdata item
<td> <span>Valid URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">itemprop</code>
<td> <span data-x="attr-itemprop">HTML elements</span>
<td> <span>Property names</span> of a microdata item
<td> <span>Unordered set of unique space-separated tokens</span> consisting of <span data-x="absolute URL">valid absolute URLs</span>, <span data-x="defined property name">defined property names</span>, or text*
<tr>
<th> <code data-x="">itemref</code>
<td> <span data-x="attr-itemref">HTML elements</span>
<td> <span data-x="referenced">Referenced</span> elements
<td> <span>Unordered set of unique space-separated tokens</span> consisting of IDs*
<tr>
<th> <code data-x="">itemscope</code>
<td> <span data-x="attr-itemscope">HTML elements</span>
<td> Introduces a microdata item
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">itemtype</code>
<td> <span data-x="attr-itemtype">HTML elements</span>
<td> <span>Item types</span> of a microdata item
<td> <span>Unordered set of unique space-separated tokens</span> consisting of <span data-x="absolute URL">valid absolute URLs</span>*
<tr>
<th> <code data-x="">kind</code>
<td> <code data-x="attr-track-kind">track</code>
<td> The type of text track
<td> "<code data-x="attr-track-kind-keyword-subtitles">subtitles</code>";
"<code data-x="attr-track-kind-keyword-captions">captions</code>";
"<code data-x="attr-track-kind-keyword-descriptions">descriptions</code>";
"<code data-x="attr-track-kind-keyword-chapters">chapters</code>";
"<code data-x="attr-track-kind-keyword-metadata">metadata</code>"
<tr>
<th> <code data-x="">label</code>
<td> <code data-x="attr-optgroup-label">optgroup</code>;
<code data-x="attr-option-label">option</code>;
<code data-x="attr-track-label">track</code>
<td> User-visible label
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">lang</code>
<td> <span data-x="attr-lang">HTML elements</span>
<td> <span>Language</span> of the element
<td> Valid BCP 47 language tag or the empty string
<tr>
<th> <code data-x="">list</code>
<td> <code data-x="attr-input-list">input</code>
<td> List of autocomplete options
<td> <span data-x="concept-id">ID</span>*
<tr>
<th> <code data-x="">loading</code>
<td> <code data-x="attr-iframe-loading">iframe</code>;
<code data-x="attr-img-loading">img</code>
<td> Used when determining loading deferral
<td> "<code data-x="attr-loading-lazy">lazy</code>";
"<code data-x="attr-loading-eager">eager</code>"
<tr>
<th> <code data-x="">loop</code>
<td> <code data-x="attr-media-loop">audio</code>;
<code data-x="attr-media-loop">video</code>
<td> Whether to loop the <span>media resource</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">low</code>
<td> <code data-x="attr-meter-low">meter</code>
<td> High limit of low range
<td> <span>Valid floating-point number</span>*
<tr>
<th> <code data-x="">max</code>
<td> <code data-x="attr-input-max">input</code>
<td> Maximum value
<td> Varies*
<tr>
<th> <code data-x="">max</code>
<td> <code data-x="attr-meter-max">meter</code>;
<code data-x="attr-progress-max">progress</code>
<td> Upper bound of range
<td> <span>Valid floating-point number</span>*
<tr>
<th> <code data-x="">maxlength</code>
<td> <code data-x="attr-input-maxlength">input</code>;
<code data-x="attr-textarea-maxlength">textarea</code>
<td> Maximum <span>length</span> of value
<td> <span>Valid non-negative integer</span>
<tr>
<th> <code data-x="">media</code>
<td> <code data-x="attr-link-media">link</code>;
<code data-x="attr-meta-media">meta</code>;
<code data-x="attr-source-media">source</code>;
<code data-x="attr-style-media">style</code>
<td> Applicable media
<td> <span>Valid media query list</span>
<tr>
<th> <code data-x="">method</code>
<td> <code data-x="attr-fs-method">form</code>
<td> Variant to use for <span>form submission</span>
<td> "<code data-x="attr-fs-method-GET-keyword">GET</code>";
"<code data-x="attr-fs-method-POST-keyword">POST</code>";
"<code data-x="attr-fs-method-dialog-keyword">dialog</code>"
<tr>
<th> <code data-x="">min</code>
<td> <code data-x="attr-input-min">input</code>
<td> Minimum value
<td> Varies*
<tr>
<th> <code data-x="">min</code>
<td> <code data-x="attr-meter-min">meter</code>
<td> Lower bound of range
<td> <span>Valid floating-point number</span>*
<tr>
<th> <code data-x="">minlength</code>
<td> <code data-x="attr-input-minlength">input</code>;
<code data-x="attr-textarea-minlength">textarea</code>
<td> Minimum <span>length</span> of value
<td> <span>Valid non-negative integer</span>
<tr>
<th> <code data-x="">multiple</code>
<td> <code data-x="attr-input-multiple">input</code>;
<code data-x="attr-select-multiple">select</code>
<td> Whether to allow multiple values
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">muted</code>
<td> <code data-x="attr-media-muted">audio</code>;
<code data-x="attr-media-muted">video</code>
<td> Whether to mute the <span>media resource</span> by default
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-fe-name">button</code>;
<code data-x="attr-fe-name">fieldset</code>;
<code data-x="attr-fe-name">input</code>;
<code data-x="attr-fe-name">output</code>;
<code data-x="attr-fe-name">select</code>;
<code data-x="attr-fe-name">textarea</code>;
<span data-x="attr-fe-name">form-associated custom elements</span>
<td> Name of the element to use for <span>form submission</span> and in the <code data-x="dom-form-elements">form.elements</code> API <!--or: Name of the element to use in the <code data-x="dom-form-elements">form.elements</code> API. -->
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-details-name">details</code>
<td> Name of group of mutually-exclusive <code>details</code> elements
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-form-name">form</code>
<td> Name of form to use in the <code data-x="dom-document-forms">document.forms</code> API
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-iframe-name">iframe</code>;
<code data-x="attr-object-name">object</code>
<td> Name of <span>content navigable</span>
<td> <span>Valid navigable target name or keyword</span>
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-map-name">map</code>
<td> Name of <span>image map</span> to <span data-x="referenced">reference</span> from the <code data-x="attr-hyperlink-usemap">usemap</code> attribute
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-meta-name">meta</code>
<td> Metadata name
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-slot-name">slot</code>
<td> Name of shadow tree slot
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">nomodule</code>
<td> <code data-x="attr-script-nomodule">script</code>
<td> Prevents execution in user agents that support <span data-x="module script">module scripts</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">nonce</code>
<td> <span data-x="attr-nonce">HTML elements</span>
<td> Cryptographic nonce used in <cite>Content Security Policy</cite> checks <ref>CSP</ref>
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">novalidate</code>
<td> <code data-x="attr-fs-novalidate">form</code>
<td> Bypass form control validation for <span>form submission</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">open</code>
<td> <code data-x="attr-details-open">details</code>
<td> Whether the details are visible
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">open</code>
<td> <code data-x="attr-dialog-open">dialog</code>
<td> Whether the dialog box is showing
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">optimum</code>
<td> <code data-x="attr-meter-optimum">meter</code>
<td> Optimum value in gauge
<td> <span>Valid floating-point number</span>*
<tr>
<th> <code data-x="">pattern</code>
<td> <code data-x="attr-input-pattern">input</code>
<td> Pattern to be matched by the form control's value
<td> Regular expression matching the JavaScript <i data-x="js-prod-Pattern">Pattern</i> production
<tr>
<th> <code data-x="">ping</code>
<td> <code data-x="attr-hyperlink-ping">a</code>;
<code data-x="attr-hyperlink-ping">area</code>
<td> <span data-x="URL">URLs</span> to ping
<td> <span>Set of space-separated tokens</span> consisting of <span data-x="valid non-empty URL">valid non-empty URLs</span>
<tr>
<th> <code data-x="">placeholder</code>
<td> <code data-x="attr-input-placeholder">input</code>;
<code data-x="attr-textarea-placeholder">textarea</code>
<td> User-visible label to be placed within the form control
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">playsinline</code>
<td> <code data-x="attr-video-playsinline">video</code>
<td> Encourage the user agent to display video content within the element's playback area
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">popover</code>
<td> <span data-x="attr-popover">HTML elements</span>
<td> Makes the element a <span data-x="attr-popover">popover</span> element
<td> "<code data-x="attr-popover-auto">auto</code>";
"<code data-x="attr-popover-manual">manual</code>";
<tr>
<th> <code data-x="">popovertarget</code>
<td> <code data-x="attr-popovertarget">button</code>;
<code data-x="attr-popovertarget">input</code>
<td> Targets a popover element to toggle, show, or hide
<td> <span data-x="concept-id">ID</span>*
<tr>
<th> <code data-x="">popovertargetaction</code>
<td> <code data-x="attr-popovertargetaction">button</code>;
<code data-x="attr-popovertargetaction">input</code>
<td> Indicates whether a targeted popover element is to be toggled, shown, or hidden
<td> "<code data-x="attr-popovertargetaction-toggle">toggle</code>";
"<code data-x="attr-popovertargetaction-show">show</code>";
"<code data-x="attr-popovertargetaction-hide">hide</code>"
<tr>
<th> <code data-x="">poster</code>
<td> <code data-x="attr-video-poster">video</code>
<td> Poster frame to show prior to video playback
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">preload</code>
<td> <code data-x="attr-media-preload">audio</code>;
<code data-x="attr-media-preload">video</code>
<td> Hints how much buffering the <span>media resource</span> will likely need
<td> "<code data-x="attr-media-preload-none">none</code>";
"<code data-x="attr-media-preload-metadata">metadata</code>";
"<code data-x="attr-media-preload-auto">auto</code>"
<tr>
<th> <code data-x="">readonly</code>
<td> <code data-x="attr-input-readonly">input</code>;
<code data-x="attr-textarea-readonly">textarea</code>
<td> Whether to allow the value to be edited by the user
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">readonly</code>
<td> <span data-x="attr-face-readonly">form-associated custom elements</span>
<td> Affects <code data-x="dom-ElementInternals-willValidate">willValidate</code>, plus any behavior added by the custom element author
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">referrerpolicy</code>
<td> <code data-x="attr-hyperlink-referrerpolicy">a</code>;
<code data-x="attr-hyperlink-referrerpolicy">area</code>;
<code data-x="attr-iframe-referrerpolicy">iframe</code>;
<code data-x="attr-img-referrerpolicy">img</code>;
<code data-x="attr-link-referrerpolicy">link</code>;
<code data-x="attr-script-referrerpolicy">script</code>
<td> <span>Referrer policy</span> for <span data-x="concept-fetch">fetches</span> initiated by the element
<td> <span>Referrer policy</span>
<tr>
<th> <code data-x="">rel</code>
<td> <code data-x="attr-hyperlink-rel">a</code>;
<code data-x="attr-hyperlink-rel">area</code>
<td> Relationship between the location in the document containing the <span>hyperlink</span> and the destination resource
<td> <span>Unordered set of unique space-separated tokens</span>*
<tr>
<th> <code data-x="">rel</code>
<td> <code data-x="attr-link-rel">link</code>
<td> Relationship between the document containing the <span>hyperlink</span> and the destination resource
<td> <span>Unordered set of unique space-separated tokens</span>*
<tr>
<th> <code data-x="">required</code>
<td> <code data-x="attr-input-required">input</code>;
<code data-x="attr-select-required">select</code>;
<code data-x="attr-textarea-required">textarea</code>
<td> Whether the control is required for <span>form submission</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">reversed</code>
<td> <code data-x="attr-ol-reversed">ol</code>
<td> Number the list backwards
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">rows</code>
<td> <code data-x="attr-textarea-rows">textarea</code>
<td> Number of lines to show
<td> <span>Valid non-negative integer</span> greater than zero
<tr>
<th> <code data-x="">rowspan</code>
<td> <code data-x="attr-tdth-rowspan">td</code>;
<code data-x="attr-tdth-rowspan">th</code>
<td> Number of rows that the cell is to span
<td> <span>Valid non-negative integer</span>
<tr>
<th> <code data-x="">sandbox</code>
<td> <code data-x="attr-iframe-sandbox">iframe</code>
<td> Security rules for nested content
<td> <span>Unordered set of unique space-separated tokens</span>, <span>ASCII case-insensitive</span>, consisting of
<ul class="brief">
<li>"<code data-x="attr-iframe-sandbox-allow-downloads">allow-downloads</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-forms">allow-forms</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-modals">allow-modals</code>"</li>
<li>"<code
data-x="attr-iframe-sandbox-allow-orientation-lock">allow-orientation-lock</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-pointer-lock">allow-pointer-lock</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-popups">allow-popups</code>"</li>
<li>"<code
data-x="attr-iframe-sandbox-allow-popups-to-escape-sandbox">allow-popups-to-escape-sandbox</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-presentation">allow-presentation</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-same-origin">allow-same-origin</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-scripts">allow-scripts</code>"</li>
<li>"<code data-x="attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</code>"</li>
<li>"<code
data-x="attr-iframe-sandbox-allow-top-navigation-by-user-activation">allow-top-navigation-by-user-activation</code>"</li>
<li>"<code
data-x="attr-iframe-sandbox-allow-top-navigation-to-custom-protocols">allow-top-navigation-to-custom-protocols</code>"</li>
</ul>
<tr>
<th> <code data-x="">scope</code>
<td> <code data-x="attr-th-scope">th</code>
<td> Specifies which cells the header cell applies to
<td> "<code data-x="attr-th-scope-row">row</code>";
"<code data-x="attr-th-scope-col">col</code>";
"<code data-x="attr-th-scope-rowgroup">rowgroup</code>";
"<code data-x="attr-th-scope-colgroup">colgroup</code>"
<tr>
<th> <code data-x="">selected</code>
<td> <code data-x="attr-option-selected">option</code>
<td> Whether the option is selected by default
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">shadowrootclonable</code>
<td> <code data-x="attr-template-shadowrootclonable">template</code>
<td> Sets <span>clonable</span> on a declarative shadow root
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">shadowrootdelegatesfocus</code>
<td> <code data-x="attr-template-shadowrootdelegatesfocus">template</code>
<td> Sets <span>delegates focus</span> on a declarative shadow root
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">shadowrootmode</code>
<td> <code data-x="attr-template-shadowrootmode">template</code>
<td> Enables streaming declarative shadow roots
<td> "<code data-x="">open</code>";
"<code data-x="">closed</code>"
<tr>
<th> <code data-x="">shadowrootserializable</code>
<td> <code data-x="attr-template-shadowrootserializable">template</code>
<td> Sets <span>serializable</span> on a declarative shadow root
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">shape</code>
<td> <code data-x="attr-area-shape">area</code>
<td> The kind of shape to be created in an <span>image map</span>
<td> "<code data-x="attr-area-shape-keyword-circle">circle</code>";
"<code data-x="attr-area-shape-keyword-default">default</code>";
"<code data-x="attr-area-shape-keyword-poly">poly</code>";
"<code data-x="attr-area-shape-keyword-rect">rect</code>"
<tr>
<th> <code data-x="">size</code>
<td> <code data-x="attr-input-size">input</code>;
<code data-x="attr-select-size">select</code>
<td> Size of the control
<td> <span>Valid non-negative integer</span> greater than zero
<tr>
<th> <code data-x="">sizes</code>
<td> <code data-x="attr-link-sizes">link</code>
<td> Sizes of the icons (for <code data-x="attr-link-rel">rel</code>="<code data-x="rel-icon">icon</code>")
<td> <span>Unordered set of unique space-separated tokens</span>, <span>ASCII case-insensitive</span>, consisting of sizes*
<tr>
<th> <code data-x="">sizes</code>
<td> <code data-x="attr-img-sizes">img</code>;
<code data-x="attr-source-sizes">source</code>
<td> Image sizes for different page layouts
<td> <span>Valid source size list</span>
<tr>
<th> <code data-x="">slot</code>
<td> <span data-x="attr-id">HTML elements</span>
<td> The element's desired slot
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">span</code>
<td> <code data-x="attr-col-span">col</code>;
<code data-x="attr-colgroup-span">colgroup</code>
<td> Number of columns spanned by the element
<td> <span>Valid non-negative integer</span> greater than zero
<tr>
<th> <code data-x="">spellcheck</code>
<td> <span data-x="attr-spellcheck">HTML elements</span>
<td> Whether the element is to have its spelling and grammar checked
<td> "<code data-x="attr-spellcheck-true">true</code>";
"<code data-x="attr-spellcheck-false">false</code>";
the empty string
<tr>
<th> <code data-x="">src</code>
<td> <code data-x="attr-media-src">audio</code>;
<code data-x="attr-embed-src">embed</code>;
<code data-x="attr-iframe-src">iframe</code>;
<code data-x="attr-img-src">img</code>;
<code data-x="attr-input-src">input</code>;
<code data-x="attr-script-src">script</code>;
<code data-x="attr-source-src">source</code> (in <code>video</code> or <code>audio</code>);
<code data-x="attr-track-src">track</code>;
<code data-x="attr-media-src">video</code>
<td> Address of the resource
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<tr>
<th> <code data-x="">srcdoc</code>
<td> <code data-x="attr-iframe-srcdoc">iframe</code>
<td> A document to render in the <code>iframe</code>
<td> The source of <span>an <code>iframe</code> <code data-x="attr-iframe-srcdoc">srcdoc</code> document</span>*
<tr>
<th> <code data-x="">srclang</code>
<td> <code data-x="attr-track-srclang">track</code>
<td> Language of the text track
<td> Valid BCP 47 language tag
<tr>
<th> <code data-x="">srcset</code>
<td> <code data-x="attr-img-srcset">img</code>;
<code data-x="attr-source-srcset">source</code>
<td> Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
<td> Comma-separated list of <span data-x="image candidate string">image candidate strings</span>
<tr>
<th> <code data-x="">start</code>
<td> <code data-x="attr-ol-start">ol</code>
<td> <span data-x="concept-ol-start">Starting value</span> of the list
<td> <span>Valid integer</span>
<tr>
<th> <code data-x="">step</code>
<td> <code data-x="attr-input-step">input</code>
<td> Granularity to be matched by the form control's value
<td> <span>Valid floating-point number</span> greater than zero, or "<code data-x="">any</code>"
<tr>
<th> <code data-x="">style</code>
<td> <span data-x="attr-style">HTML elements</span>
<td> Presentational and formatting instructions
<td> CSS declarations*
<tr>
<th> <code data-x="">tabindex</code>
<td> <span data-x="attr-tabindex">HTML elements</span>
<td> Whether the element is <span>focusable</span> and <span>sequentially focusable</span>, and
the relative order of the element for the purposes of <span>sequential focus navigation</span>
<td> <span>Valid integer</span>
<tr>
<th> <code data-x="">target</code>
<td> <code data-x="attr-hyperlink-target">a</code>;
<code data-x="attr-hyperlink-target">area</code>
<td> <span>Navigable</span> for <span>hyperlink</span> <span data-x="navigate">navigation</span>
<td> <span>Valid navigable target name or keyword</span>
<tr>
<th> <code data-x="">target</code>
<td> <code data-x="attr-base-target">base</code>
<td> Default <span>navigable</span> for <span>hyperlink</span> <span data-x="navigate">navigation</span> and <span>form submission</span>
<td> <span>Valid navigable target name or keyword</span>
<tr>
<th> <code data-x="">target</code>
<td> <code data-x="attr-fs-target">form</code>
<td> <span>Navigable</span> for <span>form submission</span>
<td> <span>Valid navigable target name or keyword</span>
<tr>
<th> <code data-x="">title</code>
<td> <span data-x="attr-title">HTML elements</span>
<td> Advisory information for the element
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">title</code>
<td> <code data-x="attr-abbr-title">abbr</code>;
<code data-x="attr-dfn-title">dfn</code>
<td> Full term or expansion of abbreviation
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">title</code>
<td> <code data-x="attr-input-title">input</code>
<td> Description of pattern (when used with <code data-x="attr-input-pattern">pattern</code> attribute)
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">title</code>
<td> <code data-x="attr-link-title">link</code>
<td> Title of the link
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">title</code>
<td> <code data-x="attr-link-title">link</code>;
<code data-x="attr-style-title">style</code>
<td> <span>CSS style sheet set name</span>
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">translate</code>
<td> <span data-x="attr-translate">HTML elements</span>
<td> Whether the element is to be translated when the page is localized
<td> "<code data-x="">yes</code>"; "<code data-x="">no</code>"
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-hyperlink-type">a</code>;
<code data-x="attr-link-type">link</code>
<td> Hint for the type of the referenced resource
<td> <span>Valid MIME type string</span>
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-button-type">button</code>
<td> Type of button
<td> "<code data-x="attr-button-type-submit">submit</code>";
"<code data-x="attr-button-type-reset">reset</code>";
"<code data-x="attr-button-type-button">button</code>"
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-embed-type">embed</code>;
<code data-x="attr-object-type">object</code>;
<code data-x="attr-source-type">source</code>
<td> Type of embedded resource
<td> <span>Valid MIME type string</span>
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-input-type">input</code>
<td> Type of form control
<td> <span data-x="attr-input-type"><code>input</code> type keyword</span>
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-ol-type">ol</code>
<td> Kind of list marker
<td> "<code data-x="attr-ol-type-keyword-decimal">1</code>";
"<code data-x="attr-ol-type-keyword-lower-alpha">a</code>";
"<code data-x="attr-ol-type-keyword-upper-alpha">A</code>";
"<code data-x="attr-ol-type-keyword-lower-roman">i</code>";
"<code data-x="attr-ol-type-keyword-upper-roman">I</code>"
<tr>
<th> <code data-x="">type</code>
<td> <code data-x="attr-script-type">script</code>
<td> Type of script
<td> "<code data-x="">module</code>"; a <span>valid MIME type string</span> that is not a <span>JavaScript MIME type essence match</span>
<tr>
<th> <code data-x="">usemap</code>
<td> <code data-x="attr-hyperlink-usemap">img</code>
<td> Name of <span>image map</span> to use
<td> <span>Valid hash-name reference</span>*
<tr>
<th> <code data-x="">value</code>
<td> <code data-x="attr-button-value">button</code>;
<code data-x="attr-option-value">option</code>
<td> Value to be used for <span>form submission</span>
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">value</code>
<td> <code data-x="attr-data-value">data</code>
<td> Machine-readable value
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">value</code>
<td> <code data-x="attr-input-value">input</code>
<td> Value of the form control
<td> Varies*
<tr>
<th> <code data-x="">value</code>
<td> <code data-x="attr-li-value">li</code>
<td> <span>Ordinal value</span> of the list item
<td> <span>Valid integer</span>
<tr>
<th> <code data-x="">value</code>
<td> <code data-x="attr-meter-value">meter</code>;
<code data-x="attr-progress-value">progress</code>
<td> Current value of the element
<td> <span>Valid floating-point number</span>
<tr>
<th> <code data-x="">width</code>
<td> <code data-x="attr-canvas-width">canvas</code>;
<code data-x="attr-dim-width">embed</code>;
<code data-x="attr-dim-width">iframe</code>;
<code data-x="attr-dim-width">img</code>;
<code data-x="attr-dim-width">input</code>;
<code data-x="attr-dim-width">object</code>;
<code data-x="attr-dim-width">source</code> (in <code>picture</code>);
<code data-x="attr-dim-width">video</code>
<td> Horizontal dimension
<td> <span>Valid non-negative integer</span>
<tr>
<th> <code data-x="">wrap</code>
<td> <code data-x="attr-textarea-wrap">textarea</code>
<td> How the value of the form control is to be wrapped for <span>form submission</span>
<td> "<code data-x="attr-textarea-wrap-soft">soft</code>";
"<code data-x="attr-textarea-wrap-hard">hard</code>"
<tr>
<th> <code data-x="">writingsuggestions</code>
<td> <span data-x="attr-writingsuggestions">HTML elements</span>
<td> Whether the element can offer writing suggestions or not.
<td> "<code data-x="attr-writingsuggestions-true">true</code>";
"<code data-x="attr-writingsuggestions-false">false</code>";
the empty string
</table>
<p class="tablenote"><small>An asterisk (*) in a cell indicates that the actual rules are more
complicated than indicated in the table above.</small></p>
<hr>
<table id="ix-event-handlers">
<caption>List of event handler content attributes</caption>
<thead>
<tr>
<th> Attribute
<th> Element(s)
<th> Description
<th> Value
<tbody>
<tr>
<th id="ix-handler-window-onafterprint"> <code data-x="">onafterprint</code>
<td> <code data-x="handler-window-onafterprint">body</code>
<td> <code data-x="event-afterprint">afterprint</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onauxclick"> <code data-x="">onauxclick</code>
<td> <span data-x="handler-onauxclick">HTML elements</span>
<td> <code data-x="event-auxclick">auxclick</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onbeforeinput"> <code data-x="">onbeforeinput</code>
<td> <span data-x="handler-onbeforeinput">HTML elements</span>
<td> <code data-x="event-beforeinput">beforeinput</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onbeforematch"> <code data-x="">onbeforematch</code>
<td> <span data-x="handler-onbeforematch">HTML elements</span>
<td> <code data-x="event-beforematch">beforematch</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onbeforeprint"> <code data-x="">onbeforeprint</code>
<td> <code data-x="handler-window-onbeforeprint">body</code>
<td> <code data-x="event-beforeprint">beforeprint</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onbeforeunload"> <code data-x="">onbeforeunload</code>
<td> <code data-x="handler-window-onbeforeunload">body</code>
<td> <code data-x="event-beforeunload">beforeunload</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onbeforetoggle"> <code data-x="">onbeforetoggle</code>
<td> <span data-x="handler-onbeforetoggle">HTML elements</span>
<td> <code data-x="event-beforetoggle">beforetoggle</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onblur"> <code data-x="">onblur</code>
<td> <span data-x="handler-onblur">HTML elements</span>
<td> <code data-x="event-blur">blur</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncancel"> <code data-x="">oncancel</code>
<td> <span data-x="handler-oncancel">HTML elements</span>
<td> <code data-x="event-cancel">cancel</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncanplay"> <code data-x="">oncanplay</code>
<td> <span data-x="handler-oncanplay">HTML elements</span>
<td> <code data-x="event-media-canplay">canplay</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncanplaythrough"> <code data-x="">oncanplaythrough</code>
<td> <span data-x="handler-oncanplaythrough">HTML elements</span>
<td> <code data-x="event-media-canplaythrough">canplaythrough</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onchange"> <code data-x="">onchange</code>
<td> <span data-x="handler-onchange">HTML elements</span>
<td> <code data-x="event-change">change</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onclick"> <code data-x="">onclick</code>
<td> <span data-x="handler-onclick">HTML elements</span>
<td> <code data-x="event-click">click</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onclose"> <code data-x="">onclose</code>
<td> <span data-x="handler-onclose">HTML elements</span>
<td> <code data-x="event-close">close</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncommand"> <code data-x="">oncommand</code>
<td> <span data-x="handler-oncommand">HTML elements</span>
<td> <code data-x="event-command">command</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncontextlost"> <code data-x="">oncontextlost</code>
<td> <span data-x="handler-oncontextlost">HTML elements</span>
<td> <code data-x="event-contextlost">contextlost</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncontextmenu"> <code data-x="">oncontextmenu</code>
<td> <span data-x="handler-oncontextmenu">HTML elements</span>
<td> <code data-x="event-contextmenu">contextmenu</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncontextrestored"> <code data-x="">oncontextrestored</code>
<td> <span data-x="handler-oncontextrestored">HTML elements</span>
<td> <code data-x="event-contextrestored">contextrestored</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncopy"> <code data-x="">oncopy</code>
<td> <span data-x="handler-oncopy">HTML elements</span>
<td> <code data-x="event-copy">copy</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncuechange"> <code data-x="">oncuechange</code>
<td> <span data-x="handler-oncuechange">HTML elements</span>
<td> <code data-x="event-media-cuechange">cuechange</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oncut"> <code data-x="">oncut</code>
<td> <span data-x="handler-oncut">HTML elements</span>
<td> <code data-x="event-cut">cut</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondblclick"> <code data-x="">ondblclick</code>
<td> <span data-x="handler-ondblclick">HTML elements</span>
<td> <code data-x="event-dblclick">dblclick</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondrag"> <code data-x="">ondrag</code>
<td> <span data-x="handler-ondrag">HTML elements</span>
<td> <code data-x="event-dnd-drag">drag</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondragend"> <code data-x="">ondragend</code>
<td> <span data-x="handler-ondragend">HTML elements</span>
<td> <code data-x="event-dnd-dragend">dragend</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondragenter"> <code data-x="">ondragenter</code>
<td> <span data-x="handler-ondragenter">HTML elements</span>
<td> <code data-x="event-dnd-dragenter">dragenter</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondragleave"> <code data-x="">ondragleave</code>
<td> <span data-x="handler-ondragleave">HTML elements</span>
<td> <code data-x="event-dnd-dragleave">dragleave</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondragover"> <code data-x="">ondragover</code>
<td> <span data-x="handler-ondragover">HTML elements</span>
<td> <code data-x="event-dnd-dragover">dragover</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondragstart"> <code data-x="">ondragstart</code>
<td> <span data-x="handler-ondragstart">HTML elements</span>
<td> <code data-x="event-dnd-dragstart">dragstart</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondrop"> <code data-x="">ondrop</code>
<td> <span data-x="handler-ondrop">HTML elements</span>
<td> <code data-x="event-dnd-drop">drop</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ondurationchange"> <code data-x="">ondurationchange</code>
<td> <span data-x="handler-ondurationchange">HTML elements</span>
<td> <code data-x="event-media-durationchange">durationchange</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onemptied"> <code data-x="">onemptied</code>
<td> <span data-x="handler-onemptied">HTML elements</span>
<td> <code data-x="event-media-emptied">emptied</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onended"> <code data-x="">onended</code>
<td> <span data-x="handler-onended">HTML elements</span>
<td> <code data-x="event-media-ended">ended</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onerror"> <code data-x="">onerror</code>
<td> <span data-x="handler-onerror">HTML elements</span>
<td> <code data-x="event-error">error</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onfocus"> <code data-x="">onfocus</code>
<td> <span data-x="handler-onfocus">HTML elements</span>
<td> <code data-x="event-focus">focus</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onformdata"> <code data-x="">onformdata</code>
<td> <span data-x="handler-onformdata">HTML elements</span>
<td> <code data-x="event-formdata">formdata</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onhashchange"> <code data-x="">onhashchange</code>
<td> <code data-x="handler-window-onhashchange">body</code>
<td> <code data-x="event-hashchange">hashchange</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oninput"> <code data-x="">oninput</code>
<td> <span data-x="handler-oninput">HTML elements</span>
<td> <code data-x="event-input">input</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-oninvalid"> <code data-x="">oninvalid</code>
<td> <span data-x="handler-oninvalid">HTML elements</span>
<td> <code data-x="event-invalid">invalid</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onkeydown"> <code data-x="">onkeydown</code>
<td> <span data-x="handler-onkeydown">HTML elements</span>
<td> <code data-x="event-keydown">keydown</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onkeypress"> <code data-x="">onkeypress</code>
<td> <span data-x="handler-onkeypress">HTML elements</span>
<td> <code data-x="event-keypress">keypress</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onkeyup"> <code data-x="">onkeyup</code>
<td> <span data-x="handler-onkeyup">HTML elements</span>
<td> <code data-x="event-keyup">keyup</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onlanguagechange"> <code data-x="">onlanguagechange</code>
<td> <code data-x="handler-window-onlanguagechange">body</code>
<td> <code data-x="event-languagechange">languagechange</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onload"> <code data-x="">onload</code>
<td> <span data-x="handler-onload">HTML elements</span>
<td> <code data-x="event-load">load</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onloadeddata"> <code data-x="">onloadeddata</code>
<td> <span data-x="handler-onloadeddata">HTML elements</span>
<td> <code data-x="event-media-loadeddata">loadeddata</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onloadedmetadata"> <code data-x="">onloadedmetadata</code>
<td> <span data-x="handler-onloadedmetadata">HTML elements</span>
<td> <code data-x="event-media-loadedmetadata">loadedmetadata</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onloadstart"> <code data-x="">onloadstart</code>
<td> <span data-x="handler-onloadstart">HTML elements</span>
<td> <code data-x="event-media-loadstart">loadstart</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onmessage"> <code data-x="">onmessage</code>
<td> <code data-x="handler-window-onmessage">body</code>
<td> <code data-x="event-message">message</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onmessageerror"> <code data-x="">onmessageerror</code>
<td> <code data-x="handler-window-onmessageerror">body</code>
<td> <code data-x="event-messageerror">messageerror</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmousedown"> <code data-x="">onmousedown</code>
<td> <span data-x="handler-onmousedown">HTML elements</span>
<td> <code data-x="event-mousedown">mousedown</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmouseenter"> <code data-x="">onmouseenter</code>
<td> <span data-x="handler-onmouseenter">HTML elements</span>
<td> <code data-x="event-mouseenter">mouseenter</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmouseleave"> <code data-x="">onmouseleave</code>
<td> <span data-x="handler-onmouseleave">HTML elements</span>
<td> <code data-x="event-mouseleave">mouseleave</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmousemove"> <code data-x="">onmousemove</code>
<td> <span data-x="handler-onmousemove">HTML elements</span>
<td> <code data-x="event-mousemove">mousemove</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmouseout"> <code data-x="">onmouseout</code>
<td> <span data-x="handler-onmouseout">HTML elements</span>
<td> <code data-x="event-mouseout">mouseout</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmouseover"> <code data-x="">onmouseover</code>
<td> <span data-x="handler-onmouseover">HTML elements</span>
<td> <code data-x="event-mouseover">mouseover</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onmouseup"> <code data-x="">onmouseup</code>
<td> <span data-x="handler-onmouseup">HTML elements</span>
<td> <code data-x="event-mouseup">mouseup</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onoffline"> <code data-x="">onoffline</code>
<td> <code data-x="handler-window-onoffline">body</code>
<td> <code data-x="event-offline">offline</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-ononline"> <code data-x="">ononline</code>
<td> <code data-x="handler-window-ononline">body</code>
<td> <code data-x="event-online">online</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onpagehide"> <code data-x="">onpagehide</code>
<td> <code data-x="handler-window-onpagehide">body</code>
<td> <code data-x="event-pagehide">pagehide</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onpagereveal"> <code data-x="">onpagereveal</code>
<td> <code data-x="handler-window-onpagereveal">body</code>
<td> <code data-x="event-pagereveal">pagereveal</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onpageshow"> <code data-x="">onpageshow</code>
<td> <code data-x="handler-window-onpageshow">body</code>
<td> <code data-x="event-pageshow">pageshow</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onpageswap"> <code data-x="">onpageswap</code>
<td> <code data-x="handler-window-onpageswap">body</code>
<td> <code data-x="event-pageswap">pageswap</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onpaste"> <code data-x="">onpaste</code>
<td> <span data-x="handler-onpaste">HTML elements</span>
<td> <code data-x="event-paste">paste</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onpause"> <code data-x="">onpause</code>
<td> <span data-x="handler-onpause">HTML elements</span>
<td> <code data-x="event-media-pause">pause</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onplay"> <code data-x="">onplay</code>
<td> <span data-x="handler-onplay">HTML elements</span>
<td> <code data-x="event-media-play">play</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onplaying"> <code data-x="">onplaying</code>
<td> <span data-x="handler-onplaying">HTML elements</span>
<td> <code data-x="event-media-playing">playing</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onpopstate"> <code data-x="">onpopstate</code>
<td> <code data-x="handler-window-onpopstate">body</code>
<td> <code data-x="event-popstate">popstate</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onprogress"> <code data-x="">onprogress</code>
<td> <span data-x="handler-onprogress">HTML elements</span>
<td> <code data-x="event-media-progress">progress</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onratechange"> <code data-x="">onratechange</code>
<td> <span data-x="handler-onratechange">HTML elements</span>
<td> <code data-x="event-media-ratechange">ratechange</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onreset"> <code data-x="">onreset</code>
<td> <span data-x="handler-onreset">HTML elements</span>
<td> <code data-x="event-reset">reset</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onresize"> <code data-x="">onresize</code>
<td> <span data-x="handler-onresize">HTML elements</span>
<td> <code data-x="event-resize">resize</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onrejectionhandled"> <code data-x="">onrejectionhandled</code>
<td> <code data-x="handler-window-onrejectionhandled">body</code>
<td> <code data-x="event-rejectionhandled">rejectionhandled</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onscroll"> <code data-x="">onscroll</code>
<td> <span data-x="handler-onscroll">HTML elements</span>
<td> <code data-x="event-scroll">scroll</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onscrollend"> <code data-x="">onscrollend</code>
<td> <span data-x="handler-onscrollend">HTML elements</span>
<td> <code data-x="event-scrollend">scrollend</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onsecuritypolicyviolation"> <code data-x="">onsecuritypolicyviolation</code>
<td> <span data-x="handler-onsecuritypolicyviolation">HTML elements</span>
<td> <code data-x="event-securitypolicyviolation">securitypolicyviolation</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onseeked"> <code data-x="">onseeked</code>
<td> <span data-x="handler-onseeked">HTML elements</span>
<td> <code data-x="event-media-seeked">seeked</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onseeking"> <code data-x="">onseeking</code>
<td> <span data-x="handler-onseeking">HTML elements</span>
<td> <code data-x="event-media-seeking">seeking</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onselect"> <code data-x="">onselect</code>
<td> <span data-x="handler-onselect">HTML elements</span>
<td> <code data-x="event-select">select</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onslotchange"> <code data-x="">onslotchange</code>
<td> <span data-x="handler-onslotchange">HTML elements</span>
<td> <code data-x="event-slotchange">slotchange</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onstalled"> <code data-x="">onstalled</code>
<td> <span data-x="handler-onstalled">HTML elements</span>
<td> <code data-x="event-media-stalled">stalled</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onstorage"> <code data-x="">onstorage</code>
<td> <code data-x="handler-window-onstorage">body</code>
<td> <code data-x="event-storage">storage</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onsubmit"> <code data-x="">onsubmit</code>
<td> <span data-x="handler-onsubmit">HTML elements</span>
<td> <code data-x="event-submit">submit</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onsuspend"> <code data-x="">onsuspend</code>
<td> <span data-x="handler-onsuspend">HTML elements</span>
<td> <code data-x="event-media-suspend">suspend</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ontimeupdate"> <code data-x="">ontimeupdate</code>
<td> <span data-x="handler-ontimeupdate">HTML elements</span>
<td> <code data-x="event-media-timeupdate">timeupdate</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-ontoggle"> <code data-x="">ontoggle</code>
<td> <span data-x="handler-ontoggle">HTML elements</span>
<td> <code data-x="event-toggle">toggle</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onunhandledrejection"> <code data-x="">onunhandledrejection</code>
<td> <code data-x="handler-window-onunhandledrejection">body</code>
<td> <code data-x="event-unhandledrejection">unhandledrejection</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-window-onunload"> <code data-x="">onunload</code>
<td> <code data-x="handler-window-onunload">body</code>
<td> <code data-x="event-unload">unload</code> event handler for <code>Window</code> object
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onvolumechange"> <code data-x="">onvolumechange</code>
<td> <span data-x="handler-onvolumechange">HTML elements</span>
<td> <code data-x="event-media-volumechange">volumechange</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onwaiting"> <code data-x="">onwaiting</code>
<td> <span data-x="handler-onwaiting">HTML elements</span>
<td> <code data-x="event-media-waiting">waiting</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
<tr>
<th id="ix-handler-onwheel"> <code data-x="">onwheel</code>
<td> <span data-x="handler-onwheel">HTML elements</span>
<td> <code data-x="event-wheel">wheel</code> event handler
<td> <span data-x="event handler content attributes">Event handler content attribute</span>
</table>
<h3 class="no-num">Element interfaces</h3>
<!-- NON-NORMATIVE SECTION -->
<table>
<caption>List of interfaces for elements</caption>
<thead>
<tr>
<th> Element(s)
<th> Interface(s)
<tbody>
<tr>
<td> <code>a</code>
<td> <code>HTMLAnchorElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>abbr</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>address</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>area</code>
<td> <code>HTMLAreaElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>article</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>aside</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>audio</code>
<td> <code>HTMLAudioElement</code> : <code>HTMLMediaElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>b</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>base</code>
<td> <code>HTMLBaseElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>bdi</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>bdo</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>blockquote</code>
<td> <code>HTMLQuoteElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>body</code>
<td> <code>HTMLBodyElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>br</code>
<td> <code>HTMLBRElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>button</code>
<td> <code>HTMLButtonElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>canvas</code>
<td> <code>HTMLCanvasElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>caption</code>
<td> <code>HTMLTableCaptionElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>cite</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>code</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>col</code>
<td> <code>HTMLTableColElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>colgroup</code>
<td> <code>HTMLTableColElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>data</code>
<td> <code>HTMLDataElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>datalist</code>
<td> <code>HTMLDataListElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>dd</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>del</code>
<td> <code>HTMLModElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>details</code>
<td> <code>HTMLDetailsElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>dfn</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>dialog</code>
<td> <code>HTMLDialogElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>div</code>
<td> <code>HTMLDivElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>dl</code>
<td> <code>HTMLDListElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>dt</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>em</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>embed</code>
<td> <code>HTMLEmbedElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>fieldset</code>
<td> <code>HTMLFieldSetElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>figcaption</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>figure</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>footer</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>form</code>
<td> <code>HTMLFormElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h1</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h2</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h3</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h4</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h5</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>h6</code>
<td> <code>HTMLHeadingElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>head</code>
<td> <code>HTMLHeadElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>header</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>hgroup</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>hr</code>
<td> <code>HTMLHRElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>html</code>
<td> <code>HTMLHtmlElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>i</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>iframe</code>
<td> <code>HTMLIFrameElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>img</code>
<td> <code>HTMLImageElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>input</code>
<td> <code>HTMLInputElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>ins</code>
<td> <code>HTMLModElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>kbd</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>label</code>
<td> <code>HTMLLabelElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>legend</code>
<td> <code>HTMLLegendElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>li</code>
<td> <code>HTMLLIElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>link</code>
<td> <code>HTMLLinkElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>main</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>map</code>
<td> <code>HTMLMapElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>mark</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>menu</code>
<td> <code>HTMLMenuElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>meta</code>
<td> <code>HTMLMetaElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>meter</code>
<td> <code>HTMLMeterElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>nav</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>noscript</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>object</code>
<td> <code>HTMLObjectElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>ol</code>
<td> <code>HTMLOListElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>optgroup</code>
<td> <code>HTMLOptGroupElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>option</code>
<td> <code>HTMLOptionElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>output</code>
<td> <code>HTMLOutputElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>p</code>
<td> <code>HTMLParagraphElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>picture</code>
<td> <code>HTMLPictureElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>pre</code>
<td> <code>HTMLPreElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>progress</code>
<td> <code>HTMLProgressElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>q</code>
<td> <code>HTMLQuoteElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>rp</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>rt</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>ruby</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>s</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>samp</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>search</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>script</code>
<td> <code>HTMLScriptElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>section</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>select</code>
<td> <code>HTMLSelectElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>slot</code>
<td> <code>HTMLSlotElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>small</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>source</code>
<td> <code>HTMLSourceElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>span</code>
<td> <code>HTMLSpanElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>strong</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>style</code>
<td> <code>HTMLStyleElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>sub</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>summary</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>sup</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>table</code>
<td> <code>HTMLTableElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>tbody</code>
<td> <code>HTMLTableSectionElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>td</code>
<td> <code>HTMLTableCellElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>template</code>
<td> <code>HTMLTemplateElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>textarea</code>
<td> <code>HTMLTextAreaElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>tfoot</code>
<td> <code>HTMLTableSectionElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>th</code>
<td> <code>HTMLTableCellElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>thead</code>
<td> <code>HTMLTableSectionElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>time</code>
<td> <code>HTMLTimeElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>title</code>
<td> <code>HTMLTitleElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>tr</code>
<td> <code>HTMLTableRowElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>track</code>
<td> <code>HTMLTrackElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>u</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>ul</code>
<td> <code>HTMLUListElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>var</code>
<td> <code>HTMLElement</code>
<tr>
<td> <code>video</code>
<td> <code>HTMLVideoElement</code> : <code>HTMLMediaElement</code> : <code>HTMLElement</code>
<tr>
<td> <code>wbr</code>
<td> <code>HTMLElement</code>
<tr>
<td> <span data-x="custom element">custom elements</span>
<td> supplied by the element's author (inherits from <code>HTMLElement</code>)
</table>
<h3 class="no-num">All interfaces</h3>
<!-- NON-NORMATIVE SECTION -->
INSERT INTERFACES HERE
<h3 class="no-num">Events</h3>
<!-- NON-NORMATIVE SECTION -->
<p>The following table lists events fired by this document, excluding those
already defined in <a href="#mediaevents">media element events</a> and
<a href="#dndevents">drag-and-drop events</a>.</p>
<table>
<caption>List of events</caption>
<thead>
<tr>
<th> Event
<th> Interface
<th> Interesting targets
<th> Description
<tbody>
<tr> <!-- DOMContentLoaded -->
<td> <dfn event for="Document"><code data-x="event-DOMContentLoaded">DOMContentLoaded</code></dfn>
<td> <code>Event</code>
<td> <code>Document</code>
<td> Fired at the <code>Document</code> once the parser has finished
<tr> <!-- afterprint -->
<td> <dfn event for="Window"><code data-x="event-afterprint">afterprint</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> after printing
<tr> <!-- beforeprint -->
<td> <dfn event for="Window"><code data-x="event-beforeprint">beforeprint</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> before printing
<tr> <!-- beforematch -->
<td> <dfn event for="HTMLElement"><code data-x="event-beforematch">beforematch</code></dfn>
<td> <code>Event</code>
<td> Elements
<td> Fired on elements with the <code
data-x="attr-hidden-until-found-state">hidden=until-found</code> attribute before they are
revealed.
<tr> <!-- beforetoggle -->
<td> <dfn event for="HTMLElement"><code data-x="event-beforetoggle">beforetoggle</code></dfn>
<td> <code>ToggleEvent</code>
<td> Elements
<td> Fired on elements with the <code data-x="attr-popover">popover</code> attribute when they
are transitioning between showing and hidden
<tr> <!-- beforeunload -->
<td> <dfn event for="Window"><code data-x="event-beforeunload">beforeunload</code></dfn>
<td> <code>BeforeUnloadEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when the page is about to be unloaded, in case the page would like to show a warning prompt
<tr> <!-- blur -->
<td> <dfn event for="Window,HTMLElement"><code data-x="event-blur">blur</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>, elements
<td> Fired at nodes when they stop being <span>focused</span>
<tr> <!-- cancel -->
<td> <dfn event for="CloseWatcher,HTMLElement"><code data-x="event-cancel">cancel</code></dfn>
<td> <code>Event</code>
<td> <code>CloseWatcher</code>, <code>dialog</code> elements, <code>input</code> elements
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they receive a <span>close request</span>, or at <code>input</code> elements whose <span data-x="attr-input-type">type</span> attribute is in the <span data-x="attr-input-type-file">File</span> state when the user does not change their selection
<tr> <!-- change -->
<td> <dfn event for="HTMLElement"><code data-x="event-change" id="event-input-change">change</code></dfn>
<td> <code>Event</code>
<td> Form controls
<td> Fired at controls when the user commits a value change (see also the <code data-x="event-input">input</code> event)
<tr> <!-- click -->
<td> <code data-x="event-click">click</code>
<td> <code>PointerEvent</code>
<td> Elements
<td> Normally a mouse event; also synthetically fired at an element before its <span>activation behavior</span> is run, when an element is activated from a non-pointer input device (e.g. a keyboard)
<tr> <!-- close -->
<td> <dfn event for="CloseWatcher,HTMLElement,MessagePort"><code data-x="event-close">close</code></dfn>
<td> <code>Event</code>
<td> <code>CloseWatcher</code>, <code>dialog</code> elements, <code>MessagePort</code>
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they are closed via a <span>close request</span> or via web developer code, or at <code>MessagePort</code> objects when <span data-x="disentangle">disentangled</span>
<tr> <!-- command -->
<td> <dfn event for="HTMLElement"><code data-x="event-command">command</code></dfn>
<td> <code>CommandEvent</code>
<td> Elements
<td> Fired at elements when they handle a user invocation, via a <code
data-x="attr-button-commandfor">commandfor</code> attribute.
<tr> <!-- connect -->
<td> <dfn event for="SharedWorkerGlobalScope"><code data-x="event-WorkerGlobalScope-connect">connect</code></dfn>
<td> <code>MessageEvent</code>
<td> <code>SharedWorkerGlobalScope</code>
<td> Fired at a shared worker's global scope when a new client connects
<tr> <!-- contextlost -->
<td> <dfn event for="HTMLElement,OffscreenCanvas"><code data-x="event-contextlost">contextlost</code></dfn>
<td> <code>Event</code>
<td> <code>canvas</code> elements, <code>OffscreenCanvas</code> objects
<td> Fired when the corresponding <code>CanvasRenderingContext2D</code> or <code>OffscreenCanvasRenderingContext2D</code> is lost
<tr> <!-- contextrestore -->
<td> <dfn event for="HTMLElement,OffscreenCanvas"><code data-x="event-contextrestored">contextrestored</code></dfn>
<td> <code>Event</code>
<td> <code>canvas</code> elements, <code>OffscreenCanvas</code> objects
<td> Fired when the corresponding <code>CanvasRenderingContext2D</code> or <code>OffscreenCanvasRenderingContext2D</code> is restored after being lost
<tr> <!-- currententrychange -->
<td> <dfn event for="Navigation"><code data-x="event-currententrychange">currententrychange</code></dfn>
<td> <code>NavigationCurrentEntryChangeEvent</code>
<td> <code>Navigation</code>
<td> Fired when <code data-x="dom-Navigation-currentEntry">navigation.currentEntry</code> changes
<tr> <!-- dispose -->
<td> <dfn event for="NavigationHistoryEntry"><code data-x="event-dispose">dispose</code></dfn>
<td> <code>Event</code>
<td> <code>NavigationHistoryEntry</code>
<td> Fired when the <span>session history entry</span> corresponding to the <code>NavigationHistoryEntry</code> has been permanently evicted from session history and can no longer be traversed to
<tr> <!-- error -->
<td> <dfn event for="Window,WorkerGlobalScope,HTMLElement,EventSource,Worker,SharedWorker,AbstractWorker"><code data-x="event-error">error</code></dfn>
<td> <code>Event</code> or <code>ErrorEvent</code>
<td> Global scope objects, <code>Worker</code> objects, elements, networking-related objects
<td> Fired when unexpected errors occur (e.g. networking errors, script errors, decoding errors)
<tr> <!-- focus -->
<td> <dfn event for="Window,HTMLElement"><code data-x="event-focus">focus</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>, elements
<td> Fired at nodes <span data-x="gains focus">gaining focus</span>
<tr> <!-- formdata -->
<td> <dfn event for="HTMLElement"><code data-x="event-formdata">formdata</code></dfn>
<td> <code>FormDataEvent</code>
<td> <code>form</code> elements
<td> Fired at a <code>form</code> element when it is <span>constructing the entry list</span>
<tr> <!-- hashchange -->
<td> <dfn event for="Window"><code data-x="event-hashchange">hashchange</code></dfn>
<td> <code>HashChangeEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when the <span data-x="concept-url-fragment">fragment</span> part of the document's <span data-x="concept-document-url">URL</span> changes
<tr> <!-- input -->
<td> <span><code data-x="event-input">input</code></span>
<td> <code>Event</code>
<td> Elements
<td> Fired when the user changes the <code data-x="attr-contenteditable">contenteditable</code> element's content, or the form control's value. See also the <code data-x="event-change">change</code> event for form controls.
<tr> <!-- invalid -->
<td> <dfn event for="HTMLElement"><code data-x="event-invalid">invalid</code></dfn>
<td> <code>Event</code>
<td> Form controls
<td> Fired at controls during form validation if they do not satisfy their constraints
<tr> <!-- languagechange -->
<td> <dfn event for="Window,WorkerGlobalScope"><code data-x="event-languagechange">languagechange</code></dfn>
<td> <code>Event</code>
<td> Global scope objects
<td> Fired at the global scope object when the user's preferred languages change
<tr> <!-- load -->
<td> <dfn event for="Window,HTMLElement"><code data-x="event-load">load</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>, elements
<td> Fired at the <code>Window</code> when the document has finished loading; fired at an element containing a resource (e.g. <code>img</code>, <code>embed</code>) when its resource has finished loading
<tr> <!-- message -->
<td> <dfn event for="Window,EventSource,MessagePort,BroadcastChannel,DedicatedWorkerGlobalScope,Worker,ServiceWorkerContainer"><code data-x="event-message">message</code></dfn>
<td> <code>MessageEvent</code>
<td> <code>Window</code>, <code>EventSource</code>, <code>MessagePort</code>, <code>BroadcastChannel</code>, <code>DedicatedWorkerGlobalScope</code>, <code>Worker</code>, <code>ServiceWorkerContainer</code>
<td> Fired at an object when it receives a message
<tr> <!-- messageerror -->
<td> <dfn event for="Window,MessagePort,BroadcastChannel,DedicatedWorkerGlobalScope,Worker,ServiceWorkerContainer"><code data-x="event-messageerror">messageerror</code></dfn>
<td> <code>MessageEvent</code>
<td> <code>Window</code>, <code>MessagePort</code>, <code>BroadcastChannel</code>, <code>DedicatedWorkerGlobalScope</code>, <code>Worker</code>, <code>ServiceWorkerContainer</code>
<td> Fired at an object when it receives a message that cannot be deserialized
<tr> <!-- navigate -->
<td> <dfn event for="Navigation"><code data-x="event-navigate">navigate</code></dfn>
<td> <code>NavigateEvent</code>
<td> <code>Navigation</code>
<td> Fired before the <span>navigable</span> <span data-x="navigate">navigates</span>, <span data-x="reload">reloads</span>, <span data-x="traverse the history by a delta">traverses</span>, or <span data-x="shared history push/replace state steps">otherwise</span> changes its URL
<tr> <!-- navigateerror -->
<td> <dfn event for="Navigation"><code data-x="event-navigateerror">navigateerror</code></dfn>
<td> <code>ErrorEvent</code>
<td> <code>Navigation</code>
<td> Fired when a navigation does not complete successfully
<tr> <!-- navigatesuccess -->
<td> <dfn event for="Navigation"><code data-x="event-navigatesuccess">navigatesuccess</code></dfn>
<td> <code>Event</code>
<td> <code>Navigation</code>
<td> Fired when a navigation completes successfully
<tr> <!-- offline -->
<td> <dfn event for="Window,WorkerGlobalScope"><code data-x="event-offline">offline</code></dfn>
<td> <code>Event</code>
<td> Global scope objects
<td> Fired at the global scope object when the network connections fails
<tr> <!-- online -->
<td> <dfn event for="Window,WorkerGlobalScope"><code data-x="event-online">online</code></dfn>
<td> <code>Event</code>
<td> Global scope objects
<td> Fired at the global scope object when the network connections returns
<tr> <!-- open -->
<td> <dfn event for="EventSource"><code data-x="event-open">open</code></dfn>
<td> <code>Event</code>
<td> <code>EventSource</code>
<td> Fired at <code>EventSource</code> objects when a connection is established
<tr> <!-- pageswap -->
<td> <dfn event for="Window"><code data-x="event-pageswap">pageswap</code></dfn>
<td> <code>PageSwapEvent</code>
<td> <code>Window</code>
<td>Fired at the <code>Window</code> right before a document is <span
data-x="unload a document">unloaded</span> as a result of a navigation.
<tr> <!-- pagehide -->
<td> <dfn event for="Window"><code data-x="event-pagehide">pagehide</code></dfn>
<td> <code>PageTransitionEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when the page's <span>session history entry</span> stops
being the <span data-x="nav-active-history-entry">active entry</span>
<tr> <!-- pagereveal -->
<td> <dfn event for="Window"><code data-x="event-pagereveal">pagereveal</code></dfn>
<td> <code>PageRevealEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when the page begins to render for the first time after
it has been initialized or <span data-x="reactivate a document">reactivated</span>
<tr> <!-- pageshow -->
<td> <dfn event for="Window"><code data-x="event-pageshow">pageshow</code></dfn>
<td> <code>PageTransitionEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when the page's <span>session history entry</span>
becomes the <span data-x="nav-active-history-entry">active entry</span>
<tr> <!-- pointercancel -->
<td> <span><code data-x="event-pointercancel">pointercancel</code></span>
<td> <code>PointerEvent</code>
<td> Elements and <code>Text</code> nodes
<td> Fired at the <span>source node</span> when the user attempts to initiate a drag-and-drop operation
<tr> <!-- popstate -->
<td> <dfn event for="Window"><code data-x="event-popstate">popstate</code></dfn>
<td> <code>PopStateEvent</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> when in some cases of <span data-x="traverse the history by a delta">session history traversal</span>
<tr> <!-- readystatechange -->
<td> <dfn event for="Document"><code data-x="event-readystatechange">readystatechange</code></dfn>
<td> <code>Event</code>
<td> <code>Document</code>
<td> Fired at the <code>Document</code> when it finishes parsing and again when all its subresources have finished loading
<tr> <!-- rejectionhandled -->
<td> <dfn event for="Window,WorkerGlobalScope"><code data-x="event-rejectionhandled">rejectionhandled</code></dfn>
<td> <code>PromiseRejectionEvent</code>
<td> Global scope objects
<td> Fired at global scope objects when a previously-unhandled promise rejection becomes handled
<tr> <!-- reset -->
<td> <dfn event for="HTMLElement"><code data-x="event-reset">reset</code></dfn>
<td> <code>Event</code>
<td> <code>form</code> elements
<td> Fired at a <code>form</code> element when it is <span data-x="concept-form-reset">reset</span>
<tr> <!-- select -->
<td> <dfn event for="HTMLElement"><code data-x="event-select">select</code></dfn>
<td> <code>Event</code>
<td> Form controls
<td> Fired at form controls when their text selection is adjusted (whether by an API or by the user)
<tr> <!-- storage -->
<td> <dfn event for="Window"><code data-x="event-storage">storage</code></dfn>
<td> <code>StorageEvent</code>
<td> <code>Window</code>
<td> Fired at <code>Window</code> event when the corresponding <code data-x="dom-localStorage">localStorage</code> or <code data-x="dom-sessionStorage">sessionStorage</code> storage areas change
<tr> <!-- submit -->
<td> <dfn event for="HTMLElement"><code data-x="event-submit">submit</code></dfn>
<td> <code>SubmitEvent</code>
<td> <code>form</code> elements
<td> Fired at a <code>form</code> element when it is <span data-x="concept-form-submit">submitted</span>
<tr> <!-- toggle -->
<td> <dfn event for="HTMLElement"><code data-x="event-toggle">toggle</code></dfn>
<td> <code>ToggleEvent</code>
<td> <code>details</code> and <span data-x="attr-popover">popover</span> elements
<td> Fired at <code>details</code> elements when they open or close; fired on elements with the
<code data-x="attr-popover">popover</code> attribute when they are transitioning between
showing and hidden
<tr> <!-- unhandledrejection -->
<td> <dfn event for="Window,WorkerGlobalScope"><code data-x="event-unhandledrejection">unhandledrejection</code></dfn>
<td> <code>PromiseRejectionEvent</code>
<td> Global scope objects
<td> Fired at global scope objects when a promise rejection goes unhandled
<tr> <!-- unload -->
<td> <dfn event for="Window"><code data-x="event-unload">unload</code></dfn>
<td> <code>Event</code>
<td> <code>Window</code>
<td> Fired at the <code>Window</code> object when the page is going away
<tr> <!-- visibilitychange -->
<td> <dfn event for="Document"><code data-x="event-visibilitychange">visibilitychange</code></dfn>
<td> <code>Event</code>
<td> <code>Document</code>
<td> Fired at the <code>Document</code> object when the page becomes visible or hidden to the
user
</table>
<h3 class="no-num">HTTP headers</h3>
<!-- NON-NORMATIVE SECTION -->
<p>The following HTTP request headers are defined by this specification:</p>
<ul>
<li>`<code>Last-Event-ID</code>`</li>
<li>`<code>Ping-From</code>`</li>
<li>`<code>Ping-To</code>`</li>
</ul>
<p>The following HTTP response headers are defined by this specification:</p>
<ul>
<li>`<code>Cross-Origin-Embedder-Policy</code>`</li>
<li>`<code>Cross-Origin-Embedder-Policy-Report-Only</code>`</li>
<li>`<code>Cross-Origin-Opener-Policy</code>`</li>
<li>`<code>Cross-Origin-Opener-Policy-Report-Only</code>`</li>
<li>`<code>Origin-Agent-Cluster</code>`</li>
<li>`<code>Refresh</code>`</li>
<li>`<code>X-Frame-Options</code>`</li>
</ul>
<h3 class="no-num">MIME types</h3>
<!-- NON-NORMATIVE SECTION -->
<p>The following MIME types are mentioned in this specification:</p>
<dl>
<dt><dfn><code>application/atom+xml</code></dfn></dt>
<dd>Atom <ref>ATOM</ref></dd>
<dt><dfn><code>application/json</code></dfn></dt>
<dd>JSON <ref>JSON</ref></dd>
<dt><dfn data-x-href="https://www.rfc-editor.org/rfc/rfc2046#section-4.5.1"><code>application/octet-stream</code></dfn></dt>
<dd>Generic binary data <ref>RFC2046</ref></dd>
<dt><code>application/microdata+json</code></dt>
<dd>Microdata as JSON
<dt><dfn><code>application/rss+xml</code></dfn></dt>
<dd>RSS <!--<ref>RSS</ref>-->
<dt><dfn><code>application/wasm</code></dfn></dt>
<dd>WebAssembly <ref>WASM</ref></dd>
<dt><code>application/x-www-form-urlencoded</code></dt>
<dd>Form submission</dd>
<dt><code>application/xhtml+xml</code></dt>
<dd>HTML</dd>
<dt><dfn><code>application/xml</code></dfn></dt>
<dd>XML <ref>XML</ref> <ref>RFC7303</ref></dd>
<dt><dfn><code>image/gif</code></dfn></dt>
<dd>GIF images <ref>GIF</ref></dd>
<dt><dfn><code>image/jpeg</code></dfn></dt>
<dd>JPEG images <ref>JPEG</ref></dd>
<dt><dfn><code>image/png</code></dfn></dt>
<dd>PNG images <ref>PNG</ref></dd>
<dt><dfn><code>image/svg+xml</code></dfn></dt>
<dd>SVG images <ref>SVG</ref></dd>
<dt><dfn><code>multipart/form-data</code></dfn></dt>
<dd>Form submission <ref>RFC7578</ref></dd>
<dt><dfn><code>multipart/mixed</code></dfn></dt>
<dd>Generic mixed content <ref>RFC2046</ref></dd>
<dt><code>multipart/x-mixed-replace</code></dt>
<dd>Streaming server push</dd>
<dt><dfn><code>text/css</code></dfn></dt>
<dd>CSS <ref>CSS</ref></dd>
<dt><code>text/event-stream</code></dt>
<dd>Server-sent event streams</dd>
<dt><dfn><code>text/javascript</code></dfn></dt>
<dd>JavaScript <ref>JAVASCRIPT</ref> <ref>RFC9239</ref>
<!--
<dt><dfn><code>text/javascript;e4x=1</code></dfn></dt>
<dd>E4X <ref>E4X</ref>
-->
<dt><dfn><code>text/json</code></dfn></dt>
<dd>JSON (legacy type)</dd>
<dt><dfn data-x-href="https://www.rfc-editor.org/rfc/rfc2046#section-4.1.3"><code>text/plain</code></dfn></dt>
<dd>Generic plain text <ref>RFC2046</ref> <ref>RFC3676</ref></dd>
<dt><code>text/html</code></dt>
<dd>HTML</dd>
<dt><code>text/ping</code></dt>
<dd>Hyperlink auditing</dd>
<dt><dfn><code>text/uri-list</code></dfn></dt>
<dd>List of URLs <ref>RFC2483</ref>
<dt><dfn><code>text/vcard</code></dfn></dt>
<dd>vCard <ref>RFC6350</ref>
<dt><dfn><code>text/vtt</code></dfn></dt>
<dd>WebVTT <ref>WEBVTT</ref></dd>
<dt><dfn><code>text/xml</code></dfn></dt>
<dd>XML <ref>XML</ref> <ref>RFC7303</ref></dd>
<dt><dfn data-x-href="https://www.rfc-editor.org/rfc/rfc4337#section-3"><code>video/mp4</code></dfn></dt>
<dd>MPEG-4 video <ref>RFC4337</ref></dd>
<dt><dfn><code>video/mpeg</code></dfn></dt>
<dd>MPEG video <ref>RFC2046</ref></dd>
</dl>
<h2 split-filename="references" class="no-num" id="references">References</h2><!--REFS-->
<p>All references are normative unless marked "Non-normative".</p>
<!-- Dates are only included for standards older than the web, because the newer ones keep changing. -->
<dl id="ref-list">
<dt id="refsABNF">[ABNF]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a></cite>, D. Crocker, P. Overell. IETF.</dd>
<dt id="refsABOUT">[ABOUT]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6694">The 'about' URI scheme</a></cite>, S. Moonesamy. IETF.</dd>
<dt id="refsAPNG">[APNG]</dt>
<dd>(Non-normative) <cite><a href="https://wiki.mozilla.org/APNG_Specification">APNG Specification</a></cite>. S. Parmenter, V. Vukicevic, A. Smith. Mozilla.</dd>
<dt id="refsARIA">[ARIA]</dt>
<dd><cite><a href="https://w3c.github.io/aria/">Accessible Rich Internet Applications (WAI-ARIA)</a></cite>, J. Diggs, J. Nurthen, M. Cooper. W3C.</dd>
<dt id="refsARIAHTML">[ARIAHTML]</dt>
<dd><cite><a href="https://w3c.github.io/html-aria/">ARIA in HTML</a></cite>, S. Faulkner, S. O'Hara. W3C.</dd>
<dt id="refsATAG">[ATAG]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/TR/ATAG20/">Authoring Tool Accessibility Guidelines (ATAG) 2.0</a></cite>, J. Richards, J. Spellman, J. Treviranus. W3C.</dd>
<dt id="refsATOM">[ATOM]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc4287">The Atom Syndication Format</a></cite>, M. Nottingham, R. Sayre. IETF.</dd>
<dt id="refsBATTERY">[BATTERY]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/battery/">Battery Status API</a></cite>, A. Kostiainen, M. Lamouri. W3C.</dd>
<dt id="refsBCP47">[BCP47]</dt>
<dd><cite><a href="https://www.rfc-editor.org/info/bcp47">Tags for Identifying Languages; Matching of Language Tags</a></cite>, A. Phillips, M. Davis. IETF.</dd>
<dt id="refsBEZIER">[BEZIER]</dt>
<dd><cite>Courbes à poles</cite>, P. de Casteljau. INPI, 1959.</dd>
<dt id="refsBIDI">[BIDI]</dt>
<dd><cite><a href="https://www.unicode.org/reports/tr9/">UAX #9: Unicode Bidirectional Algorithm</a></cite>, M. Davis. Unicode Consortium.</dd>
<dt id="refsBOCU1">[BOCU1]</dt>
<dd>(Non-normative) <cite><a href="https://www.unicode.org/notes/tn6/">UTN #6: BOCU-1: MIME-Compatible Unicode Compression</a></cite>, M. Scherer, M. Davis. Unicode Consortium.</dd>
<dt id="refsCESU8">[CESU8]</dt>
<dd>(Non-normative) <cite><a href="https://www.unicode.org/reports/tr26/">UTR #26: Compatibility Encoding Scheme For UTF-16: 8-BIT (CESU-8)</a></cite>, T. Phipps. Unicode Consortium.</dd>
<dt id="refsCHARMOD">[CHARMOD]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/TR/charmod/">Character Model for the World Wide Web 1.0: Fundamentals</a></cite>, M. Dürst, F. Yergeau, R. Ishida, M. Wolf, T. Texin. W3C.</dd>
<dt id="refsCHARMODNORM">[CHARMODNORM]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/charmod-norm/">Character Model for the World Wide Web: String Matching</a></cite>, A. Phillips. W3C.</dd>
<dt id="refsCLIPBOARD-APIS">[CLIPBOARD-APIS]</dt>
<dd><cite><a href="https://w3c.github.io/clipboard-apis/">Clipboard API and events</a></cite>, G. Kacmarcik, A. Snigdha. W3C.</dd>
<dt id="refsCOMPOSITE">[COMPOSITE]</dt>
<dd><cite><a href="https://drafts.fxtf.org/compositing/">Compositing and Blending</a></cite>, R. Cabanier, N. Andronikos. W3C.</dd>
<dt id="refsCOMPUTABLE">[COMPUTABLE]</dt>
<dd>(Non-normative) <cite><a href="http://www.turingarchive.org/browse.php/B/12">On computable numbers, with an application to the Entscheidungsproblem</a></cite>, A. Turing. In <cite>Proceedings of the London Mathematical Society</cite>, series 2, volume 42, pages 230-265. London Mathematical Society, 1937.</dd>
<dt id="refsCOMPUTEPRESSURE">[COMPUTEPRESSURE]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/compute-pressure/">Compute Pressure</a></cite>, K. Christiansen, A. Mandy. W3C.</dd>
<dt id="refsCONSOLE">[CONSOLE]</dt>
<dd><cite><a href="https://console.spec.whatwg.org/">Console</a></cite>, T. Stock, R. Kowalski, D. Farolino. WHATWG.</dd>
<dt id="refsCOOKIES">[COOKIES]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc6265.html">HTTP State Management Mechanism</a></cite>, A. Barth. IETF.</dd>
<dt id="refsCREDMAN">[CREDMAN]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-credential-management/">Credential Management</a></cite>, N. Satragno, J. Hodges, M. West. W3C.</dd>
<dt id="refsCSP">[CSP]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-csp/">Content Security Policy</a></cite>, M. West, D. Veditz. W3C.</dd>
<dt id="refsCSS">[CSS]</dt>
<dd><cite><a href="https://drafts.csswg.org/css2/">Cascading Style Sheets Level 2 Revision 2</a></cite>, B. Bos, T. Çelik, I. Hickson, H. Lie. W3C.</dd>
<dt id="refsCSSALIGN">[CSSALIGN]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-align/">CSS Box Alignment</a></cite>, E. Etemad, T. Atkins. W3C.</dd>
<dt id="refsCSSANCHOR">[CSSANCHOR]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-anchor-position/">CSS Anchor Positioning</a></cite>, T. Atkins, E. Etemad, I. Kilpatrick. W3C.</dd>
<dt id="refsCSSANIMATIONS">[CSSANIMATIONS]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-animations/">CSS Animations</a></cite>, D. Jackson, D. Hyatt, C. Marrin, S. Galineau, L. Baron. W3C.</dd>
<dt id="refsCSSATTR">[CSSATTR]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-style-attr/">CSS Style Attributes</a></cite>, T. Çelik, E. Etemad. W3C.</dd>
<dt id="refsCSSBG">[CSSBG]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-backgrounds/">CSS Backgrounds and Borders</a></cite>, B. Bos, E. Etemad, B. Kemper. W3C.</dd>
<dt id="refsCSSBOX">[CSSBOX]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-box-3/">CSS Box Model</a></cite>, E. Etemad. W3C.</dd>
<dt id="refsCSSCASCADE">[CSSCASCADE]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-cascade/">CSS Cascading and Inheritance</a></cite>, E. Etemad, T. Atkins. W3C.</dd>
<dt id="refsCSSCONTAIN">[CSSCONTAIN]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-contain/">CSS Containment</a></cite>, T. Atkins, F. Rivoal, V. Levin. W3C.</dd>
<dt id="refsCSSCOLOR">[CSSCOLOR]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-color/">CSS Color Module</a></cite>, T. Çelik, C. Lilley, L. Baron. W3C.</dd>
<dt id="refsCSSCOLORADJUST">[CSSCOLORADJUST]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-color-adjust/">CSS Color Adjustment Module</a></cite>, E. Etemad, R. Atanassov, R. Lillesveen, T. Atkins. W3C.</dd>
<dt id="refsCSSDEVICEADAPT">[CSSDEVICEADAPT]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-device-adapt/">CSS Device Adaption</a></cite>, F. Rivoal, M. Rakow. W3C.</dd>
<dt id="refsCSSDISPLAY">[CSSDISPLAY]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-display/">CSS Display</a></cite>, T. Atkins, E. Etemad. W3C.</dd>
<dt id="refsCSSFONTLOAD">[CSSFONTLOAD]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-font-loading/">CSS Font Loading</a></cite>, T. Atkins, J. Daggett. W3C.</dd>
<dt id="refsCSSFONTS">[CSSFONTS]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-fonts/">CSS Fonts</a></cite>, J. Daggett. W3C.</dd>
<dt id="refsCSSFLEXBOX">[CSSFLEXBOX]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-flexbox/">CSS Flexible Box Layout</a></cite>, T. Atkins, E. Etemad, R. Atanassov. W3C.</dd>
<dt id="refsCSSGC">[CSSGC]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-content/">CSS Generated Content</a></cite>, H. Lie, E. Etemad, I. Hickson. W3C.</dd>
<dt id="refsCSSGRID">[CSSGRID]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-grid/">CSS Grid Layout</a></cite>, T. Atkins, E. Etemad, R. Atanassov. W3C.</dd>
<dt id="refsCSSIMAGES">[CSSIMAGES]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-images/">CSS Images Module</a></cite>, E. Etemad, T. Atkins, L. Verou. W3C.</dd>
<dt id="refsCSSIMAGES4">[CSSIMAGES4]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-images-4/">CSS Images Module Level 4</a></cite>, E. Etemad, T. Atkins, L. Verou. W3C.</dd>
<dt id="refsCSSINLINE">[CSSINLINE]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-inline/">CSS Inline Layout</a></cite>, D. Cramer, E. Etemad. W3C.</dd>
<dt id="refsCSSLISTS">[CSSLISTS]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-lists/">CSS Lists and Counters</a></cite>, T. Atkins. W3C.</dd>
<dt id="refsCSSLOGICAL">[CSSLOGICAL]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-logical/">CSS Logical Properties</a></cite>, R. Atanassov, E. Etemad. W3C.</dd>
<dt id="refsCSSMULTICOL">[CSSMULTICOL]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-multicol/">CSS Multi-column Layout</a></cite>, H. Lie, F. Rivoal, R. Andrew. W3C.</dd>
<dt id="refsCSSOM">[CSSOM]</dt>
<dd><cite><a href="https://drafts.csswg.org/cssom/">Cascading Style Sheets Object Model (CSSOM)</a></cite>, S. Pieters, G. Adams. W3C.</dd>
<dt id="refsCSSOMVIEW">[CSSOMVIEW]</dt>
<dd><cite><a href="https://drafts.csswg.org/cssom-view/">CSSOM View Module</a></cite>, S. Pieters, G. Adams. W3C.</dd>
<dt id="refsCSSOVERFLOW">[CSSOVERFLOW]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-overflow-3/">CSS Overflow Module</a></cite>, L. Baron, F. Rivoal. W3C.</dd>
<dt id="refsCSSPAINT">[CSSPAINT]</dt>
<dd>(Non-normative) <cite><a href="https://drafts.css-houdini.org/css-paint-api/">CSS Painting API</a></cite>, I. Kilpatrick, D. Jackson. W3C.</dd>
<dt id="refsCSSPOSITION">[CSSPOSITION]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-position/">CSS Positioned Layout</a></cite>, R. Atanassov, A. Eicholz. W3C.</dd>
<dt id="refsCSSPSEUDO">[CSSPSEUDO]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-pseudo/">CSS Pseudo-Elements</a></cite>, D. Glazman, E. Etemad, A. Stearns. W3C.</dd>
<dt id="refsCSSRUBY">[CSSRUBY]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-ruby/">CSS3 Ruby Module</a></cite>, R. Ishida. W3C.</dd>
<dt id="refsCSSSCOPING">[CSSSCOPING]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-scoping/">CSS Scoping Module</a></cite>, T. Atkins. W3C.</dd>
<dt id="refsCSSSIZING">[CSSSIZING]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-sizing/">CSS Box Sizing Module</a></cite>, T. Atkins, E. Etemad. W3C.</dd>
<dt id="refsCSSSCROLLANCHORING">[CSSSCROLLANCHORING]</dt>
<dd>(Non-normative) <cite><a href="https://drafts.csswg.org/css-scroll-anchoring/">CSS Scroll Anchoring</a></cite>, T. Atkins-Bittner. W3C.</dd>
<dt id="refsCSSSYNTAX">[CSSSYNTAX]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-syntax/">CSS Syntax</a></cite>, T. Atkins, S. Sapin. W3C.</dd>
<dt id="refsCSSTRANSITIONS">[CSSTRANSITIONS]</dt>
<dd>(Non-normative) <cite><a href="https://drafts.csswg.org/css-transitions/">CSS Transitions</a></cite>, L. Baron, D. Jackson, B. Birtles. W3C.</dd>
<dt id="refsCSSTABLE">[CSSTABLE]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-tables/">CSS Table</a></cite>, F. Remy, G. Whitworth. W3C.</dd>
<dt id="refsCSSTEXT">[CSSTEXT]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-text/">CSS Text</a></cite>, E. Etemad, K. Ishii. W3C.</dd>
<dt id="refsCSSVALUES">[CSSVALUES]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-values/">CSS3 Values and Units</a></cite>, H. Lie, T. Atkins, E. Etemad. W3C.</dd>
<dt id="refsCSSVIEWTRANSITIONS">[CSSVIEWTRANSITIONS]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-view-transitions/">CSS View Transitions</a></cite>, T. Atkins Jr.; J. Archibald; K Sagar. W3C.</dd>
<dt id="refsCSSUI">[CSSUI]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-ui/">CSS3 Basic User Interface Module</a></cite>, F. Rivoal. W3C.</dd>
<dt id="refsCSSWM">[CSSWM]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-writing-modes/">CSS Writing Modes</a></cite>, E. Etemad, K. Ishii. W3C.</dd>
<dt id="refsDASH">[DASH]</dt>
<dd><cite><a href="https://www.iso.org/standard/65274.html">Dynamic adaptive streaming over HTTP (DASH)</a></cite>. ISO.</dd>
<dt id="refsDEVICEPOSTURE">[DEVICEPOSTURE]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/device-posture/">Device Posture API</a></cite>, D. Gonzalez-Zuniga, K. Christiansen. W3C.</dd>
<dt id="refsDOM">[DOM]</dt>
<dd><cite><a href="https://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
<dt id="refsDOMPARSING">[DOMPARSING]</dt>
<dd><cite><a href="https://w3c.github.io/DOM-Parsing/">DOM Parsing and Serialization</a></cite>, T. Leithead. W3C.</dd>
<dt id="refsDOT">[DOT]</dt>
<dd>(Non-normative) <cite><a href="https://graphviz.org/doc/info/lang.html">The DOT Language</a></cite>. Graphviz.</dd>
<dt id="refsE163">[E163]</dt>
<dd><cite>Recommendation E.163 — Numbering Plan for The International Telephone Service</cite>, CCITT Blue Book, Fascicle II.2, pp. 128-134, November 1988.</dd>
<dt id="refsENCODING">[ENCODING]</dt>
<dd><cite><a href="https://encoding.spec.whatwg.org/">Encoding</a></cite>, A. van Kesteren, J. Bell. WHATWG.</dd>
<dt id="refsEXECCOMMAND">[EXECCOMMAND]</dt>
<dd><cite><a href="https://w3c.github.io/editing/docs/execCommand/">execCommand</a></cite>, J. Wilm, A. Gregor. W3C Editing APIs CG.</dd>
<dt id="refsEXIF">[EXIF]</dt>
<dd>(Non-normative) <cite><a href="https://www.jeita.or.jp/cgi-bin/standard_e/list.cgi?cateid=1&subcateid=4">Exchangeable image file format</a></cite>. JEITA.</dd>
<dt id="refsFETCH">[FETCH]</dt>
<dd><cite><a href="https://fetch.spec.whatwg.org/">Fetch</a></cite>, A. van Kesteren. WHATWG.</dd>
<dt id="refsFETCHMETADATA">[FETCH-METADATA]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-fetch-metadata/">Fetch Metadata Request Headers</a></cite>, M.West. W3C.</dd>
<dt id="refsFILEAPI">[FILEAPI]</dt>
<dd><cite><a href="https://w3c.github.io/FileAPI/">File API</a></cite>, A. Ranganathan. W3C.</dd>
<dt id="refsFILTERS">[FILTERS]</dt>
<dd><cite><a href="https://drafts.fxtf.org/filter-effects/">Filter Effects</a></cite>, D. Schulze, D. Jackson, C. Harrelson. W3C.</dd>
<dt id="refsFULLSCREEN">[FULLSCREEN]</dt>
<dd><cite><a href="https://fullscreen.spec.whatwg.org/">Fullscreen</a></cite>, A. van Kesteren, T. Çelik. WHATWG.</dd>
<dt id="refsGEOMETRY">[GEOMETRY]</dt>
<dd><cite><a href="https://drafts.fxtf.org/geometry/">Geometry Interfaces</a></cite>. S. Pieters, D. Schulze, R. Cabanier. W3C.</dd>
<dt id="refsGIF">[GIF]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/Graphics/GIF/spec-gif89a.txt">Graphics Interchange Format</a></cite>. CompuServe.</dd>
<dt id="refsGRAPHICS">[GRAPHICS]</dt>
<dd>(Non-normative) <cite>Computer Graphics: Principles and Practice in C</cite>, Second Edition, J. Foley, A. van Dam, S. Feiner, J. Hughes. Addison-Wesley. ISBN 0-201-84840-6.</dd>
<!--
This book ("Computer Graphics: Principles and Practice in C") apparently does not make any
references to literature in the bibliographic section to define the "even-odd" rule for polygon
filling and hit testing. In the absence of such a reference, I guess that this book is the most
authoritative reference.
-->
<dt id="refsGREGORIAN">[GREGORIAN]</dt>
<dd>(Non-normative) <cite>Inter Gravissimas</cite>, A. Lilius, C. Clavius. Gregory XIII Papal Bull, February 1582.</dd>
<dt id="refsHRT">[HRT]</dt>
<dd><cite><a href="https://w3c.github.io/hr-time/">High Resolution Time</a></cite>, I. Grigorik, J. Simonsen, J. Mann. W3C.</dd>
<dt id="refsHTMLAAM">[HTMLAAM]</dt>
<dd><cite><a href="https://w3c.github.io/html-aam/">HTML Accessibility API Mappings 1.0</a></cite>, S. Faulkner, A. Surkov, S. O'Hara. W3C.</dd>
<dt id="refsHTTP">[HTTP]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc7230.html">Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</a></cite>, R. Fielding, J. Reschke. IETF.</dd>
<dd><cite><a href="https://httpwg.org/specs/rfc7231.html">Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</a></cite>, R. Fielding, J. Reschke. IETF.</dd>
<dd><cite><a href="https://httpwg.org/specs/rfc7232.html">Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</a></cite>, R. Fielding, J. Reschke. IETF.</dd>
<dd><cite><a href="https://httpwg.org/specs/rfc7233.html">Hypertext Transfer Protocol (HTTP/1.1): Range Requests</a></cite>, R. Fielding, Y. Lafon, J. Reschke. IETF.</dd>
<dd><cite><a href="https://httpwg.org/specs/rfc7234.html">Hypertext Transfer Protocol (HTTP/1.1): Caching</a></cite>, R. Fielding, M. Nottingham, J. Reschke. IETF.</dd>
<dd><cite><a href="https://httpwg.org/specs/rfc7235.html">Hypertext Transfer Protocol (HTTP/1.1): Authentication</a></cite>, R. Fielding, J. Reschke. IETF.</dd>
<dt id="refsINDEXEDDB">[INDEXEDDB]</dt>
<dd><cite><a href="https://w3c.github.io/IndexedDB/">Indexed Database API</a></cite>, A. Alabbas, J. Bell. W3C.</dd>
<dt id="refsINBAND">[INBAND]</dt>
<dd><cite><a href="https://dev.w3.org/html5/html-sourcing-inband-tracks/">Sourcing In-band Media Resource Tracks from Media Containers into HTML</a></cite>, S. Pfeiffer, B. Lund. W3C.</dd>
<dt id="refsINFRA">[INFRA]</dt>
<dd><cite><a href="https://infra.spec.whatwg.org/">Infra</a></cite>, A. van Kesteren, D. Denicola. WHATWG.</dd>
<dt id="refsINTERSECTIONOBSERVER">[INTERSECTIONOBSERVER]</dt>
<dd><cite><a href="https://w3c.github.io/IntersectionObserver/">Intersection Observer</a></cite>, S. Zager. W3C.</dd>
<dt id="refsRESIZEOBSERVER">[RESIZEOBSERVER]</dt>
<dd><cite><a href="https://drafts.csswg.org/resize-observer-1/">Resize Observer</a></cite>, O. Brufau, E. Álvarez. W3C.</dd>
<dt id="refsISO3166">[ISO3166]</dt>
<dd><cite><a href="https://www.iso.org/iso-3166-country-codes.html">ISO 3166: Codes for the representation of names of countries and their subdivisions</a></cite>. ISO.</dd>
<dt id="refsISO4217">[ISO4217]</dt>
<dd><cite><a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217: Codes for the representation of currencies and funds</a></cite>. ISO.</dd>
<dt id="refsISO8601">[ISO8601]</dt>
<dd>(Non-normative) <cite><a href="http://isotc.iso.org/livelink/livelink/4021199/ISO_8601_2004_E.zip?func=doc.Fetch&nodeid=4021199">ISO8601: Data elements and interchange formats — Information interchange — Representation of dates and times</a></cite>. ISO.</dd>
<dt id="refsJAVASCRIPT">[JAVASCRIPT]</dt>
<dd><cite><a href="https://tc39.es/ecma262/">ECMAScript Language Specification</a></cite>. Ecma International.</dd>
<dt id="refsJLREQ">[JLREQ]</dt>
<dd><cite><a href="https://www.w3.org/TR/jlreq/">Requirements for Japanese Text Layout</a></cite>. W3C.</dd> <!-- too many editors to list -->
<dt id="refsJPEG">[JPEG]</dt>
<dd><cite><a href="https://www.w3.org/Graphics/JPEG/jfif3.pdf">JPEG File Interchange Format</a></cite>, E. Hamilton.</dd>
<dt id="refsJSERRORSTACKS">[JSERRORSTACKS]</dt>
<dd>(Non-normative) <cite><a href="https://tc39.es/proposal-error-stacks/">Error Stacks</a></cite>. Ecma International.</dd>
<dt id="refsJSDYNAMICCODEBRANDCHECKS">[JSDYNAMICCODEBRANDCHECKS]</dt>
<dd><cite><a href="https://tc39.es/proposal-dynamic-code-brand-checks/">Dynamic code brand checks</a></cite>. Ecma International.</dd>
<dt id="refsJSINTL">[JSINTL]</dt>
<dd><cite><a href="https://tc39.es/ecma402/">ECMAScript Internationalization API Specification</a></cite>. Ecma International.</dd>
<dt id="refsJSON">[JSON]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc8259">The JavaScript Object Notation (JSON) Data Interchange Format</a></cite>, T. Bray. IETF.</dd>
<dt id="refsJSTEMPORAL">[JSTEMPORAL]</dt>
<dd><cite><a href="https://tc39.es/proposal-temporal/">Temporal</a></cite>. Ecma International.</dd>
<dt id="refsLONGTASKS">[LONGTASKS]</dt>
<dd><cite><a href="https://w3c.github.io/longtasks/">Long Tasks</a></cite>, D. Denicola, I. Grigorik, S. Panicker. W3C.</dd>
<dt id="refsLONGANIMATIONFRAMES">[LONGANIMATIONFRAMES]</dt>
<dd><cite><a href="https://w3c.github.io/long-animation-frames/">Long Animation Frames</a></cite>, N. Rosenthal. W3C.</dd>
<dt id="refsMAILTO">[MAILTO]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc6068">The 'mailto' URI scheme</a></cite>, M. Duerst, L. Masinter, J. Zawinski. IETF.</dd>
<dt id="refsMANIFEST">[MANIFEST]</dt>
<dd><cite><a href="https://www.w3.org/TR/appmanifest/">Web App Manifest</a></cite>, M. Caceres, K. Rohde Christiansen, M. Lamouri, A. Kostiainen, M. Giuca, A. Gustafson. W3C.</dd>
<dt id="refsMATHML">[MATHMLCORE]</dt>
<dd><cite><a href="https://w3c.github.io/mathml-core/">Mathematical Markup Language (MathML)</a></cite>, D. Carlisle, Frédéric Wang. W3C.</dd>
<dt id="refsMEDIAFRAG">[MEDIAFRAG]</dt>
<dd><cite><a href="https://www.w3.org/TR/media-frags/">Media Fragments URI</a></cite>, R. Troncy, E. Mannens, S. Pfeiffer, D. Van Deursen. W3C.</dd>
<dt id="refsMEDIASOURCE">[MEDIASOURCE]</dt>
<dd><cite><a href="https://w3c.github.io/media-source/">Media Source Extensions</a></cite>, A. Colwell, A. Bateman, M. Watson. W3C.</dd>
<dt id="refsMEDIASTREAM">[MEDIASTREAM]</dt>
<dd><cite><a href="https://w3c.github.io/mediacapture-main/getusermedia.html">Media Capture and Streams</a></cite>, D. Burnett, A. Bergkvist, C. Jennings, A. Narayanan. W3C.</dd>
<dt id="refsREPORTING">[REPORTING]</dt>
<dd><cite><a href="https://w3c.github.io/reporting/">Reporting</a></cite>, D. Creager, I. Clelland, M. West. W3C.</dd>
<dt id="refsMFREL">[MFREL]</dt>
<dd><cite><a href="https://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions">Microformats Wiki: existing rel values</a></cite>. Microformats.</dd>
<dt id="refsMIMESNIFF">[MIMESNIFF]</dt>
<dd><cite><a href="https://mimesniff.spec.whatwg.org/">MIME Sniffing</a></cite>, G. Hemsley. WHATWG.</dd>
<dt id="refsMIX">[MIX]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-mixed-content/">Mixed Content</a></cite>, M. West. W3C.</dd>
<dt id="refsMNG">[MNG]</dt>
<dd><cite><a href="http://www.libpng.org/pub/mng/spec/">MNG (Multiple-image Network Graphics) Format</a></cite>. G. Randers-Pehrson.</dd>
<dt id="refsMPEG2">[MPEG2]</dt>
<dd><cite>ISO/IEC 13818-1: Information technology — Generic coding of moving pictures and associated audio information: Systems</cite>. ISO/IEC.</dd>
<!-- search for ["bytes are removed from this buffer at a rate defined by sb_leak_rate"] to find it -->
<dt id="refsMPEG4">[MPEG4]</dt>
<dd><cite>ISO/IEC 14496-12: ISO base media file format</cite>. ISO/IEC.</dd>
<!-- search for ["Box Structure was and subsequent clauses were re-organized"] to find it -->
<dt id="refsMQ">[MQ]</dt>
<dd><cite><a href="https://drafts.csswg.org/mediaqueries/">Media Queries</a></cite>, H. Lie, T. Çelik, D. Glazman, A. van Kesteren. W3C.</dd>
<dt id="refsMULTIPLEBUFFERING">[MULTIPLEBUFFERING]</dt>
<dd>(Non-normative) <cite><a href="https://en.wikipedia.org/wiki/Multiple_buffering">Multiple buffering</a></cite>. Wikipedia.</dd>
<dt id="refsNAVIGATIONTIMING">[NAVIGATIONTIMING]</dt>
<dd><cite><a href="https://w3c.github.io/navigation-timing/">Navigation Timing</a></cite>, Y. Weiss. W3C.</dd>
<dt id="refsNPAPI">[NPAPI]</dt>
<dd>(Non-normative) <cite><a href="https://developer.mozilla.org/en-US/docs/Plugins/Guide">Gecko Plugin API Reference</a></cite>. Mozilla.</dd>
<dt id="refsOGGSKELETONHEADERS">[OGGSKELETONHEADERS]</dt>
<dd><cite><a href="https://wiki.xiph.org/SkeletonHeaders">SkeletonHeaders</a></cite>. Xiph.Org.</dd>
<dt id="refsOPENSEARCH">[OPENSEARCH]</dt>
<dd><cite><a href="https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md#autodiscovery-in-htmlxhtml">Autodiscovery in HTML/XHTML</a></cite>. In <cite>OpenSearch 1.1 Draft 6</cite>. GitHub.</dd>
<dt id="refsORIGIN">[ORIGIN]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc6454">The Web Origin Concept</a></cite>, A. Barth. IETF.</dd>
<dt id="refsPAINTTIMING">[PAINTTIMING]</dt>
<dd><cite><a href="https://w3c.github.io/paint-timing/">Paint Timing</a></cite>, S. Panicker. W3C.</dd>
<dt id="refsPAYMENTREQUEST">[PAYMENTREQUEST]</dt>
<dd><cite><a href="https://w3c.github.io/payment-request/">Payment Request API</a></cite>, M. Cáceres, D. Wang, R. Solomakhin, I. Jacobs. W3C.</dd>
<dt id="refsPDF">[PDF]</dt>
<dd>(Non-normative) <cite><a href="https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf">Document management — Portable document format — Part 1: PDF</a></cite>. ISO.</dd>
<dt id="refsPERFORMANCETIMELINE">[PERFORMANCETIMELINE]</dt>
<dd><cite><a href="https://w3c.github.io/performance-timeline/">Performance Timeline</a></cite>, N. Peña Moreno, W3C.</dd>
<dt id="refsPERMISSIONSPOLICY">[PERMISSIONSPOLICY]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-feature-policy/">Permissions Policy</a></cite>, I. Clelland, W3C.</dd>
<dt id="refsPICTUREINPICTURE">[PICTUREINPICTURE]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/picture-in-picture/">Picture-in-Picture</a></cite>, F. Beaufort, M. Lamouri, W3C</dd>
<dt id="refsPINGBACK">[PINGBACK]</dt>
<dd><cite><a href="https://www.hixie.ch/specs/pingback/pingback">Pingback 1.0</a></cite>, S. Langridge, I. Hickson.</dd>
<dt id="refsPNG">[PNG]</dt>
<dd><cite><a href="https://www.w3.org/TR/PNG/">Portable Network Graphics (PNG) Specification</a></cite>, D. Duce. W3C.</dd>
<dt id="refsPOINTEREVENTS">[POINTEREVENTS]</dt>
<dd><cite><a href="https://w3c.github.io/pointerevents/">Pointer Events</a></cite>, J. Rossi, M. Brubeck, R. Byers, P. H. Lauke. W3C.</dd>
<dt id="refsPOINTERLOCK">[POINTERLOCK]</dt>
<dd><cite><a href="https://w3c.github.io/pointerlock/">Pointer Lock</a></cite>, V. Scheib. W3C.</dd>
<dt id="refsPPUTF8">[PPUTF8]</dt>
<dd>(Non-normative) <cite><a href="https://www.sw.it.aoyama.ac.jp/2012/pub/IUC11-UTF-8.pdf">The Properties and Promises <!-- Promizes (sic) --> of UTF-8</a></cite>, M. Dürst. University of Zürich. In <cite>Proceedings of the 11th International Unicode Conference</cite>.</dd>
<dt id="refsPRESENTATION">[PRESENTATION]</dt>
<dd><cite><a href="https://w3c.github.io/presentation-api/">Presentation API</a></cite>, M. Foltz, D. Röttsches. W3C.</dd>
<dt id="refsREFERRERPOLICY">[REFERRERPOLICY]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-referrer-policy/">Referrer Policy</a></cite>, J. Eisinger, E. Stark. W3C.</dd>
<dt id="refsREQUESTIDLECALLBACK">[REQUESTIDLECALLBACK]</dt>
<dd><cite><a href="https://w3c.github.io/requestidlecallback/">Cooperative Scheduling of Background Tasks</a></cite>, R. McIlroy, I. Grigorik. W3C.</dd>
<dt id="refsRESOURCETIMING">[RESOURCETIMING]</dt>
<dd><cite><a href="https://w3c.github.io/resource-timing/">Resource Timing</a></cite>, Yoav Weiss; Noam Rosenthal. W3C.</dd>
<dt id="refsRFC1034">[RFC1034]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc1034">Domain Names - Concepts and Facilities</a></cite>, P. Mockapetris. IETF, November 1987.</dd>
<dt id="refsRFC1123">[RFC1123]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc1123">Requirements for Internet Hosts -- Application and Support</a></cite>, R. Braden. IETF, October 1989.</dd>
<dt id="refsRFC2046">[RFC2046]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc2046">Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</a></cite>, N. Freed, N. Borenstein. IETF.</dd> <!-- for text/plain and "Internet Media type"; not for definition of "MIME type". -->
<dt id="refsRFC2397">[RFC2397]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc2397">The "data" URL scheme</a></cite>, L. Masinter. IETF.</dd>
<dt id="refsRFC5545">[RFC5545]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc5545">Internet Calendaring and Scheduling Core Object Specification (iCalendar)</a></cite>, B. Desruisseaux. IETF.</dd>
<dt id="refsRFC2483">[RFC2483]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc2483">URI Resolution Services Necessary for URN Resolution</a></cite>, M. Mealling, R. Daniel. IETF.</dd>
<dt id="refsRFC3676">[RFC3676]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc3676">The Text/Plain Format and DelSp Parameters</a></cite>, R. Gellens. IETF.</dd>
<dt id="refsRFC9239">[RFC9239]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc9239">Updates to ECMAScript Media Types</a></cite>, M. Miller, M. Borins, M. Bynens, B. Farias. IETF.</dd>
<dt id="refsRFC4337">[RFC4337]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc4337">MIME Type Registration for MPEG-4</a></cite>, Y. Lim, D. Singer. IETF.</dd>
<dt id="refsRFC7595">[RFC7595]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc7595">Guidelines and Registration Procedures for URI Schemes</a></cite>, D. Thaler, T. Hansen, T. Hardie. IETF.</dd>
<dt id="refsRFC5322">[RFC5322]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc5322">Internet Message Format</a></cite>, P. Resnick. IETF.</dd>
<dt id="refsRFC6381">[RFC6381]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6381">The 'Codecs' and 'Profiles' Parameters for "Bucket" Media Types</a></cite>, R. Gellens, D. Singer, P. Frojdh. IETF.</dd>
<dt id="refsRFC6266">[RFC6266]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc6266.html">Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)</a></cite>, J. Reschke. IETF.</dd>
<dt id="refsRFC6350">[RFC6350]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6350">vCard Format Specification</a></cite>, S. Perreault. IETF.</dd>
<dt id="refsRFC6596">[RFC6596]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6596">The Canonical Link Relation</a></cite>, M. Ohye, J. Kupke. IETF.</dd>
<dt id="refsRFC6903">[RFC6903]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6903">Additional Link Relation Types</a></cite>, J. Snell. IETF.</dd>
<dt id="refsRFC7034">[RFC7034]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc7034">HTTP Header Field X-Frame-Options</a></cite>, D. Ross, T. Gondrom. IETF.</dd>
<dt id="refsRFC7303">[RFC7303]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc7303">XML Media Types</a></cite>, H. Thompson, C. Lilley. IETF.</dd>
<dt id="refsRFC7578">[RFC7578]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc7578">Returning Values from Forms: multipart/form-data</a></cite>, L. Masinter. IETF.</dd>
<dt id="refsRFC8297">[RFC8297]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc8297.html">An HTTP Status Code for Indicating Hints</a></cite>, K. Oku. IETF.</dd>
<dt id="refsSCREENORIENTATION">[SCREENORIENTATION]</dt>
<dd><cite><a href="https://w3c.github.io/screen-orientation/">Screen Orientation</a></cite>, M. Cáceres. W3C.</dd>
<dt id="refsSCSU">[SCSU]</dt>
<dd>(Non-normative) <cite><a href="https://www.unicode.org/reports/tr6/">UTR #6: A Standard Compression Scheme For Unicode</a></cite>, M. Wolf, K. Whistler, C. Wicksteed, M. Davis, A. Freytag, M. Scherer. Unicode Consortium.</dd>
<dt id="refsSECURE-CONTEXTS">[SECURE-CONTEXTS]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-secure-contexts/">Secure Contexts</a></cite>, M. West. W3C.</dd>
<dt id="refsSELECTION">[SELECTION]</dt>
<dd><cite><a href="https://w3c.github.io/selection-api/">Selection API</a></cite>, R. Niwa. W3C.</dd>
<dt id="refsSELECTORS">[SELECTORS]</dt>
<dd><cite><a href="https://drafts.csswg.org/selectors/">Selectors</a></cite>, E. Etemad, T. Çelik, D. Glazman, I. Hickson, P. Linss, J. Williams. W3C.</dd>
<dt id="refsSMS">[SMS]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc5724">URI Scheme for Global System for Mobile Communications (GSM) Short Message Service (SMS)</a></cite>, E. Wilde, A. Vaha-Sipila. IETF.</dd>
<dt id="refsSTRUCTURED-FIELDS">[STRUCTURED-FIELDS]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc8941.html">Structured Field Values for HTTP</a></cite>, M. Nottingham, P-H. Kamp. IETF.</dd>
<dt id="refsSRI">[SRI]</dt>
<dd><cite><a href="https://w3c.github.io/webappsec-subresource-integrity/">Subresource Integrity</a></cite>, D. Akhawe, F. Braun, F. Marier, J. Weinberger. W3C.</dd>
<dt id="refsSTORAGE">[STORAGE]</dt>
<dd><cite><a href="https://storage.spec.whatwg.org/">Storage</a></cite>, A. van Kesteren. WHATWG.</dd>
<dt id="refsSVG">[SVG]</dt>
<dd><cite><a href="https://svgwg.org/svg2-draft/">Scalable Vector Graphics (SVG) 2</a></cite>, N Andronikos, R. Atanassov, T. Bah, B. Birtles, B. Brinza, C. Concolato, E. Dahlström, C. Lilley, C. McCormack, D. Schepers, R. Schwerdtfeger, D. Storey, S. Takagi, J. Watt. W3C.</dd>
<dt id="refsSW">[SW]</dt>
<dd><cite><a href="https://w3c.github.io/ServiceWorker/">Service Workers</a></cite>, A. Russell, J. Song, J. Archibald. W3C.</dd>
<dt id="refsTOR">[TOR]</dt>
<dd>(Non-normative) <cite><a href="https://www.torproject.org/">Tor</a></cite>.</dd>
<dt id="refsTOUCH">[TOUCH]</dt>
<dd><cite><a href="https://w3c.github.io/touch-events/">Touch Events</a></cite>, D. Schepers, S. Moon, M. Brubeck, A. Barstow, R. Byers. W3C.</dd>
<dt id="refsTRUSTED-TYPES">[TRUSTED-TYPES]</dt>
<dd><cite><a href="https://w3c.github.io/trusted-types/dist/spec/">Trusted Types</a></cite>, K. Kotowicz, M. West. W3C.</dd>
<dt id="refsTZDATABASE">[TZDATABASE]</dt>
<dd>(Non-normative) <cite><a href="https://www.iana.org/time-zones">Time Zone Database</a></cite>. IANA.</dd>
<dt id="refsUAAG">[UAAG]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/TR/UAAG20/">User Agent Accessibility Guidelines (UAAG) 2.0</a></cite>, J. Allan, K. Ford, J. Richards, J. Spellman. W3C.</dd>
<dt id="refsUIEVENTS">[UIEVENTS]</dt>
<dd><cite><a href="https://w3c.github.io/uievents/">UI Events Specification</a></cite>, G. Kacmarcik, T. Leithead. W3C.</dd>
<!--(the above references to this are commented out)
<dt id="refsUNDO">[UNDO]</dt>
<dd><cite><a href="https://dvcs.w3.org/hg/undomanager/raw-file/tip/undomanager.html">UndoManager and DOM Transaction</a></cite>, R. Niwa.</dd>
-->
<dt id="refsUNICODE">[UNICODE]</dt>
<dd><cite><a href="https://www.unicode.org/versions/">The Unicode Standard</a></cite>. Unicode Consortium.</dd>
<dt id="refsUNIVCHARDET">[UNIVCHARDET]</dt>
<dd>(Non-normative) <cite><a href="https://www-archive.mozilla.org/projects/intl/UniversalCharsetDetection.html">A composite approach to language/encoding detection</a></cite>, S. Li, K. Momoi. Netscape. In <cite>Proceedings of the 19th International Unicode Conference</cite>.</dd>
<dt id="refsURL">[URL]</dt>
<dd><cite><a href="https://url.spec.whatwg.org/">URL</a></cite>, A. van Kesteren. WHATWG.</dd>
<dt id="refsURN">[URN]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc2141">URN Syntax</a></cite>, R. Moats. IETF.</dd>
<dt id="refsUTF7">[UTF7]</dt>
<dd>(Non-normative) <cite><a href="https://www.rfc-editor.org/rfc/rfc2152">UTF-7: A Mail-Safe Transformation Format of Unicode</a></cite>, D. Goldsmith, M. Davis. IETF.</dd>
<dt id="refsUTF8DET">[UTF8DET]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/International/questions/qa-forms-utf-8">Multilingual form encoding</a></cite>, M. Dürst. W3C.</dd>
<dt id="refsUTR36">[UTR36]</dt>
<dd>(Non-normative) <cite><a href="https://www.unicode.org/reports/tr36/">UTR #36: Unicode Security Considerations</a></cite>, M. Davis, M. Suignard. Unicode Consortium.</dd>
<dt id="refsWASM">[WASM]</dt>
<dd><cite><a href="https://webassembly.github.io/spec/core/bikeshed/index.html">WebAssembly Core Specification</a></cite>, A. Rossberg. W3C.</dd>
<dt id="refsWASMESM">[WASMESM]</dt>
<dd><cite><a href="https://webassembly.github.io/esm-integration/js-api/index.html">WebAssembly JavaScript Interface: ESM Integration</a></cite>, L. Clark, D. Ehrenberg., A. Takikawa., G. Bedford. W3C.</dd>
<dt id="refsWASMJS">[WASMJS]</dt>
<dd>(Non-normative) <cite><a href="https://webassembly.github.io/spec/js-api/">WebAssembly JavaScript Interface</a></cite>, D. Ehrenberg. W3C.</dd>
<dt id="refsWCAG">[WCAG]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/wcag/guidelines/">Web Content Accessibility Guidelines (WCAG)</a></cite>, A. Kirkpatrick, J. O Connor, A. Campbell, M. Cooper. W3C.</dd>
<dt id="refsWEBANIMATIONS">[WEBANIMATIONS]</dt>
<dd><cite><a href="https://drafts.csswg.org/web-animations-1/">Web Animations</a></cite>, B. Birtles, S. Stephens, D. Stockwell. W3C.</dd>
<dt id="refsWEBAUDIO">[WEBAUDIO]</dt>
<dd>(Non-normative) <cite><a href="https://webaudio.github.io/web-audio-api/">Web Audio API</a></cite>, P. Adenot, H. Choi. W3C.</dd>
<dt id="refsWEBAUTHN">[WEBAUTHN]</dt>
<dd><cite><a href="https://w3c.github.io/webauthn">Web Authentication: An API for accessing Public Key Credentials</a></cite>, M. Jones, A. Kumar, E. Lundberg, D. Balfanz, V. Bharadwaj, A. Birgisson, A. Czeskis, J. Hodges, J.C. Jones, H. Le Van Gong, A. Liao, R. Lindemann, J. Bradley, C. Brand, T. Cappalli, A. Langley, G. Mandyam, M. Miller, N. Satragno, N. Steele, J. Tan, S. Weeden, M. West, J. Yasskin. W3C.</dd>
<dt id="refsWEBCODECS">[WEBCODECS]</dt>
<dd><cite><a href="https://w3c.github.io/webcodecs/">WebCodecs API</a></cite>, C. Cunningham, P. Adenot, B. Aboba. W3C.</dd>
<dt id="refsWEBCRYPTO">[WEBCRYPTO]</dt>
<dd><cite><a href="https://w3c.github.io/webcrypto/Overview.html">Web Cryptography API</a></cite>, D. Huigens. W3C.</dd>
<dt id="refsWEBDRIVER">[WEBDRIVER]</dt>
<dd><cite><a href="https://w3c.github.io/webdriver/">WebDriver</a></cite>, S. Stewart, D. Burns. W3C.</dd>
<dt id="refsWEBDRIVERBIDI">[WEBDRIVERBIDI]</dt>
<dd><cite><a href="https://w3c.github.io/webdriver-bidi/">WebDriver BiDi</a></cite>. W3C</dd>
<dt id="refsWEBGL">[WEBGL]</dt>
<dd><cite><a href="https://www.khronos.org/registry/webgl/specs/latest/">WebGL Specifications</a></cite>, D. Jackson, J. Gilbert. Khronos Group.</dd>
<dt id="refsWEBGPU">[WEBGPU]</dt>
<dd><cite><a href="https://gpuweb.github.io/gpuweb/">WebGPU</a></cite>, D. Malyshau, K. Ninomiya. W3C.</dd>
<dt id="refsWEBIDL">[WEBIDL]</dt>
<dd><cite><a href="https://webidl.spec.whatwg.org/">Web IDL</a></cite>, E. Chen, T. Gu. WHATWG.</dd>
<dt id="refsWEBLINK">[WEBLINK]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc8288.html">Web Linking</a></cite>, M. Nottingham. IETF.</dd>
<dt id="refsWEBLOCKS">[WEBLOCKS]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/web-locks/">Web Locks API</a></cite>, J. Bell, K. Rosylight. W3C.</dd>
<dt id="refsWEBMCG">[WEBMCG]</dt>
<dd><cite><a href="https://www.webmproject.org/docs/container/">WebM Container Guidelines</a></cite>. The WebM Project.</dd>
<dt id="refsWEBNFC">[WEBNFC]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/web-nfc/">Web NFC</a></cite>, F. Beaufort, K. Christiansen, Z. Kis. W3C.</dd>
<dt id="refsWEBRTC">[WEBRTC]</dt>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/webrtc-pc/">Web RTC</a></cite>, C. Jennings, F. Castelli, H. Boström, J. Bruaroey. W3C.</dd>
<dt id="refsWEBSOCKETS">[WEBSOCKETS]</dt>
<dd><cite><a href="https://websockets.spec.whatwg.org/">WebSockets</a></cite>, A. Rice. WHATWG.</dd>
<dt id="refsWEBTRANSPORT">[WEBTRANSPORT]</dt>
<dd><cite><a href="https://w3c.github.io/webtransport/">WebTransport</a></cite>, B. Aboba, N. Jaju, V. Vasiliev. W3C.</dd>
<dt id="refsWEBVTT">[WEBVTT]</dt>
<dd><cite><a href="https://w3c.github.io/webvtt/">WebVTT</a></cite>, S. Pieters. W3C.</dd>
<dt id="refsWHATWGWIKI">[WHATWGWIKI]</dt>
<dd><cite><a href="https://wiki.whatwg.org/">The WHATWG Wiki</a></cite>. WHATWG.</dd>
<dt id="refsX121">[X121]</dt>
<dd><cite>Recommendation X.121 — International Numbering Plan for Public Data Networks</cite>, CCITT Blue Book, Fascicle VIII.3, pp. 317-332.</dd>
<dt id="refsXFN">[XFN]</dt>
<dd><cite><a href="https://gmpg.org/xfn/11">XFN 1.1 profile</a></cite>, T. Çelik, M. Mullenweg, E. Meyer. GMPG.</dd>
<dt id="refsXHR">[XHR]</dt>
<dd><cite><a href="https://xhr.spec.whatwg.org/"><code>XMLHttpRequest</code></a></cite>, A. van Kesteren. WHATWG.</dd>
<dt id="refsXKCD1288">[XKCD1288]</dt>
<dd>(Non-normative) <cite><a href="https://xkcd.com/1288/">Substitutions</a></cite>, Randall Munroe. xkcd.</dd>
<dt id="refsXML">[XML]</dt>
<dd><cite><a href="https://www.w3.org/TR/xml/">Extensible Markup Language</a></cite>, T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau. W3C.</dd>
<dt id="refsXMLENTITY">[XMLENTITY]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/2003/entities/2007doc/">XML Entity Definitions for Characters</a></cite>, D. Carlisle, P. Ion. W3C.</dd>
<dt id="refsXMLNS">[XMLNS]</dt>
<dd><cite><a href="https://www.w3.org/TR/xml-names/">Namespaces in XML</a></cite>, T. Bray, D. Hollander, A. Layman, R. Tobin. W3C.</dd>
<dt id="refsXMLSSPI">[XMLSSPI]</dt>
<dd><cite><a href="https://www.w3.org/TR/xml-stylesheet/">Associating Style Sheets with XML documents</a></cite>, J. Clark, S. Pieters, H. Thompson. W3C.</dd>
<dt id="refsXPATH10">[XPATH10]</dt>
<dd><cite><a href="https://www.w3.org/TR/1999/REC-xpath-19991116/">XML Path Language (XPath) Version 1.0</a></cite>, J. Clark, S. DeRose. W3C.</dd>
<dt id="refsXSLT10">[XSLT10]</dt>
<dd>(Non-normative) <cite><a href="https://www.w3.org/TR/1999/REC-xslt-19991116">XSL Transformations (XSLT) Version 1.0</a></cite>, J. Clark. W3C.</dd>
<dt id="refsXSLTP">[XSLTP]</dt>
<dd>(Non-normative) <cite><a href="https://wiki.whatwg.org/wiki/DOM_XSLTProcessor">DOM XSLTProcessor</a></cite>, WHATWG Wiki. WHATWG.</dd>
</dl>
<h2 split-filename="acknowledgements" id="acknowledgments" class="no-num">Acknowledgments</h2>
<!-- ACKS (the filename is in en-GB for historical reasons) -->
<p>Thanks to Tim Berners-Lee for inventing HTML, without which none of this would exist.</p>
<p>Thanks to
Aankhen,
Aaqa Ishtyaq,
Aaron Boodman,
Aaron Leventhal,
Aaron Krajeski,
Abhishek Ghaskata,
Abhishek Gupta, <!-- a1626 on GitHub -->
Adam Barth,
Adam de Boor,
Adam Hepton,
Adam Klein,
Adam Rice,
Adam Roben,
Addison Phillips,
Adele Peterson,
Adrian Bateman,
Adrian Roselli,
Adrian Sutton,
Agustín Fernández,
Aharon (Vladimir) Lanin,
Ajai Tirumali,
Ajay Poshak, <!-- ajayposhak on GitHub -->
Akash Balenalli,
Akatsuki Kitamura,
Alan Jeffrey, <!-- asajeffrey on GitHub -->
Alan Plum,
Alastair Campbell,
Alejandro G. Castro,
Alex Bishop,
Alex Nicolaou,
Alex Nozdriukhin,
Alex Rousskov,
Alex Soncodi,
Alexander Farkas,
Alexander J. Vincent,
Alexander Kalenik,
Alexandre Dieulot,
Alexandre Morgaut,
Alexey Feldgendler,
Алексей Проскуряков (Alexey Proskuryakov),
Alexey Shvayka,
Alexis Deveria,
Alfred Agrell, <!-- Alcaro on GitHub -->
Ali Juma,
Alice Boxhall,
Alice Wonder,
Allan Clements,
Allen Wirfs-Brock,
Alex Komoroske,
Alex Russell,
Alphan Chen,
Aman Ansari, <!-- aman-atg on Github -->
Ami Fischman,
Amos Jeffries,
Amos Lim,
Anders Carlsson,
André Bargull,
André E. Veltstra,
Andrea Rendine,
Andreas<!-- mqmq87 -->,
Andreas Deuschlinger, <!-- AndyOGo on GitHub -->
Andreas Farre,
Andreas Kling,
Andrei Popescu,
Andres Gomez,
Andres Rios,
Andreu Botella,
Andrew Barfield,
Andrew Clover,
Andrew Gove,
Andrew Grieve,
Andrew Kaster,
Andrew Macpherson, <!-- fuzzbomb on GitHub -->
Andrew Oakley,
Andrew Paseltiner,
Andrew Simons,
Andrew Smith,
Andrew W. Hagen,
Andrew Williams,
Andrey V. Lukyanov,
Andry Rendy,
Andy Davies,
Andy Earnshaw,
Andy Heydon,
Andy Paicu,
Andy Palay,
Anjana Vakil,
Ankur Kaushal,
Anna Belle Leiserson,
Anna Sidwell,
Anthony Boyd,
Anthony Bryan,
Anthony Hickson,
Anthony Ramine,
Anthony Ricaud,
Anton Vayvod,
Antonio Sartori,
Antti Koivisto,
Arfat Salman,
Arkadiusz Michalski,
Arne Thomassen,
Aron Spohr,
Arphen Lin,
Arthur Hemery,
Arthur Sonzogni, <!-- ArthurSonzogni on GitHub -->
Arthur Stolyar,
Arun Patole,
Aryeh Gregor,
Asanka Herath,
Asbjørn Ulsberg,
Ashley Gullen,
Ashley Sheridan,
Asumu Takikawa,
Atsushi Takayama,
Attila Haraszti,
Aurelien Levy,
Ave Wrigley,
Avi Drissman,
Axel Dahmen,
방성범 (Bang Seongbeom), <!-- bangseongbeom on GitHub -->
Barry Pollard, <!-- tunetheweb on GitHub -->
Ben Boyle,
Ben Godfrey,
Ben Golightly, <!-- golightlyb on GitHub -->
Ben Kelly,
Ben Lerner,
Ben Leslie,
Ben Meadowcroft,
Ben Millard,
Benjamin Carl Wiley Sittler,
Benjamin Hawkes-Lewis,
Benji Bilheimer, <!-- benjibee on GitHub -->
Benoit Ren,
Bert Bos,
Bijan Parsia,
Bil Corry,
Bill Mason,
Bill McCoy,
Billy Wong,
Billy Woods,
Bjartur Thorlacius,
Björn Höhrmann,
Blake Frantz,
Bob Lund,
Bob Owen,
Bobby Holley,
Boris Zbarsky,
Brad Fults,
Brad Neuberg,
Brad Spencer,
Bradley Meck,
Brady Eidson,
Brandon Jones,
Brendan Eich,
Brenton Simpson,
Brett Wilson,
Brett Zamir,
Brian Birtles,
Brian Blakely,
Brian Campbell,
Brian Korver,
Brian Kuhn,
Brian M. Dube,
Brian Ryner,
Brian Smith,
Brian Wilson,
Bryan Sullivan,
Bruce Bailey,
Bruce D'Arcus,
Bruce Lawson,
Bruce Miller,
Bugs Nash,
C. Scott Ananian,
C. Williams,
Cameron McCormack,
Cameron Zemek,
Cao Yipeng,
Carlos Amengual,
Carlos Gabriel Cardona,
Carlos Ibarra López, <!-- carlosjoan91 on GitHub -->
Carlos Perelló Marín,
Carolyn MacLeod,
Casey Leask,
Cătălin Badea,
Cătălin Mariș,
Cem Turesoy, <!-- ctur on GitHub -->
ceving, <!-- GitHub -->
Chao Cai,
윤석찬 (Channy Yun),
Charl van Niekerk,
Charlene Wright,
Charles Iliya Krempeaux,
Charles McCathie Nevile,
Charlie Reis,
白丞祐 (Cheng-You Bai), <!-- CYBAI on GitHub -->
Chris Apers,
Chris Cressman,
Chris Dumez,
Chris Evans,
Chris Harrelson,
Chris Markiewicz,
Chris Morris,
Chris Nardi,
Chris Needham,
Chris Pearce,
Chris Peterson,
Chris Rebert,
Chris Weber,
Chris Wilson,
Christian Biesinger,
Christian Johansen,
Christian Schmidt,
Christoph Päper,
Christophe Dumez,
Christopher Aillon,
Christopher Cameron,
Christopher Ferris,
Chriswa,
Clark Buehler,
Cole Robison,
Colin Fine,
Collin Jackson,
Corey Farwell,
Corprew Reed,
Craig Cockburn,
Csaba Gabor,
Csaba Marton,
Cynthia Shelly,
Cyrille Tuzi,
Daksh Shah,
Dan Callahan,
Dan Yoder,
Dane Foster, <!-- studdugie on GitHub -->
Daniel Barclay,
Daniel Bratell,
Daniel Brooks,
Daniel Brumbaugh Keeney,
Daniel Buchner,
Daniel Cheng,
Daniel Clark, <!-- dandclark on GitHub -->
Daniel Davis,
Daniel Ehrenberg,
Daniel Ethridge, <!-- wlib on GitHub -->
Daniel Glazman,
Daniel Holbert,
Daniel Peng,
Daniel Schattenkirchner,
Daniel Spång,
Daniel Steinberg,
Daniel Tan,
Daniel Trebbien,
Daniel Vogelheim,
Danny Sullivan,
Daphne Preston-Kendal,
Darien Maillet Valentine,
Darin Adler,
Darin Fisher,
Darxus,
Dave Camp,
Dave Cramer,
Dave Hodder,
Dave Lampton,
Dave Singer,
Dave Tapuska,
Dave Townsend<!-- Mossop on moz irc -->,
David Baron,
David Bloom,
David Bokan,
David Bruant,
David Carlisle,
David E. Cleary,
David Egan Evans,
David Fink,
David Flanagan,
David Gerard,
David Grogan,
David Hale,
David Håsäther,
David Hyatt,
David I. Lehn,
David John Burrowes,
David Matja,
David Remahl,
David Resseguie,
David Smith,
David Storey,
David Vest,
David Woolley,
David Zbarsky,
Dave Methvin,
DeWitt Clinton,
Dean Edridge,
Dean Edwards,
Dean Jackson,
Debanjana Sarkar, <!-- debanjana-a11y on GitHub -->
Debi Orton,
Delan Azabani, <!-- delan on GitHub -->
Derek Featherstone,
Derek Guenther,
Devarshi Pant,
Devdatta,
Devin Mullins,
Devin Rousso,
Di Zhang,
Diego Ferreiro Val,
Diego González Zúñiga, <!-- diekus on GitHub -->
Diego Ponce de León,
Dimitri Glazkov,
Dimitry Golubovsky,
Dirk Pranke,
Dirk Schulze,
Dirkjan Ochtman,
Divya Manian,
Dmitry Lazutkin,
Dmitry Titov,
dolphinling,
Dominic Cooney,
Dominique Hazaël-Massieux,
Don Brutzman,
Donovan Glover,
Doron Rosenberg,
Doug Kramer,
Doug Simpkinson,
Drew Wilson,
Edgar Chen,
Edmund Lai,
Eduard Pascual,
Eduardo Vela,
Edward Welbourne,
Edward Z. Yang,
Ehsan Akhgari,
Ehsan Karamad,
Eira Monstad,
Eitan Adler,
Eli Friedman,
Eli Grey,
Eliot Graff,
Elisabeth Robson,
Elizabeth Castro,
Elliott Sprehn,
Elliotte Harold,
Emilio Cobos Álvarez,
Emily Stark,
Eric Carlson,
Eric Casler,
Eric Lawrence,
Eric Portis,
Eric Rescorla,
Eric Semling,
Eric Shepherd, <!-- a2sheppy on GitHub -->
Eric Willigers,
Erik Arvidsson,
Erik Charlebois,
Erik Rose,
栗本 英理子 (Eriko Kurimoto),
espretto, <!-- GitHub -->
Evan Jacobs,
Evan Martin,
Evan Prodromou,
Evan Stade,
Evert,
Evgeny Kapun,
ExE-Boss, <!-- GitHub -->
Ezequiel Garzón,
fantasai,
Félix Sanz,
Felix Sasaki,
Fernando Altomare Serboncini,
Forbes Lindesay,
Francesco Schwarz,
Francis Brosnan Blazquez,
Franck 'Shift' Quélain,
François Marier,
Frank Barchard,
Frank Liberato,
Franklin Shirley,
Frederik Braun,
Fredrik Söderquist,
鵜飼文敏 (Fumitoshi Ukai),
Futomi Hatano,
Gavin Carothers,
Gavin Kistner,
Gareth Rees,
Garrett Smith,
Gary Blackwood,
Gary Kacmarcik,
Gary Katsevman,
Geoff Richards,
Geoffrey Garen,
Georg Neis,
George Lund,
Gianmarco Armellin,
Giovanni Campagna,
Giuseppe Pascale,
Glenn Adams,
Glenn Maynard,
Graham Klyne,
Greg Botten,
Greg Houston,
Greg Wilkins,
Gregg Tavares,
Gregory J. Rosmaita,
Gregory Terzian,
Grey,
guest271314,
Guilherme Johansson Tramontina,
Guy Bedford,
Gytis Jakutonis,
Håkon Wium Lie,
Habib Virji,
Hajime Morrita,
Hallvord Reiar Michaelsen Steen,
Hanna Laakso,
Hans S. Tømmerhalt,
Hans Stimer,
Harald Alvestrand,
Hayato Ito,
何志翔 (HE Zhixiang),
Henri Sivonen,
Henrik Lied,
Henrik Lievonen,
Henry Lewis,
Henry Mason,
Henry Story,
Hermann Donfack Zeufack,
中川博貴 (Hiroki Nakagawa), <!-- nhiroki on GitHub -->
Hiroshige Hayashizaki,
Hiroyuki USHITO,
Hitoshi Yoshida,
Hongchan Choi, <!-- hoch on GitHub -->
王华 (Hua Wang), <!-- PaperStrike on GitHub -->
Hugh Bellamy,
Hugh Guiney,
Hugh Winkler,
Ian Bicking,
Ian Clelland,
Ian Davis,
Ian Fette,
Ian Henderson,
Ian Kilpatrick,
Ibrahim Ahmed,
Ido Green,
Ignacio Javier,
Igor Oliveira,
安次嶺 一功 (Ikko Ashimine), <!-- eltociear on GitHub -->
Ilya Grigorik,
Ingvar Stepanyan,
isonmad,
Iurii Kucherov,
Ivan Enderlin,
Ivan Nikulin, <!-- inikulin on GitHub -->
Ivan Panchenko,
Ivo Emanuel Gonçalves,
J. King,
J.C. Jones,
Jackson Ray Hamilton,
Jacob Davies,
Jacques Distler,
Jake Archibald,
Jake Verbaten,
Jakub Vrána,
Jakub Łopuszański,
Jakub Wilk,
James Craig,
James Graham,
James Greene,
James Justin Harrell,
James Kozianski,
James M Snell,
James Perrett,
James Robinson,
Jamie Liu,
Jamie Lokier,
Jamie Mansfield,
Jan Kühle, <!-- frigus02 on GitHub -->
Jan Miksovsky,
Janice Shiu,
Janusz Majnert,
Jan-Ivar Bruaroey,
Jan-Klaas Kollhof,
Jared Jacobs,
Jason Duell,
Jason Kersey,
Jason Lustig,
Jason Orendorff,
Jason White,
Jasper Bryant-Greene,
Jasper St. Pierre,
Jatinder Mann,
Jay Henry Kao,
Jean-Yves Avenard,
Jed Hartman,
Jeff Balogh,
Jeff Cutsinger,
Jeff Gilbert,
Jeff "=JeffH" Hodges,
Jeff Schiller,
Jeff Walden,
Jeffrey Yasskin,
Jeffrey Zeldman,
胡慧鋒 (Jennifer Braithwaite),
Jellybean Stonerfish,
Jennifer Apacible,
Jens Bannmann,
Jens Fendler,
Jens Oliver Meiert,
Jens Widell,
Jer Noble,
Jeremey Hustman,
Jeremy Keith,
Jeremy Orlow,
Jeremy Roman,
Jeroen van der Meer,
Jerry Smith,
Jesse Renée Beach,
Jessica Jong,
jfkthame, <!-- GitHub -->
Jian Li,
Jihye Hong,
Jim Jewett,
Jim Ley,
Jim Meehan,
Jim Michaels,
Jinho Bang,
Jinjiang (勾三股四), <!-- GitHub -->
Jirka Kosek,
Jjgod Jiang,
Joaquim Medeiros,
João Eiras,
Jochen Eisinger,
Joe Clark,
Joe Gregorio,
Joel Spolsky,
Joel Verhagen,
Joey Arhar,
Johan Herland,
Johanna Herman,
John Boyer,
John Bussjaeger,
John Carpenter,
John Daggett,
John Fallows,
John Foliot,
John Harding,
John Keiser,
John Law,
John Musgrave,
John Snyders,
John Stockton,
John-Mark Bell,
Johnny Stenback,
Jon Coppeard,
Jon Ferraiolo,
Jon Gibbins,
Jon Jensen,
Jon Perlow,
Jonas Sicking,
Jonathan Cook,
Jonathan Kew,
Jonathan Neal,
Jonathan Oddy,
Jonathan Rees,
Jonathan Watt,
Jonathan Worent,
Jonny Axelsson,
Joram Schrijver,
Jordan Tucker,
Jorgen Horstink,
Joris van der Wel,
Jorunn Danielsen Newth,
Joseph Kesselman,
Joseph Mansfield,
Joseph Pecoraro,
Josh Aas,
Josh Hart,
Josh Juran,
Josh Levenberg,
Josh Matthews,
Joshua Bell,
Joshua Chen, <!-- Josh-Cena on GitHub -->
Joshua Randall,
Juan Olvera, <!-- thinkxl on GitHub -->
Juanmi Huertas,
Jukka K. Korpela,
Jules Clément-Ripoche,
Julian Reschke,
Julio Lopez,
小勝 純 (Jun Kokatsu),
Jun Yang (harttle),
Jungkee Song,
Jürgen Jeka,
Justin Lebar,
Justin Novosad,
Justin Rogers,
Justin Schuh,
Justin Sinclair,
Juuso Lapinlampi,
Ka-Sing Chou,
Kagami Sascha Rosylight,
Kai Hendry,
Kamishetty Sreeja,
呂康豪 (KangHao Lu)<!-- Kenny, kennyluck-->,
Karl Dubost,
Karl Tomlinson,
Kartik Arora,
Kartikaya Gupta,
Kathy Walton,
河童エクマ（Kawarabe Ecma）<!-- heppokofrontend on GitHub -->
Keith Cirkel, <!-- keithamus on GitHub -->
Keith Rollin,
Keith Yeung,
Kelly Ford,
Kelly Norton,
Ken Russell,
Kenji Baheux,
Kevin Benson,
Kevin Cole,
Kevin Gadd,
Kevin McNee,
Kevin Venkiteswaran,
Khushal Sagar,
Kinuko Yasuda,
Koji Ishii,
Kornél Pál,
Kornel Lesinski,
上野 康平 (UENO, Kouhei),
Kris Northfield,
Kristian Spangsege,
Kristof Zelechovski,
Krzysztof Maczyński,
黒澤剛志 (Kurosawa Takeshi),
Kyle Barnhart,
Kyle Hofmann<!-- Ozob -->,
Kyle Huey,
Léonard Bouchet,
Léonie Watson,
Lachlan Hunt,
Larry Masinter,
Larry Page,
Lars Gunther<!-- Keryx Web -->,
Lars Solberg,
Laura Carlson,
Laura Granka,
Laura L. Carlson,
Laura Wisewell,
Laurens Holst,
Lawrence Forooghian,
Lee Kowalkowski,
Leif Halvard Silli,
Leif Kornstaedt,
Lenny Domnitser,
Leonard Rosenthol,
Leons Petrazickis,
Liviu Tinta,
Lobotom Dysmon,
Logan<!-- on moz irc -->,
Logan Moore,
Loune,
Lucas Gadani,
Łukasz Pilorz,
Luke Kenneth Casson Leighton,
Luke Warlow,
Luke Wilde,
Maciej Stachowiak,
Magne Andersson,
Magnus Kristiansen<!-- Dashiva -->,
Maik Merten,
Majid Valipour,
Maksim Sadym,
Malcolm Rowe,
Manish Goregaokar,
Manish Tripathi,
Manuel Martinez-Almeida,
Manuel Rego Casasnovas,
Marc Hoyois,
Marc-André Choquette, <!-- eel-in-a-hovercraft on GitHub -->
Marc-André Lafortune,
Marco Zehe,
Marcus Bointon,
Marcus Otterström,
Marijn Kruisselbrink,
Mark Amery,
Mark Birbeck,
Mark Davis,
Mark Green,
Mark Miller,
Mark Nottingham,
Mark Pilgrim,
Mark Rogers, <!-- dd8 on GitHub -->
Mark Rowe<!--bdash-->,
Mark Schenk,
Mark Vickers,
Mark Wilton-Jones,
Markus Cadonau,
Markus Stange,
Martijn van der Ven,
Martijn Wargers,
Martin Atkins,
Martin Chaov,
Martin Dürst,
Martin Honnen,
Martin Janecke,
Martin Kutschker,
Martin Nilsson,
Martin Thomson,
Masataka Yakura,
Masatoshi Kimura,
Mason Freed, <!-- mfreed7 on GitHub -->
Mason Mize,
Mathias Bynens,
Mathieu Henri,
Matias Larsson,
Matt Brubeck,
Matt Di Pasquale,
Matt Falkenhagen,
Matt Giuca, <!-- mgiuca on GitHub -->
Matt Harding,
Matt Schmidt,
Matt Wright,
Matthew Gaudet, <!-- mgaudet on GitHub -->
Matthew Gregan,
Matthew Mastracci,
Matthew Noorenberghe,
Matthew Raymond,
Matthew Thomas,
Matthew Tylee Atkinson, <!-- matatk on GitHub -->
Mattias Waldau,
Max Romantschuk,
Maxim Tsoy, <!-- muodov on GitHub -->
Mayeul Cantan,
Menachem Salomon,
Menno van Slooten,
Micah Dubinko,
Micah Nerren,
Michael 'Ratt' Iannarelli,
Michael A. Nachbaur,
Michael A. Puls II<!--Shadow2531-->,
Michael Carter,
Michael Daskalov,
Michael Day,
Michael Dyck,
Michael Enright,
Michael Ficarra,
Michael Gratton,
Michael Kohler,
Michael McKelvey,
Michael Nordman,
Michael Powers,
Michael Rakowski,
Michael(tm) Smith,
Michael Walmsley,
Michal Zalewski,
Michel Buffa,
Michel Fortin,
Michelangelo De Simone,
Michiel van der Blonk,
Miguel Casas-Sanchez<!-- yellowdoge on GitHub -->,
Mihai Şucan<!-- from ROBO Design -->,
Mihai Parparita,
Mike Brown,
Mike Dierken<!-- S. Mike Dierken -->,
Mike Dixon,
Mike Hearn,
Mike Pennisi,
Mike Schinkel,
Mike Shaver,
Mikko Rantalainen,
Mingye Wang,
Mirko Brodesser,
Mohamed Zergaoui<!-- Innovimax SARL -->,
Mohammad Al Houssami,
Mohammad Reza Zakerinasab,
Momdo Nakamura,
Morten Stenshorne,
Mounir Lamouri,
Ms2ger,
mtrootyy,
邱慕安 (Mu-An<!--grammar-check-override--> Chiou),
Mukilan Thiyagarajan,
Mustaq Ahmed,
Myles Borins,
Nadia Heninger,
Nate Chapin,
NARUSE Yui,
Navid Zolghadr,
Neil Deakin,
Neil Rashbrook,
Neil Soiffer,
Nereida Rondon,
networkException,
Nicholas Shanks,
Nicholas Stimpson,
Nicholas Zakas,
Nickolay Ponomarev,
Nicolas Gallagher,
Nicolas Pena Moreno,
Nicolò Ribaudo,
Nidhi Jaju,
Nikki Bee,
Niklas Gögge,
Nina Satragno,
Noah Mendelsohn,
Noah Slater,
Noam Rosenthal,
Noel Gordon,
Nolan Waite,
NoozNooz42,
Norbert Lindenberg,
Oisín Nolan, <!-- oisinnolan on GitHub -->
Ojan Vafai,
Olaf Hoffmann,
Olav Junker Kjær,
Oldřich Vetešník,
Oli Studholme,
Oliver Hunt,
Oliver Rigby,
Olivia (Xiaoni) Lai, <!-- xlai-o on GitHub -->
Olivier Gendrin,
Olli Pettay,
Ondřej Žára, <!-- ondras on GitHub -->
Ori Avtalion,
Oriol Brufau,
oSand, <!-- from reddit -->
Pablo Flouret,
Patrick Dark,
Patrick Garies,
Patrick H. Lauke,
Patrik Persson,
Paul Adenot,
Paul Lewis,
Paul Norman,
Per-Erik Brodin,
一丝 (percyley), <!-- yisibl on GitHub -->
Perry Smith,
Peter Beverloo,
Peter Karlsson,
Peter Kasting,
Peter Moulder,
Peter Occil,
Peter Stark,
Peter Van der Beken,
Peter van der Zee,
Peter-Paul Koch,
Phil Pickering,
Philip Ahlberg,
Philip Brembeck, <!-- philipbrembeck on GitHub -->
Philip Taylor,
Philip TAYLOR<!-- a different one -->,
Philippe De Ryck,
Pierre-Arnaud Allumé,
Pierre-Marie Dartus,
Pierre-Yves Gérardy,
Piers Wombwell, <!-- pwombwell on GitHub -->
Pooja Sanklecha,
Prashant Hiremath,
Prashanth Chandra,
Prateek Rungta,
Pravir Gupta,
Prayag Verma,
李普君 (Pujun Li)<!-- masa jack -->,
Rachid Finge,
Rafael Weinstein,
Rafał Miłecki,
Rahim Abdi,
Rahul Purohit,
Raj Doshi,
Rajas Moonka,
Rakina Zata Amni,
Ralf Stoltze,
Ralph Giles,
Raphael Champeimont,
Rebecca Star,
Remci Mizkur,
Remco,
Remy Sharp,
Rene Saarsoo,
Rene Stach,
Ric Hardacre,
Rich Clark,
Rich Doughty,
Richa Rupela,
Richard Gibson,
Richard Ishida,
Richard Torres<!-- richardtorres314 on GitHub -->,
Ricky Mondello,
Rigo Wenning,
Rikkert Koppes,
Rimantas Liubertas,
Riona Macnamara,
Rob Buis,
Rob Ennals,
Rob Jellinghaus,
Rob S,
Rob Smith,
Robert Blaut,
Robert Collins,
Robert Hogan,
Robert Kieffer,
Robert Linder,
Robert Millan,
Robert O'Callahan,
Robert Sayre,
Robin Berjon,
Robin Schaufler,
Rodger Combs,
Roland Steiner,
Roma Matusevich,
Romain Deltour,
Roman Ivanov,
Roy Fielding,
Rune Lillesveen,
Russell Bicknell,
Ruud Steltenpool,
Ryan King,
Ryan Landay,
Ryan Sleevi,
Ryo Kajiwara, <!-- sylph01 on GitHub -->
Ryo Kato,
Ryosuke Niwa,
S. Mike Dierken,
Salvatore Loreto,
Sam Atkins, <!-- atkinssj on GitHub -->
Sam Dutton,
Sam Kuper,
Sam Ruby,
Sam Sneddon, <!-- gsnedders on GitHub -->
Sam Weinig,
Samikshya Chand,
Samuel Bronson,
Samy Kamkar,
Sander van Lambalgen,
Sanjoy Pal,
Sanket Joshi,
Sarah Gebauer,
Sarven Capadisli,
Satrujit Behera,
Sayan Sivakumaran,
Schalk Neethling,
Scott Beardsley,
Scott González,
Scott Hess,
Scott Miles,
Scott O'Hara,
Sean B. Palmer, <!-- sbp on GitHub -->
Sean Feng,
Sean Fraser,
Sean Hayes,
Sean Hogan,
Sean Knapp,
Sebastian Markbåge,
Sebastian Schnitzenbaumer,
Sendil Kumar N,
Seth Call,
Seth Dillingham,
Shannon Moeller,
Shanti Rao,
Shaun Inman,
Shiino Yuki, <!-- yuki3 on GitHub -->
贺师俊 (HE Shi-Jun), <!-- hax on GitHub -->
Shiki Okasaka,
Shivani Sharma,
shreyateeza, <!-- GitHub -->
Shubheksha Jalan,
Sidak Singh Aulakh,
Sierk Bornemann,
Sigbjørn Finne,
Sigbjørn Vik,
Silver Ghost, <!-- see bug 19614 -->
Silvia Pfeiffer,
Šime Vidas,
Simon Fraser,
Simon Montagu,
Simon Sapin,
Yu Han, <!-- yuzhe-han on GitHub -->
Simon Spiegel,
Simon Wülker, <!-- Wuelle on GitHub -->
Siye Liu,
skeww, <!-- on reddit -->
Smylers,
Srirama Chandra Sekhar Mogali,
Stanton McCandlish,
stasoid, <!-- GitHub -->
Stefan Håkansson,
Stefan Haustein,
Stefan Santesson,
Stefan Schumacher,
Ştefan Vargyas,
Stefan Weiss,
Steffen Meschkat,
Stephen Chenney,
Stephen Ma,
Stephen Stewart,
Stephen White,
Steve Comstock,
Steve Faulkner,
Steve Fink,
Steve Orvell,
Steve Runyon,
Steven Bennett,
Steven Bingler,
Steven Garrity,
Steven Tate,
Stewart Brodie,
Stuart Ballard,
Stuart Langridge,
Stuart Parmenter,
Subramanian Peruvemba,
Sudhanshu Jaiswal,
sudokus999, <!-- GitHub -->
Sunava Dutta,
Surma,
Susan Borgrink,
Susan <!--G.--> Lesch,
Sylvain Pasche,
T.J. Crowder, <!-- tjcrowder and farsightsoftware on GitHub -->
Tab Atkins-Bittner,
Taiju Tsuiki,
Takashi Toyoshima,
Takayoshi Kochi,
Takeshi Yoshino,
<span data-x="" lang="tr">Tantek Çelik</span>,
田村健人 (Kent TAMURA),
Tawanda Moyo, <!-- tawandamoyo on GitHub-->
Taylor Hunt,
Ted Mielczarek,
Terence Eden, <!-- edent on GitHub -->
Terrence Wood,
Tetsuharu OHZEKI,
Theresa O'Connor,
Thijs van der Vossen,
Thomas Broyer,
Thomas Koetter,
Thomas O'Connor,
Tim Altman,
Tim Dresser,
Tim Flynn, <!-- trflynn89 on GitHub -->
Tim Johansson,
Tim Nguyen, <!-- nt1m on Github -->
Tim Perry,
Tim van der Lippe,
TJ VanToll,
Tobias Schneider,
Tobie Langel,
Toby Inkster,
Todd Moody,
Tom Baker,
Tom Pike,
Tom Schuster,
Tom ten Thij,
Tomasz Jakut, <!-- Comandeer on GitHub -->
Tomek Wytrębowicz,
Tommy Thorsen,
Tony Ross,
Tooru Fujisawa,
Toru Kobayashi,
Traian Captan,
Travis Leithead,
Trevor Rowbotham,
Trevor Saunders,
Trey Eckels,
triple-underscore, <!-- GitHub -->
Tristan Fraipont, <!-- Kaiido on GitHub -->
Tristan Parisot, <!-- quadristan on GitHub -->
保呂 毅 (Tsuyoshi Horo),
Tyler Close,
Valentin Gosu,
Vardhan Gupta,
Vas Sudanagunta,
Veli Şenol,
Victor Carbune,
Victor Costan,
Vipul Snehadeep Chawathe,
Vitya Muhachev,
Vlad Levin,
Vladimir Katardjiev,
Vladimir Vukićević,
Vyacheslav Aristov,
voracity,
Walter Steiner,
Wakaba,
Wayne Carr,
Wayne Pollock,
Wellington Fernando de Macedo,
Wenson Hsieh,
Weston Ruter,
Wilhelm Joys Andersen,
Will Levine,
Will Ray,
William Chen,
William Swanson,
Willy Martin Aguirre Rodriguez,
Wladimir Palant,
Wojciech Mach,
Wolfram Kriesing,
Xan Gregg,
xenotheme,
XhmikosR,
Xida Chen,
Xidorn Quan,
Xue Fuqiao,
Yang Chen,
Yao Xiao,
Yash Handa,
Yay295,
Ye-Kui Wang,
Yehuda Katz,
Yi Xu,
Yi-An Huang,
Yngve Nysaeter Pettersen,
Yoav Weiss,
Yonathan Randolph,
Yu Huojiang,
Yuki Okushi, <!-- JohnTitor on GitHub -->
Yury Delendik,
平野裕 (Yutaka Hirano),
Yuzo Fujishima,
西條柚 (Yuzu Saijo),
Zhenbin Xu,
张智强 (Zhiqiang Zhang),
Zoltan Herczeg,
Zyachel,
and
Øistein E. Andersen,
for their useful comments, both large and small, that have led to changes to this specification
over the years.</p>
<p>Thanks also to everyone who has ever posted about HTML to their blogs, public mailing lists, or
forums, including all the contributors to the <a href="https://www.w3.org/html/wg/lists/">various
W3C HTML WG lists</a> and the <a href="https://whatwg.org/mailing-list">various WHATWG
lists</a>.
<p>Special thanks to Richard Williamson for creating the first implementation of
<code>canvas</code> in Safari, from which the canvas feature was designed.</p>
<p>Special thanks also to the Microsoft employees who first implemented the event-based
drag-and-drop mechanism, <code data-x="attr-contenteditable">contenteditable</code>, and other
features first widely deployed by the Windows Internet Explorer browser.</p>
<p w-nodev>Special thanks and $10,000 to David Hyatt who came up with a broken implementation
of the <a href="#adoptionAgency">adoption agency algorithm</a> that the editor had to reverse
engineer and fix before using it in the parsing section.</p>
<p>Thanks to the participants of the microdata usability study for allowing us to use their
mistakes as a guide for designing the microdata feature.</p>
<p>Thanks to the many sources that provided inspiration for the examples used in the
specification.</p>
<p>Thanks also to the Microsoft blogging community for some ideas, to the attendees of the W3C
Workshop on Web Applications and Compound Documents for inspiration, to the #mrt crew, the #mrt.no
crew, and the #whatwg crew, and to Pillar and Hedral for their ideas and support.</p>
<p>Thanks to Igor Zhbanov for generating PDF versions of the specification.</p>
<p>Special thanks to the <a href="https://www.w3.org/community/respimg/">RICG</a> for developing
the <code>picture</code> element and related features; in particular thanks to Adrian Bateman,
Bruce Lawson, David Newton, Ilya Grigorik, John Schoenick, Leon de Rijke, Mat Marquis, Marcos
Cáceres, Tab Atkins, Theresa O'Connor, and Yoav Weiss for their contributions.</p>
<p>Special thanks to the <a href="https://www.w3.org/WebPlatform/WG/">WPWG</a> for incubating the
<a href="#custom-elements">custom elements</a> feature. In particular, thanks to David Hyatt and
Ian Hickson for their influence through the XBL specifications, Dimitri Glazkov for the first
draft of the custom elements specification, and to
Alex Komoroske,
Alex Russell,
Andres Rios,
Boris Zbarsky,
Brian Kardell,
Daniel Buchner,
Dominic Cooney,
Erik Arvidsson,
Elliott Sprehn,
Hajime Morrita,
Hayato Ito,
Jan Miksovsky,
Jonas Sicking,
Olli Pettay,
Rafael Weinstein,
Roland Steiner,
Ryosuke Niwa,
Scott Miles,
Steve Faulkner,
Steve Orvell,
Tab Atkins,
Theresa O'Connor,
Tim Perry, and
William Chen
for their contributions.</p>
<p>Special thanks to the <a href="https://www.w3.org/Style/CSS/members">CSSWG</a> for developing
the <a href="#worklets">worklets</a>. In particular, thanks to Ian Kilpatrick for his work as
editor of the original worklets specification.</p>
<p>For about ten years starting in 2003, this standard was almost entirely written by Ian Hickson
(<a href="https://www.google.com/">Google</a>, <a
href="mailto:ian@hixie.ch">ian@hixie.ch</a>).</p>
<p>Starting in 2015, the editor group expanded. It is currently maintained by
<a href="https://annevankesteren.nl/">Anne van Kesteren</a> (<a href="https://www.apple.com/">Apple</a>, <a href="mailto:annevk@annevk.nl">annevk@annevk.nl</a>),
<a href="https://domenic.me/">Domenic Denicola</a> (<a href="https://www.google.com/">Google</a>, <a href="mailto:d@domenic.me">d@domenic.me</a>)
<a href="https://domfarolino.com">Dominic Farolino</a> (<a href="https://www.google.com/">Google</a>, <a href="mailto:domfarolino@gmail.com">domfarolino@gmail.com</a>),
<a href="https://foolip.org/">Philip Jägenstedt</a> (<a href="https://www.google.com/">Google</a>, <a href="mailto:philip@foolip.org">philip@foolip.org</a>), and
Simon Pieters (<a href="https://www.mozilla.org/">Mozilla</a>, <a href="mailto:zcorpan@gmail.com">zcorpan@gmail.com</a>).</p>
<!-- Hopefully Kam and Tess won't notice they're covered by these acknowledgments three times! -->
<h2 id="ipr" class="no-num">Intellectual property rights</h2>
<div w-nodev itemscope itemtype="http://n.whatwg.org/work">
<p>The image in the introduction is based on <a itemprop="work" href="https://www.flickr.com/photos/wonderlane/2986252088/">a photo</a>
by <a itemprop="https://creativecommons.org/ns#attributionURL" href="https://www.flickr.com/photos/wonderlane/">Wonderlane</a>.
(<a itemprop="license" href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0</a>)
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The image of the wolf in the embedded content introduction is based on <a itemprop="work" href="https://commons.wikimedia.org/wiki/File:WolfRunningInSnow.jpg">a photo</a>
by <a itemprop="http://creativecommons.org/ns#attributionURL" href="https://commons.wikimedia.org/wiki/File:WolfRunningInSnow.jpg">Barry O'Neill</a>.
(<a itemprop="license" href="https://en.wikipedia.org/wiki/Public_domain">Public domain</a>)
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The image of the kettlebell swing in the embedded content introduction is based on <a itemprop="work" href="https://pixabay.com/en/functional-mobility-articular-606568/">a photo</a>
by <a itemprop="http://creativecommons.org/ns#attributionURL" href="https://pixabay.com/en/users/506563-506563/">kokkarina</a>.
(<a itemprop="license" href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a>)
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The Blue Robot Player sprite used in the canvas demo is based on
<a itemprop="work" href="https://johncolburn.deviantart.com/art/Blue-Robot-Player-Sprite-323813997">a work</a> by
<a itemprop="https://creativecommons.org/ns#attributionURL" href="https://johncolburn.deviantart.com/">JohnColburn</a>.
(<a itemprop="license" href="https://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0</a>)</p>
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The photograph of robot 148 climbing the tower at the FIRST Robotics Competition 2013 Silicon Valley Regional is based on
<a itemprop="work" href="https://www.flickr.com/photos/lenore-m/8631391979/">a work</a> by
<a itemprop="https://creativecommons.org/ns#attributionURL" href="https://www.flickr.com/photos/lenore-m/">Lenore Edman</a>.
(<a itemprop="license" href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0</a>)</p>
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The diagram showing how <code data-x="attr-script-async">async</code> and <code
data-x="attr-script-defer">defer</code> impact <code>script</code> loading is based on a
similar diagram from <a itemprop="work"
href="https://peter.sh/experiments/asynchronous-and-deferred-javascript-execution-explained/">a
blog post</a> by <a itemprop="https://creativecommons.org/ns#attributionURL"
href="https://peter.sh/about/">Peter Beverloo</a>.
(<a itemprop="license" href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a>)</p>
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The image decoding demo used to demonstrate module-based workers draws on some example code
from <a itemprop="work" href="https://www.html5rocks.com/en/tutorials/canvas/imagefilters/">a
tutorial</a> by <a itemprop="https://creativecommons.org/ns#attributionURL"
href="https://www.fhtr.net/">Ilmari Heikkinen</a>.
(<a itemprop="license" href="https://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>)</p>
</div>
<div itemscope itemtype="http://n.whatwg.org/work">
<p>The <code data-x=""><flag-icon></code> example was inspired by <a itemprop="work"
href="https://github.com/stevenrskelton/flag-icon">a custom element</a> by <a
itemprop="https://creativecommons.org/ns#attributionURL" href="http://stevenskelton.ca/">Steven
Skelton</a>. (<a itemprop="license" href="https://opensource.org/licenses/MIT">MIT</a>)</p>
</div>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the
<code>picture</code> element and related features can be found in the <a
href="https://github.com/ResponsiveImagesCG/picture-element"><code>ResponsiveImagesCG/picture-element</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <code
data-x="meta-theme-color">theme-color</code> metadata name can be found in the <a
href="https://github.com/whatwg/meta-theme-color"><code>whatwg/meta-theme-color</code>
repository</a>, which is available under <a itemprop="license"
href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#custom-elements">custom elements</a> feature can be found in the <a
href="https://github.com/w3c/webcomponents"><code>w3c/webcomponents</code> repository</a>, which
is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <code
data-x="dom-innerText">innerText</code> getter and setter can be found in the <a
href="https://github.com/rocallahan/innerText-spec"><code>rocallahan/innerText-spec</code>
repository</a>, which is available under <a itemprop="license"
href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#worklets">worklets</a> feature can be found in the <a
href="https://github.com/w3c/css-houdini-drafts"><code>w3c/css-houdini-drafts</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#import-maps">import maps</a> feature can be found in the <a
href="https://github.com/WICG/import-maps"><code>WICG/import-maps</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#navigation-api">navigation API</a> feature can be found in the <a
href="https://github.com/WICG/navigation-api"><code>WICG/navigation-api</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#close-requests-and-close-watchers">Close requests and close watchers</a> section can be
found in the <a href="https://github.com/WICG/close-watcher"><code>WICG/close-watcher</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
<p>Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a <a
rel="license" href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0
International License</a>. To the extent portions of it are incorporated into source code, such
portions in the source code are licensed under the <a rel="license"
href="https://opensource.org/licenses/BSD-3-Clause">BSD 3-Clause License</a> instead.</p>
<p w-nodev w-noreview>This is the Living Standard. Those interested in the patent-review version
should view the <a href="/review-drafts/2025-01/">Living Standard Review Draft</a>.</p>
</body>
</html>