HTML
Living Standard — Last Updated 15 December 2025
Living Standard — Last Updated 15 December 2025
select element inner content elementsoptgroup element inner content elementsoption element inner content elementsinnerText and outerText propertiesbody elementarticle elementsection elementnav elementaside elementh1, h2, h3, h4, h5, and h6
elementshgroup elementheader elementfooter elementaddress elementp elementhr elementpre elementblockquote elementol elementul elementmenu elementli elementdl elementdt elementdd elementfigure elementfigcaption elementmain elementsearch elementdiv elementa elementem elementstrong elementsmall elements elementcite elementq elementdfn elementabbr elementruby elementrt elementrp elementdata elementtime elementcode elementvar elementsamp elementkbd elementsub and sup elementsi elementb elementu elementmark elementbdi elementbdo elementspan elementbr elementwbr elementa and area elementsa and area elementsalternate"author"bookmark"canonical"dns-prefetch"expect"external"help"icon"license"manifest"modulepreload"nofollow"noopener"noreferrer"opener"pingback"preconnect"prefetch"preload"privacy-policy"search"stylesheet"tag"terms-of-service"picture elementsource elementimg elementsource,
img, and link elementsiframe elementembed elementobject elementvideo elementaudio elementtrack elementTrackEvent interfacemap elementarea elementtable elementcaption elementcolgroup elementcol elementtbody elementthead elementtfoot elementtr elementtd elementth elementtd and th elementsform elementlabel elementinput elementtype attributetype=hidden)type=text) state and Search state (type=search)type=tel)type=url)type=email)type=password)type=date)type=month)type=week)type=time)type=datetime-local)type=number)type=range)type=color)type=checkbox)type=radio)type=file)type=submit)type=image)type=reset)type=button)input element attributesmaxlength and minlength attributessize attributereadonly attributerequired attributemultiple attributepattern attributemin and max attributesstep attributelist attributeplaceholder attributeinput element APIsbutton elementselect elementdatalist elementoptgroup elementoption elementtextarea elementoutput elementprogress elementmeter elementfieldset elementlegend elementselectedcontent elementname attributedirname attributemaxlength attributeminlength attributedisabled attributeSubmitEvent interfaceFormDataEvent interfacedetails elementsummary elementa element to define a commandbutton element to define a commandinput element to define a commandoption element to define a commandaccesskey attribute
on a legend element to define a commandaccesskey
attribute to define a command on other elementsdialog elementscript elementnoscript elementtemplate elementslot elementcanvas elementPath2D objectsImageBitmap rendering contextOffscreenCanvas interfacecanvas elementsCustomElementRegistry interfacehidden attributecontenteditable content attributedesignMode getter and setterinputmode attributeenterkeyhint
attributepopover attributeWindow,
WindowProxy, and Location objectsWindow objectWindowProxy exotic objectLocation interfaceHistory interfaceNavigation interfaceNavigationHistoryEntry interfaceNavigationActivation interfacenavigate eventNotRestoredReasons interfacemultipart/x-mixed-replace
documentsX-Frame-Options` headerRefresh` headerWindowOrWorkerGlobalScope mixinbutton elementdetails and summary elementsinput element as a text entry widgetinput element as domain-specific widgetsinput element as a range controlinput element as a color
wellinput element as a checkbox and radio button widgetsinput element as a file upload controlinput element as a buttonmarquee elementmeter elementprogress elementselect elementtextarea elementThis 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:
This section is non-normative.
In short: Yes.
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 the WHATWG Standards overview.
This section is non-normative.
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.
This section is non-normative.
This specification is intended for authors of documents and scripts that use the features defined in this specification, 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.
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.
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.
This section is non-normative.
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.
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).
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.
This section is non-normative.
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.
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.
The following year, the W3C membership decided to stop evolving HTML and instead begin work on an XML-based equivalent, called XHTML. 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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
In 2019, the WHATWG and W3C signed an agreement to collaborate on a single version of HTML going forward: this document.
This section is non-normative.
It must be admitted that many aspects of HTML appear at first glance to be nonsensical and inconsistent.
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.
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.
Despite all this, efforts have been made to adhere to certain design goals. These are described in the next few subsections.
This section is non-normative.
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 workers, the intent is that the behavior of implementations can be thought of as completely serializing the execution of all scripts in all globals.
The exception to this general design principle is the JavaScript SharedArrayBuffer
class. Using SharedArrayBuffer objects, it can in fact be observed that scripts in
other agents are executing simultaneously. Furthermore, due to the
JavaScript memory model, there are situations which not only are un-representable via serialized
script execution, but also un-representable via serialized statement execution
among those scripts.
This section is non-normative.
HTML has a wide array of extensibility mechanisms that can be used for adding semantics in a safe manner:
Authors can use the class 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.
Authors can include data for inline client-side scripts or server-side site-wide scripts
to process using the data-*="" 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.
Authors can use the <meta name="" content=""> mechanism to
include page-wide metadata.
Authors can use the rel="" mechanism to annotate
links with specific meanings by registering extensions to
the predefined set of link types. This is also used by microformats.
Authors can embed raw data using the <script type="">
mechanism with a custom type, for further handling by inline or server-side scripts.
Authors can extend APIs using the JavaScript prototyping mechanism. This is widely used by script libraries, for instance.
Authors can use the microdata feature (the itemscope="" and itemprop=""
attributes) to embed nested name-value pairs of data to be shared with other applications and
sites.
Authors can define, share, and use custom elements to extend the vocabulary of HTML. The requirements of valid custom element names ensure forward compatibility (since no elements will be added to HTML, SVG, or MathML with hyphen-containing local names in the future).
This section is non-normative.
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.
The in-memory representation is known as "DOM HTML", or "the DOM" for short.
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.
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
text/html MIME type, then it will be processed as an HTML document by
web browsers. This specification defines the latest HTML syntax, known simply as "HTML".
The second concrete syntax is XML. When a document is transmitted with an XML MIME
type, such as application/xhtml+xml, 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.
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).
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 noscript 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 "-->" can only be represented in the
DOM, not in the HTML and XML syntaxes.
This section is non-normative.
This specification is divided into the following major sections:
EventSource, and a two-way full-duplex socket protocol for scripts known as Web
Sockets.There are also some appendices, listing obsolete features and IANA considerations, and several indices.
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.
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 producers, for example authors and the documents they create, and there are conformance requirements that apply to consumers, 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.
For example, "the foo attribute's value must be a valid
integer" is a requirement on producers, as it lays out the allowed values; in contrast,
the requirement "the foo attribute's value must be parsed using the
rules for parsing integers" is a requirement on consumers, as it describes how to
process the content.
Requirements on producers have no bearing whatsoever on consumers.
Continuing the above example, a requirement stating that a particular attribute's value is constrained to being a valid integer emphatically does not 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.
This is a definition, requirement, or explanation.
This is a note.
This is an example.
This is an open issue.
This is a warning.
[Exposed =Window ]
interface Example {
// this is an IDL definition
};variable = object.method([optionalArgument])This is a note to authors describing the usage of an interface.
/* this is a CSS fragment */ The defining instance of a term is marked up like this. Uses of that term are marked up like this or like this.
The defining instance of an element, attribute, or API is marked up like this. References to that element, attribute, or API are marked up
like this.
Other code fragments are marked up like this.
Variables are marked up like this.
In an algorithm, steps in synchronous sections are marked with ⌛.
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:
This section is non-normative.
A basic HTML document looks like this:
<!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 > HTML documents consist of a tree of elements and text. Each element is denoted in the source by
a start tag, such as "<body>", and
an end tag, such as "</body>".
(Certain start tags and end tags can in certain cases be omitted and are implied by other tags.)
Tags have to be nested such that elements are all completely within each other, without overlapping:
< p > This is < em > very < strong > wrong</ em > !</ strong ></ p > < p > This < em > is < strong > correct</ strong > .</ em ></ 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.
Elements can have attributes, which control how the elements work. In the example below, there
is a hyperlink, formed using the a element and its href attribute:
< a href = "demo.html" > simple</ a > Attributes are placed inside the start tag, and consist
of a name and a value, separated by an "=" character.
The attribute value can remain unquoted if it doesn't contain ASCII
whitespace or any of " ' ` = < or >. Otherwise, it has to be quoted using either single or double quotes. The
value, along with the "=" character, can be omitted altogether if the value
is the empty string.
<!-- 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" > HTML user agents (e.g., web browsers) then parse this markup, turning it into a DOM (Document Object Model) tree. A DOM tree is an in-memory representation of a document.
DOM trees contain several kinds of nodes, in particular a DocumentType node,
Element nodes, Text nodes, Comment nodes, and in some cases
ProcessingInstruction nodes.
The markup snippet at the top of this section would be turned into the following DOM tree:
The document element of this tree is the html element, which is the
element always found in that position in HTML documents. It contains two elements,
head and body, as well as a Text node between them.
There are many more Text 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 Text 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 head start tag ends up being dropped silently,
and all the whitespace after the body end tag ends up placed at the end of the
body.
The head element contains a title element, which itself contains a
Text node with the text "Sample page". Similarly, the body element
contains an h1 element, a p element, and a comment.
This DOM tree can be manipulated from scripts in the page. Scripts (typically in JavaScript)
are small programs that can be embedded using the script element or using event
handler content attributes. For example, here is a form with a script that sets the value
of the form's output element to say "Hello World":
< form name = "main" >
Result: < output name = "result" ></ output >
< script >
document. forms. main. elements. result. value = 'Hello World' ;
</ script >
</ form > 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 a element in the tree above)
can have its "href" attribute changed in several
ways:
var a = document. links[ 0 ]; // obtain the first link in the document
a. href = 'sample.html' ; // change the destination URL of the link
a. protocol = 'https' ; // change just the scheme part of the URL
a. setAttribute( 'href' , 'https://example.com/' ); // change the content attribute directly 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.
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.
In the following example, the page has been made yellow-on-blue using CSS.
<!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 > 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.
This section is non-normative.
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.
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.
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. [ORIGIN]
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.
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).
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:
< 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 > If the message was just displayed to the user without escaping, a hostile attacker could then craft a URL that contained a script element:
https://example.com/message.cgi?say=%3Cscript%3Ealert%28%27Oh%20no%21%27%29%3C/script%3E
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.
This is called a cross-site scripting attack.
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:
img, it is important to safelist
any provided attributes as well. If one allowed all attributes then an attacker could, for
instance, use the onload attribute to run arbitrary
script.javascript:", but user agents can
implement (and indeed, have historically implemented) others.base element to be inserted means any script elements
in the page with relative links can be hijacked, and similarly that any form submissions can
get redirected to a hostile site.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.
This problem exists because HTML forms can be submitted to other origins.
Sites can prevent such attacks by populating forms with user-specific hidden tokens, or by
checking `Origin` headers on all requests.
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.
One way that a user could be so tricked is if a hostile site places the victim site in a
small iframe 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.
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 window object to the value of the top
attribute).
This section is non-normative.
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.
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.
There are two techniques for doing this reliably: use event handler content attributes, 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.
One way this could manifest itself is with img elements and the load event. The event could fire as soon as the element has been
parsed, especially if the image has already been cached (which is common).
Here, the author uses the onload handler on an
img element to catch the load event:
< img src = "games.png" alt = "Games" onload = "gamesLogoHasLoaded(event)" > 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:
< script >
var img = new Image();
img. src = 'games.png' ;
img. alt = 'Games' ;
img. onload = gamesLogoHasLoaded;
// img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
</ script > However, if the author first created the img element and then in a separate
script added the event listeners, there's a chance that the load
event would be fired in between, leading it to be missed:
<!-- 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 > This section is non-normative.
Authors are encouraged to make use of conformance checkers (also known as validators) to catch common mistakes. The WHATWG maintains a list of such tools at: https://whatwg.org/validator/
This section is non-normative.
Unlike previous versions of the HTML specification, this specification defines in some detail the required processing for invalid documents as well as valid documents.
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.
This section is non-normative.
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:
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.
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).
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 <font color=""> 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.
Presentational markup tends to be much more redundant, and thus results in larger document sizes.
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.
The only remaining presentational markup features in HTML are the style attribute and the style element. Use of the style 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 style 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.
It is also worth noting that some elements that were previously presentational have been
redefined in this specification to be media-independent: b, i,
hr, s, small, and u.
This section is non-normative.
The syntax of HTML is constrained to avoid a wide variety of problems.
Certain invalid syntax constructs, when parsed, result in DOM trees that are highly unintuitive.
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 parse error.
Some error-handling behavior, such as the behavior for the <table><hr>... 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.
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.)
Certain syntax constructs can result in disproportionately poor performance. To discourage the use of such constructs, they are typically made non-conforming.
For example, the following markup results in poor performance, since all the unclosed
i elements have to be reconstructed in each paragraph, resulting in progressively
more elements in each paragraph:
< p >< i > She dreamt.
< p >< i > She dreamt that she ate breakfast.
< p >< i > Then lunch.
< p >< i > And finally dinner.The resulting DOM for this fragment would be:
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.
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 does form a named character reference, they will be interpreted as that character instead.
In this fragment, the attribute's value is "?bill&ted":
< a href = "?bill&ted" > Bill and Ted</ a > In the following fragment, however, the attribute's value is actually "?art©", not the intended "?art©",
because even without the final semicolon, "©" is handled the same
as "©" and thus gets interpreted as "©":
< a href = "?art©" > Art and Copy</ a > 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.
Thus, the correct way to express the above cases is as follows:
< a href = "?bill&ted" > Bill and Ted</ a > <!-- &ted is ok, since it's not a named character reference --> < a href = "?art&copy" > Art and Copy</ a > <!-- the & has to be escaped, since © is a named character reference --> 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.
For example, this is why the U+0060 GRAVE ACCENT character (`) is not allowed in unquoted attributes. In certain legacy user agents, it is sometimes treated as a quote character.
Another example of this is the DOCTYPE, which is required to trigger no-quirks mode, because the behavior of legacy user agents in quirks mode is often largely undocumented.
Certain restrictions exist purely to avoid known security problems.
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. [UTF7]
Markup where the author's intent is very unclear is often made non-conforming. Correcting these errors early makes later maintenance easier.
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.
For example, if the author typed <capton> instead of <caption>, this would be flagged as an error and the author could correct
the typo immediately.
In order to allow the language syntax to be extended in the future, certain otherwise harmless features are disallowed.
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.
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.
This section is non-normative.
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:
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.
For example, this specification disallows nesting a section
element inside a kbd element, since it is highly unlikely for an author to indicate
that an entire section should be keyed in.
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.
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.
< hr role = "cell" > < input type = radio role = progressbar > Another example is the restrictions on the content models of the
ul element, which only allows li element children. Lists by definition
consist just of zero or more list items, so if a ul element contains something
other than an li element, it's not clear what was meant.
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.
For example, div elements are rendered as block boxes, and span elements as inline boxes. Putting a block box in an
inline box is unnecessarily confusing; since either nesting just div
elements, or nesting just span elements, or nesting span elements
inside div elements all serve the same purpose as nesting a div
element in a span element, but only the latter involves a block box in
an inline box, the latter combination is disallowed.
Another example would be the way interactive content cannot be
nested. For example, a button element cannot contain a textarea
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.
Sometimes, something is disallowed because allowing it would likely cause author confusion.
For example, setting the disabled
attribute to the value "false" is disallowed, because despite the
appearance of meaning that the element is enabled, it in fact means that the element is
disabled (what matters for implementations is the presence of the attribute, not its
value).
Some conformance errors simplify the language that authors need to learn.
For example, the area element's shape attribute, despite accepting both circ and circle values in practice as synonyms, disallows
the use of the circ 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.
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.
For example, a form element isn't allowed inside phrasing content,
because when parsed as HTML, a form element's start tag will imply a
p element's end tag. Thus, the following markup results in two paragraphs, not one:
< p > Welcome. < form >< label > Name:</ label > < input ></ form > It is parsed exactly like the following:
< p > Welcome. </ p >< form >< label > Name:</ label > < input ></ form > Some errors are intended to help prevent script problems that would be hard to debug.
This is why, for instance, it is non-conforming to have two id attributes with the same value. Duplicate IDs lead to the wrong
element being selected, with sometimes disastrous effects whose cause is hard to determine.
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.
For example, a script element's src 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 script element when the src attribute is present. This means that authors who are
validating their documents are less likely to waste time with this kind of mistake.
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.
For example, there are somewhat complicated rules surrounding the lang and xml:lang attributes
intended to keep the two synchronized.
Another example would be the restrictions on the values of xmlns 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.
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.
For example, limiting the values of the target 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.
Certain restrictions are intended to support the restrictions made by other specifications.
For example, requiring that attributes that take media query lists use only valid media query lists reinforces the importance of following the conformance rules of that specification.
This section is non-normative.
The following documents might be of interest to readers of this specification.
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.
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.
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.
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.
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.
This specification depends on Infra. [INFRA]
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 content attributes for HTML and XML attributes, and IDL attributes 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 object properties and CSS properties respectively.
Generally, when the specification states that a feature applies to the HTML syntax or the XML syntax, 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)".
This specification uses the term document 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 Document
objects and their descendant DOM trees, and to serialized byte streams using the HTML syntax or the XML syntax, depending
on context.
In the context of the DOM structures, the terms HTML
document and XML document are used as defined in
DOM, and refer specifically to two different modes that Document objects
can find themselves in. [DOM] (Such uses are always hyperlinked to their
definition.)
In the context of byte streams, the term HTML document refers to resources labeled as
text/html, and the term XML document refers to resources labeled with an XML
MIME type.
For simplicity, terms such as shown, displayed, and visible 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.
To run steps in parallel 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 event loop). 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 immediately must interrupt the currently running task, run itself, and then resume the previously running task.
For guidance on writing specifications that leverage parallelism, see Dealing with the event loop from other specifications.
To avoid race conditions between different in parallel algorithms that operate on the same data, a parallel queue can be used.
A parallel queue represents a queue of algorithm steps that must be run in series.
A parallel queue has an algorithm queue (a queue), initially empty.
To enqueue steps to a parallel queue, enqueue the algorithm steps to the parallel queue's algorithm queue.
To start a new parallel queue, run the following steps:
Let parallelQueue be a new parallel queue.
Run the following steps in parallel:
While true:
Let steps be the result of dequeuing from parallelQueue's algorithm queue.
If steps is not nothing, then run steps.
Assert: running steps did not throw an exception, as steps running in parallel are not allowed to throw.
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.
Return parallelQueue.
Steps running in parallel can themselves run other steps in in parallel. E.g., inside a parallel queue it can be useful to run a series of steps in parallel with the queue.
Imagine a standard defined nameList (a list), along with a method to add a name to nameList, unless nameList already contains name, in which case it rejects.
The following solution suffers from race conditions:
Let p be a new promise created in this's relevant realm.
Let global be this's relevant global object.
Run the following steps in parallel:
If nameList contains name,
then queue a global task on the DOM manipulation task source given
global to reject p with a TypeError, and abort these
steps.
Do some potentially lengthy work.
Append name to nameList.
Queue a global task on the DOM manipulation task source given global to resolve p with undefined.
Return p.
Two invocations of the above could run simultaneously, meaning name isn't in nameList during step 3.1, but it might be added before step 3.3 runs, meaning name ends up in nameList twice.
Parallel queues solve this. The standard would let nameListQueue be the result of starting a new parallel queue, then:
Let p be a new promise created in this's relevant realm.
Let global be this's relevant global object.
Enqueue the following steps to nameListQueue:
If nameList contains name,
then queue a global task on the DOM manipulation task source given
global to reject p with a TypeError, and abort these
steps.
Do some potentially lengthy work.
Append name to nameList.
Queue a global task on the DOM manipulation task source given global to resolve p with undefined.
Return p.
The steps would now queue and the race is avoided.
The specification uses the term supported 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 supported 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 supported can depend on what features of the resource's format are in use.
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.
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.
What some specifications, in particular the HTTP specifications, refer to as a representation is referred to in this specification as a resource. [HTTP]
A resource's critical subresources 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.
For CSS style sheets, we tentatively define here that
their critical subresources are other style sheets imported via @import
rules, including those indirectly imported by other imported style sheets.
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 w3c/csswg-drafts issue #1088 to track progress on that front.
To ease migration from HTML to XML, user agents conforming to this
specification will place elements in HTML in the http://www.w3.org/1999/xhtml namespace, at least for the purposes of the DOM and
CSS. The term "HTML elements" refers to any element in that namespace, even in
XML documents.
Except where otherwise stated, all elements defined or mentioned in this specification are in
the HTML namespace ("http://www.w3.org/1999/xhtml"), and all
attributes defined or mentioned in this specification have no namespace.
The term element type is used to refer to the set of elements that have a given
local name and namespace. For example, button elements are elements with the element
type button, meaning they have the local name "button" and
(implicitly as defined above) the HTML namespace.
When it is stated that some element or attribute is ignored, 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. A user agent must not mutate the DOM in such situations.
A content attribute is said to change 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.
The term empty, when used for an attribute value, Text node,
or string, means that the length of the text is zero (i.e., not even containing controls or U+0020 SPACE).
An HTML element can have specific HTML element insertion steps, HTML element post-connection steps, HTML element removing steps, and HTML element moving steps all defined for the element's local name.
The insertion steps for the HTML Standard, given insertedNode, are defined as the following:
If insertedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element insertion steps for insertedNode's local name, then run the corresponding HTML element insertion steps given insertedNode.
If insertedNode is a form-associated element or the ancestor of a form-associated element, then:
If the form-associated element's parser inserted flag is set, then return.
If insertedNode is an Element that is not on the
stack of open elements of an HTML parser, then
process internal resource links given insertedNode's
node document.
The post-connection steps for the HTML Standard, given insertedNode, are defined as the following:
If insertedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element post-connection steps for insertedNode's local name, then run the corresponding HTML element post-connection steps given insertedNode.
The removing steps for the HTML Standard, given removedNode and oldParent, are defined as the following:
Let document be removedNode's node document.
If document's focused area is removedNode, then set document's focused area to document's viewport, and set document's relevant global object's navigation API's focus changed during ongoing navigation to false.
This does not perform the unfocusing steps,
focusing steps, or focus update steps, and thus no blur or change events are
fired.
If removedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element removing steps for removedNode's local name, then run the corresponding HTML element removing steps given removedNode and oldParent.
If removedNode is a form-associated element with a non-null form owner and removedNode and its form owner are no longer in the same tree, then reset the form owner of removedNode.
If removedNode's popover attribute is not in
the No Popover state, then run the hide
popover algorithm given removedNode, false, false, false, and null.
The moving steps for the HTML Standard, given movedNode, are defined as the following:
If movedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element moving steps for movedNode's local name, then run the corresponding HTML element moving steps given movedNode.
If movedNode is a form-associated element with a non-null form owner and movedNode and its form owner are no longer in the same tree, then reset the form owner of movedNode.
A node is inserted into a document when the insertion steps are invoked with it as the argument and it is now in a document tree. Analogously, a node is removed from a document when the removing steps are invoked with it as the argument and it is now no longer in a document tree.
A node becomes connected when the insertion steps are invoked with it as the argument and it is now connected. Analogously, a node becomes disconnected when the removing steps are invoked with it as the argument and it is now no longer connected.
A node is browsing-context connected when it is connected and its shadow-including root's browsing context is non-null. A node becomes browsing-context connected when the insertion steps are invoked with it as the argument and it is now browsing-context connected. A node becomes browsing-context disconnected either when the removing steps are invoked with it as the argument and it is now no longer browsing-context connected, or when its shadow-including root's browsing context becomes null.
The construction "a Foo object", where Foo is
actually an interface, is sometimes used instead of the more accurate "an object implementing the
interface Foo".
An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.
If a DOM object is said to be live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
The term plugin refers to an implementation-defined set of content
handlers used by the user agent that can take part in the user agent's rendering of a
Document object, but that neither act as child
navigables of the Document nor introduce any Node objects to the
Document's DOM.
Typically such content handlers are provided by third parties, though a user agent can also designate built-in content handlers as plugins.
A user agent must not consider the types text/plain and
application/octet-stream as having a registered plugin.
One example of a plugin would be a PDF viewer that is instantiated in a navigable 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.
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. [NPAPI]
Browsers should take extreme care when interacting with external content intended for plugins. 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.
Since different users having different sets of plugins provides a
tracking vector that increases the chances of users being uniquely identified, user agents are
encouraged to support the exact same set of plugins for each
user.
A character encoding, or just encoding where that is not ambiguous, is a defined way to convert between byte streams and Unicode strings, as defined in Encoding. An encoding has an encoding name and one or more encoding labels, referred to as the encoding's name and labels in the Encoding standard. [ENCODING]
This specification describes the conformance criteria for user agents (relevant to implementers) and documents (relevant to authors and authoring tool implementers).
Conforming documents 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.)
For example, if a requirement states that "authors must not
use the foobar element", it would imply that documents are not allowed to
contain elements named foobar.
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.
User agents fall into several (overlapping) categories with different conformance requirements.
Web browsers that support the XML syntax must process elements and attributes from the HTML namespace 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.
A conforming web browser would, upon finding a script 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 script element as an opaque element that forms
part of the transform.
Web browsers that support the HTML syntax must process documents labeled with an HTML MIME type as described in this specification, so that users can interact with them.
User agents that support scripting must also be conforming implementations of the IDL fragments in this specification, as described in Web IDL. [WEBIDL]
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 script element in the example above would still implement the
HTMLScriptElement interface.
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.
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 lack scripting support.
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.
User agents, whether interactive or not, may be designated (possibly as a user option) as supporting the suggested default rendering defined by this specification.
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.
User agents that are designated as supporting the suggested default rendering must, while so designated, implement the rules the Rendering section defines as the behavior that user agents are expected to implement.
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.
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.
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 blockquote element is not a quote,
conformance checkers running without the input of human judgement do not have to check that
blockquote elements only contain quoted material).
Conformance checkers must check that the input document conforms when parsed without a browsing context (meaning that no scripts are run, and that the parser's scripting flag is disabled), and should also check that the input document conforms when parsed with a browsing context 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. [COMPUTABLE])
The term "HTML validator" can be used to refer to a conformance checker that itself conforms to the applicable requirements of this specification.
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.
To put it another way, there are three types of conformance criteria:
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.
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.
A tool that generates document outlines but increases the nesting level for each paragraph and does not increase the nesting level for headings would not be conforming.
Authoring tools and markup generators must generate conforming documents. Conformance criteria that apply to authors also apply to authoring tools, where appropriate.
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.
For example, it is not conforming to use an address element for
arbitrary contact information; that element can only be used for marking up contact information
for its nearest article or body 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 address
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
article element, that the user really is doing that and not inserting something
else instead.
In terms of conformance checking, an editor has to output documents that conform to the same extent that a conformance checker will verify.
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.
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).
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.
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
div, b, i, and span and making liberal use
of the style attribute.
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.
For compatibility with existing content and prior specifications, this specification describes two authoring formats: one based on XML, and one using a custom format inspired by SGML (referred to as the HTML syntax). Implementations must support at least one of these two formats, although supporting both is encouraged.
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.)
This specification relies on several other underlying specifications.
The following terms are defined in Infra: [INFRA]
The Unicode character set is used to represent textual data, and Encoding defines requirements around character encodings. [UNICODE]
This specification introduces terminology based on the terms defined in those specifications, as described earlier.
The following terms are used as defined in Encoding: [ENCODING]
Implementations that support the XML syntax for HTML must support some version of XML, as well as its corresponding namespaces specification, because that syntax uses an XML serialization with namespaces. [XML] [XMLNS]
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.
In the HTML syntax, 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.
The attribute with the name space in the XML namespace is defined by
Extensible Markup Language (XML). [XML]
The Name production is defined in XML.
[XML]
This specification also references the <?xml-stylesheet?>
processing instruction, defined in Associating Style Sheets with XML documents.
[XMLSSPI]
This specification also non-normatively mentions the XSLTProcessor
interface and its transformToFragment() and transformToDocument() methods.
[XSLTP]
The following terms are defined in URL: [URL]
application/x-www-form-urlencoded formatapplication/x-www-form-urlencoded serializerA number of schemes and protocols are referenced by this specification also:
about: scheme
[ABOUT]blob: scheme
[FILEAPI]data: scheme
[RFC2397]http: scheme
[HTTP]https: scheme
[HTTP]mailto:
scheme [MAILTO]sms: scheme
[SMS]urn: scheme
[URN]Media fragment syntax is defined in Media Fragments URI. [MEDIAFRAG]
The following terms are defined in URL Pattern: [URLPATTERN]
The following terms are defined in the HTTP specifications: [HTTP]
Accept` headerAccept-Language` headerCache-Control` headerContent-Disposition` headerContent-Language` headerContent-Range` headerLast-Modified` headerRange` headerReferer` headerThe following terms are defined in HTTP State Management Mechanism: [COOKIES]
The following term is defined in Web Linking: [WEBLINK]
Link` headerLink` field valueThe following terms are defined in Structured Field Values for HTTP: [STRUCTURED-FIELDS]
The following terms are defined in MIME Sniffing: [MIMESNIFF]
The following terms are defined in Fetch: [FETCH]
about:blankSec-Purpose`User-Agent` valueOrigin` headerCross-Origin-Resource-Policy` headerRequestCredentials enumerationRequestDestination enumerationfetch() methodThe following terms are defined in Referrer Policy: [REFERRERPOLICY]
Referrer-Policy` HTTP headerReferrer-Policy` header algorithmno-referrer",
"no-referrer-when-downgrade",
"origin-when-cross-origin", and
"unsafe-url" referrer policiesThe following terms are defined in Mixed Content: [MIX]
The following terms are defined in Subresource Integrity: [SRI]
The following terms are defined in The No-Vary-Search HTTP Response Header Field: [NOVARYSEARCH]
The following terms are defined in Paint Timing: [PAINTTIMING]
The following terms are defined in Navigation Timing: [NAVIGATIONTIMING]
NavigationTimingType and its
"navigate",
"reload", and
"back_forward" values.The following terms are defined in Resource Timing: [RESOURCETIMING]
The following terms are defined in Performance Timeline: [PERFORMANCETIMELINE]
PerformanceEntry and its
name,
entryType,
startTime, and
duration attributes.The following terms are defined in Long Animation Frames: [LONGANIMATIONFRAMES]
The following terms are defined in Long Tasks: [LONGTASKS]
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in Web IDL. [WEBIDL]
The following terms are defined in Web IDL:
[Global][LegacyFactoryFunction][LegacyLenientThis][LegacyNullToEmptyString][LegacyOverrideBuiltIns][LegacyTreatNonObjectAsNull][LegacyUnenumerableNamedProperties][LegacyUnforgeable]Web IDL also defines the following types that are used in this specification:
ArrayBufferArrayBufferViewbooleanDOMStringdoubleFloat16ArrayFunctionlongobjectPromiseUint8ClampedArrayunrestricted doubleunsigned longUSVStringVoidFunctionQuotaExceededErrorThe term throw in this
specification is used as defined in Web IDL. The DOMException
type and the following exception names are defined by Web IDL and used by this
specification:
IndexSizeError"HierarchyRequestError"InvalidCharacterError"NoModificationAllowedError"NotFoundError"NotSupportedError"InvalidStateError"SyntaxError"InvalidAccessError"SecurityError"NetworkError"AbortError"DataCloneError"EncodingError"NotAllowedError"When this specification requires a user agent to create a Date object
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 Date object must represent the resulting truncated time.
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 Date 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 Date object that represents a time value NaN (indicating that the object does
not represent a specific instant of time).
Some parts of the language described by this specification only support JavaScript as the underlying scripting language. [JAVASCRIPT]
The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.
The following terms are defined in the JavaScript specification and used in this specification:
Atomics objectAtomics.waitAsync objectDate classFinalizationRegistry classRegExp classSharedArrayBuffer classSyntaxError classTypeError classRangeError classWeakRef classeval() functionWeakRef.prototype.deref() functionimport()import.metatypeof operatordelete operatorUser agents that support JavaScript must also implement the Dynamic Code Brand Checks proposal. The following terms are defined there, and used in this specification: [JSDYNAMICCODEBRANDCHECKS]
User agents that support JavaScript must also implement ECMAScript Internationalization API. [JSINTL]
User agents that support JavaScript must also implement the Temporal proposal. The following terms are defined there, and used in this specification: [JSTEMPORAL]
The following term is defined in WebAssembly JavaScript Interface: [WASMJS]
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. [DOM]
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. [DOM] [UIEVENTS]
In particular, the following features are defined in DOM: [DOM]
Attr interfaceCharacterData interfaceComment interfaceDOMImplementation interfaceDocument interface and its
doctype attribute
DocumentOrShadowRoot interfaceDocumentFragment interfaceDocumentType interfaceChildNode interfaceElement interfaceattachShadow() method.Node interfaceNodeList interfaceProcessingInstruction interfaceShadowRoot interfaceText interfaceRange interfaceHTMLCollection interface, its
length attribute, and its
item() and
namedItem() methodsDOMTokenList interface, and its
value attribute and
supports operationcreateDocument() methodcreateHTMLDocument() methodcreateElement() methodcreateElementNS() methodgetElementById() methodgetElementsByClassName() methodappend() methodappendChild() methodcloneNode() methodmoveBefore() methodimportNode() methodpreventDefault() methodid attributesetAttribute() methodtextContent attributeslotchange eventCharacterData node and its
replace data algorithmEvent interfaceEvent and derived interfaces constructor behaviorEventTarget interfaceEventInit dictionary typetype attributecurrentTarget attributebubbles attributecancelable attributecomposed attributeisTrusted attributeinitEvent() methodaddEventListener() methodEventListener callback interfaceDocumentis valueMutationObserver interface and mutation observers in generalAbortController and its
signalAbortSignalThe following features are defined in UI Events: [UIEVENTS]
MouseEvent interfaceMouseEvent interface's relatedTarget attributeMouseEvent interface's button attributeMouseEventInit dictionary typeFocusEvent interfaceFocusEvent interface's relatedTarget attributeUIEvent interfaceUIEvent interface's view attributeauxclick eventbeforeinput eventclick eventcontextmenu eventdblclick eventinput eventmousedown eventmouseenter eventmouseleave eventmousemove eventmouseout eventmouseover eventmouseup eventwheel eventkeydown eventkeypress eventkeyup eventThe following features are defined in Touch Events: [TOUCH]
Touch interfacetouchend eventThe following features are defined in Pointer Events: [POINTEREVENTS]
PointerEvent interfacePointerEvent interface's pointerType attributepointerdown eventpointerup eventpointercancel eventThe following events are defined in Clipboard API and events: [CLIPBOARD-APIS]
This specification sometimes uses the term name to refer to the event's
type; as in, "an event named click" or "if the event name is keypress". The terms
"name" and "type" for events are synonymous.
The following features are defined in DOM Parsing and Serialization: [DOMPARSING]
The following features are defined in Selection API: [SELECTION]
User agents are encouraged to implement the features described in execCommand. [EXECCOMMAND]
The following features are defined in Fullscreen API: [FULLSCREEN]
requestFullscreen()fullscreenchangeHigh Resolution Time provides the following features: [HRT]
This specification uses the following features defined in File API: [FILEAPI]
Blob interface and its
type attributeFile interface and its
name and
lastModified attributesFileList interfaceBlob's snapshot stateThe following terms are defined in Indexed Database API: [INDEXEDDB]
The following terms are defined in Media Source Extensions: [MEDIASOURCE]
The following terms are defined in Media Capture and Streams: [MEDIASTREAM]
The following terms are defined in Reporting: [REPORTING]
The following features and terms are defined in XMLHttpRequest: [XHR]
XMLHttpRequest interface, and its
responseXML attributeProgressEvent interface, and its
lengthComputable,
loaded, and
total attributesFormData interface, and its associated
entry listThe following features are defined in Battery Status API: [BATTERY]
getBattery() methodImplementations must support Media Queries. The <media-condition> feature is defined therein. [MQ]
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.
When this specification requires that something be parsed according to a particular CSS grammar, the relevant algorithm in CSS Syntax must be followed, including error handling rules. [CSSSYNTAX]
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 "rgb(0,0,0" (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 "rgb(0,0," (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.
The following terms and features are defined in Cascading Style Sheets (CSS): [CSS]
The basic version of the 'display' property is defined in CSS, and the property is extended by other CSS modules. [CSS] [CSSRUBY] [CSSTABLE]
The following terms and features are defined in CSS Box Model: [CSSBOX]
The following features are defined in CSS Logical Properties: [CSSLOGICAL]
The following terms and features are defined in CSS Color: [CSSCOLOR]
The following terms are defined in CSS Images: [CSSIMAGES]
The term paint source is used as defined in CSS Images Level 4 to define the interaction of certain HTML elements with the CSS 'element()' function. [CSSIMAGES4]
The following features are defined in CSS Backgrounds and Borders: [CSSBG]
CSS Backgrounds and Borders also defines the following border properties: [CSSBG]
| Top | Bottom | Left | Right | |
|---|---|---|---|---|
| Width | 'border-top-width' | 'border-bottom-width' | 'border-left-width' | 'border-right-width' |
| Style | 'border-top-style' | 'border-bottom-style' | 'border-left-style' | 'border-right-style' |
| Color | 'border-top-color' | 'border-bottom-color' | 'border-left-color' | 'border-right-color' |
The following features are defined in CSS Box Alignment: [CSSALIGN]
The following terms and features are defined in CSS Display: [CSSDISPLAY]
The following features are defined in CSS Flexible Box Layout: [CSSFLEXBOX]
The following terms and features are defined in CSS Fonts: [CSSFONTS]
The following features are defined in CSS Forms: [CSSFORMS]
The following features are defined in CSS Grid Layout: [CSSGRID]
The following terms are defined in CSS Inline Layout: [CSSINLINE]
The following terms and features are defined in CSS Box Sizing: [CSSSIZING]
The following features are defined in CSS Lists and Counters. [CSSLISTS]
The following features are defined in CSS Overflow. [CSSOVERFLOW]
The following terms and features are defined in CSS Positioned Layout: [CSSPOSITION]
The following features are defined in CSS Multi-column Layout. [CSSMULTICOL]
The 'ruby-base' value of the 'display' property is defined in CSS Ruby Layout. [CSSRUBY]
The following features are defined in CSS Table: [CSSTABLE]
The following features are defined in CSS Text: [CSSTEXT]
The following features are defined in CSS Writing Modes: [CSSWM]
The following features are defined in CSS Basic User Interface: [CSSUI]
The algorithm to update animations and send events is defined in Web Animations. [WEBANIMATIONS]
Implementations that support scripting must support the CSS Object Model. The following features and terms are defined in the CSSOM specifications: [CSSOM] [CSSOMVIEW]
Screen interfaceLinkStyle interfaceCSSStyleDeclaration interfacestyle IDL attributecssText attribute of CSSStyleDeclarationStyleSheet interfaceCSSStyleSheet interfaceCSSStyleSheetCSSStyleSheetresize eventscroll eventscrollend eventThe following features and terms are defined in CSS Syntax: [CSSSYNTAX]
The following terms are defined in Selectors: [SELECTORS]
<selector-list>:focus-visible
pseudo-classThe following features are defined in CSS Values and Units: [CSSVALUES]
The following features are defined in CSS View Transitions: [CSSVIEWTRANSITIONS]
ViewTransitionThe term style attribute is defined in CSS Style Attributes. [CSSATTR]
The following terms are defined in the CSS Cascading and Inheritance: [CSSCASCADE]
The CanvasRenderingContext2D object's use of fonts depends on the features
described in the CSS Fonts and Font Loading specifications, including
in particular FontFace objects and the font source concept.
[CSSFONTS] [CSSFONTLOAD]
The following interfaces and terms are defined in Geometry Interfaces: [GEOMETRY]
DOMMatrix interface, and associated
m11 element,
m12 element,
m21 element,
m22 element,
m41 element, and
m42 elementDOMMatrix2DInit and
DOMMatrixInit dictionariesDOMMatrix from a dictionary
and create a DOMMatrix from a 2D dictionary
algorithms for DOMMatrix2DInit or DOMMatrixInitDOMPointInit dictionary, and associated
x and
y membersThe following terms are defined in the CSS Scoping: [CSSSCOPING]
The following terms and features are defined in CSS Color Adjustment: [CSSCOLORADJUST]
The following terms are defined in CSS Pseudo-Elements: [CSSPSEUDO]
The following terms are defined in CSS Containment: [CSSCONTAIN]
The following terms are defined in CSS Anchor Positioning: [CSSANCHOR]
The following term is defined in Intersection Observer: [INTERSECTIONOBSERVER]
The following terms are defined in Resize Observer: [RESIZEOBSERVER]
The following interfaces are defined in the WebGL specifications: [WEBGL]
WebGLRenderingContext interfaceWebGL2RenderingContext interfaceWebGLContextAttributes dictionaryThe following interfaces are defined in WebGPU: [WEBGPU]
GPUCanvasContext interfaceImplementations may support WebVTT as a text track format for subtitles, captions, metadata, etc., for media resources. [WEBVTT]
The following terms, used in this specification, are defined in WebVTT:
The role attribute is defined in
Accessible Rich Internet Applications (ARIA), as are the following
roles: [ARIA]
In addition, the following aria-* content
attributes are defined in ARIA: [ARIA]
Finally, the following terms are defined in ARIA: [ARIA]
ARIAMixin interface, with its associated
ARIAMixin getter steps and
ARIAMixin setter steps hooks, and its
role and
aria* attributesThe following terms are defined in Content Security Policy: [CSP]
report-uri directiveframe-ancestors directivesandbox directiveSecurityPolicyViolationEvent interfacesecuritypolicyviolation eventThe following terms are defined in Service Workers: [SW]
The following algorithms are defined in Secure Contexts: [SECURE-CONTEXTS]
The following terms are defined in Permissions Policy: [PERMISSIONSPOLICY]
The following feature is defined in Payment Request API: [PAYMENTREQUEST]
PaymentRequest interfaceWhile 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. [MATHML]
The following features are defined in Mathematical Markup Language (MathML):
annotation-xml elementmath elementmerror elementmi elementmn elementmo elementms elementmtext elementWhile 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.
User agents that implement SVG must implement the SVG 2 specification, and not any earlier revisions.
The following features are defined in the SVG 2 specification: [SVG]
SVGElement interfaceSVGImageElement interfaceSVGScriptElement interfaceSVGSVGElement interfacea elementdesc elementforeignObject elementimage elementscript elementsvg elementtitle elementuse elementtext-rendering propertyThe following features are defined in Filter Effects: [FILTERS]
The following features are defined in Compositing and Blending: [COMPOSITE]
The following features are defined in Cooperative Scheduling of Background Tasks: [REQUESTIDLECALLBACK]
The following terms are defined in Screen Orientation: [SCREENORIENTATION]
The following terms are defined in Storage: [STORAGE]
The following features are defined in Web App Manifest: [MANIFEST]
The following terms are defined in WebAssembly JavaScript Interface: ESM Integration: [WASMESM]
The following features are defined in WebCodecs: [WEBCODECS]
The following terms are defined in WebDriver: [WEBDRIVER]
The following terms are defined in WebDriver BiDi: [WEBDRIVERBIDI]
The following terms are defined in Web Cryptography API: [WEBCRYPTO]
The following terms are defined in WebSockets: [WEBSOCKETS]
The following terms are defined in WebTransport: [WEBTRANSPORT]
The following terms are defined in Web Authentication: An API for accessing Public Key Credentials: [WEBAUTHN]
The following terms are defined in Credential Management: [CREDMAN]
The following terms are defined in Console: [CONSOLE]
The following terms are defined in Web Locks API: [WEBLOCKS]
This specification uses the following features defined in Trusted Types: [TRUSTED-TYPES]
The following terms are defined in WebRTC API: [WEBRTC]
The following terms are defined in Picture-in-Picture API: [PICTUREINPICTURE]
The following terms are defined in Idle Detection API:
The following terms are defined in Web Speech API:
The following terms are defined in WebOTP API:
The following terms are defined in Web Share API:
The following terms are defined in Web Smart Card API:
The following terms are defined in Web Background Synchronization:
The following terms are defined in Web Periodic Background Synchronization:
The following terms are defined in Background Fetch:
The following terms are defined in Keyboard Lock:
The following terms are defined in Web MIDI API:
The following terms are defined in Generic Sensor API:
The following terms are defined in WebHID API:
The following terms are defined in WebXR Device API:
This specification does not require 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.
A user agent that implements the HTTP protocol must implement HTTP State Management Mechanism (Cookies) as well. [HTTP] [COOKIES]
This specification might have certain additional requirements on character encodings, image formats, audio formats, and video formats in the respective sections.
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.
All extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.
For example, while strongly discouraged from doing so, an implementation could add a new IDL
attribute "typeTime" 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 elements array would be in violation
of the above requirement, as it would violate the definition of elements given in this specification.
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 applicable specification for the purposes of conformance requirements in this specification.
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 agrees is applicable.
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.
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.
Implementations of XPath 1.0 that operate on HTML
documents parsed or created in the manners described in this specification (e.g. as part of
the document.evaluate() API) must act as if the following edit was applied
to the XPath 1.0 specification.
First, remove this paragraph:
A QName in the node test is expanded into an expanded-name 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
xmlnsis not used: if the QName 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 QName has a prefix for which there is no namespace declaration in the expression context.
Then, insert in its place the following:
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 namespace declaration for this prefix in the expression context, and the corresponding 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.
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:
- If the context node is from an HTML DOM, the default element namespace is "http://www.w3.org/1999/xhtml".
- Otherwise, the default element namespace URI is null.
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.
This change is a willful violation 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. [XPATH10]
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:
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 HTML namespace, ASCII-lowercase the element's local name, and ASCII-lowercase the names of any non-namespaced attributes on the element.
This requirement is a willful violation 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.) [XSLT10]
This specification does not specify precisely how XSLT processing interacts with the HTML
parser infrastructure (for example, whether an XSLT processor acts as if it puts any
elements into a stack of open elements). However, XSLT processors must stop
parsing if they successfully complete, and must update the current document
readiness first to "interactive" and then to "complete" if they are aborted.
This specification does not specify how XSLT interacts with the navigation algorithm, how it fits in with the event loop, 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.).
There are also additional non-normative comments regarding the interaction of XSLT
and HTML in the script element section, and of
XSLT, XPath, and HTML in the template element
section.
Headers/Permissions-Policy/document-domain
Support in one engine only.
This document defines the following policy-controlled features:
Headers/Feature-Policy/autoplay
Headers/Permissions-Policy/autoplay
Support in one engine only.
autoplay", which has a default allowlist of 'self'.cross-origin-isolated", which has a default allowlist of 'self'.focus-without-user-activation", which has a default allowlist of 'self'.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.
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.
Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.
A number of attributes are boolean attributes. The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.
If the attribute is present, its value must either be the empty string or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace.
The values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether.
Here is an example of a checkbox that is checked and disabled. The checked and disabled
attributes are the boolean attributes.
< label >< input type = checkbox checked name = cheese disabled > Cheese</ label > This could be equivalently written as this:
< label >< input type = checkbox checked = checked name = cheese disabled = disabled > Cheese</ label > You can also mix styles; the following is still equivalent:
< label >< input type = 'checkbox' checked name = cheese disabled = "" > Cheese</ label > Some attributes, called enumerated attributes, 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, and three possible special states that can also be given in the specification of the attribute. These special states are the invalid value default, the missing value default, and the empty value default.
Multiple keywords can map to the same state.
To determine the state of an attribute, use the following steps:
If the attribute is not specified:
If the attribute has a missing value default state defined, then return that missing value default state.
Otherwise, return no state.
If the attribute's value is an ASCII case-insensitive match for one of the keywords defined for the attribute, then return the state represented by that keyword.
If the attribute has an empty value default state defined and the attribute's value is the empty string, then return that empty value default state.
If the attribute has an invalid value default state defined, then return that invalid value default state.
Return no state.
For authoring conformance purposes, if an enumerated attribute is specified, the attribute's value must be one of:
An ASCII case-insensitive match for one of the conforming keywords for that attribute, with no leading or trailing whitespace.
The empty string and the attribute must have an empty value default defined.
For reflection purposes, states which have any keywords mapping to them are said to have a canonical keyword. This is determined as follows:
If there is only one keyword mapping to the given state, then it is that keyword.
If there is only one conforming keyword mapping to the given state, then it is that conforming keyword.
If there are two conforming keywords mapping to the given state, and one is the empty string, then the canonical keyword will be the conforming keyword that is not the empty string.
Otherwise, the canonical keyword for the state will be explicitly given in the specification for the attribute.
A string is a valid integer if it consists of one or more ASCII digits, optionally prefixed with a U+002D HYPHEN-MINUS character (-).
A valid integer without a U+002D HYPHEN-MINUS (-) prefix represents the number that is represented in base ten by that string of digits. A valid integer with 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.
The rules for parsing integers 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Let sign have the value "positive".
Skip ASCII whitespace within input given position.
If position is past the end of input, return an error.
If the character indicated by position (the first character) is a U+002D HYPHEN-MINUS character (-):
Otherwise, if the character indicated by position (the first character) is a U+002B PLUS SIGN character (+):
+" is
ignored, but it is not conforming.)If the character indicated by position is not an ASCII digit, then return an error.
Collect a sequence of code points that are ASCII digits from input given position, and interpret the resulting sequence as a base-ten integer. Let value be that integer.
If sign is "positive", return value, otherwise return the result of subtracting value from zero.
A string is a valid non-negative integer if it consists of one or more ASCII digits.
A valid non-negative integer represents the number that is represented in base ten by that string of digits.
The rules for parsing non-negative integers 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.
Let input be the string being parsed.
Let value be the result of parsing input using the rules for parsing integers.
If value is an error, return an error.
If value is less than zero, return an error.
Return value.
A string is a valid floating-point number if it consists of:
Optionally, a U+002D HYPHEN-MINUS character (-).
One or both of the following, in the given order:
A series of one or more ASCII digits.
Both of the following, in the given order:
A single U+002E FULL STOP character (.).
A series of one or more ASCII digits.
Optionally:
Either a U+0065 LATIN SMALL LETTER E character (e) or a U+0045 LATIN CAPITAL LETTER E character (E).
Optionally, a U+002D HYPHEN-MINUS character (-) or U+002B PLUS SIGN character (+).
A series of one or more ASCII digits.
A valid floating-point number 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.
The Infinity and Not-a-Number (NaN) values are not valid floating-point numbers.
The valid floating-point number concept is typically only used to
restrict what is allowed for authors, while the user agent requirements use the rules for
parsing floating-point number values below (e.g., the max attribute of the progress element). However, in
some cases the user agent requirements include checking if a string is a valid
floating-point number (e.g., the value sanitization algorithm for the Number state of the input element, or the
parse a srcset attribute algorithm).
The best representation of the number n as a floating-point number is the string obtained from running ToString(n). The abstract operation ToString is not uniquely determined. When there are multiple possible strings that could be obtained from ToString 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).
The rules for parsing floating-point number values 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Let value have the value 1.
Let divisor have the value 1.
Let exponent have the value 1.
Skip ASCII whitespace within input given position.
If position is past the end of input, return an error.
If the character indicated by position is a U+002D HYPHEN-MINUS character (-):
Otherwise, if the character indicated by position (the first character) is a U+002B PLUS SIGN character (+):
+"
is ignored, but it is not conforming.)If the character indicated by position is a U+002E FULL STOP (.), and that is not the last character in input, and the character after the character indicated by position is an ASCII digit, then set value to zero and jump to the step labeled fraction.
If the character indicated by position is not an ASCII digit, then return an error.
Collect a sequence of code points that are ASCII digits from input given position, and interpret the resulting sequence as a base-ten integer. Multiply value by that integer.
Fraction: If the character indicated by position is a U+002E FULL STOP (.), run these substeps:
Advance position to the next character.
If position is past the end of input, or if the character indicated by position is not an ASCII digit, U+0065 LATIN SMALL LETTER E (e), or U+0045 LATIN CAPITAL LETTER E (E), then jump to the step labeled conversion.
If the character indicated by position 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.
Fraction loop: Multiply divisor by ten.
Advance position to the next character.
If position is past the end of input, then jump to the step labeled conversion.
If the character indicated by position is an ASCII digit, jump back to the step labeled fraction loop in these substeps.
If the character indicated by position is U+0065 (e) or a U+0045 (E), then:
Advance position to the next character.
If position is past the end of input, then jump to the step labeled conversion.
If the character indicated by position is a U+002D HYPHEN-MINUS character (-):
If position is past the end of input, then jump to the step labeled conversion.
Otherwise, if the character indicated by position is a U+002B PLUS SIGN character (+):
If position is past the end of input, then jump to the step labeled conversion.
If the character indicated by position is not an ASCII digit, then jump to the step labeled conversion.
Collect a sequence of code points that are ASCII digits from input given position, and interpret the resulting sequence as a base-ten integer. Multiply exponent by that integer.
Multiply value by ten raised to the exponentth power.
Conversion: Let S be the set of finite IEEE 754 double-precision floating-point values except −0, but with two special values added: 21024 and −21024.
Let rounded-value be the number in S that is closest to value, selecting the number with an even significand if there are two equally close values. (The two special values 21024 and −21024 are considered to have even significands for this purpose.)
If rounded-value is 21024 or −21024, return an error.
Return rounded-value.
The rules for parsing dimension values 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.
Let input be the string being parsed.
Let position be a position variable for input, initially pointing at the start of input.
Skip ASCII whitespace within input given position.
If position is past the end of input or the code point at position within input is not an ASCII digit, then return failure.
Collect a sequence of code points that are ASCII digits from input given position, and interpret the resulting sequence as a base-ten integer. Let value be that number.
If position is past the end of input, then return value as a length.
If the code point at position within input is U+002E (.), then:
Advance position by 1.
If position is past the end of input or the code point at position within input is not an ASCII digit, then return the current dimension value with value, input, and position.
Let divisor have the value 1.
While true:
Multiply divisor by ten.
Add the value of the code point at position within input, interpreted as a base-ten digit (0..9) and divided by divisor, to value.
Advance position by 1.
If position is past the end of input, then return value as a length.
If the code point at position within input is not an ASCII digit, then break.
Return the current dimension value with value, input, and position.
The current dimension value, given value, input, and position, is determined as follows:
If position is past the end of input, then return value as a length.
If the code point at position within input is U+0025 (%), then return value as a percentage.
Return value as a length.
The rules for parsing nonzero dimension values 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.
Let input be the string being parsed.
Let value be the result of parsing input using the rules for parsing dimension values.
If value is an error, return an error.
If value is zero, return an error.
If value is a percentage, return value as a percentage.
Return value as a length.
A valid list of floating-point numbers is a number of valid floating-point numbers separated by U+002C COMMA characters, with no other characters (e.g. no ASCII whitespace). In addition, there might be restrictions on the number of floating-point numbers that can be given, or on the range of values allowed.
The rules for parsing a list of floating-point numbers are as follows:
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Let numbers be an initially empty list of floating-point numbers. This list will be the result of this algorithm.
Collect a sequence of code points that are ASCII whitespace, U+002C COMMA, or U+003B SEMICOLON characters from input given position. This skips past any leading delimiters.
While position is not past the end of input:
Collect a sequence of code points that are not ASCII whitespace, U+002C COMMA, U+003B SEMICOLON, ASCII digits, U+002E FULL STOP, or U+002D HYPHEN-MINUS characters from input given position. This skips past leading garbage.
Collect a sequence of code points that are not ASCII whitespace, U+002C COMMA, or U+003B SEMICOLON characters from input given position, and let unparsed number be the result.
Let number be the result of parsing unparsed number using the rules for parsing floating-point number values.
If number is an error, set number to zero.
Append number to numbers.
Collect a sequence of code points that are ASCII whitespace, U+002C COMMA, or U+003B SEMICOLON characters from input given position. This skips past the delimiter.
Return numbers.
The rules for parsing a list of dimensions 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 percentage, relative, and absolute.
Let raw input be the string being parsed.
If the last character in raw input is a U+002C COMMA character (,), then remove that character from raw input.
Split the string raw input on commas. Let raw tokens be the resulting list of tokens.
Let result be an empty list of number/unit pairs.
For each token in raw tokens, run the following substeps:
Let input be the token.
Let position be a pointer into input, initially pointing at the start of the string.
Let value be the number 0.
Let unit be absolute.
If position is past the end of input, set unit to relative and jump to the last substep.
If the character at position is an ASCII digit, collect a sequence of code points that are ASCII digits from input given position, interpret the resulting sequence as an integer in base ten, and increment value by that integer.
If the character at position is U+002E (.), then:
Collect a sequence of code points consisting of ASCII whitespace and ASCII digits from input given position. Let s be the resulting sequence.
Remove all ASCII whitespace in s.
If s is not the empty string, then:
Let length be the number of characters in s (after the spaces were removed).
Let fraction be the result of interpreting s as a base-ten integer, and then dividing that number by 10length.
Increment value by fraction.
Skip ASCII whitespace within input given position.
If the character at position is a U+0025 PERCENT SIGN character (%), then set unit to percentage.
Otherwise, if the character at position is a U+002A ASTERISK character (*), then set unit to relative.
Add an entry to result consisting of the number given by value and the unit given by unit.
Return the list result.
In the algorithms below, the number of days in month month of year year is: 31 if month is 1, 3, 5, 7, 8, 10, or 12; 30 if month is 4, 6, 9, or 11; 29 if month is 2 and year is a number divisible by 400, or if year is a number divisible by 4 but not by 100; and 28 otherwise. This takes into account leap years in the Gregorian calendar. [GREGORIAN]
When ASCII digits are used in the date and time syntaxes defined in this section, they express numbers in base ten.
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. [ISO8601]
Where this specification refers to the proleptic Gregorian calendar, it means the modern Gregorian calendar, extrapolated backwards to year 1. A date in the proleptic Gregorian calendar, sometimes explicitly referred to as a proleptic-Gregorian date, is one that is described using that calendar even if that calendar was not in use at the time (or place) in question. [GREGORIAN]
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 date, time, and number formats in forms
(for authors), implementation notes regarding
localization of form controls, and the time element.
A month consists of a specific proleptic-Gregorian date with no time-zone information and no date information beyond a year and a month. [GREGORIAN]
A string is a valid month string representing a year year and month month if it consists of the following components in the given order:
The rules to parse a month string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a month component to obtain year and month. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Return year and month.
The rules to parse a month component, given an input string and a position, 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.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not at least four characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let year be that number.
If year is not a number greater than zero, then fail.
If position is beyond the end of input or if the character at position is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let month be that number.
If month is not a number in the range 1 ≤ month ≤ 12, then fail.
Return year and month.
A date consists of a specific proleptic-Gregorian date with no time-zone information, consisting of a year, a month, and a day. [GREGORIAN]
A string is a valid date string representing a year year, month month, and day day if it consists of the following components in the given order:
The rules to parse a date string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Let date be the date with year year, month month, and day day.
Return date.
The rules to parse a date component, given an input string and a position, 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.
Parse a month component to obtain year and month. If this returns nothing, then fail.
Let maxday be the number of days in month month of year year.
If position is beyond the end of input or if the character at position is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let day be that number.
If day is not a number in the range 1 ≤ day ≤ maxday, then fail.
Return year, month, and day.
A yearless date consists of a Gregorian month and a day within that month, but with no associated year. [GREGORIAN]
A string is a valid yearless date string representing a month month and a day day if it consists of the following components in the given order:
In other words, if the month is "02",
meaning February, then the day can be 29, as if the year was a leap year.
The rules to parse a yearless date string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a yearless date component to obtain month and day. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Return month and day.
The rules to parse a yearless date component, given an input string and a position, 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.
Collect a sequence of code points that are U+002D HYPHEN-MINUS characters (-) from input given position. If the collected sequence is not exactly zero or two characters long, then fail.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let month be that number.
If month is not a number in the range 1 ≤ month ≤ 12, then fail.
Let maxday be the number of days in month month of any arbitrary leap year (e.g. 4 or 2000).
If position is beyond the end of input or if the character at position is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let day be that number.
If day is not a number in the range 1 ≤ day ≤ maxday, then fail.
Return month and day.
A time consists of a specific time with no time-zone information, consisting of an hour, a minute, a second, and a fraction of a second.
A string is a valid time string representing an hour hour, a minute minute, and a second second if it consists of the following components in the given order:
The second component cannot be 60 or 61; leap seconds cannot be represented.
The rules to parse a time string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Let time be the time with hour hour, minute minute, and second second.
Return time.
The rules to parse a time component, given an input string and a position, 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.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let hour be that number.
If position is beyond the end of input or if the character at position is not a U+003A COLON character, then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let minute be that number.
Let second be 0.
If position is not beyond the end of input and the character at position is U+003A (:), then:
Advance position to the next character in input.
If position is beyond the end of input, or at the last character in input, or if the next two characters in input starting at position are not both ASCII digits, then fail.
Collect a sequence of code points that are either ASCII digits or U+002E FULL STOP characters from input given position. 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 second to that number.
If second is not a number in the range 0 ≤ second < 60, then fail.
Return hour, minute, and second.
A local date and time consists of a specific proleptic-Gregorian date, 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. [GREGORIAN]
A string is a valid local date and time string representing a date and time if it consists of the following components in the given order:
A string is a valid normalized local date and time string representing a date and time if it consists of the following components in the given order:
The rules to parse a local date and time string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
If position is beyond the end of input or if the character at position is neither a U+0054 LATIN CAPITAL LETTER T character (T) nor a U+0020 SPACE character, then fail. Otherwise, move position forwards one character.
Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Let date be the date with year year, month month, and day day.
Let time be the time with hour hour, minute minute, and second second.
Return date and time.
A time-zone offset consists of a signed number of hours and minutes.
A string is a valid time-zone offset string representing a time-zone offset if it consists of either:
A U+005A LATIN CAPITAL LETTER Z character (Z), allowed only if the time zone is UTC
Or, the following components, in the given order:
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.
See also the usage notes and examples in the global date and time section below for details on using time-zone offsets with historical times that predate the formation of formal time zones.
The rules to parse a time-zone offset string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Return the time-zone offset that is timezonehours hours and timezoneminutes minutes from UTC.
The rules to parse a time-zone offset component, given an input string and a position, 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.
If the character at position is a U+005A LATIN CAPITAL LETTER Z character (Z), then:
Let timezonehours be 0.
Let timezoneminutes be 0.
Advance position to the next character in input.
Otherwise, if the character at position is either a U+002B PLUS SIGN (+) or a U+002D HYPHEN-MINUS (-), then:
If the character at position is a U+002B PLUS SIGN (+), let sign be "positive". Otherwise, it's a U+002D HYPHEN-MINUS (-); let sign be "negative".
Advance position to the next character in input.
Collect a sequence of code points that are ASCII digits from input given position. Let s be the collected sequence.
If s is exactly two characters long, then:
Interpret s as a base-ten integer. Let timezonehours be that number.
If position is beyond the end of input or if the character at position is not a U+003A COLON character, then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let timezoneminutes be that number.
If s is exactly four characters long, then:
Interpret the first two characters of s as a base-ten integer. Let timezonehours be that number.
Interpret the last two characters of s as a base-ten integer. Let timezoneminutes be that number.
Otherwise, fail.
Otherwise, fail.
Return timezonehours and timezoneminutes.
A global date and time consists of a specific proleptic-Gregorian date, 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. [GREGORIAN]
A string is a valid global date and time string representing a date, time, and a time-zone offset if it consists of the following components in the given order:
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.
The following are some examples of dates written as valid global date and time strings.
0037-12-13 00:00Z"1979-10-14T12:00:00.001-04:00"8592-01-01T02:09+02:09"Several things are notable about these dates:
T" is replaced by a space, it must be a single space
character. The string "2001-12-21 12:00Z" (with two spaces
between the components) would not be parsed successfully.The rules to parse a global date and time string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
If position is beyond the end of input or if the character at position is neither a U+0054 LATIN CAPITAL LETTER T character (T) nor a U+0020 SPACE character, then fail. Otherwise, move position forwards one character.
Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If position is beyond the end of input, then fail.
Parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
Let time be the moment in time at year year, month month, day day, hours hour, minute minute, second second, subtracting timezonehours hours and timezoneminutes minutes. That moment in time is a moment in the UTC time zone.
Let timezone be timezonehours hours and timezoneminutes minutes from UTC.
Return time and timezone.
A week 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. [GREGORIAN]
A week-year with a number year has 53 weeks if it corresponds to either a year year in the proleptic Gregorian calendar that has a Thursday as its first day (January 1st), or a year year in the proleptic Gregorian calendar that has a Wednesday as its first day (January 1st) and where year is a number divisible by 400, or a number divisible by 4 but not by 100. All other week-years have 52 weeks.
The week number of the last day 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.
The week-year number of a particular day can be different than the number of the year that contains that day in the proleptic Gregorian calendar. The first week in a week-year y is the week that contains the first Thursday of the Gregorian year y.
For modern purposes, a week as defined here is equivalent to ISO weeks as defined in ISO 8601. [ISO8601]
A string is a valid week string representing a week-year year and week week if it consists of the following components in the given order:
The rules to parse a week string 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not at least four characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let year be that number.
If year is not a number greater than zero, then fail.
If position is beyond the end of input or if the character at position is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move position forwards one character.
If position is beyond the end of input or if the character at position is not a U+0057 LATIN CAPITAL LETTER W character (W), then fail. Otherwise, move position forwards one character.
Collect a sequence of code points that are ASCII digits from input given position. If the collected sequence is not exactly two characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer. Let week be that number.
Let maxweek be the week number of the last day of year year.
If week is not a number in the range 1 ≤ week ≤ maxweek, then fail.
If position is not beyond the end of input, then fail.
Return the week-year number year and the week number week.
A duration consists of a number of seconds.
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 duration as defined in this specification cannot include months (or years, which are equivalent to twelve months). Only durations that describe a specific number of seconds can be described.
A string is a valid duration string representing a duration t if it consists of either of the following:
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 days, hours, minutes, and seconds corresponds to the same number of seconds as in t:
One or more ASCII digits followed by a U+0044 LATIN CAPITAL LETTER D character, representing a number of days.
A U+0054 LATIN CAPITAL LETTER T character followed by one or more of the following subcomponents, in the order given:
One or more ASCII digits followed by a U+0048 LATIN CAPITAL LETTER H character, representing a number of hours.
One or more ASCII digits followed by a U+004D LATIN CAPITAL LETTER M character, representing a number of minutes.
The following components:
One or more ASCII digits, representing a number of seconds.
Optionally, a U+002E FULL STOP character (.) followed by one, two, or three ASCII digits, representing a fraction of a second.
A U+0053 LATIN CAPITAL LETTER S character.
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. [ISO8601]
One or more duration time components, each with a different duration time component scale, in any order; the sum of the represented seconds being equal to the number of seconds in t.
A duration time component is a string consisting of the following components:
Zero or more ASCII whitespace.
One or more ASCII digits, representing a number of time units, scaled by the duration time component scale specified (see below) to represent a number of seconds.
If the duration time component scale specified is 1 (i.e. the units are seconds), then, optionally, a U+002E FULL STOP character (.) followed by one, two, or three ASCII digits, representing a fraction of a second.
Zero or more ASCII whitespace.
One of the following characters, representing the duration time component scale of the time unit used in the numeric part of the duration time component:
Zero or more ASCII whitespace.
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.
The rules to parse a duration string are as follows. This will return either a duration or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Let months, seconds, and component count all be zero.
Let M-disambiguator be minutes.
This flag's other value is months. 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.
Skip ASCII whitespace within input given position.
If position is past the end of input, then fail.
If the character in input pointed to by position is a U+0050 LATIN CAPITAL LETTER P character, then advance position to the next character, set M-disambiguator to months, and skip ASCII whitespace within input given position.
While true:
Let units be undefined. It will be assigned one of the following values: years, months, weeks, days, hours, minutes, and seconds.
Let next character be undefined. It is used to process characters from the input.
If position is past the end of input, then break.
If the character in input pointed to by position is a U+0054 LATIN CAPITAL LETTER T character, then advance position to the next character, set M-disambiguator to minutes, skip ASCII whitespace within input given position, and continue.
Set next character to the character in input pointed to by position.
If next character is a U+002E FULL STOP character (.), then let N be 0. (Do not advance position. That is taken care of below.)
Otherwise, if next character is an ASCII digit, then collect a sequence of code points that are ASCII digits from input given position, interpret the resulting sequence as a base-ten integer, and let N be that number.
Otherwise, next character is not part of a number; fail.
If position is past the end of input, then fail.
Set next character to the character in input pointed to by position, and this time advance position to the next character. (If next character was a U+002E FULL STOP character (.) before, it will still be that character this time.)
If next character is U+002E (.), then:
Collect a sequence of code points that are ASCII digits from input given position. Let s be the resulting sequence.
If s is the empty string, then fail.
Let length be the number of characters in s.
Let fraction be the result of interpreting s as a base-ten integer, and then dividing that number by 10length.
Increment N by fraction.
Skip ASCII whitespace within input given position.
If position is past the end of input, then fail.
Set next character to the character in input pointed to by position, and advance position to the next character.
If next character is neither a U+0053 LATIN CAPITAL LETTER S character nor a U+0073 LATIN SMALL LETTER S character, then fail.
Set units to seconds.
Otherwise:
If next character is ASCII whitespace, then skip ASCII whitespace within input given position, set next character to the character in input pointed to by position, and advance position to the next character.
If next character is a U+0059 LATIN CAPITAL LETTER Y character, or a U+0079 LATIN SMALL LETTER Y character, set units to years and set M-disambiguator to months.
If next character is a U+004D LATIN CAPITAL LETTER M character or a U+006D LATIN SMALL LETTER M character, and M-disambiguator is months, then set units to months.
If next character is a U+0057 LATIN CAPITAL LETTER W character or a U+0077 LATIN SMALL LETTER W character, set units to weeks and set M-disambiguator to minutes.
If next character is a U+0044 LATIN CAPITAL LETTER D character or a U+0064 LATIN SMALL LETTER D character, set units to days and set M-disambiguator to minutes.
If next character is a U+0048 LATIN CAPITAL LETTER H character or a U+0068 LATIN SMALL LETTER H character, set units to hours and set M-disambiguator to minutes.
If next character is a U+004D LATIN CAPITAL LETTER M character or a U+006D LATIN SMALL LETTER M character, and M-disambiguator is minutes, then set units to minutes.
If next character is a U+0053 LATIN CAPITAL LETTER S character or a U+0073 LATIN SMALL LETTER S character, set units to seconds and set M-disambiguator to minutes.
Otherwise, if next character is none of the above characters, then fail.
Increment component count.
Let multiplier be 1.
If units is years, multiply multiplier by 12 and set units to months.
If units is months, add the product of N and multiplier to months.
Otherwise:
If units is weeks, multiply multiplier by 7 and set units to days.
If units is days, multiply multiplier by 24 and set units to hours.
If units is hours, multiply multiplier by 60 and set units to minutes.
If units is minutes, multiply multiplier by 60 and set units to seconds.
Forcibly, units is now seconds. Add the product of N and multiplier to seconds.
Skip ASCII whitespace within input given position.
If component count is zero, fail.
If months is not zero, fail.
Return the duration consisting of seconds seconds.
A string is a valid date string with optional time if it is also one of the following:
The rules to parse a date or time string are as follows. The algorithm will return either a date, a time, a global 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.
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Set start position to the same position as position.
Set the date present and time present flags to true.
Parse a date component to obtain year, month, and day. If this fails, then set the date present flag to false.
If date present is true, and position is not beyond the end of input, and the character at position is either a U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character, then advance position to the next character in input.
Otherwise, if date present is true, and either position is beyond the end of input or the character at position is neither a U+0054 LATIN CAPITAL LETTER T character (T) nor a U+0020 SPACE character, then set time present to false.
Otherwise, if date present is false, set position back to the same position as start position.
If the time present flag is true, then parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
If the date present and time present flags are both true, but position is beyond the end of input, then fail.
If the date present and time present flags are both true, parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this returns nothing, then fail.
If position is not beyond the end of input, then fail.
If the date present flag is true and the time present flag is false, then let date be the date with year year, month month, and day day, and return date.
Otherwise, if the time present flag is true and the date present flag is false, then let time be the time with hour hour, minute minute, and second second, and return time.
Otherwise, let time be the moment in time at year year, month month, day day, hours hour, minute minute, second second, subtracting timezonehours hours and timezoneminutes minutes, that moment in time being a moment in the UTC time zone; let timezone be timezonehours hours and timezoneminutes minutes from UTC; and return time and timezone.
Some obsolete legacy attributes parse colors using the rules for parsing a legacy color value, given a string input. They will return either a CSS color or failure.
If input is the empty string, then return failure.
Strip leading and trailing ASCII whitespace from input.
If input is an ASCII case-insensitive match for "transparent", then return failure.
If input is an ASCII case-insensitive match for one of the named colors, then return the CSS color corresponding to that keyword. [CSSCOLOR]
CSS2 System Colors are not recognized.
If input's code point length is four, and the first character in input is U+0023 (#), and the last three characters of input are all ASCII hex digits, then:
Let result be a CSS color.
Interpret the second character of input as a hexadecimal digit; let the red component of result be the resulting number multiplied by 17.
Interpret the third character of input as a hexadecimal digit; let the green component of result be the resulting number multiplied by 17.
Interpret the fourth character of input as a hexadecimal digit; let the blue component of result be the resulting number multiplied by 17.
Return result.
Replace any code points greater than U+FFFF in
input (i.e., any characters that are not in the basic multilingual plane) with "00".
If input's code point length is greater than 128, truncate input, leaving only the first 128 characters.
If the first character in input is U+0023 (#), then remove it.
Replace any character in input that is not an ASCII hex digit with U+0030 (0).
While input's code point length is zero or not a multiple of three, append U+0030 (0) to input.
Split input into three strings of equal code point length, to obtain three components. Let length be the code point length that all of those components have (one third the code point length of input).
If length is greater than 8, then remove the leading length-8 characters in each component, and let length be 8.
While length is greater than two and the first character in each component is U+0030 (0), remove that character and reduce length by one.
If length is still greater than two, truncate each component, leaving only the first two characters in each.
Let result be a CSS color.
Interpret the first component as a hexadecimal number; let the red component of result be the resulting number.
Interpret the second component as a hexadecimal number; let the green component of result be the resulting number.
Interpret the third component as a hexadecimal number; let the blue component of result be the resulting number.
Return result.
A set of space-separated tokens is a string containing zero or more words (known as tokens) separated by one or more ASCII whitespace, where words consist of any string of one or more characters, none of which are ASCII whitespace.
A string containing a set of space-separated tokens may have leading or trailing ASCII whitespace.
An unordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated.
An ordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated but where the order of the tokens is meaningful.
Sets of space-separated tokens 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.
How tokens in a set of space-separated tokens are to be compared (e.g. case-sensitively or not) is defined on a per-set basis.
A set of comma-separated tokens 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 ASCII whitespace, nor containing any U+002C COMMA characters (,), and optionally surrounded by ASCII whitespace.
For instance, the string " a ,b,,d d " 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.
Sets of comma-separated tokens 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.
A valid hash-name reference to an element of type type is a
string consisting of a U+0023 NUMBER SIGN character (#) followed by a string which exactly matches
the value of the name attribute of an element with type type in
the same tree.
The rules for parsing a hash-name reference to an element of type type, given a context node scope, are as follows:
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.
Let s 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.
Return the first element of type type in scope's tree, in
tree order, that has an id or name attribute whose value is s, or null if there is no such
element.
Although id attributes are accounted for when
parsing, they are not used in determining whether a value is a valid hash-name
reference. That is, a hash-name reference that refers to an element based on id is a conformance error (unless that element also has a name attribute with the same value).
A string is a valid media query list if it matches the <media-query-list> production of Media Queries.
[MQ]
A string matches the environment of the user if it is the empty string, a string consisting of only ASCII whitespace, or is a media query list that matches the user's environment according to the definitions given in Media Queries. [MQ]
A unique internal value is a value that is serializable, comparable by value, and never exposed to script.
To create a new unique internal value, return a unique internal value that has never previously been returned by this algorithm.
A string is a valid non-empty URL if it is a valid URL string but it is not the empty string.
A string is a valid URL potentially surrounded by spaces if, after stripping leading and trailing ASCII whitespace from it, it is a valid URL string.
A string is a valid non-empty URL potentially surrounded by spaces if, after stripping leading and trailing ASCII whitespace from it, it is a valid non-empty URL.
This specification defines the URL about:legacy-compat as a reserved,
though unresolvable, about: URL, for use in DOCTYPEs in HTML documents when needed for
compatibility with XML tools. [ABOUT]
This specification defines the URL about:html-kind as a reserved,
though unresolvable, about: URL, that is used as an
identifier for kinds of media tracks. [ABOUT]
This specification defines the URL about:srcdoc as a reserved, though
unresolvable, about: URL, that is used as the URL of iframe srcdoc documents.
[ABOUT]
A URL matches about:blank if its scheme is "about", its path contains a single string "blank", its
username and password are the empty string, and its host is null.
Such a URL's query and fragment can be non-null. For example, the URL
record created by parsing "about:blank?foo#bar" matches about:blank.
A URL matches about:srcdoc if its scheme is "about", its path contains a single string "srcdoc",
its query is null, its username and password are the empty string, and its host is null.
The reason that matches about:srcdoc ensures that the
URL's query is null is because it is not
possible to create an iframe srcdoc document whose URL has a non-null query, unlike Documents whose URL matches about:blank. In other
words, the set of all URLs that match
about:srcdoc only vary in their fragment.
Parsing a URL is the process of taking a string and obtaining the URL record that it represents. While this process is defined in URL, the HTML standard defines several wrappers to abstract base URLs and encodings. [URL]
Most new APIs are to use parse a URL. Older APIs and HTML elements might have reason to use encoding-parse a URL. When a custom base URL is needed or no base URL is desired, the URL parser can of course be used directly as well.
To parse a URL, given a string url, relative to a
Document object or environment settings object environment,
run these steps. They return failure or a URL.
Let baseURL be environment's base
URL, if environment is a Document object; otherwise
environment's API base URL.
Return the result of applying the URL parser to url, with baseURL.
To encoding-parse a URL,
given a string url, relative to a Document object or environment
settings object environment, run these steps. They return failure or a
URL.
Let encoding be UTF-8.
If environment is a Document object, then set encoding
to environment's character
encoding.
Otherwise, if environment's relevant global object is a
Window object, set encoding to environment's relevant
global object's associated
Document's character
encoding.
Let baseURL be environment's base
URL, if environment is a Document object; otherwise
environment's API base URL.
Return the result of applying the URL parser to url, with baseURL and encoding.
To encoding-parse-and-serialize a
URL, given a string url, relative to a Document object or
environment settings object environment, run these steps. They return
failure or a string.
Let url be the result of encoding-parsing a URL given url, relative to environment.
If url is failure, then return failure.
Return the result of applying the URL serializer to url.
The document base URL of a Document document is the
URL record obtained by running these steps:
If document has no descendant base element that has
an href attribute, then return document's
fallback base URL.
Otherwise, return the frozen base URL of the first base element
in document that has an href attribute, in
tree order.
The fallback base URL of a Document object document is the
URL record obtained by running these steps:
If document is an iframe
srcdoc document:
Assert: document's about base URL is non-null.
Return document's about base URL.
If document's URL matches
about:blank and document's about base URL is non-null, then return
document's about base
URL.
Return document's URL.
To set the URL for a Document document to a URL
record url:
Set document's URL to url.
Respond to base URL changes given document.
To respond to base URL changes for a
Document document:
The user agent should update any user interface elements which are displaying affected
URLs, or data derived from such URLs, to the user. Examples of such user interface elements would
be a status bar that displays a hyperlink's url, or some user interface which displays the URL
specified by a q, blockquote, ins, or del
element's cite attribute.
Ensure that the CSS :link/:visited/etc. pseudo-classes
are updated appropriately.
For each descendant of document's shadow-including descendants:
If descendant is a script element whose result is a speculation rules parse result,
then:
Let oldResult be element's result.
Let newResult be the result of creating a speculation rules parse result given element's child text content and element's node document.
Update speculation rules given element's relevant global object, oldResult, and newResult.
Consider speculative loads given document.
This means that changing the base
URL doesn't affect, for example, the image displayed by img elements. Thus,
subsequent accesses of the src IDL attribute from script will
return a new absolute URL that might no longer correspond to the image being
shown.
A response's unsafe response is its internal response if it has one, and the response itself otherwise.
To create a potential-CORS request, given a url, destination, corsAttributeState, and an optional same-origin fallback flag, run these steps:
Let mode be "no-cors" if corsAttributeState
is No CORS, and "cors"
otherwise.
If same-origin fallback flag is set and mode is "no-cors", set mode to "same-origin".
Let credentialsMode be "include".
If corsAttributeState is Anonymous, set credentialsMode to "same-origin".
Return a new request whose URL is url, destination is destination, mode is mode, credentials mode is credentialsMode, and whose use-URL-credentials flag is set.
The Content-Type metadata of a resource must be obtained and interpreted in a manner consistent with the requirements of MIME Sniffing. [MIMESNIFF]
The computed MIME type of a resource must be found in a manner consistent with the requirements given in MIME Sniffing. [MIMESNIFF]
The rules for sniffing images specifically, the rules for distinguishing if a resource is text or binary, and the rules for sniffing audio and video specifically are also defined in MIME Sniffing. These rules return a MIME type as their result. [MIMESNIFF]
It is imperative that the rules in MIME Sniffing 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 MIME Sniffing. [MIMESNIFF]
meta elementsThe algorithm for extracting a character encoding from a meta element,
given a string s, is as follows. It returns either a character encoding or
nothing.
Let position be a pointer into s, initially pointing at the start of the string.
Loop: Find the first seven characters in s after position that are an ASCII case-insensitive match for the word "charset". If no such match is found, return nothing.
Skip any ASCII whitespace that immediately follow the word "charset" (there might not be any).
If the next character is not a U+003D EQUALS SIGN (=), then move position to point just before that next character, and jump back to the step labeled loop.
Skip any ASCII whitespace that immediately follow the equals sign (there might not be any).
Process the next character as follows:
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). While the algorithm is used in contexts that, historically, were related to HTTP, the syntax as supported by implementations diverged some time ago. [HTTP]
Support in all current engines.
A CORS settings attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
anonymous
| Anonymous | Requests for the element will have their
mode set to "cors" and their
credentials mode set to "same-origin".
|
use-credentials
| Use Credentials | Requests for the element will have their mode set to "cors" and their credentials mode set to "include".
|
The attribute's missing value default is the No CORS state, and its invalid value default and empty value default are both the Anonymous state.
The majority of fetches governed by CORS settings attributes will be done via the create a potential-CORS request algorithm.
For more modern features, where the request's mode is always "cors", certain CORS settings attributes have been repurposed to have a
slightly different meaning, wherein they only impact the request's credentials mode. To perform this translation, we
define the CORS settings attribute credentials mode for a given CORS
settings attribute to be determined by switching on the attribute's state:
same-origin"include"A referrer policy attribute is an enumerated attribute. Each referrer policy, including the empty string, is a keyword for this attribute, mapping to a state of the same name.
The attribute's missing value default and invalid value default are both the empty string state.
The impact of these states on the processing model of various fetches is defined in more detail throughout this specification, in Fetch, and in Referrer Policy. [FETCH] [REFERRERPOLICY]
Several signals can contribute to which processing model is used for a given fetch; a referrer policy attribute is only one of them. In general, the order in which these signals are processed are:
First, the presence of a noreferrer link
type;
Then, the value of a referrer policy attribute;
Then, the presence of any meta element with name attribute set to referrer.
Finally, the `Referrer-Policy` HTTP
header.
Support in all current engines.
A nonce content
attribute represents a cryptographic nonce ("number used once") which can be used by Content
Security Policy to determine whether or not a given fetch will be allowed to proceed. The
value is text. [CSP]
Elements that have a nonce 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 [[CryptographicNonce]], exposing it to script
via the HTMLOrSVGElement interface mixin, and setting the content attribute to the
empty string. Unless otherwise specified, the slot's value is the empty string.
element.nonceReturns the value set for element's cryptographic nonce. If the setter was not
used, this will be the value originally found in the nonce
content attribute.
element.nonce = valueUpdates element's cryptographic nonce value.
The nonce IDL attribute must, on getting, return the
value of this element's [[CryptographicNonce]]; and on setting, set this element's
[[CryptographicNonce]] to the given value.
Note how the setter for the nonce IDL attribute does not update the corresponding
content attribute. This, as well as the below setting of the nonce content attribute to the empty string when an element
becomes browsing-context connected, is meant to prevent exfiltration of the nonce
value through mechanisms that can easily read content attributes, such as selectors. Learn more in
issue #2369, where this behavior was
introduced.
The following attribute change
steps are used for the nonce content attribute:
If element does not include HTMLOrSVGElement, then
return.
If localName is not nonce or
namespace is not null, then return.
If value is null, then set element's [[CryptographicNonce]] to the empty string.
Otherwise, set element's [[CryptographicNonce]] to value.
Whenever an element including HTMLOrSVGElement
becomes browsing-context connected, the user agent must execute the following steps
on the element:
Let CSP list be element's shadow-including root's policy container's CSP list.
If CSP list contains a header-delivered Content Security Policy, and
element has a nonce content attribute
whose value is not the empty string, then:
Let nonce be element's [[CryptographicNonce]].
Set an attribute value for
element using "nonce" and the empty
string.
Set element's [[CryptographicNonce]] to nonce.
If element's [[CryptographicNonce]] were not restored it would be the empty string at this point.
The cloning steps for elements that
include HTMLOrSVGElement given node, copy, and
subtree are to set copy's [[CryptographicNonce]] to
node's [[CryptographicNonce]].
Support in all current engines.
A lazy loading attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
lazy
| Lazy | Used to defer fetching a resource until some conditions are met. |
eager
| Eager | Used to fetch a resource immediately; the default state. |
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.
The attribute's missing value default and invalid value default are both the Eager state.
The will lazy load element steps, given an element element, are as follows:
If scripting is disabled for element, then return false.
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.
If element's lazy loading attribute is in the Lazy state, then return true.
Return false.
Each img and iframe element has associated lazy load resumption
steps, initially null.
For img and iframe elements that will lazy load, these steps are run from the lazy load
intersection observer's callback or when their lazy loading attribute is set
to the Eager state. This causes the element to
continue loading.
Each Document has a lazy load intersection observer, initially set to
null but can be set to an IntersectionObserver instance.
To start intersection-observing a lazy loading element element, run these steps:
Let doc be element's node document.
If doc's lazy load intersection observer is null, set it to a new
IntersectionObserver instance, initialized as follows:
The intention is to use the original value of the
IntersectionObserver constructor. However, we're forced to use the
JavaScript-exposed constructor in this specification, until Intersection Observer
exposes low-level hooks for use in specifications. See bug w3c/IntersectionObserver#464
which tracks this. [INTERSECTIONOBSERVER]
The callback is these steps, with arguments entries and observer:
For each entry in entries using a method of iteration which does not trigger developer-modifiable array accessors or iteration hooks:
Let resumptionSteps be null.
If entry.isIntersecting is true, then
set resumptionSteps to entry.target's
lazy load resumption steps.
If resumptionSteps is null, then return.
Stop intersection-observing a lazy loading element for
entry.target.
Set entry.target's lazy load resumption
steps to null.
Invoke resumptionSteps.
The intention is to use the original value of the
isIntersecting and
target getters. See w3c/IntersectionObserver#464.
[INTERSECTIONOBSERVER]
The options is an IntersectionObserverInit dictionary with the
following dictionary members: «[ "scrollMargin" → lazy load scroll
margin ]»
This allows for fetching the image during scrolling, when it does not yet — but is about to — intersect the viewport.
The lazy load scroll margin suggestions imply dynamic changes to the
value, but the IntersectionObserver API does not support changing the scroll
margin. See issue w3c/IntersectionObserver#428.
Call doc's lazy load intersection observer's observe method with element as the
argument.
The intention is to use the original value of the observe method. See w3c/IntersectionObserver#464.
[INTERSECTIONOBSERVER]
To stop intersection-observing a lazy loading element element, run these steps:
Let doc be element's node document.
Assert: doc's lazy load intersection observer is not null.
Call doc's lazy load intersection observer's unobserve method with element as
the argument.
The intention is to use the original value of the unobserve method. See w3c/IntersectionObserver#464.
[INTERSECTIONOBSERVER]
The lazy load scroll margin is an
implementation-defined value, but with the following suggestions to consider:
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.
The typical scrolling speed: increase the value for devices with faster typical scrolling speeds.
The current scrolling speed or momentum: the UA can attempt to predict where the scrolling will likely stop, and adjust the value accordingly.
The network quality: increase the value for slow or high-latency connections.
User preferences can influence the value.
It is important for privacy that the lazy load scroll margin 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.
A blocking attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. The operations that can be blocked are represented by possible blocking tokens, which are strings listed by the following table:
| Possible blocking token | Description |
|---|---|
"render"
| The element is potentially render-blocking. |
In the future, there might be more possible blocking tokens.
A blocking attribute must have a value that is an unordered set of unique space-separated tokens, each of which are possible blocking tokens. The supported tokens of a blocking attribute are the possible blocking tokens. Any element can have at most one blocking attribute.
The blocking tokens set for an element el are the result of the following steps:
Let value be the value of el's blocking attribute, or the empty string if no such attribute exists.
Set value to value, converted to ASCII lowercase.
Let rawTokens be the result of splitting value on ASCII whitespace.
Return a set containing the elements of rawTokens that are possible blocking tokens.
An element is potentially render-blocking if its blocking tokens set
contains "render", or if it is
implicitly potentially render-blocking, which will be defined at the individual
elements. By default, an element is not implicitly potentially render-blocking.
A fetch priority attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
high
| High | Signals a high-priority fetch relative to other resources with the same destination. |
low
| Low | Signals a low-priority fetch relative to other resources with the same destination. |
auto
| Auto | Signals automatic determination of fetch priority relative to other resources with the same destination. |
The attribute's missing value default and invalid value default are both the Auto state.
The building blocks for reflecting are as follows:
A reflected target is an element or ElementInternals
object. It is typically clear from context and typically identical to the interface of the
reflected IDL attribute. It is always identical to that interface when it is an
ElementInternals object.
A reflected IDL attribute is an attribute interface member.
A reflected content attribute name is a string. When the reflected
target is an element, it represents the local name of a content attribute whose namespace
is null. When the reflected target is an ElementInternals object, it
represents a key of the reflected target's target
element's internal content attribute map.
A reflected IDL attribute can be defined to reflect a reflected content attribute name of a reflected target. 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.
Reflected targets have these associated algorithms:
For a reflected target that is an element element, these are defined as follows:
Return element.
Let attribute be the result of running get an attribute by namespace and local name given null, the reflected content attribute name, and element.
If attribute is null, then return null.
Return attribute's value.
Set an attribute value given element, the reflected content attribute name, and value.
Remove an attribute by namespace and local name given null, the reflected content attribute name, and element.
For a reflected target that is an ElementInternals object
elementInternals, they are defined as follows:
Return elementInternals's target element.
If elementInternals's target element's internal content attribute map[the reflected content attribute name] does not exist, then return null.
Return elementInternals's target element's internal content attribute map[the reflected content attribute name].
Set elementInternals's target element's internal content attribute map[the reflected content attribute name] to value.
Remove elementInternals's target element's internal content attribute map[the reflected content attribute name].
This results in somewhat redundant data structures for
ElementInternals objects as their target
element's internal content attribute map 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 reflected targets and benefit from common API semantics.
IDL attributes of type DOMString or DOMString? that reflect enumerated content attributes can be limited to only known values.
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.
If a reflected IDL attribute has the type DOMString:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.
If attributeDefinition indicates it is an enumerated attribute and the reflected IDL attribute is defined to be limited to only known values:
If contentAttributeValue does not correspond to any state of attributeDefinition (e.g., it is null and there is no missing value default), or if it is in a state of attributeDefinition with no associated keyword value, then return the empty string.
Return the canonical keyword for the state of attributeDefinition that contentAttributeValue corresponds to.
If contentAttributeValue is null, then return the empty string.
Return contentAttributeValue.
The setter steps are to run this's set the content attribute with the given value.
If a reflected IDL attribute has the type DOMString?:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.
If attributeDefinition indicates it is an enumerated attribute:
Assert: the reflected IDL attribute is limited to only known values.
Assert: contentAttributeValue corresponds to a state of attributeDefinition.
If contentAttributeValue corresponds to a state of attributeDefinition with no associated keyword value, then return null.
Return the canonical keyword for the state of attributeDefinition that contentAttributeValue corresponds to.
Return contentAttributeValue.
The setter steps are:
If the given value is null, then run this's delete the content attribute.
Otherwise, run this's set the content attribute with the given value.
If a reflected IDL attribute has the type USVString, optionally treated as a URL:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
If the reflected IDL attribute is treated as a URL:
If contentAttributeValue is null, then return the empty string.
Let urlString be the result of encoding-parsing-and-serializing a URL given contentAttributeValue, relative to element's node document.
If urlString is not failure, then return urlString.
Return contentAttributeValue, converted to a scalar value string.
The setter steps are to run this's set the content attribute with the given value.
If a reflected IDL attribute has the type boolean:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is null, then return false.
Return true.
The setter steps are:
If the given value is false, then run this's delete the content attribute.
If the given value is true, then run this's set the content attribute with the empty string.
This corresponds to the rules for boolean content attributes.
If a reflected IDL attribute has the type long,
optionally limited to only non-negative numbers and optionally with a default
value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is not null:
Let parsedValue be the result of integer parsing contentAttributeValue if the reflected IDL attribute is not limited to only non-negative numbers; otherwise the result of non-negative integer parsing contentAttributeValue.
If parsedValue is not an error and is within the long range, then return parsedValue.
If the reflected IDL attribute has a default value, then return defaultValue.
If the reflected IDL attribute is limited to only non-negative numbers, then return −1.
Return 0.
The setter steps are:
If the reflected IDL attribute is limited to only non-negative
numbers and the given value is negative, then throw an
"IndexSizeError" DOMException.
Run this's set the content attribute with the given value converted to the shortest possible string representing the number as a valid integer.
If a reflected IDL attribute has the type unsigned long, optionally limited to only positive
numbers, limited to only positive
numbers with fallback, or clamped to the range [clampedMin,
clampedMax], and optionally with a default value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
Let minimum be 0.
If the reflected IDL attribute is limited to only positive numbers or limited to only positive numbers with fallback, then set minimum to 1.
If the reflected IDL attribute is clamped to the range, then set minimum to clampedMin.
Let maximum be 2147483647 if the reflected IDL attribute is not clamped to the range; otherwise clampedMax.
If contentAttributeValue is not null:
Let parsedValue be the result of non-negative integer parsing contentAttributeValue.
If parsedValue is not an error and is in the range minimum to maximum, inclusive, then return parsedValue.
If parsedValue is not an error and the reflected IDL attribute is clamped to the range:
If parsedValue is less than minimum, then return minimum.
Return maximum.
If the reflected IDL attribute has a default value, then return defaultValue.
Return minimum.
The setter steps are:
If the reflected IDL attribute is limited to only positive
numbers and the given value is 0, then throw an
"IndexSizeError" DOMException.
Let minimum be 0.
If the reflected IDL attribute is limited to only positive numbers or limited to only positive numbers with fallback, then set minimum to 1.
Let newValue be minimum.
If the reflected IDL attribute has a default value, then set newValue to defaultValue.
If the given value is in the range minimum to 2147483647, inclusive, then set newValue to it.
Run this's set the content attribute with newValue converted to the shortest possible string representing the number as a valid non-negative integer.
Clamped to the range has no effect on the setter steps.
If a reflected IDL attribute has the type double,
optionally limited to only positive numbers
and optionally with a default value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is not null:
Let parsedValue be the result of floating-point number parsing contentAttributeValue.
If parsedValue is not an error and is greater than 0, then return parsedValue.
If parsedValue is not an error and the reflected IDL attribute is not limited to only positive numbers, then return parsedValue.
If the reflected IDL attribute has a default value, then return defaultValue.
Return 0.
The setter steps are:
If the reflected IDL attribute is limited to only positive numbers and the given value is not greater than 0, then return.
Run this's set the content attribute with the given value, converted to the best representation of the number as a floating-point number.
The values Infinity and Not-a-Number (NaN) values throw an exception on setting, as defined in Web IDL. [WEBIDL]
If a reflected IDL attribute has the type DOMTokenList, then its
getter steps are to return a DOMTokenList object whose associated element is
this and associated attribute's local name is the reflected content
attribute name. Specification authors cannot reflect IDL attributes of this type on
ElementInternals.
If a reflected IDL attribute has the type T?,
where T is either Element or an interface that inherits from
Element, then with attr being the reflected content attribute
name:
Its reflected target has an explicitly set attr-element, which is a weak reference to an element or null. It is initially null.
Its reflected target reflectedTarget has a get the attr-associated element algorithm, that runs these steps:
Let element be the result of running reflectedTarget's get the element.
Let contentAttributeValue be the result of running reflectedTarget's get the content attribute.
If reflectedTarget's explicitly set attr-element is not null:
If reflectedTarget's explicitly set attr-element is a descendant of any of element's shadow-including ancestors, then return reflectedTarget's explicitly set attr-element.
Return null.
Otherwise, if contentAttributeValue is not null, return the first element candidate, in tree order, that meets the following criteria:
candidate's ID is contentAttributeValue; and
candidate implements T.
If no such element exists, then return null.
Return null.
The getter steps are to return the result of running this's get the attr-associated element.
The setter steps are:
If the given value is null, then:
Set this's explicitly set attr-element to null.
Run this's delete the content attribute.
Return.
Run this's set the content attribute with the empty string.
Set this's explicitly set attr-element to a weak reference to the given value.
For element reflected targets only: the following attribute change steps, given element, localName, oldValue, value, and namespace, are used to synchronize between the content attribute and the IDL attribute:
If localName is not attr or namespace is not null, then return.
Set element's explicitly set attr-element to null.
Reflected IDL attributes of this
type are strongly encouraged to have their identifier end in "Element" for
consistency.
If a reflected IDL attribute has the type FrozenArray<T>?, where T is either
Element or an interface that inherits from Element, then with
attr being the reflected content attribute name:
Its reflected target has an explicitly set attr-elements, which is either a list of weak references to elements or null. It is initially null.
Its reflected target has a cached attr-associated elements, which is a list of elements. It is initially « ».
Its reflected target has a cached attr-associated
elements object, which is a FrozenArray<T>?. It is
initially null.
Its reflected target reflectedTarget has a get the attr-associated elements algorithm, which runs these steps:
Let elements be an empty list.
Let element be the result of running reflectedTarget's get the element.
If reflectedTarget's explicitly set attr-elements is not null:
For each attrElement in reflectedTarget's explicitly set attr-elements:
If attrElement is not a descendant of any of element's shadow-including ancestors, then continue.
Append attrElement to elements.
Otherwise:
Let contentAttributeValue be the result of running reflectedTarget's get the content attribute.
If contentAttributeValue is null, then return null.
Let tokens be contentAttributeValue, split on ASCII whitespace.
For each id of tokens:
Let candidate be the first element, in tree order, that meets the following criteria:
candidate's ID is id; and
candidate implements T.
If no such element exists, then continue.
Append candidate to elements.
Return elements.
The getter steps are:
Let elements be the result of running this's get the attr-associated elements.
If the contents of elements is equal to the contents of this's cached attr-associated elements, then return this's cached attr-associated elements object.
Let elementsAsFrozenArray be elements, converted to a FrozenArray<T>?.
Set this's cached attr-associated elements to elements.
Set this's cached attr-associated elements object to elementsAsFrozenArray.
Return elementsAsFrozenArray.
This extra caching layer is necessary to preserve the invariant that element.reflectedElements === element.reflectedElements.
The setter steps are:
If the given value is null:
Set this's explicitly set attr-elements to null.
Run this's delete the content attribute.
Return.
Run this's set the content attribute with the empty string.
Let elements be an empty list.
For each element in the given value:
Append a weak reference to element to elements.
Set this's explicitly set attr-elements to elements.
For element reflected targets only: the following attribute change steps, given element, localName, oldValue, value, and namespace, are used to synchronize between the content attribute and the IDL attribute:
If localName is not attr or namespace is not null, then return.
Set element's explicitly set attr-elements to null.
Reflected IDL attributes of this
type are strongly encouraged to have their identifier end in "Elements" for
consistency.
Reflection can be used from IDL through extended attributes. [Reflect], [ReflectSetter], [ReflectURL],
[ReflectNonNegative], [ReflectPositive], and
[ReflectPositiveWithFallback] all
trigger reflection. These must either take no arguments, or take a
string; they must not appear on anything other than an interface member attribute; and only one of
these can be used at a time.
For one of these primary reflection extended attributes, its reflected content attribute name is the string value it takes, if one is provided; otherwise it is the IDL attribute name converted to ASCII lowercase.
IDL attributes with the [Reflect] extended
attribute must reflect [Reflect]'s
reflected content attribute name.
IDL attributes with the [ReflectSetter]
extended attribute on setting must reflect [ReflectSetter]'s reflected content attribute
name.
The [ReflectURL] extended attribute must
only appear on attributes with a type of USVString.
IDL attributes with the [ReflectURL] extended
attribute must reflect, as a URL, [ReflectURL]'s reflected content attribute name.
The [ReflectNonNegative] extended
attribute must only appear on attributes with a type of long.
IDL attributes with the [ReflectNonNegative]
extended attribute must reflect, limited to only non-negative
numbers, [ReflectNonNegative]'s
reflected content attribute name.
The [ReflectPositive] and [ReflectPositiveWithFallback] extended attributes must only appear on attributes with a type
of double or unsigned
long.
IDL attributes with the [ReflectPositive]
extended attribute must reflect, limited to only positive
numbers, [ReflectPositive]'s reflected
content attribute name.
IDL attributes with the [ReflectPositiveWithFallback] extended
attribute must reflect, limited to only positive numbers with
fallback, [ReflectPositiveWithFallback]'s reflected
content attribute name.
To supplement the above extended attributes we also
introduce [ReflectRange], and [ReflectDefault]. These
augment how reflection works and also must only appear on interface
member attributes.
The [ReflectRange] extended attribute
must take an integer list limited to two values. It must only be used on attributes with a type of
unsigned long. Additionally, it must also only appear
alongside [Reflect].
IDL attributes with the [ReflectRange] extended
attribute are clamped to the range [clampedMin,
clampedMax] where clampedMin is the first, and clampedMax is the
second argument to the list provided to [ReflectRange].
The [ReflectDefault] extended attribute
must only be used on attributes with a type of double, long, or unsigned long. When used
on an attribute of type double, it must take a decimal; otherwise
it must take an integer. Additionally, it must also only appear alongside [Reflect], [ReflectNonNegative], [ReflectPositive], or [ReflectPositiveWithFallback].
IDL attributes with the [ReflectDefault]
extended attribute have a default value provided by the argument
provided to [ReflectDefault].
Reflection is primarily about improving web developer ergonomics by giving them typed access to content attributes through reflected IDL attributes. The ultimate source of truth, which the web platform builds upon, is the content attributes themselves. That is, specification authors must not use the reflected IDL attribute 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 enumerated attribute.)
Two important exceptions to this are reflected IDL attributes whose type is one of the following:
T?, where T is either Element or
an interface that inherits from Element
FrozenArray<T>?, where T is either
Element or an interface that inherits from Element
For those, specification authors must use the reflected target's get the attr-associated element and get the attr-associated elements, respectively. The content attribute presence and value must not be used as they cannot be fully synchronized with the reflected IDL attribute.
A reflected target's explicitly set attr-element, explicitly set attr-elements, cached attr-associated elements, and cached attr-associated elements object are to be treated as internal implementation details and not to be built upon.
The HTMLFormControlsCollection and HTMLOptionsCollection interfaces
are collections derived from the
HTMLCollection interface. The HTMLAllCollection interface is a collection, but is not so derived.
HTMLAllCollection interfaceThe HTMLAllCollection interface is used for the legacy document.all attribute. It operates similarly to
HTMLCollection; 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.
All HTMLAllCollection objects are rooted at a Document
and have a filter that matches all elements, so the elements represented by the
collection of an HTMLAllCollection object consist of all the descendant
elements of the root Document.
Objects that implement the HTMLAllCollection interface are legacy platform objects with an additional [[Call]] internal
method described in the section below. They also have an
[[IsHTMLDDA]] internal slot.
Objects that implement the HTMLAllCollection interface have several unusual
behaviors, due of the fact that they have an [[IsHTMLDDA]] internal slot:
The ToBoolean abstract operation in JavaScript returns
false when given objects implementing the HTMLAllCollection interface.
The IsLooselyEqual abstract operation,
when given objects implementing the HTMLAllCollection interface, returns true when
compared to the undefined and null values.
(Comparisons using the IsStrictlyEqual abstract
operation, and IsLooselyEqual comparisons to other values such as strings or objects, are
unaffected.)
The typeof operator in JavaScript returns the string
"undefined" when applied to objects implementing the
HTMLAllCollection interface.
These special behaviors are motivated by a desire for compatibility with two classes of legacy
content: one that uses the presence of document.all as a
way to detect legacy user agents, and one that only supports those legacy user agents and uses
the document.all object without testing for its presence
first. [JAVASCRIPT]
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface HTMLAllCollection {
readonly attribute unsigned long length ;
getter Element (unsigned long index );
getter (HTMLCollection or Element )? namedItem (DOMString name );
(HTMLCollection or Element )? item (optional DOMString nameOrIndex );
// Note: HTMLAllCollection objects have a custom [[Call]] internal method and an [[IsHTMLDDA]] internal slot.
};The object's supported property indices are as defined for
HTMLCollection objects.
The supported property names consist of the non-empty values of all the id attributes of all the elements represented by the
collection, and the non-empty values of all the name attributes of
all the "all"-named elements represented by the collection, in
tree order, ignoring later duplicates, with the id of
an element preceding its name if it contributes both, they differ from
each other, and neither is the duplicate of an earlier entry.
The length getter steps are to return the number
of nodes represented by the collection.
The indexed property getter must return the result of getting the "all"-indexed element from this given the passed index.
The namedItem(name) method steps are
to return the result of getting the "all"-named
element(s) from this given name.
The item(nameOrIndex) method steps
are:
If nameOrIndex was not provided, return null.
Return the result of getting the "all"-indexed or named element(s) from this, given nameOrIndex.
The following elements are "all"-named elements:
a,
button,
embed,
form,
frame,
frameset,
iframe,
img,
input,
map,
meta,
object,
select, and
textarea
To get the "all"-indexed element from an
HTMLAllCollection collection given an index index, return the
indexth element in collection, or null if there is no such
indexth element.
To get the "all"-named element(s) from an
HTMLAllCollection collection given a name name, perform the
following steps:
If name is the empty string, return null.
Let subCollection be an HTMLCollection object rooted at the same
Document as collection, whose filter matches only elements that are
either:
"all"-named elements with a name attribute equal to
name, or
elements with an ID equal to name.
If there is exactly one element in subCollection, then return that element.
Otherwise, if subCollection is empty, return null.
Otherwise, return subCollection.
To get the "all"-indexed or named
element(s) from an HTMLAllCollection collection given
nameOrIndex:
If nameOrIndex, converted to a JavaScript String value, is an array index property name, return the result of getting the "all"-indexed element from collection given the number represented by nameOrIndex.
Return the result of getting the "all"-named element(s) from collection given nameOrIndex.
If argumentsList's size is zero, or if argumentsList[0] is undefined, return null.
Let nameOrIndex be the result of converting argumentsList[0] to a DOMString.
Let result be the result of getting the "all"-indexed or named element(s)
from this HTMLAllCollection given nameOrIndex.
Return the result of converting result to an ECMAScript value.
The thisArgument is ignored, and thus code such as Function.prototype.call.call(document.all, null, "x") will still search for
elements. (document.all.call does not exist, since document.all does not inherit from Function.prototype.)
HTMLFormControlsCollection interfaceThe HTMLFormControlsCollection interface is used for
collections of listed
elements in form elements.
Support in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
getter (RadioNodeList or Element )? namedItem (DOMString name ); // shadows inherited namedItem()
};
[Exposed =Window ]
interface RadioNodeList : NodeList {
attribute DOMString value ;
};collection.lengthReturns the number of elements in collection.
element = collection.item(index)element = collection[index]Returns the item at index index in collection. The items are sorted in tree order.
element = collection.namedItem(name)HTMLFormControlsCollection/namedItem
Support in all current engines.
radioNodeList = collection.namedItem(name)element = collection[name]radioNodeList = collection[name]Returns the item with ID or name name from collection.
If there are multiple matching items, then a RadioNodeList object containing all
those elements is returned.
radioNodeList.valueReturns the value of the first checked radio button represented by radioNodeList.
radioNodeList.value = valueChecks the first radio button represented by radioNodeList that has value value.
The object's supported property indices are as defined for
HTMLCollection objects.
The supported property names consist of the non-empty values of all the id and name attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is the
duplicate of an earlier entry.
The namedItem(name) method
must act according to the following algorithm:
id attribute or a name
attribute equal to name, then return that node and stop the algorithm.id attribute or a name attribute equal
to name, then return null and stop the algorithm.RadioNodeList object representing a live
view of the HTMLFormControlsCollection object, further filtered so that the only
nodes in the RadioNodeList object are those that have either an id attribute or a name attribute equal
to name. The nodes in the RadioNodeList object must be sorted in
tree order.RadioNodeList object.Members of the RadioNodeList interface inherited from the NodeList
interface must behave as they would on a NodeList object.
Support in all current engines.
The value IDL attribute on the
RadioNodeList object, on getting, must return the value returned by running the
following steps:
Let element be the first element in tree order
represented by the RadioNodeList object that is an input element whose
type attribute is in the Radio Button state and whose checkedness is true. Otherwise, let it be null.
If element is null, return the empty string.
If element is an element with no value attribute, return the string "on".
Otherwise, return the value of element's value attribute.
On setting, the value IDL attribute must run the
following steps:
If the new value is the string "on": let element be the first element in tree order
represented by the RadioNodeList object that is an input element whose
type attribute is in the Radio Button state and whose value content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let element be null.
Otherwise: let element be the first element in tree order
represented by the RadioNodeList object that is an input element whose
type attribute is in the Radio Button state and whose value content attribute is present and equal to the new value, if
any. If no such element exists, then instead let element be null.
If element is not null, then set its checkedness to true.
HTMLOptionsCollection interfaceSupport in all current engines.
The HTMLOptionsCollection interface is used for collections of option elements. It is always
rooted on a select element and has attributes and methods that manipulate that
element's descendants.
[Exposed =Window ]
interface HTMLOptionsCollection : HTMLCollection {
// inherits item(), namedItem()
[CEReactions ] attribute unsigned long length ; // shadows inherited length
[CEReactions ] setter undefined (unsigned long index , HTMLOptionElement ? option );
[CEReactions ] undefined add ((HTMLOptionElement or HTMLOptGroupElement ) element , optional (HTMLElement or long )? before = null );
[CEReactions ] undefined remove (long index );
attribute long selectedIndex ;
};collection.lengthReturns the number of elements in collection.
collection.length = valueWhen set to a smaller number than the existing length, truncates the number of
option elements in the container corresponding to collection.
When set to a greater number than the existing length, if that number is less than or equal
to 100000, adds new blank option elements to the container corresponding to
collection.
element = collection.item(index)element = collection[index]Returns the item at index index in collection. The items are sorted in tree order.
collection[index] = elementWhen index is a greater number than the number of items in collection,
adds new blank option elements in the corresponding container.
When set to null, removes the item at index index from collection.
When set to an option element, adds or replaces it at index index in
collection.
element = collection.namedItem(name)element = collection[name]Returns the item with ID or name name from collection.
If there are multiple matching items, then the first is returned.
collection.add(element[, before])Inserts element before the node given by before.
The before argument can be a number, in which case element is inserted before the item with that number, or an element from collection, in which case element is inserted before that element.
If before is omitted, null, or a number out of range, then element will be added at the end of the list.
Throws a "HierarchyRequestError" DOMException if
element is an ancestor of the element into which it is to be inserted.
collection.remove(index)Removes the item with index index from collection.
collection.selectedIndexReturns the index of the first selected item, if any, or −1 if there is no selected item.
collection.selectedIndex = indexChanges the selection to the option element at index index in
collection.
The object's supported property indices are as defined for
HTMLCollection objects.
The length getter steps are to return the
number of nodes represented by the collection.
The length setter steps are:
Let current be the number of nodes represented by the collection.
If the given value is greater than current, then:
If the given value is less than current, then:
Let n be current − value.
Remove the last n nodes in the collection from their parent nodes.
Setting length never removes
or adds any optgroup elements, and never adds new children to existing
optgroup elements (though it can remove children from them).
The supported property names consist of the non-empty values of all the id and name attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is
the duplicate of an earlier entry.
When the user agent is to set the value of a new indexed property or set the value of an existing indexed property for a given property index index to a new value value, it must run the following algorithm:
If value is null, invoke the steps for the remove method with index as
the argument, and return.
Let length be the number of nodes represented by the collection.
Let delta be index minus length.
If delta is greater than zero, then append a DocumentFragment consisting of
delta new option elements with no attributes and
no child nodes to the select element on which the HTMLOptionsCollection
is rooted.
If delta is greater than or equal to zero, append value to the select
element. Otherwise, replace the indexth element in the collection by value.
The add(element, before)
method must act according to the following algorithm:
If element is an ancestor of the select element on which
the HTMLOptionsCollection is rooted, then throw a
"HierarchyRequestError" DOMException.
If before is an element, but that element isn't a descendant of the
select element on which the HTMLOptionsCollection is rooted, then throw
a "NotFoundError" DOMException.
If element and before are the same element, then return.
If before is a node, then let reference be that node. Otherwise, if before is an integer, and there is a beforeth node in the collection, let reference be that node. Otherwise, let reference be null.
If reference is not null, let parent be the parent
node of reference. Otherwise, let parent be the
select element on which the HTMLOptionsCollection is rooted.
Pre-insert element into parent node before reference.
The remove(index) method must act
according to the following algorithm:
If the number of nodes represented by the collection is zero, return.
If index is not a number greater than or equal to 0 and less than the number of nodes represented by the collection, return.
Let element be the indexth element in the collection.
Remove element from its parent node.
The selectedIndex IDL attribute must act
like the identically named attribute on the select element on which the
HTMLOptionsCollection is rooted
DOMStringList interfaceSupport in all current engines.
The DOMStringList interface is a non-fashionable retro way of representing a list
of strings.
[Exposed =(Window ,Worker )]
interface DOMStringList {
readonly attribute unsigned long length ;
getter DOMString ? item (unsigned long index );
boolean contains (DOMString string );
};New APIs must use sequence<DOMString> or
equivalent rather than DOMStringList.
strings.lengthReturns the number of strings in strings.
strings[index]strings.item(index)Returns the string with index index from strings.
strings.contains(string)Returns true if strings contains string, and false otherwise.
Each DOMStringList object has an associated list.
The DOMStringList interface supports indexed properties. The
supported property indices are the indices of this's
associated list.
Support in all current engines.
Support in all current engines.
The item(index) method steps are to
return the indexth item in this's associated list, or null if
index plus one is greater than this's associated list's size.
Support in all current engines.
The contains(string) method steps
are to return true if this's associated list contains string, and false otherwise.
To support passing JavaScript objects,
including platform objects, across realm
boundaries, this specification defines the following 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 structuredClone()
method.)
This section uses the terminology and typographic conventions from the JavaScript specification. [JAVASCRIPT]
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
Serializable objects support being serialized, and later deserialized, in a way that is independent of any given realm. This allows them to be stored on disk and later restored, or cloned across agent and even agent cluster boundaries.
Not all objects are serializable objects, and not all aspects of objects that are serializable objects are necessarily preserved when they are serialized.
Platform objects can be serializable objects
if their primary interface is decorated with the [Serializable] IDL extended
attribute. Such interfaces must also define the following algorithms:
A set of steps that serializes the data in value into fields of serialized. The resulting data serialized into serialized must be independent of any realm.
These steps may throw an exception if serialization is not possible.
These steps may perform a sub-serialization to serialize nested data structures. They should not call StructuredSerialize directly, as doing so will omit the important memory argument.
The introduction of these steps should omit mention of the forStorage argument if it is not relevant to the algorithm.
A set of steps that deserializes the data in serialized, using it to set up value as appropriate. value will be a newly-created instance of the platform object type in question, with none of its internal data set up; setting that up is the job of these steps.
These steps may throw an exception if deserialization is not possible.
These steps may perform a sub-deserialization to deserialize nested data structures. They should not call StructuredDeserialize directly, as doing so will omit the important targetRealm and memory arguments.
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.
The [Serializable] extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.
For a given platform object, only the object's primary interface is
considered during the (de)serialization process. Thus, if inheritance is involved in defining the
interface, each [Serializable]-annotated interface in the
inheritance chain needs to define standalone serialization steps and
deserialization steps, including taking into account any important data that might
come from inherited interfaces.
Let's say we were defining a platform object Person, which had
associated with it two pieces of associated data:
a name value, which is a string; and
a best friend value, which is either another Person instance
or null.
We could then define Person instances to be serializable
objects by annotating the Person interface with the [Serializable] extended attribute, and defining the
following accompanying algorithms:
Their serialization steps, given value and serialized:
Set serialized.[[Name]] to value's associated name value.
Let serializedBestFriend be the sub-serialization of value's associated best friend value.
Set serialized.[[BestFriend]] to serializedBestFriend.
Their deserialization steps, given serialized, value, and targetRealm:
Set value's associated name value to serialized.[[Name]].
Let deserializedBestFriend be the sub-deserialization of serialized.[[BestFriend]].
Set value's associated best friend value to deserializedBestFriend.
Objects defined in the JavaScript specification are handled by the StructuredSerialize abstract operation directly.
Originally, this specification defined the concept of "cloneable objects", which could be cloned from one realm to another. However, to better specify the behavior of certain more complex situations, the model was updated to make the serialization and deserialization explicit.
Transferable objects support being transferred across agents. 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 transferable objects and not all aspects of objects that are transferable objects are necessarily preserved when transferred.
Transferring is an irreversible and non-idempotent operation. Once an object has been transferred, it cannot be transferred, or indeed used, again.
Platform objects can be transferable objects
if their primary interface is decorated with the [Transferable] IDL extended
attribute. Such interfaces must also define the following algorithms:
A set of steps that transfers the data in value into fields of dataHolder. The resulting data held in dataHolder must be independent of any realm.
These steps may throw an exception if transferral is not possible.
A set of steps that receives the data in dataHolder, using it to set up value as appropriate. value will be a newly-created instance of the platform object type in question, with none of its internal data set up; setting that up is the job of these steps.
These steps may throw an exception if it is not possible to receive the transfer.
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.
The [Transferable] extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.
For a given platform object, only the object's primary interface is
considered during the transferring process. Thus, if inheritance is involved in defining the
interface, each [Transferable]-annotated interface in the
inheritance chain needs to define standalone transfer steps and
transfer-receiving steps, including taking into account any important data that might
come from inherited interfaces.
Platform objects that are transferable objects have a [[Detached]] internal slot. This is used to ensure that once a platform object has been transferred, it cannot be transferred again.
Objects defined in the JavaScript specification are handled by the StructuredSerializeWithTransfer abstract operation directly.
The StructuredSerializeInternal abstract operation takes as input a JavaScript value value and serializes it to a realm-independent form, represented here as a Record. This serialized form has all the information necessary to later deserialize into a new JavaScript value in a different realm.
This process can throw an exception, for example when trying to serialize un-serializable objects.
If memory was not supplied, let memory be an empty map.
The purpose of the memory map is to avoid serializing objects twice. This ends up preserving cycles and the identity of duplicate objects in graphs.
If memory[value] exists, then return memory[value].
Let deep be false.
If value is undefined, null, a Boolean, a Number, a BigInt, or a String, then return { [[Type]]: "primitive", [[Value]]: value }.
If value is a Symbol, then throw a
"DataCloneError" DOMException.
Let serialized be an uninitialized value.
If value has a [[BooleanData]] internal slot, then set serialized to { [[Type]]: "Boolean", [[BooleanData]]: value.[[BooleanData]] }.
Otherwise, if value has a [[NumberData]] internal slot, then set serialized to { [[Type]]: "Number", [[NumberData]]: value.[[NumberData]] }.
Otherwise, if value has a [[BigIntData]] internal slot, then set serialized to { [[Type]]: "BigInt", [[BigIntData]]: value.[[BigIntData]] }.
Otherwise, if value has a [[StringData]] internal slot, then set serialized to { [[Type]]: "String", [[StringData]]: value.[[StringData]] }.
Otherwise, if value has a [[DateValue]] internal slot, then set serialized to { [[Type]]: "Date", [[DateValue]]: value.[[DateValue]] }.
Otherwise, if value has a [[RegExpMatcher]] internal slot, then set serialized to { [[Type]]: "RegExp", [[RegExpMatcher]]: value.[[RegExpMatcher]], [[OriginalSource]]: value.[[OriginalSource]], [[OriginalFlags]]: value.[[OriginalFlags]] }.
Otherwise, if value has an [[ArrayBufferData]] internal slot, then:
If IsSharedArrayBuffer(value) is true, then:
If the current settings object's cross-origin isolated
capability is false, then throw a "DataCloneError"
DOMException.
This check is only needed when serializing (and not when deserializing) as
the cross-origin
isolated capability cannot change over time and a SharedArrayBuffer
cannot leave an agent cluster.
If forStorage is true, then throw a
"DataCloneError" DOMException.
If value has an [[ArrayBufferMaxByteLength]] internal slot, then set serialized to { [[Type]]: "GrowableSharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLengthData]]: value.[[ArrayBufferByteLengthData]], [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]], [[AgentCluster]]: the surrounding agent's agent cluster }.
Otherwise, set serialized to { [[Type]]: "SharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLength]]: value.[[ArrayBufferByteLength]], [[AgentCluster]]: the surrounding agent's agent cluster }.
Otherwise:
If IsDetachedBuffer(value) is true, then throw a
"DataCloneError" DOMException.
Let size be value.[[ArrayBufferByteLength]].
Let dataCopy be ? CreateByteDataBlock(size).
This can throw a RangeError exception
upon allocation failure.
Perform CopyDataBlockBytes(dataCopy, 0, value.[[ArrayBufferData]], 0, size).
If value has an [[ArrayBufferMaxByteLength]] internal slot, then set serialized to { [[Type]]: "ResizableArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size, [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]] }.
Otherwise, set serialized to { [[Type]]: "ArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size }.
Otherwise, if value has a [[ViewedArrayBuffer]] internal slot, then:
If IsArrayBufferViewOutOfBounds(value) is true, then throw a
"DataCloneError" DOMException.
Let buffer be the value of value's [[ViewedArrayBuffer]] internal slot.
Let bufferSerialized be ? StructuredSerializeInternal(buffer, forStorage, memory).
Assert: bufferSerialized.[[Type]] is "ArrayBuffer", "ResizableArrayBuffer", "SharedArrayBuffer", or "GrowableSharedArrayBuffer".
If value has a [[DataView]] internal slot, then set serialized to { [[Type]]: "ArrayBufferView", [[Constructor]]: "DataView", [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]] }.
Otherwise:
Assert: value has a [[TypedArrayName]] internal slot.
Set serialized to { [[Type]]: "ArrayBufferView", [[Constructor]]: value.[[TypedArrayName]], [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]], [[ArrayLength]]: value.[[ArrayLength]] }.
Otherwise, if value has a [[MapData]] internal slot, then:
Set serialized to { [[Type]]: "Map", [[MapData]]: a new empty List }.
Set deep to true.
Otherwise, if value has a [[SetData]] internal slot, then:
Set serialized to { [[Type]]: "Set", [[SetData]]: a new empty List }.
Set deep to true.
Otherwise, if value has an [[ErrorData]] internal slot and value is not a platform object, then:
Let name be ? Get(value, "name").
If name is not one of "Error", "EvalError", "RangeError", "ReferenceError", "SyntaxError", "TypeError", or "URIError", then set name to "Error".
Let valueMessageDesc be ? value.[[GetOwnProperty]]("message").
Let message be undefined if IsDataDescriptor(valueMessageDesc) is false, and ? ToString(valueMessageDesc.[[Value]]) otherwise.
Set serialized to { [[Type]]: "Error", [[Name]]: name, [[Message]]: message }.
User agents should attach a serialized representation of any interesting accompanying
data which are not yet specified, notably the stack property, to
serialized.
See the Error Stacks proposal for in-progress work on specifying this data. [JSERRORSTACKS]
Otherwise, if value is an Array exotic object, then:
Let valueLenDescriptor be ?
OrdinaryGetOwnProperty(value, "length").
Let valueLen be valueLenDescriptor.[[Value]].
Set serialized to { [[Type]]: "Array", [[Length]]: valueLen, [[Properties]]: a new empty List }.
Set deep to true.
Otherwise, if value is a platform object that is a serializable object:
If value has a [[Detached]] internal slot whose value is true,
then throw a "DataCloneError" DOMException.
Let typeString be the identifier of the primary interface of value.
Set serialized to { [[Type]]: typeString }.
Set deep to true.
Otherwise, if value is a platform object, then throw a
"DataCloneError" DOMException.
Otherwise, if IsCallable(value) is true, then throw a
"DataCloneError" DOMException.
Otherwise, if value has any internal slot other than [[Prototype]],
[[Extensible]], or [[PrivateElements]], then throw a "DataCloneError"
DOMException.
For instance, a [[PromiseState]] or [[WeakMapData]] internal slot.
Otherwise, if value is an exotic object and value is not the
%Object.prototype% intrinsic object associated with any realm, then
throw a "DataCloneError" DOMException.
For instance, a proxy object.
Otherwise:
Set serialized to { [[Type]]: "Object", [[Properties]]: a new empty List }.
Set deep to true.
%Object.prototype% 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 immutable prototype exotic object).
Set memory[value] to serialized.
If deep is true, then:
If value has a [[MapData]] internal slot, then:
Let copiedList be a new empty List.
For each Record { [[Key]], [[Value]] } entry of value.[[MapData]]:
For each Record { [[Key]], [[Value]] } entry of copiedList:
Let serializedKey be ? StructuredSerializeInternal(entry.[[Key]], forStorage, memory).
Let serializedValue be ? StructuredSerializeInternal(entry.[[Value]], forStorage, memory).
Append { [[Key]]: serializedKey, [[Value]]: serializedValue } to serialized.[[MapData]].
Otherwise, if value has a [[SetData]] internal slot, then:
Let copiedList be a new empty List.
For each entry of value.[[SetData]]:
If entry is not the special value empty, append entry to copiedList.
For each entry of copiedList:
Let serializedEntry be ? StructuredSerializeInternal(entry, forStorage, memory).
Append serializedEntry to serialized.[[SetData]].
Otherwise, if value is a platform object that is a serializable object, then perform the serialization steps for value's primary interface, given value, serialized, and forStorage.
The serialization steps may need to perform a sub-serialization. This is an operation which takes as input a value subValue, and returns StructuredSerializeInternal(subValue, forStorage, memory). (In other words, a sub-serialization is a specialization of StructuredSerializeInternal to be consistent within this invocation.)
Otherwise, for each key in ! EnumerableOwnProperties(value, key):
If ! HasOwnProperty(value, key) is true, then:
Let inputValue be ? value.[[Get]](key, value).
Let outputValue be ? StructuredSerializeInternal(inputValue, forStorage, memory).
Append { [[Key]]: key, [[Value]]: outputValue } to serialized.[[Properties]].
Return serialized.
It's important to realize that the Records produced by StructuredSerializeInternal might contain "pointers" to other records that create circular references. For example, when we pass the following JavaScript object into StructuredSerializeInternal:
const o = {};
o. myself = o; it produces the following result:
{
[[Type]]: "Object",
[[Properties]]: «
{
[[Key]]: "myself",
[[Value]]: <a pointer to this whole structure>
}
»
}
Return ? StructuredSerializeInternal(value, false).
Return ? StructuredSerializeInternal(value, true).
The StructuredDeserialize abstract operation takes as input a Record serialized, which was previously produced by StructuredSerialize or StructuredSerializeForStorage, and deserializes it into a new JavaScript value, created in targetRealm.
This process can throw an exception, for example when trying to allocate memory for the new
objects (especially ArrayBuffer objects).
If memory was not supplied, let memory be an empty map.
The purpose of the memory map is to avoid deserializing objects twice. This ends up preserving cycles and the identity of duplicate objects in graphs.
If memory[serialized] exists, then return memory[serialized].
Let deep be false.
Let value be an uninitialized value.
If serialized.[[Type]] is "primitive", then set value to serialized.[[Value]].
Otherwise, if serialized.[[Type]] is "Boolean", then set value to a new Boolean object in targetRealm whose [[BooleanData]] internal slot value is serialized.[[BooleanData]].
Otherwise, if serialized.[[Type]] is "Number", then set value to a new Number object in targetRealm whose [[NumberData]] internal slot value is serialized.[[NumberData]].
Otherwise, if serialized.[[Type]] is "BigInt", then set value to a new BigInt object in targetRealm whose [[BigIntData]] internal slot value is serialized.[[BigIntData]].
Otherwise, if serialized.[[Type]] is "String", then set value to a new String object in targetRealm whose [[StringData]] internal slot value is serialized.[[StringData]].
Otherwise, if serialized.[[Type]] is "Date", then set value to a new Date object in targetRealm whose [[DateValue]] internal slot value is serialized.[[DateValue]].
Otherwise, if serialized.[[Type]] is "RegExp", then set value to a new RegExp object in targetRealm whose [[RegExpMatcher]] internal slot value is serialized.[[RegExpMatcher]], whose [[OriginalSource]] internal slot value is serialized.[[OriginalSource]], and whose [[OriginalFlags]] internal slot value is serialized.[[OriginalFlags]].
Otherwise, if serialized.[[Type]] is "SharedArrayBuffer", then:
If targetRealm's corresponding agent cluster is not
serialized.[[AgentCluster]], then throw a
"DataCloneError" DOMException.
Otherwise, set value to a new SharedArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]] and whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]].
Otherwise, if serialized.[[Type]] is "GrowableSharedArrayBuffer", then:
If targetRealm's corresponding agent cluster is not
serialized.[[AgentCluster]], then throw a
"DataCloneError" DOMException.
Otherwise, set value to a new SharedArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], whose [[ArrayBufferByteLengthData]] internal slot value is serialized.[[ArrayBufferByteLengthData]], and whose [[ArrayBufferMaxByteLength]] internal slot value is serialized.[[ArrayBufferMaxByteLength]].
Otherwise, if serialized.[[Type]] is "ArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]].
If this throws an exception, catch it, and then throw a
"DataCloneError" DOMException.
This step might throw an exception if there is not enough memory available to create such an ArrayBuffer object.
Otherwise, if serialized.[[Type]] is "ResizableArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]], and whose [[ArrayBufferMaxByteLength]] internal slot value is serialized.[[ArrayBufferMaxByteLength]].
If this throws an exception, catch it, and then throw a
"DataCloneError" DOMException.
This step might throw an exception if there is not enough memory available to create such an ArrayBuffer object.
Otherwise, if serialized.[[Type]] is "ArrayBufferView", then:
Let deserializedArrayBuffer be ? StructuredDeserialize(serialized.[[ArrayBufferSerialized]], targetRealm, memory).
If serialized.[[Constructor]] is "DataView", then set value to a new DataView object in targetRealm whose [[ViewedArrayBuffer]] internal slot value is deserializedArrayBuffer, whose [[ByteLength]] internal slot value is serialized.[[ByteLength]], and whose [[ByteOffset]] internal slot value is serialized.[[ByteOffset]].
Otherwise, set value to a new typed array object in targetRealm, using the constructor given by serialized.[[Constructor]], whose [[ViewedArrayBuffer]] internal slot value is deserializedArrayBuffer, whose [[TypedArrayName]] internal slot value is serialized.[[Constructor]], whose [[ByteLength]] internal slot value is serialized.[[ByteLength]], whose [[ByteOffset]] internal slot value is serialized.[[ByteOffset]], and whose [[ArrayLength]] internal slot value is serialized.[[ArrayLength]].
Otherwise, if serialized.[[Type]] is "Map", then:
Set value to a new Map object in targetRealm whose [[MapData]] internal slot value is a new empty List.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Set", then:
Set value to a new Set object in targetRealm whose [[SetData]] internal slot value is a new empty List.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Array", then:
Let outputProto be targetRealm.[[Intrinsics]].[[%Array.prototype%]].
Set value to ! ArrayCreate(serialized.[[Length]], outputProto).
Set deep to true.
Otherwise, if serialized.[[Type]] is "Object", then:
Set value to a new Object in targetRealm.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Error", then:
Let prototype be %Error.prototype%.
If serialized.[[Name]] is "EvalError", then set prototype to %EvalError.prototype%.
If serialized.[[Name]] is "RangeError", then set prototype to %RangeError.prototype%.
If serialized.[[Name]] is "ReferenceError", then set prototype to %ReferenceError.prototype%.
If serialized.[[Name]] is "SyntaxError", then set prototype to %SyntaxError.prototype%.
If serialized.[[Name]] is "TypeError", then set prototype to %TypeError.prototype%.
If serialized.[[Name]] is "URIError", then set prototype to %URIError.prototype%.
Let message be serialized.[[Message]].
Set value to OrdinaryObjectCreate(prototype, « [[ErrorData]] »).
Let messageDesc be PropertyDescriptor { [[Value]]: message, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }.
If message is not undefined, then perform !
OrdinaryDefineOwnProperty(value, "message",
messageDesc).
Any interesting accompanying data attached to serialized should be deserialized and attached to value.
Otherwise:
Let interfaceName be serialized.[[Type]].
If the interface identified by interfaceName is not
exposed in targetRealm, then throw a
"DataCloneError" DOMException.
Set value to a new instance of the interface identified by interfaceName, created in targetRealm.
Set deep to true.
Set memory[serialized] to value.
If deep is true, then:
If serialized.[[Type]] is "Map", then:
For each Record { [[Key]], [[Value]] } entry of serialized.[[MapData]]:
Let deserializedKey be ? StructuredDeserialize(entry.[[Key]], targetRealm, memory).
Let deserializedValue be ? StructuredDeserialize(entry.[[Value]], targetRealm, memory).
Append { [[Key]]: deserializedKey, [[Value]]: deserializedValue } to value.[[MapData]].
Otherwise, if serialized.[[Type]] is "Set", then:
For each entry of serialized.[[SetData]]:
Let deserializedEntry be ? StructuredDeserialize(entry, targetRealm, memory).
Append deserializedEntry to value.[[SetData]].
Otherwise, if serialized.[[Type]] is "Array" or "Object", then:
For each Record { [[Key]], [[Value]] } entry of serialized.[[Properties]]:
Let deserializedValue be ? StructuredDeserialize(entry.[[Value]], targetRealm, memory).
Let result be ! CreateDataProperty(value, entry.[[Key]], deserializedValue).
Assert: result is true.
Otherwise:
Perform the appropriate deserialization steps for the interface identified by serialized.[[Type]], given serialized, value, and targetRealm.
The deserialization steps may need to perform a sub-deserialization. This is an operation which takes as input a previously-serialized Record subSerialized, and returns StructuredDeserialize(subSerialized, targetRealm, memory). (In other words, a sub-deserialization is a specialization of StructuredDeserialize to be consistent within this invocation.)
Return value.
Let memory be an empty map.
In addition to how it is used normally by StructuredSerializeInternal, in this algorithm memory is also used to ensure that StructuredSerializeInternal ignores items in transferList, and let us do our own handling instead.
For each transferable of transferList:
If transferable has neither an [[ArrayBufferData]] internal slot nor a
[[Detached]] internal slot, then throw a
"DataCloneError" DOMException.
If transferable has an [[ArrayBufferData]] internal slot and
IsSharedArrayBuffer(transferable) is true, then throw a
"DataCloneError" DOMException.
If memory[transferable] exists,
then throw a "DataCloneError" DOMException.
Set memory[transferable] to { [[Type]]: an uninitialized value }.
transferable is not transferred yet as transferring has side effects and StructuredSerializeInternal needs to be able to throw first.
Let serialized be ? StructuredSerializeInternal(value, false, memory).
Let transferDataHolders be a new empty List.
For each transferable of transferList:
If transferable has an [[ArrayBufferData]] internal slot and
IsDetachedBuffer(transferable) is true, then throw a
"DataCloneError" DOMException.
If transferable has a [[Detached]] internal slot and
transferable.[[Detached]] is true, then throw a
"DataCloneError" DOMException.
Let dataHolder be memory[transferable].
If transferable has an [[ArrayBufferData]] internal slot, then:
If transferable has an [[ArrayBufferMaxByteLength]] internal slot, then:
Set dataHolder.[[Type]] to "ResizableArrayBuffer".
Set dataHolder.[[ArrayBufferData]] to transferable.[[ArrayBufferData]].
Set dataHolder.[[ArrayBufferByteLength]] to transferable.[[ArrayBufferByteLength]].
Set dataHolder.[[ArrayBufferMaxByteLength]] to transferable.[[ArrayBufferMaxByteLength]].
Otherwise:
Set dataHolder.[[Type]] to "ArrayBuffer".
Set dataHolder.[[ArrayBufferData]] to transferable.[[ArrayBufferData]].
Set dataHolder.[[ArrayBufferByteLength]] to transferable.[[ArrayBufferByteLength]].
Perform ? DetachArrayBuffer(transferable).
Specifications can use the [[ArrayBufferDetachKey]] internal slot to prevent
ArrayBuffers from being detached. This is used in
WebAssembly JavaScript Interface, for example. [WASMJS]
Otherwise:
Assert: transferable is a platform object that is a transferable object.
Let interfaceName be the identifier of the primary interface of transferable.
Set dataHolder.[[Type]] to interfaceName.
Perform the appropriate transfer steps for the interface identified by interfaceName, given transferable and dataHolder.
Set transferable.[[Detached]] to true.
Append dataHolder to transferDataHolders.
Return { [[Serialized]]: serialized, [[TransferDataHolders]]: transferDataHolders }.
Let memory be an empty map.
Analogous to StructuredSerializeWithTransfer, in addition to how it is used normally by StructuredDeserialize, in this algorithm memory is also used to ensure that StructuredDeserialize ignores items in serializeWithTransferResult.[[TransferDataHolders]], and let us do our own handling instead.
Let transferredValues be a new empty List.
For each transferDataHolder of serializeWithTransferResult.[[TransferDataHolders]]:
Let value be an uninitialized value.
If transferDataHolder.[[Type]] is "ArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is transferDataHolder.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot value is transferDataHolder.[[ArrayBufferByteLength]].
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.
Otherwise, if transferDataHolder.[[Type]] is "ResizableArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is transferDataHolder.[[ArrayBufferData]], whose [[ArrayBufferByteLength]] internal slot value is transferDataHolder.[[ArrayBufferByteLength]], and whose [[ArrayBufferMaxByteLength]] internal slot value is transferDataHolder.[[ArrayBufferMaxByteLength]].
For the same reason as the previous step, this step is also unlikely to throw an exception.
Otherwise:
Let interfaceName be transferDataHolder.[[Type]].
If the interface identified by interfaceName is not exposed in
targetRealm, then throw a "DataCloneError"
DOMException.
Set value to a new instance of the interface identified by interfaceName, created in targetRealm.
Perform the appropriate transfer-receiving steps for the interface identified by interfaceName given transferDataHolder and value.
Set memory[transferDataHolder] to value.
Append value to transferredValues.
Let deserialized be ? StructuredDeserialize(serializeWithTransferResult.[[Serialized]], targetRealm, memory).
Return { [[Deserialized]]: deserialized, [[TransferredValues]]: transferredValues }.
Other specifications may use the abstract operations defined here. The following provides some guidance on when each abstract operation is typically useful, with examples.
Cloning a value to another realm, 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.
messagePort.postMessage()
uses this pair of abstract operations, as the destination realm is not known until the
MessagePort has been shipped.
Creating a realm-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.
StructuredSerializeForStorage 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 SharedArrayBuffer objects, since storing shared memory
does not make sense. Similarly, it can throw or possibly have different behavior when given a
platform object with custom serialization steps when the
forStorage argument is true.
history.pushState() and history.replaceState() use
StructuredSerializeForStorage on author-supplied state objects, storing them as
serialized state in the appropriate session history entry. Then,
StructuredDeserialize is used so that the history.state property can return a clone of the
originally-supplied state object.
broadcastChannel.postMessage() uses
StructuredSerialize on its input, then uses StructuredDeserialize
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.
Any API for persisting JavaScript values to the filesystem would also use StructuredSerializeForStorage on its input and StructuredDeserialize on its output.
In general, call sites may pass in Web IDL values instead of JavaScript values; this is to be understood to perform an implicit conversion to the JavaScript value before invoking these algorithms.
Call sites that are not invoked as a result of author code synchronously calling into a user agent method must take care to properly prepare to run script and prepare to run a callback before invoking StructuredSerialize, StructuredSerializeForStorage, or StructuredSerializeWithTransfer 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 entry and incumbent concepts being properly set up.
window.postMessage() performs
StructuredSerializeWithTransfer 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 prepare to run script and prepare to run a
callback.
In contrast, a hypothetical API that used StructuredSerialize to serialize some author-supplied object periodically, directly from a task on the event loop, 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.
result = self.structuredClone(value[, { transfer }])Takes the input value and returns a deep copy by performing the structured clone algorithm.
Transferable objects listed in the transfer array are transferred, not
just cloned, meaning that they are no longer usable in the input value.
Throws a "DataCloneError" DOMException if any part of
the input value is not serializable.
Support in all current engines.
The structuredClone(value,
options) method steps are:
Let serialized be ?
StructuredSerializeWithTransfer(value, options["transfer"]).
Let deserializeRecord be ? StructuredDeserializeWithTransfer(serialized, this's relevant realm).
Return deserializeRecord.[[Deserialized]].
Every XML and HTML document in an HTML UA is represented by a Document object.
[DOM]
The Document object's URL is defined in
DOM. It is initially set when the Document object is created, but can
change during the lifetime of the Document object; for example, it changes when the
user navigates to a fragment
on the page and when the pushState() method is called
with a new URL. [DOM]
Interactive user agents typically expose the Document object's
URL in their user interface. This is the primary
mechanism by which a user can tell if a site is attempting to impersonate another.
The Document object's origin is defined in
DOM. It is initially set when the Document object is created, and can
change during the lifetime of the Document only upon setting document.domain. A Document's origin can differ from the origin of its URL;
for example when a child navigable is created, its active document's origin is inherited from its parent's active document's origin, even though its active document's URL is
about:blank. [DOM]
When a Document is created by a script using
the createDocument() or createHTMLDocument() methods, the
Document is ready for post-load tasks immediately.
The document's referrer is a string (representing a URL) that
can be set when the Document is created. If it is not explicitly set, then its value
is the empty string.
Document objectSupport in all current engines.
DOM defines a Document interface, which
this specification extends significantly.
enum DocumentReadyState { "loading" , "interactive" , "complete" };
enum DocumentVisibilityState { "visible" , "hidden" };
typedef (HTMLScriptElement or SVGScriptElement ) HTMLOrSVGScriptElement ;
[LegacyOverrideBuiltIns ]
partial interface Document {
static Document parseHTMLUnsafe ((TrustedHTML or DOMString ) html );
// resource metadata management
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location ? location ;
attribute USVString domain ;
readonly attribute USVString referrer ;
attribute USVString cookie ;
readonly attribute DOMString lastModified ;
readonly attribute DocumentReadyState readyState ;
// DOM tree accessors
getter object (DOMString name );
[CEReactions ] attribute DOMString title ;
[CEReactions ] attribute DOMString dir ;
[CEReactions ] attribute HTMLElement ? body ;
readonly attribute HTMLHeadElement ? head ;
[SameObject ] readonly attribute HTMLCollection images ;
[SameObject ] readonly attribute HTMLCollection embeds ;
[SameObject ] readonly attribute HTMLCollection plugins ;
[SameObject ] readonly attribute HTMLCollection links ;
[SameObject ] readonly attribute HTMLCollection forms ;
[SameObject ] readonly attribute HTMLCollection scripts ;
NodeList getElementsByName (DOMString elementName );
readonly attribute HTMLOrSVGScriptElement ? currentScript ; // classic scripts in a document tree only
// dynamic markup insertion
[CEReactions ] Document open (optional DOMString unused1 , optional DOMString unused2 ); // both arguments are ignored
WindowProxy ? open (USVString url , DOMString name , DOMString features );
[CEReactions ] undefined close ();
[CEReactions ] undefined write ((TrustedHTML or DOMString )... text );
[CEReactions ] undefined writeln ((TrustedHTML or DOMString )... text );
// user interaction
readonly attribute WindowProxy ? defaultView ;
boolean hasFocus ();
[CEReactions ] attribute DOMString designMode ;
[CEReactions ] boolean execCommand (DOMString commandId , optional boolean showUI = false , optional DOMString value = "");
boolean queryCommandEnabled (DOMString commandId );
boolean queryCommandIndeterm (DOMString commandId );
boolean queryCommandState (DOMString commandId );
boolean queryCommandSupported (DOMString commandId );
DOMString queryCommandValue (DOMString commandId );
readonly attribute boolean hidden ;
readonly attribute DocumentVisibilityState visibilityState ;
// special event handler IDL attributes that only apply to Document objects
[LegacyLenientThis ] attribute EventHandler onreadystatechange ;
attribute EventHandler onvisibilitychange ;
// also has obsolete members
};
Document includes GlobalEventHandlers ;Each Document has a policy container (a policy container), initially a new policy
container, which contains policies which apply to the Document.
Each Document has a permissions policy, which
is a permissions policy, which is initially
empty.
Each Document has a module map,
which is a module map, initially empty.
Each Document has an opener policy,
which is an opener policy, initially a new opener policy.
Each Document has an is initial about:blank, which is a
boolean, initially false.
Each Document has a during-loading
navigation ID for WebDriver BiDi, which is a navigation ID or null, initially
null.
As the name indicates, this is used for interfacing with the WebDriver
BiDi specification, which needs to be informed about certain occurrences during the early
parts of the Document's lifecycle, in a way that ties them to the original
navigation ID used when the navigation that created this Document was
the ongoing navigation. This eventually gets set back to null, after WebDriver
BiDi considers the loading process to be finished. [BIDI]
Each Document has an about base
URL, which is a URL or null, initially null.
This is only populated for "about:"-schemed
Documents.
Each Document has a bfcache blocking details, which is a
set of not restored reason details,
initially empty.
Each Document has an open dialogs list, which is a list of
dialog elements, initially empty.
DocumentOrShadowRoot interfaceDOM defines the DocumentOrShadowRoot mixin, which this specification
extends.
partial interface mixin DocumentOrShadowRoot {
readonly attribute Element ? activeElement ;
};document.referrerSupport in all current engines.
Returns the URL of the Document 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.
The noreferrer link type can be used to block the
referrer.
The referrer
attribute must return the document's referrer.
document.cookie [ = value ]Returns the HTTP cookies that apply to the Document. If there are no cookies or
cookies can't be applied to this resource, the empty string will be returned.
Can be set, to add a new cookie to the element's set of HTTP cookies.
If the contents are sandboxed into an
opaque origin (e.g., in an iframe with the sandbox attribute), a
"SecurityError" DOMException will be thrown on getting
and setting.
Support in all current engines.
The cookie
attribute represents the cookies of the resource identified by the document's URL.
Using the synchronous document.cookie
API can be a source of performance issues. The Cookie Store API can be used instead,
as it provides an asynchronous way to handle cookies to avoid performance issues. See the Cookie Store API introduction for more
information. [COOKIESTORE]
A Document object that falls into one of the following conditions is a
cookie-averse Document object:
Document object whose browsing
context is null.Document whose URL's scheme is not an HTTP(S) scheme.
On getting, if the document is a cookie-averse
Document object, then the
user agent must return the empty string. Otherwise, if the Document's origin is an opaque
origin, the user agent must throw a "SecurityError"
DOMException. Otherwise, the user agent must return the cookie-string
for the document's URL for a "non-HTTP" API, decoded
using UTF-8 decode without BOM. [COOKIES]
On setting, if the document is a cookie-averse Document object, then
the user agent must do nothing. Otherwise, if the Document's origin is an opaque
origin, the user agent must throw a "SecurityError"
DOMException. Otherwise, the user agent must act as it would when receiving a set-cookie-string for the document's
URL via a "non-HTTP" API, consisting of the new value
encoded as UTF-8. [COOKIES] [ENCODING]
Since the cookie 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.
The cookie 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.
document.lastModifiedSupport in all current engines.
Returns the date of the last modification to the document, as reported by the server, in the
form "MM/DD/YYYY hh:mm:ss", in the user's local time zone.
If the last modification date is not known, the current time is returned instead.
The lastModified attribute, on getting, must return
the date and time of the Document's source file's last modification, in the user's
local time zone, in the following format:
The month component of the date.
A U+002F SOLIDUS character (/).
The day component of the date.
A U+002F SOLIDUS character (/).
The year component of the date.
A U+0020 SPACE character.
The hours component of the time.
A U+003A COLON character (:).
The minutes component of the time.
A U+003A COLON character (:).
The seconds component of the time.
All the numeric components above, other than the year, must be given as two ASCII digits representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more ASCII digits representing the number in base ten, zero-padded if necessary.
The Document'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 `Last-Modified` 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.
document.readyStateReturns "loading" while the Document is loading, "interactive" once it is finished parsing but still loading subresources, and
"complete" once it has loaded.
The readystatechange event fires on the
Document object when this value changes.
The DOMContentLoaded event fires after the transition to
"interactive" but before the transition to "complete", at the point where all subresources apart from async script elements have loaded.
Support in all current engines.
Each Document has a current document readiness, a string, initially
"complete".
For Document objects created via the create and initialize a Document object
algorithm, this will be immediately reset to "loading" before any script
can observe the value of document.readyState. This
default applies to other cases such as initial
about:blank Documents or Documents without a
browsing context.
The readyState getter steps are to return
this's current document readiness.
To update the current document readiness for Document
document to readinessValue:
If document's current document readiness equals readinessValue, then return.
Set document's current document readiness to readinessValue.
If document is associated with an HTML parser, then:
Let now be the current high resolution time given document's relevant global object.
If readinessValue is "complete", and
document's load timing info's DOM complete time is 0, then
set document's load timing info's DOM complete time to
now.
Otherwise, if readinessValue is "interactive", and
document's load timing info's DOM interactive time is 0,
then set document's load timing info's DOM interactive
time to now.
Fire an event named readystatechange at document.
A Document is said to have an active parser if it is associated with an
HTML parser or an XML parser that has not yet been stopped or aborted.
A Document has a document load timing info load timing info.
A Document has a document unload timing info previous document unload timing.
A Document has a boolean was created via cross-origin redirects,
initially false.
The document load timing info struct has the following items:
DOMHighResTimeStamp valuesThe document unload timing info struct has the following items:
DOMHighResTimeStamp valuesEach Document has a render-blocking element set, a set of
elements, initially the empty set.
A Document document allows adding render-blocking elements
if document's content type is
"text/html" and the body element of document is null.
A Document document is render-blocked if both of the
following are true:
document's render-blocking element set is non-empty, or document allows adding render-blocking elements.
The current high resolution time given document's relevant global object has not exceeded an implementation-defined timeout value.
An element el is render-blocking if el's node document document is render-blocked, and el is in document's render-blocking element set.
To block rendering on an element el:
Let document be el's node document.
If document allows adding render-blocking elements, then append el to document's render-blocking element set.
To unblock rendering on an element el:
Let document be el's node document.
Remove el from document's render-blocking element set.
Whenever a render-blocking element el becomes browsing-context disconnected, or el's blocking attribute's value is changed so that el is no longer potentially render-blocking, then unblock rendering on el.
The html element of a document is its document element,
if it's an html element, and null otherwise.
document.headSupport in all current engines.
Returns the head element.
The head element of a document is the first head element
that is a child of the html element, if there is one, or null
otherwise.
The head attribute,
on getting, must return the head element of the document (a
head element or null).
document.title [ = value ]Returns the document's title, as given by the title element for
HTML and as given by the SVG title element for SVG.
Can be set, to update the document's title. If there is no appropriate element to update, the new value is ignored.
The title element of a document is the first title element
in the document (in tree order), if there is one, or null otherwise.
Support in all current engines.
The title attribute must, on getting, run the following
algorithm:
If the document element is an SVG svg element, then
let value be the child text content of the first SVG
title element that is a child of the document element.
Otherwise, let value be the child text content of the
title element, or the empty string if the title
element is null.
Strip and collapse ASCII whitespace in value.
Return value.
On setting, the steps corresponding to the first matching condition in the following list must be run:
svg elementIf there is an SVG title element that is a child of the
document element, let element be the first such element.
Otherwise:
Let element be the result of creating an
element given the document element's node document, "title", and the SVG namespace.
Insert element as the first child of the document element.
String replace all with the given value within element.
If the title element is null and the head
element is null, then return.
If the title element is non-null, let element be
the title element.
Otherwise:
Let element be the result of creating an
element given the document element's node document, "title", and the HTML namespace.
Append element to the
head element.
String replace all with the given value within element.
Do nothing.
document.body [ = value ]Support in all current engines.
Returns the body element.
Can be set, to replace the body element.
If the new value is not a body or frameset element, this will throw
a "HierarchyRequestError" DOMException.
The body element of a document is the first of the html
element's children that is either a body element or a frameset
element, or null if there is no such element.
The body attribute,
on getting, must return the body element of the document (either a body
element, a frameset element, or null). On setting, the following algorithm must be
run:
body or frameset element, then throw a
"HierarchyRequestError" DOMException.HierarchyRequestError" DOMException.The value returned by the body getter is
not always the one passed to the setter.
In this example, the setter successfully inserts a body element (though this is
non-conforming since SVG does not allow a body as child of SVG
svg). However the getter will return null because the document element is not
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 > document.imagesSupport in all current engines.
Returns an HTMLCollection of the img elements in the
Document.
document.embedsSupport in all current engines.
document.pluginsSupport in all current engines.
Returns an HTMLCollection of the embed elements in the
Document.
document.linksSupport in all current engines.
Returns an HTMLCollection of the a and area elements
in the Document that have href
attributes.
document.formsSupport in all current engines.
Returns an HTMLCollection of the form elements in the
Document.
document.scriptsSupport in all current engines.
Returns an HTMLCollection of the script elements in the
Document.
The images
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only img elements.
The embeds
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only embed elements.
The plugins
attribute must return the same object as that returned by the embeds attribute.
The links
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only a elements with href attributes and area elements with href attributes.
The forms
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only form elements.
The scripts
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only script elements.
collection = document.getElementsByName(name)Support in all current engines.
Returns a NodeList of elements in the Document that have a name attribute with the value name.
The getElementsByName(elementName) method
steps are to return a live NodeList containing all the HTML
elements in that document that have a name attribute whose value is
identical to the elementName argument, in tree order. When the
method is invoked on a Document 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
NodeList object must be returned.
document.currentScriptSupport in all current engines.
Returns the script element, or the SVG script element,
that is currently executing, as long as the element represents a classic script. In
the case of reentrant script execution, returns the one that most recently started executing
amongst those that have not yet finished executing.
Returns null if the Document is not currently executing a script or
SVG script element (e.g., because the running script is an event
handler, or a timeout), or if the currently executing script or SVG
script element represents a module script.
The currentScript attribute, on getting, must return
the value to which it was most recently set. When the Document is created, the currentScript must be initialized to null.
This API has fallen out of favor in the implementer and standards community, as
it globally exposes script or SVG script elements. As such,
it is not available in newer contexts, such as when running module
scripts or when running scripts in a shadow tree. We are looking into creating
a new solution for identifying the running script in such contexts, which does not make it
globally available: see issue #1013.
The Document interface supports named properties. The supported property names of a
Document object document at any moment consist of the following, in
tree order according to the element that contributed them, ignoring later duplicates,
and with values from id attributes coming before values from name attributes when the same element contributes both:
the value of the name content attribute for all
exposed embed, form, iframe,
img, and exposed object elements that have a non-empty
name content attribute and are in a document tree with
document as their root;
the value of the id content attribute for all
exposed object elements that have a non-empty
id content attribute and are in a document tree with
document as their root; and
the value of the id content attribute for all
img elements that have both a non-empty id content
attribute and a non-empty name content attribute, and are in a
document tree with document as their root.
To determine the value of a named property
name for a Document, the user agent must return the value obtained using
the following steps:
Let elements be the list of named
elements with the name name that are in a document tree with the
Document as their root.
There will be at least one such element, since the algorithm would otherwise not have been invoked by Web IDL.
If elements has only one element, and that element is an iframe
element, and that iframe element's content navigable is not null, then
return the active WindowProxy of the element's
content navigable.
Otherwise, if elements has only one element, return that element.
Otherwise, return an HTMLCollection rooted at the Document node,
whose filter matches only named elements with
the name name.
Named elements with the name name, for the purposes of the above algorithm, are those that are either:
embed, form, iframe,
img, or exposed object elements that have a name content attribute whose value is name, orobject elements that have an id content attribute whose value is name, orimg elements that have an id content attribute
whose value is name, and that have a non-empty name
content attribute present also.An embed or object element is said to be exposed if it has
no exposed object ancestor, and, for object elements, is
additionally either not showing its fallback content or has no object or
embed descendants.
The dir attribute on the
Document interface is defined along with the dir
content attribute.
Elements, attributes, and attribute values in HTML are defined (by this specification) to have
certain meanings (semantics). For example, the ol element represents an ordered list,
and the lang attribute represents the language of the content.
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.
As a simple example, consider a web page written by an author who only considered desktop computer web browsers:
<!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 > Because HTML conveys meaning, 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.
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.
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.
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).
This example has focused on headings, but the same principle applies to all of the semantics in HTML.
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.
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).
< body >
< h1 > ACME Corporation</ h1 >
< h2 > The leaders in arbitrary fast delivery since 1920</ h2 >
...The hgroup element can be used for these kinds of situations:
< body >
< hgroup >
< h1 > ACME Corporation</ h1 >
< p > The leaders in arbitrary fast delivery since 1920</ p >
</ hgroup >
...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 cite element mis-used:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
< body >
< table >
< tr > < td > 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 > 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.
A corrected version of this document might be:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
< body >
< blockquote >
< p > 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 > Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications, as doing so makes it significantly harder for the language to be extended in the future.
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:
< label > Carpet: < input type = "carpet" name = "c" texture = "deep pile" ></ label > Here would be an alternative and correct way to mark this up:
< label > Carpet: < input type = "text" class = "carpet" name = "c" data-texture = "deep pile" ></ label > DOM nodes whose node document's browsing context is null are exempt from all document conformance requirements other than the HTML syntax requirements and XML syntax requirements.
In particular, the template element's template contents's node
document's browsing context is null. For
example, the content model requirements and
attribute value microsyntax requirements do not apply to a template element's
template contents. In this example an img element has attribute values
that are placeholders that would be invalid outside a template element.
< template >
< article >
< img src = "{{src}}" alt = "{{alt}}" >
< h1 ></ h1 >
</ article >
</ template > However, if the above markup were to omit the </h1> end tag, that
would be a violation of the HTML syntax, and would thus be flagged as an
error by conformance checkers.
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 must update their presentation of the document as this occurs.
HTML has a progress 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.
The nodes representing HTML elements in the DOM must implement, and expose to scripts, the interfaces listed for them in the relevant sections of this specification. This includes HTML elements in XML documents, even when those documents are in another context (e.g. inside an XSLT transform).
Elements in the DOM represent things; that is, they have intrinsic meaning, also known as semantics.
For example, an ol element represents an ordered list.
Elements can be referenced (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 id attribute to the element, and then creating a
hyperlink with that id attribute's value as the fragment for the hyperlink's href attribute value. Hyperlinks are not necessary for a
reference, however; any manner of referring to the element in question will suffice.
Consider the following figure element, which is given an id attribute:
< 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 > A hyperlink-based reference could be created
using the a element, like so:
As we can see in < a href = "#module-script-graph" > figure 27</ a > , ...However, there are many other ways of referencing the
figure element, such as:
"As depicted in the figure of modules A, B, C, and D..."
"In Figure 27..." (without a hyperlink)
"From the contents of the 'simple module graph' figure..."
"In the figure below..." (but this is discouraged)
The basic interface, from which all the HTML elements' interfaces inherit, and which must be used by elements that have no additional requirements, is
the HTMLElement interface.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLElement : Element {
[HTMLConstructor ] constructor ();
// metadata attributes
[CEReactions , Reflect ] attribute DOMString title ;
[CEReactions , Reflect ] attribute DOMString lang ;
[CEReactions ] attribute boolean translate ;
[CEReactions ] attribute DOMString dir ;
// user interaction
[CEReactions ] attribute (boolean or unrestricted double or DOMString )? hidden ;
[CEReactions , Reflect ] attribute boolean inert ;
undefined click ();
[CEReactions , Reflect ] attribute DOMString accessKey ;
readonly attribute DOMString accessKeyLabel ;
[CEReactions ] attribute boolean draggable ;
[CEReactions ] attribute boolean spellcheck ;
[CEReactions , ReflectSetter ] attribute DOMString writingSuggestions ;
[CEReactions , ReflectSetter ] attribute DOMString autocapitalize ;
[CEReactions ] attribute boolean autocorrect ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString innerText ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString outerText ;
ElementInternals attachInternals ();
// The popover API
undefined showPopover (optional ShowPopoverOptions options = {});
undefined hidePopover ();
boolean togglePopover (optional (TogglePopoverOptions or boolean ) options = {});
[CEReactions ] attribute DOMString ? popover ;
[CEReactions , Reflect , ReflectRange=(0, 8)] attribute unsigned long headingOffset ;
[CEReactions , Reflect ] attribute boolean headingReset ;
};
dictionary ShowPopoverOptions {
HTMLElement source ;
};
dictionary TogglePopoverOptions : ShowPopoverOptions {
boolean force ;
};
HTMLElement includes GlobalEventHandlers ;
HTMLElement includes ElementContentEditable ;
HTMLElement includes HTMLOrSVGElement ;
[Exposed =Window ]
interface HTMLUnknownElement : HTMLElement {
// Note: intentionally no [HTMLConstructor]
};The HTMLElement 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.
The element interface for an element with name name in the HTML namespace is determined as follows:
If name is applet, bgsound, blink,
isindex, keygen, multicol, nextid, or
spacer, then return HTMLUnknownElement.
If name is acronym, basefont, big,
center, nobr, noembed, noframes,
plaintext, rb, rtc, strike, or
tt, then return HTMLElement.
If name is listing or xmp, then return
HTMLPreElement.
Otherwise, if this specification defines an interface appropriate for the element type corresponding to the local name name, then return that interface.
If other applicable specifications define an appropriate interface for name, then return the interface they define.
If name is a valid custom element name, then return
HTMLElement.
Return HTMLUnknownElement.
The use of HTMLElement instead of HTMLUnknownElement in
the case of valid custom element names is done to
ensure that any potential future upgrades only cause
a linear transition of the element's prototype chain, from HTMLElement to a subclass,
instead of a lateral one, from HTMLUnknownElement to an unrelated subclass.
Features shared between HTML and SVG elements use the HTMLOrSVGElement interface
mixin: [SVG]
Support in one engine only.
interface mixin HTMLOrSVGElement {
[SameObject ] readonly attribute DOMStringMap dataset ;
attribute DOMString nonce ; // intentionally no [CEReactions]
[CEReactions , Reflect ] attribute boolean autofocus ;
[CEReactions , ReflectSetter ] attribute long tabIndex ;
undefined focus (optional FocusOptions options = {});
undefined blur ();
};An example of an element that is neither an HTML nor SVG element is one created as follows:
const el = document.createElementNS("some namespace", "example");
console.assert(el.constructor === Element);To support the custom elements feature, all HTML elements have
special constructor behavior. This is indicated via the [HTMLConstructor] IDL
extended attribute. It indicates that the interface object for the given interface
will have a specific behavior when called, as defined in detail below.
The [HTMLConstructor] extended attribute must take no
arguments, and must only appear on constructor
operations. 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.
Interfaces declared with constructor operations that are annotated with the [HTMLConstructor] extended attribute have the following
overridden constructor steps:
If NewTarget is equal to the active function
object, then throw a TypeError.
This can occur when a custom element is defined using an element interface as its constructor:
customElements. define( "bad-1" , HTMLButtonElement);
new HTMLButtonElement(); // (1)
document. createElement( "bad-1" ); // (2) In this case, during the execution of HTMLButtonElement (either explicitly, as
in (1), or implicitly, as in (2)), both the active function object and
NewTarget are HTMLButtonElement. If this check was not present, it
would be possible to create an instance of HTMLButtonElement whose local name was
bad-1.
Let registry be null.
If the surrounding agent's active custom element constructor map[NewTarget] exists:
Set registry to the surrounding agent's active custom element constructor map[NewTarget].
Remove the surrounding agent's active custom element constructor map[NewTarget].
Otherwise, set registry to the current global object's associated Document's custom element registry.
Let definition be the item in registry's custom element
definition set with constructor equal to
NewTarget. If there is no such item, then throw a TypeError.
Since there can be no item in registry's custom element definition set with a constructor of undefined, this step also prevents HTML element constructors from being called as functions (since in that case NewTarget will be undefined).
Let isValue be null.
If definition's local name is equal to definition's name (i.e., definition is for an autonomous custom element):
If the active function object is not HTMLElement, then throw a
TypeError.
This can occur when a custom element is defined to not extend any local names, but
inherits from a non-HTMLElement class:
customElements. define( "bad-2" , class Bad2 extends HTMLParagraphElement {}); In this case, during the (implicit) super() call that occurs when
constructing an instance of Bad2, the active function
object is HTMLParagraphElement, not HTMLElement.
Otherwise (i.e., if definition is for a customized built-in element):
Let valid local names be the list of local names for elements defined in this specification or in other applicable specifications that use the active function object as their element interface.
If valid local names does not contain definition's local name, then throw a
TypeError.
This can occur when a custom element is defined to extend a given local name but inherits from the wrong class:
customElements. define( "bad-3" , class Bad3 extends HTMLQuoteElement {}, { extends : "p" }); In this case, during the (implicit) super() call that occurs when
constructing an instance of Bad3, valid local names is the
list containing q and blockquote, but definition's local name is p,
which is not in that list.
Set isValue to definition's name.
If definition's construction stack is empty:
Let element be the result of internally creating a new object implementing the interface to which the active function object corresponds, given the current realm and NewTarget.
Set element's node document to the current global
object's associated
Document.
Set element's namespace to the HTML namespace.
Set element's namespace prefix to null.
Set element's local name to definition's local name.
Set element's custom element registry to registry.
Set element's custom element state to "custom".
Set element's custom element definition to definition.
Set element's is value to isValue.
Return element.
This occurs when author script constructs a new custom element directly, e.g.,
via new MyCustomElement().
If prototype is not an Object, then:
Let realm be ? GetFunctionRealm(NewTarget).
Set prototype to the interface prototype object of realm whose interface is the same as the interface of the active function object.
The realm of the active function object might not be realm, so we are using the more general concept of "the same interface" across realms; we are not looking for equality of interface objects. This fallback behavior, including using the realm of NewTarget and looking up the appropriate prototype there, is designed to match analogous behavior for the JavaScript built-ins and Web IDL's internally create a new object implementing the interface algorithm.
Let element be the last entry in definition's construction stack.
If element is an already
constructed marker, then throw a TypeError.
This can occur when the author code inside the custom element
constructor non-conformantly creates another
instance of the class being constructed, before calling super():
let doSillyThing = true ;
class DontDoThis extends HTMLElement {
constructor() {
if ( doSillyThing) {
doSillyThing = false ;
new DontDoThis();
// Now the construction stack will contain an already constructed marker.
}
// This will then fail with a TypeError:
super ();
}
} This can also occur when author code inside the custom element constructor non-conformantly calls super()
twice, since per the JavaScript specification, this actually executes the superclass
constructor (i.e. this algorithm) twice, before throwing an error:
class DontDoThisEither extends HTMLElement {
constructor() {
super ();
// This will throw, but not until it has already called into the HTMLElement constructor
super ();
}
} Perform ? element.[[SetPrototypeOf]](prototype).
Replace the last entry in definition's construction stack with an already constructed marker.
Return element.
This step is normally reached when upgrading a custom element; the existing element is
returned, so that the super() call inside the custom element
constructor assigns that existing element to this.
In addition to the constructor behavior implied by [HTMLConstructor], some elements also have named constructors (which are really factory functions with a modified prototype property).
Named constructors for HTML elements can also be used in an extends clause when defining a custom
element constructor:
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 ); Each element in this specification has a definition that includes the following information:
A list of categories to which the element belongs. These are used when defining the content models for each element.
A non-normative 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.
For simplicity, only the most specific expectations are listed.
For example, all phrasing content is flow content. Thus, elements that are phrasing content will only be listed as "where phrasing content is expected", since this is the more-specific expectation. Anywhere that expects flow content also expects phrasing content, and thus also meets this expectation.
A normative description of what content must be included as children and descendants of the element.
A non-normative description of whether, in the text/html syntax, the
start and end tags can
be omitted. This information is redundant with the normative requirements given in the optional tags section, and is provided in the element
definitions only as a convenience.
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.)
For authors: Conformance requirements for use of ARIA role and aria-* attributes are
defined in ARIA in HTML. [ARIA] [ARIAHTML]
For implementers: User agent requirements for implementing accessibility API semantics are defined in HTML Accessibility API Mappings. [HTMLAAM]
A normative definition of a DOM interface that such elements must implement.
This is then followed by a description of what the element represents, along with any additional normative conformance criteria that may apply to authors and implementations. Examples are sometimes also included.
An attribute value is a string. Except where otherwise specified, attribute values on HTML elements may be any string value, including the empty string, and there is no restriction on what text can be specified in such attribute values.
Each element defined in this specification has a content model: a description of the element's expected contents. An HTML element must have contents that match the requirements described in the element's content model. The contents of an element are its children in the DOM.
ASCII whitespace is always allowed between elements. User agents represent these
characters between elements in the source markup as Text nodes in the DOM. Empty Text nodes and
Text nodes consisting of just sequences of those characters are considered
inter-element whitespace.
Inter-element whitespace, 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.
Thus, an element A is said to be preceded or followed
by a second element B if A and B have
the same parent node and there are no other element nodes or Text nodes (other than
inter-element whitespace) between them. Similarly, a node is the only child of
an element if that element contains no other nodes other than inter-element
whitespace, comment nodes, and processing instruction nodes.
Authors must not use HTML elements 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.
The Atom Syndication Format defines a content element. When its type attribute has the value
xhtml, The Atom Syndication Format requires that it contain a
single HTML div element. Thus, a div element is allowed in that context,
even though this is not explicitly normatively stated by this specification. [ATOM]
In addition, HTML elements may be orphan nodes (i.e. without a parent node).
For example, creating a td element and storing it in a global variable in a
script is conforming, even though td elements are otherwise only supposed to be used
inside tr elements.
var data = {
name: "Banana" ,
cell: document. createElement( 'td' ),
}; When an element's content model is nothing, the
element must contain no Text nodes (other than inter-element whitespace)
and no element nodes.
Most HTML elements whose content model is "nothing" are also, for convenience, void elements (elements that have no end tag in the HTML syntax). However, these are entirely separate concepts.
Each element in HTML falls into zero or more categories that group elements with similar characteristics together. The following broad categories are used in this specification:
Some elements also fall into other categories, which are defined in other parts of this specification.
These categories are related as follows:
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.
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.
Metadata content 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.
Elements from other namespaces whose semantics are primarily metadata-related (e.g. RDF) are also metadata content.
Thus, in the XML serialization, one can use RDF, like this:
< 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:[email protected]" />
< 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 > This isn't possible in the HTML serialization, however.
Most elements that are used in the body of documents and applications are categorized as flow content.
aabbraddressarea (if it is a descendant of a map element)articleasideaudiobbdibdoblockquotebrbuttoncanvascitecodedatadatalistdeldetailsdfndialogdivdlemembedfieldsetfigurefooterformh1h2h3h4h5h6headerhgrouphriiframeimginputinskbdlabellink (if it is allowed in the body)main (if it is a hierarchically correct main element)mapmarkmathmenumeta (if the itemprop attribute is present)meternavnoscriptobjectoloutputppicturepreprogressqrubyssampscriptsearchsectionselectslotsmallspanstrongsubsupsvgtabletemplatetextareatimeuulvarvideowbrSectioning content is content that defines the scope of header
and footer elements.
Heading content defines the heading of a section (whether explicitly marked up using sectioning content elements, or implied by the heading content itself).
Phrasing content is the text of the document, as well as elements that mark up that text at the intra-paragraph level. Runs of phrasing content form paragraphs.
aabbrarea (if it is a descendant of a map element)audiobbdibdobrbuttoncanvascitecodedatadatalistdeldfnemembediiframeimginputinskbdlabellink (if it is allowed in the body)mapmarkmathmeta (if the itemprop attribute is present)meternoscriptobjectoutputpictureprogressqrubyssampscriptselectselectedcontent (if it is a descendant of a button in a
select)slotsmallspanstrongsubsupsvgtemplatetextareatimeuvarvideowbrMost elements that are categorized as phrasing content can only contain elements that are themselves categorized as phrasing content, not any flow content.
Text, in the context of content models, means either nothing,
or Text nodes. Text is sometimes used as a content
model on its own, but is also phrasing content, and can be inter-element
whitespace (if the Text nodes are empty or contain just ASCII
whitespace).
Text nodes and attribute values must consist of scalar
values, excluding noncharacters, and controls other than ASCII whitespace.
This specification includes extra constraints on the exact value of Text nodes and
attribute values depending on their precise context.
Embedded content is content that imports another resource into the document, or content from another vocabulary that is inserted into the document.
Elements that are from namespaces other than the HTML namespace and that convey content but not metadata, are embedded content for the purposes of the content models defined in this specification. (For example, MathML or SVG.)
Some embedded content elements can have fallback content: 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.
Interactive content is content that is specifically intended for user interaction.
a (if the href attribute is present)audio (if the controls attribute is present)buttondetailsembediframeimg (if the usemap attribute is present)input (if the type attribute is not in the state)labelselecttextareavideo (if the controls attribute is present)As a general rule, elements whose content model allows any flow content or phrasing content should have at least one node in its contents that is palpable content and that does not have the attribute specified.
Palpable content makes an element non-empty by providing either
some descendant non-empty text, or else something users can
hear (audio elements) or view (video, img, or
canvas elements) or otherwise interact with (for example, interactive form
controls).
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.
Conformance checkers are encouraged to provide a mechanism for authors to find elements that fail to fulfill this requirement, as an authoring aid.
The following elements are palpable content:
aabbraddressarticleasideaudio (if the controls attribute is present)bbdibdoblockquotebuttoncanvascitecodedatadeldetailsdfndivdl (if the element's children include at least one name-value group)emembedfieldsetfigurefooterformh1h2h3h4h5h6headerhgroupiiframeimginput (if the type attribute is not in the state)inskbdlabelmainmapmarkmathmenu (if the element's children include at least one li element)meternavobjectol (if the element's children include at least one li element)outputppicturepreprogressqrubyssampsearchsectionselectsmallspanstrongsubsupsvgtabletextareatimeuul (if the element's children include at least one li element)varvideoScript-supporting elements are those that do not represent anything themselves (i.e. they are not rendered), but are used to support scripts, e.g. to provide functionality for the user.
The following elements are script-supporting elements:
select element inner content elementsselect element inner content elements are the elements which are
allowed as descendants of select elements.
The following are select element inner content elements:
optgroup element inner content elementsoptgroup element inner content elements are the elements which are
allowed as descendants of optgroup elements.
The following are optgroup element inner content elements:
option element inner content elementsoption element inner content elements are the elements which are
allowed as descendants of option elements.
The following are option element inner content elements:
divThe following are excluded from option element inner content
elements:
datalistobjecttabindex attribute specifiedSome elements are described as transparent; they have "transparent" in the description of their content model. The content model of a transparent 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.
For instance, an ins element inside a ruby element cannot contain an
rt element, because the part of the ruby element's content model that
allows ins elements is the part that allows phrasing content, and the
rt element is not phrasing content.
In some cases, where transparent elements are nested in each other, the process has to be applied iteratively.
Consider the following markup fragment:
< p >< object >< ins >< map >< a href = "/" > Apples</ a ></ map ></ ins ></ object ></ p > To check whether "Apples" is allowed inside the a element, the content models are
examined. The a element's content model is transparent, as is the map
element's, as is the ins element's, as is the object element's. The
object element is found in the p element, whose content model is
phrasing content. Thus, "Apples" is allowed, as text is phrasing content.
When a transparent element has no parent, then the part of its content model that is "transparent" must instead be treated as accepting any flow content.
The term paragraph as defined in this section is used for more than
just the definition of the p element. The paragraph concept defined here
is used to describe how to interpret documents. The p element is merely one of
several ways of marking up a paragraph.
A paragraph is typically a run of phrasing content 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.
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 inter-element whitespace do not form paragraphs.
< 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 > Paragraphs in flow content are defined relative to what the document looks like
without the a, ins, del, and map elements
complicating matters, since those elements, with their hybrid content models, can straddle
paragraph boundaries, as shown in the first two examples below.
Generally, having elements straddle paragraph boundaries is best avoided. Maintaining such markup can be difficult.
The following example takes the markup from the earlier example and puts ins and
del 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 ins and del elements
— the ins element straddles the heading and the first paragraph, and the
del element straddles the boundary between the two paragraphs.
< 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 > Let view be a view of the DOM that replaces all a,
ins, del, and map elements in the document with their contents. Then, in view, for each run
of sibling phrasing content nodes uninterrupted by other types of content, in an
element that accepts content other than phrasing content as well as phrasing
content, let first be the first node of the run, and let last be the last node of the run. For each such run that consists of at least one
node that is neither embedded content nor inter-element whitespace, a
paragraph exists in the original DOM from immediately before first to
immediately after last. (Paragraphs can thus span across a,
ins, del, and map elements.)
Conformance checkers may warn authors of cases where they have paragraphs that overlap each
other (this can happen with object, video, audio, and
canvas elements, and indirectly through elements in other namespaces that allow HTML
to be further embedded therein, like SVG svg or MathML
math).
A paragraph is also formed explicitly by p elements.
The p 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.
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.
< 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 > Here is another way of marking this up, this time showing the paragraphs explicitly, and splitting the one link element into three:
< 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 > It is possible for paragraphs to overlap when using certain elements that define fallback content. For example, in the following section:
< 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 > There are five paragraphs:
object element.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.
To avoid this confusion, explicit p elements can be used. For example:
< 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 > The following attributes are common to and may be specified on all HTML elements (even those not defined in this specification):
accesskeyautocapitalizeautocorrectautofocuscontenteditabledirdraggableenterkeyhintheadingoffsetheadingresetinertinputmodeisitemiditempropitemrefitemscopeitemtypelangnoncepopoverspellcheckstyletabindextitletranslatewritingsuggestionsThese attributes are only defined by this specification as attributes for HTML elements. 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.
For example, in the following XML fragment, the "bogus" element does not
have a dir attribute as defined in this specification, despite
having an attribute with the literal name "dir". Thus, the
directionality of the inner-most span element is 'rtl', inherited from the div element indirectly through
the "bogus" element.
< 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 > Support in all current engines.
DOM defines the user agent requirements for the class, id, and slot attributes for any element in any namespace.
[DOM]
The class, id, and slot attributes may be specified on all HTML elements.
When specified on HTML elements, the class
attribute must have a value that is a set of space-separated tokens representing the
various classes that the element belongs to.
Assigning classes to an element affects class matching in selectors in CSS, the getElementsByClassName() method in the DOM,
and other such features.
There are no additional restrictions on the tokens authors can use in the class 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.
When specified on HTML elements, the id attribute
value must be unique amongst all the IDs in the element's
tree and must contain at least one character. The value must not contain any
ASCII whitespace.
The id attribute specifies its element's unique identifier (ID).
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.
An element's unique identifier can be used for a variety of purposes, most notably as a way to link to specific parts of a document using fragments, as a way to target an element when scripting, and as a way to style a specific element from CSS.
Identifiers are opaque strings. Particular meanings should not be derived from the value of the
id attribute.
There are no conformance requirements for the slot attribute
specific to HTML elements.
The slot attribute is used to assign a
slot to an element: an element with a slot attribute is
assigned to the slot
created by the slot element whose name
attribute's value matches that slot attribute's value — but only
if that slot element finds itself in the shadow tree whose
root's host has the corresponding
slot attribute value.
To enable assistive technology products to expose a more fine-grained interface than is
otherwise possible with HTML elements and attributes, a set of annotations
for assistive technology products can be specified (the ARIA role and aria-* attributes).
[ARIA]
The following event handler content attributes may be specified on any HTML element:
onauxclickonbeforeinputonbeforematchonbeforetoggleonblur*oncanceloncanplayoncanplaythroughonchangeonclickoncloseoncommandoncontextlostoncontextmenuoncontextrestoredoncopyoncuechangeoncutondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerror*onfocus*onformdataoninputoninvalidonkeydownonkeypressonkeyuponload*onloadeddataonloadedmetadataonloadstartonmousedownonmouseenteronmouseleaveonmousemoveonmouseoutonmouseoveronmouseuponpasteonpauseonplayonplayingonprogressonratechangeonresetonresize*onscroll*onscrollend*onsecuritypolicyviolationonseekedonseekingonselectonslotchangeonstalledonsubmitonsuspendontimeupdateontoggleonvolumechangeonwaitingonwheelThe attributes marked with an asterisk have a different meaning when specified on
body elements as those elements expose event handlers of the
Window object with the same names.
While these attributes apply to all elements, they are not useful on all elements.
For example, only media elements will ever receive a volumechange event fired by the user agent.
Custom data attributes (e.g. data-foldername or data-msgid) can be specified on any
HTML element, to store custom data, state, annotations, and
similar, specific to the page.
In HTML documents, elements in the HTML namespace may have an xmlns attribute specified, if, and only if, it has the exact value "http://www.w3.org/1999/xhtml". This does not apply to XML
documents.
In HTML, the xmlns 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 HTML parser, the attribute ends up in no namespace. In XML, the
attribute is part of the namespace declaration mechanism and always ends up in the "http://www.w3.org/2000/xmlns/" namespace.
XML also allows the use of the xml:space
attribute in the XML namespace on any element in an XML
document. This attribute has no effect on HTML elements, as the default
behavior in HTML is to preserve whitespace. [XML]
There is no way to serialize the xml:space
attribute on HTML elements in the text/html syntax.
title attributeSupport in all current engines.
The title attribute
represents 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
interactive content, it could be a label for, or instructions for, use of the
element; and so forth. The value is text.
Relying on the title 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).
If this attribute is omitted from an element, then it implies that the title attribute of the nearest ancestor HTML element with a title 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.
If the title 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.
Caution is advised with respect to the use of newlines in title attributes.
For instance, the following snippet actually defines an abbreviation's expansion with a line break in it:
< p > My logs show that there was some interest in < abbr title = "Hypertext
Transport Protocol" > HTTP</ abbr > today.</ p > Some elements, such as link, abbr, and input, define
additional semantics for the title attribute beyond the semantics
described above.
The advisory information 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.
If the element has a title attribute, then return the
result of running normalize newlines on its value.
If the element has a parent element, then return the parent element's advisory information.
Return the empty string.
User agents should inform the user when elements have advisory information, otherwise the information would not be discoverable.
lang and xml:lang
attributesSupport in all current engines.
The lang 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. [BCP47]
The lang attribute in the XML namespace is defined in XML.
[XML]
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 slot elements in a
shadow tree).
The lang attribute in no namespace may be used on any HTML element.
The lang attribute in the XML
namespace may be used on HTML elements in XML documents,
as well as elements in other namespaces if the relevant specifications allow it (in particular,
MathML and SVG allow lang attributes in the
XML namespace to be specified on their elements). If both the lang attribute in no namespace and the lang attribute in the XML namespace are specified on the same
element, they must have exactly the same value when compared in an ASCII
case-insensitive manner.
Authors must not use the lang attribute in
the XML namespace on HTML elements in HTML
documents. To ease migration to and from XML, authors may specify an attribute in no
namespace with no prefix and with the literal localname "xml:lang" on
HTML elements in HTML documents, but such attributes must only be
specified if a lang attribute in no namespace is also specified,
and both attributes must have the same value when compared in an ASCII
case-insensitive manner.
The attribute in no namespace with no prefix and with the literal localname "xml:lang" has no effect on language processing.
To determine the language of a node, user agents must use the first appropriate step in the following list:
lang
attribute in the XML namespace setUse the value of that attribute.
lang in no namespace
attribute setUse the value of that attribute.
Use the language of that shadow root's host.
Use the language of that parent element.
If there is a pragma-set default language set, then that is the language of the node. If there is no pragma-set default language 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.
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. [BCP47]
Thus, for instance, an element with lang="xyzzy" would be
matched by the selector :lang(xyzzy) (e.g. in CSS), but it would not be
matched by :lang(abcde), 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 incorrect 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).
If the resulting value is the empty string, then it must be interpreted as meaning that the language of the node is explicitly unknown.
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).
translate attributeSupport in all current engines.
The translate
attribute is used to specify whether an element's attribute values and the values of its
Text node children are to be translated when the page is localized, or whether to
leave them unchanged. It is an enumerated attribute with the
following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
yes
| Yes | Sets translation mode to translate-enabled. |
no
| No | Sets translation mode to no-translate. |
The attribute's missing value default and invalid value default are both the Inherit state, and its empty value default is the Yes state.
Each element (even non-HTML elements) has a translation mode, which is in either the
translate-enabled state or the no-translate state. If an HTML element's translate
attribute is in the Yes state, then the element's
translation mode is in the translate-enabled state; otherwise, if the
element's translate attribute is in the No state, then the element's translation mode
is in the no-translate state. Otherwise, either the element's translate attribute is in the Inherit state, or the element is not an HTML element and thus does not have a translate attribute; in either case, the element's
translation mode is in the same state as its parent element's, if any,
or in the translate-enabled state, if the element's parent element is
null.
When an element is in the translate-enabled state, the element's translatable
attributes and the values of its Text node children are to be translated when
the page is localized.
When an element is in the no-translate state, the element's attribute values and the
values of its Text 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.
The following attributes are translatable attributes:
abbr on th elementsalt on area,
img, and
input elementscontent on meta elements, if the name attribute specifies a metadata name whose value is known to be translatabledownload on a and
area elementslabel on optgroup,
option, and
track elementslang on HTML elements; must be "translated" to match the language used in the translationplaceholder on input and
textarea elementssrcdoc on iframe elements; must be parsed and recursively processedstyle on HTML elements; must be parsed and
recursively processed (e.g. for the values of 'content' properties)title on all HTML elementsvalue on input elements with a
type attribute in the Button state
or the Reset Button stateOther specifications may define other attributes that are also translatable
attributes. For example, ARIA would define the aria-label attribute as translatable.
The translate IDL
attribute must, on getting, return true if the element's translation mode is
translate-enabled, and false otherwise. On setting, it must set the content
attribute's value to "yes" if the new value is true, and set the content
attribute's value to "no" otherwise.
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:
<!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 translate = no > eat honey</ kbd > . The game will respond with:</ p >
< pre >< samp translate = no > Yum yum! That was some good honey!</ samp ></ pre >
</ body >
</ html > dir attributeSupport in all current engines.
The dir attribute
is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
ltr
| LTR | The contents of the element are explicitly directionally isolated left-to-right text. |
rtl
| RTL | The contents of the element are explicitly directionally isolated right-to-left text. |
auto
| Auto | 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). |
The heuristic used by the Auto 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. [BIDI]
For textarea and pre elements, the heuristic is applied on a
per-paragraph level.
The attribute's missing value default and invalid value default are both the Undefined state.
The directionality of an element (any element, not just
an HTML element) is either 'ltr' or 'rtl'. To compute the directionality given an element element, switch on
element's dir attribute state:
Return 'ltr'.
Return 'rtl'.
Let result be the auto directionality of element.
If result is null, then return 'ltr'.
Return result.
bdi elementLet result be the auto directionality of element.
If result is null, then return 'ltr'.
Return result.
input element whose type attribute is in the Telephone stateReturn 'ltr'.
Return the parent directionality of element.
Since the dir attribute is only defined for
HTML elements, it cannot be present on elements from other namespaces. Thus, elements
from other namespaces always end up using the parent directionality.
The auto-directionality form-associated elements are:
To compute the auto directionality given an element element:
If element is an auto-directionality form-associated element:
If element is a slot element whose root is a
shadow root and element's assigned nodes are not empty:
For each node child of element's assigned nodes:
Let childDirection be null.
If child is a Text node, then set childDirection to
the text node directionality of child.
Otherwise:
Set childDirection to the contained text auto directionality of child with canExcludeRoot set to true.
If childDirection is not null, then return childDirection.
Return null.
Return the contained text auto directionality of element with canExcludeRoot set to false.
To compute the contained text auto directionality of an element element with a boolean canExcludeRoot:
For each node descendant of element's descendants, in tree order:
If any of
is one of
bdi elementscript elementstyle elementtextarea elementdir attribute is not in the Undefined statethen continue.
If descendant is a slot element whose root is a
shadow root, then return the directionality of that shadow root's host.
Let result be the text node directionality of descendant.
If result is not null, then return result.
Return null.
To compute the text node directionality given a Text node
text:
If text's data does not contain a code point whose bidirectional character type is L, AL, or R, then return null. [BIDI]
Let codePoint be the first code point in text's data whose bidirectional character type is L, AL, or R.
If codePoint is of bidirectional character type AL or R, then return 'rtl'.
If codePoint is of bidirectional character type L, then return 'ltr'.
To compute the parent directionality given an element element:
Let parentNode be element's parent node.
If parentNode is a shadow root, then return the directionality of parentNode's host.
If parentNode is an element, then return the directionality of parentNode.
Return 'ltr'.
This attribute has rendering requirements involving the bidirectional algorithm.
The directionality of an attribute of an HTML element, 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:
dir attribute is in the Auto
stateFind the first character (in logical order) of the attribute's value that is of bidirectional character type L, AL, or R. [BIDI]
If such a character is found and it is of bidirectional character type AL or R, the directionality of the attribute is 'rtl'.
Otherwise, the directionality of the attribute is 'ltr'.
The following attributes are directionality-capable attributes:
abbr on th elementsalt on area,
img, and
input elementscontent on meta elements, if the name attribute specifies a metadata name whose value is primarily intended to be human-readable rather than machine-readablelabel on optgroup,
option, and
track elementsplaceholder on input and
textarea elementstitle on all HTML elementsdocument.dir [ = value ]Returns the html element's dir
attribute's value, if any.
Can be set, to either "ltr", "rtl", or "auto" to replace the html element's dir attribute's value.
If there is no html element, returns the
empty string and ignores new values.
Support in all current engines.
The dir IDL attribute on
an element must reflect the dir content attribute of
that element, limited to only known values.
Support in all current engines.
The dir IDL
attribute on Document objects must reflect the dir content attribute of the html element, if
any, limited to only known values. If there is no such element, then the attribute
must return the empty string and do nothing on setting.
Authors are strongly encouraged to use the dir
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).
This markup fragment is of an IM conversation.
< 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 > Given a suitable style sheet and the default alignment styles for the p element,
namely to align the text to the start edge of the paragraph, the resulting rendering could
be as follows:
As noted earlier, the auto 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.
style attributeSupport in all current engines.
All HTML elements may have the style content attribute set. This is a style attribute as defined by CSS Style
Attributes. [CSSATTR]
In user agents that support CSS, the attribute's value must be parsed when the attribute is added or has its value changed, according to the rules given for style attributes. [CSSATTR]
However, if the Should element's inline behavior be blocked by Content Security
Policy? algorithm returns "Blocked" when executed upon the
attribute's element, "style attribute", and the attribute's
value, then the style rules defined in the attribute's value must not be applied to the
element. [CSP]
Documents that use style attributes on any of their elements
must still be comprehensible and usable if those attributes were removed.
In particular, using the style 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
attribute.)
element.styleReturns a CSSStyleDeclaration object for the element's style attribute.
The style IDL attribute is defined in CSS Object
Model. [CSSOM]
In the following example, the words that refer to colors are marked up using the
span element and the style attribute to make those
words show up in the relevant colors in visual media.
< 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 > data-* attributesSupport in all current engines.
A custom data attribute is an attribute in no namespace whose name starts with the
string "data-", has at least one character after the
hyphen, is a valid attribute local name, and contains no ASCII upper alphas.
All attribute names on HTML elements in HTML documents get ASCII-lowercased automatically, so the restriction on ASCII uppercase letters doesn't affect such documents.
Custom data attributes 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.
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 microdata should be used (with a standardized vocabulary).
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.
< ol >
< li data-length = "2m11s" > Beyond The Sea</ li >
...
</ ol > 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.
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.
Similarly, a page author could write markup that provides information for a translation tool that they are intending to use:
< p > The third < span data-mytrans-de = "Anspruch" > claim</ span > covers the case of < span
translate = "no" > HTML</ span > markup.</ p > In this example, the "data-mytrans-de" attribute gives specific text
for the MyTrans product to use when translating the phrase "claim" to German. However, the
standard translate 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 custom data attribute to be used.
In this example, custom data attributes are used to store the result of a feature detection
for PaymentRequest, which could be used in CSS to style a checkout page
differently.
< script >
if ( 'PaymentRequest' in window) {
document. documentElement. dataset. hasPaymentRequest = '' ;
}
</ script > Here, the data-has-payment-request attribute is effectively being used
as a boolean attribute; 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.
Every HTML element may have any number of custom data attributes specified, with any value.
Authors should carefully design such extensions so that when the attributes are ignored and any associated CSS dropped, the page is still usable.
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.
JavaScript libraries may use the custom data attributes, 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.
For example, a library called "DoQuery" could use attribute names like data-doquery-range, and a library called "jJo" could use attributes names like
data-jjo-range. The jJo library could also provide an API to set which
prefix to use (e.g. J.setDataPrefix('j2'), making the attributes have names
like data-j2-range).
element.datasetSupport in all current engines.
Support in all current engines.
Returns a DOMStringMap object for the element's data-* attributes.
Hyphenated names become camel-cased. For example, data-foo-bar=""
becomes element.dataset.fooBar.
The dataset IDL
attribute provides convenient accessors for all the data-*
attributes on an element. On getting, the dataset IDL attribute
must return a DOMStringMap whose associated element is this element.
The DOMStringMap interface is used for the dataset attribute. Each DOMStringMap has an associated element.
[Exposed =Window ,
LegacyOverrideBuiltIns ]
interface DOMStringMap {
getter DOMString (DOMString name );
[CEReactions ] setter undefined (DOMString name , DOMString value );
[CEReactions ] deleter undefined (DOMString name );
};To get a DOMStringMap's name-value
pairs, run the following algorithm:
Let list be an empty list of name-value pairs.
For each content attribute on the DOMStringMap's associated element whose first five characters are
the string "data-" and whose remaining characters (if any) do not include
any ASCII upper alphas, in the order that those
attributes are listed in the element's attribute list, add a name-value pair to
list whose name is the attribute's name with the first five characters removed and
whose value is the attribute's value.
For each name in list, for each U+002D HYPHEN-MINUS character (-) in the name that is followed by an ASCII lower alpha, remove the U+002D HYPHEN-MINUS character (-) and replace the character that followed it by the same character converted to ASCII uppercase.
Return list.
The supported property names on a DOMStringMap object at any instant
are the names of each pair returned from getting the
DOMStringMap's name-value pairs at that instant, in the order returned.
To determine the value of a named property
name for a DOMStringMap, return the value component of the name-value pair
whose name component is name in the list returned from getting the DOMStringMap's name-value
pairs.
To set the value of a new named property or
set the value of an existing named property for a DOMStringMap, given a
property name name and a new value value, run the following steps:
If name contains a U+002D HYPHEN-MINUS character (-) followed by an ASCII
lower alpha, then throw a "SyntaxError"
DOMException.
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
Insert the string data- at the front of name.
If name is not a valid attribute local name, then throw an
"InvalidCharacterError" DOMException.
Set an attribute value for the
DOMStringMap's associated element
using name and value.
To delete an existing named property
name for a DOMStringMap, run the following steps:
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
Insert the string data- at the front of name.
Remove an attribute by name given
name and the DOMStringMap's associated element.
This algorithm will only get invoked by Web IDL for names that
are given by the earlier algorithm for getting the
DOMStringMap's name-value pairs. [WEBIDL]
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 class attribute along with data-* attributes:
< 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 > Notice how the hyphenated attribute name becomes camel-cased in the API.
Given the following fragment and elements with similar constructions:
< 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" > ...one could imagine a function splashDamage() that takes some arguments, the first
of which is the element to process:
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
}
} innerText and outerText propertiesSupport in all current engines.
element.innerText [ = value ]Returns the element's text content "as rendered".
Can be set, to replace the element's children with the given value, but with line breaks
converted to br elements.
element.outerText [ = value ]Returns the element's text content "as rendered".
Can be set, to replace the element with the given value, but with line breaks converted to
br elements.
The get the text steps, given an HTMLElement element, are:
If element is not being rendered or if the user agent is a non-CSS user agent, then return element's descendant text content.
This step can produce surprising results, as when the innerText getter is invoked on an element not being
rendered, its text contents are returned, but when accessed on an element that is
being rendered, all of its children that are not being rendered have
their text contents ignored.
Let results be a new empty list.
For each child node node of element:
Let current be the list resulting in running the rendered text collection steps with node. Each item in results will either be a string or a positive integer (a required line break count).
Intuitively, a required line break count 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 required line break count items, reminiscent to CSS margin-collapsing.
For each item item in current, append item to results.
Remove any items from results that are the empty string.
Remove any runs of consecutive required line break count items at the start or end of results.
Replace each remaining run of consecutive required line break count items with a string consisting of as many U+000A LF code points as the maximum of the values in the required line break count items.
Return the concatenation of the string items in results.
Support in all current engines.
The innerText and
outerText getter steps
are to return the result of running get the text steps with this.
The rendered text collection steps, given a node node, are as follows:
Let items be the result of running the rendered text collection steps with each child node of node in tree order, and then concatenating the results to a single list.
If node's computed value of 'visibility' is not 'visible', then return items.
If node is not being rendered, then return items. For the purpose of this step, the following elements must act as described if the computed value of the 'display' property is not 'none':
select elements have an associated non-replaced inline CSS box
whose child boxes include only those of optgroup and option element
descendant nodes;
optgroup elements have an associated non-replaced block-level CSS
box whose child boxes include only those of option element descendant
nodes; and
option elements have an associated non-replaced block-level CSS
box whose child boxes are as normal for non-replaced block-level CSS boxes.
items can be non-empty due to 'display:contents'.
If node is a Text node, then for each CSS text box produced by
node, in content order, compute the text of the box after application of the CSS
'white-space' processing rules and 'text-transform' rules, set
items to the list of the resulting strings, and return items.
The CSS 'white-space' 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 br element. Soft hyphens should be preserved.
[CSSTEXT]
If node is a br element, then append a string containing a single U+000A LF code point to
items.
If node's computed value of 'display' is 'table-cell', and node's CSS box is not the last 'table-cell' box of its enclosing 'table-row' box, then append a string containing a single U+0009 TAB code point to items.
If node's computed value of 'display' is 'table-row', and node's CSS box is not the last 'table-row' box of the nearest ancestor 'table' box, then append a string containing a single U+000A LF code point to items.
If node is a p element, then append 2 (a required line break count) at the beginning and end of
items.
If node's used value of 'display' is block-level or 'table-caption', then append 1 (a required line break count) at the beginning and end of items. [CSSDISPLAY]
Floats and absolutely-positioned elements fall into this category.
Return items.
Note that descendant nodes of most replaced elements (e.g., textarea,
input, and video — but not button) are not rendered
by CSS, strictly speaking, and therefore have no CSS boxes for the
purposes of this algorithm.
This algorithm is amenable to being generalized to work on ranges. Then we can use it as the basis for Selection's
stringifier and maybe expose it directly on ranges. See Bugzilla bug 10583.
The set the inner text steps, given an HTMLElement element, and a string value are:
Let fragment be the rendered text fragment for value given element's node document.
Replace all with fragment within element.
The innerText setter steps are to run set the inner
text steps.
The outerText setter steps are:
If this's parent is null, then throw a
"NoModificationAllowedError" DOMException.
Let next be this's next sibling.
Let previous be this's previous sibling.
Let fragment be the rendered text fragment for the given value given this's node document.
If fragment has no children, then
append a new Text node whose data is the empty string and node document is
this's node document to fragment.
If next is non-null and next's previous sibling is a
Text node, then merge with the next text node given next's
previous sibling.
If previous is a Text node, then merge with the next text
node given previous.
The rendered text fragment for a string input given a
Document document is the result of running the following steps:
Let fragment be a new DocumentFragment whose node
document is document.
Let position be a position variable for input, initially pointing at the start of input.
Let text be the empty string.
While position is not past the end of input:
Collect a sequence of code points that are not U+000A LF or U+000D CR from input given position, and set text to the result.
If text is not the empty string, then append a new Text node whose data is text and node document is
document to fragment.
While position is not past the end of input, and the code point at position is either U+000A LF or U+000D CR:
If the code point at position is U+000D CR and the next code point is U+000A LF, then advance position to the next code point in input.
Advance position to the next code point in input.
Append the result of creating an element given document, "br",
and the HTML namespace to fragment.
Return fragment.
To merge with the next text node given a Text node node:
Let next be node's next sibling.
If next is not a Text node, then return.
Replace data with node, node's data's length, 0, and next's data.
Remove next.
Text content in HTML elements with Text nodes in their
contents, and text in attributes of HTML
elements 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). [BIDI]
Authors are encouraged to use the dir attribute, the
bdo element, and the bdi element, rather than maintaining the
bidirectional-algorithm formatting characters manually. The bidirectional-algorithm formatting
characters interact poorly with CSS.
User agents must implement the Unicode bidirectional algorithm to determine the proper ordering of characters when rendering documents and parts of documents. [BIDI]
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 'unicode-bidi', 'direction', and 'content' properties, and must have, in its user agent style sheet, the rules using those properties given in this specification's rendering 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. [CSSGC]
The following elements and attributes have requirements defined by the rendering section that, due to the requirements in this section, are requirements on all user agents (not just those that support the suggested default rendering):
User agent requirements for implementing Accessibility API semantics on HTML elements are defined in HTML Accessibility API Mappings. In addition to the rules there, for a custom element element, the default ARIA role semantics are determined as follows: [HTMLAAM]
Let map be element's internal content attribute map.
If map["role"] exists,
then return it.
Return no role.
Similarly, for a custom element element, the default ARIA state and property semantics, for a state or property named stateOrProperty, are determined as follows:
If element's attached internals is non-null:
If element's attached internals's get the stateOrProperty-associated element exists, then return the result of running it.
If element's attached internals's get the stateOrProperty-associated elements exists, then return the result of running it.
If element's internal content attribute map[stateOrProperty] exists, then return it.
Return the default value for stateOrProperty.
The "default semantics" referred to here are sometimes also called "native", "implicit", or "host language" semantics in ARIA. [ARIA]
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 a element change as the href attribute is added or removed.
For an example of this in action, see the custom elements section.
Conformance checker requirements for checking use of ARIA role and aria-* attributes on
HTML elements are defined in ARIA in HTML. [ARIAHTML]
html elementSupport in all current engines.
Support in all current engines.
head element followed by a body element.html element's start tag can be omitted
if the first thing inside the html element is not a comment.html element's end tag can be omitted if
the html element is not immediately followed by a comment.[Exposed =Window ]
interface HTMLHtmlElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The html element represents the root of an HTML document.
Authors are encouraged to specify a lang attribute on the root
html 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.
The html element in the following example declares that the document's language
is English.
<!DOCTYPE html>
< html lang = "en" >
< 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 >
</ html > head elementSupport in all current engines.
Support in all current engines.
html element.iframe srcdoc document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title element and no more than one is a base element.title element and no more than one is a base element.head element's start tag can be omitted if
the element is empty, or if the first thing inside the head element is an
element.head element's end tag can be omitted if
the head element is not immediately followed by ASCII whitespace or a
comment.[Exposed =Window ]
interface HTMLHeadElement : HTMLElement {
[HTMLConstructor ] constructor ();
};The head element represents a collection of metadata for the
Document.
The collection of metadata in a head element can be large or small. Here is an
example of a very short one:
<!doctype html>
< html lang = en >
< head >
< title > A document with a short head</ title >
</ head >
< body >
...Here is an example of a longer one:
<!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 >
...The title 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 title element can be omitted.
title elementSupport in all current engines.
Support in all current engines.
head element containing no other title elements.[Exposed =Window ]
interface HTMLTitleElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString text ;
};The title element represents 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.
There must be no more than one title element per document.
If it's reasonable for the Document to have no title, then the
title element is probably not required. See the head element's content
model for a description of when the element is required.
title.text [ = value ]Returns the child text content of the element.
Can be set, to replace the element's children with the given value.
The text
attribute's getter must return this title element's child text
content.
The text attribute's setter must string replace
all with the given value within this title element.
Here are some examples of appropriate titles, contrasted with the top-level headings that might be used on those same pages.
< 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...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:
< title > Dances used during bee mating rituals</ title >
...
< h1 > The Dances</ h1 > The string to use as the document's title is given by the document.title IDL attribute.
User agents should use the document's title when referring to the document in their user
interface. When the contents of a title element are used in this way, the
directionality of that title element should be used to set the directionality
of the document's title in the user interface.
base elementSupport in all current engines.
Support in all current engines.
head element containing no other base elements.href — Document base URL
target — Default navigable for hyperlink navigation and form submission
[Exposed =Window ]
interface HTMLBaseElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectSetter ] attribute USVString href ;
[CEReactions , Reflect ] attribute DOMString target ;
};The base element allows authors to specify the document base URL for
the purposes of parsing URLs, and the name of the default
navigable for the purposes of following hyperlinks. The element does not
represent any content beyond this information.
There must be no more than one base element per document.
A base element must have either an href
attribute, a target attribute, or both.
The href content
attribute, if specified, must contain a valid URL potentially surrounded by
spaces.
A base element, if it has an href attribute,
must come before any other elements in the tree that have attributes defined as taking URLs.
If there are multiple base elements with href attributes, all but the first are ignored.
The target attribute,
if specified, must contain a valid navigable target name or keyword, which specifies
which navigable is to be used as the default when hyperlinks and forms in the
Document cause navigation.
A base element, if it has a target
attribute, must come before any elements in the tree that represent hyperlinks.
If there are multiple base elements with target attributes, all but the first are ignored.
To get an element's target, given an a, area, or
form element element, and an optional string-or-null target
(default null), run these steps:
If target is null, then:
If element has a target attribute, then set
target to that attribute's value.
Otherwise, if element's node document contains a
base element with a target attribute, set
target to the value of the target attribute
of the first such base element.
If target is not null, and contains an ASCII tab or newline and a
U+003C (<), then set target to "_blank".
Return target.
A base element that is the first base element with an href content attribute in a document tree has a
frozen base URL. The frozen base URL must be immediately
set for an element whenever any of the following
situations occur:
The base element becomes the first base element in tree
order with an href content attribute in its
Document.
The base element is the first base element in tree
order with an href content attribute in its
Document, and its href content attribute is
changed.
To set the frozen base URL for an element element:
Let document be element's node document.
Let urlRecord be the result of parsing the
value of element's href content attribute with
document's fallback base URL, and document's character encoding. (Thus, the base
element isn't affected by itself.)
If any of the following are true:
urlRecord is failure;
urlRecord's scheme is "data" or "javascript"; or
running Is base allowed for Document? on urlRecord and
document returns "Blocked",
then set element's frozen base URL to document's fallback base URL and return.
Set element's frozen base URL to urlRecord.
Respond to base URL changes given document.
The href IDL
attribute, on getting, must return the result of running the following algorithm:
Let document be element's node document.
Let url be the value of the href
attribute of this element, if it has one, and the empty string otherwise.
Let urlRecord be the result of parsing
url with document's fallback base URL, and
document's character encoding.
(Thus, the base element isn't affected by other base elements or
itself.)
If urlRecord is failure, return url.
Return the serialization of urlRecord.
In this example, a base element is used to set the document base
URL:
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > This is an example for the < base> 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 > The link in the above example would be a link to "https://www.example.com/news/archives.html".
link elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
noscript element that is a child of a head element.href — Address of the hyperlink
crossorigin — How the element handles crossorigin requests
rel — Relationship between the document containing the hyperlink and the destination resource
media — Applicable media
integrity — Integrity metadata used in Subresource Integrity checks [SRI]
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
sizes — Sizes of the icons (for rel="icon")
imagesrcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc. (for rel="preload")
imagesizes — Image sizes for different page layouts (for rel="preload")
as — Potential destination for a preload request (for rel="preload" and rel="modulepreload")
blocking — Whether the element is potentially render-blocking
color — Color to use when customizing a site's icon (for rel="mask-icon")
disabled — Whether the link is disabled
fetchpriority — Sets the priority for fetches initiated by the element
title attribute has special semantics on this element: Title of the link; CSS style sheet set name
[Exposed =Window ]
interface HTMLLinkElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString href ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions , Reflect ] attribute DOMString rel ;
[CEReactions ] attribute DOMString as ;
[SameObject , PutForwards =value , Reflect="rel"] readonly attribute DOMTokenList relList ;
[CEReactions , Reflect ] attribute DOMString media ;
[CEReactions , Reflect ] attribute DOMString integrity ;
[CEReactions , Reflect ] attribute DOMString hreflang ;
[CEReactions , Reflect ] attribute DOMString type ;
[SameObject , PutForwards =value , Reflect ] readonly attribute DOMTokenList sizes ;
[CEReactions , Reflect ] attribute USVString imageSrcset ;
[CEReactions , Reflect ] attribute DOMString imageSizes ;
[CEReactions ] attribute DOMString referrerPolicy ;
[SameObject , PutForwards =value , Reflect ] readonly attribute DOMTokenList blocking ;
[CEReactions , Reflect ] attribute boolean disabled ;
[CEReactions ] attribute DOMString fetchPriority ;
// also has obsolete members
};
HTMLLinkElement includes LinkStyle ;The link element allows authors to link their document to other resources.
The address of the link(s) is given by the href attribute. If the href attribute is present, then its value must be a valid
non-empty URL potentially surrounded by spaces. One or both of the href or imagesrcset
attributes must be present.
If both the href and imagesrcset attributes are absent, then the element does not
define a link.
The types of link indicated (the relationships) are given by the value of the rel attribute, which, if present, must have a
value that is a unordered set of unique space-separated tokens. The allowed keywords and their meanings are defined in a later section. If the rel 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.
rel's
supported tokens are the keywords defined in
HTML link types which are allowed on link elements, impact
the processing model, and are supported by the user agent. The possible supported tokens are
alternate,
dns-prefetch,
expect,
icon,
manifest,
modulepreload,
next,
pingback,
preconnect,
prefetch,
preload,
search, and
stylesheet.
rel's supported
tokens must only include the tokens from this list that the user agent implements the
processing model for.
Theoretically a user agent could support the processing model for the canonical keyword — if it were a search engine that executed
JavaScript. But in practice that's quite unlikely. So in most cases, canonical ought not be included in rel's supported
tokens.
A link element must have either a rel
attribute or an itemprop attribute, but not both.
If a link element has an itemprop attribute,
or has a rel attribute that contains only keywords that are
body-ok, then the element is said to be allowed in the body. This means
that the element can be used where phrasing content is expected.
If the rel attribute is used, the element can
only sometimes be used in the body of the page. When used with the itemprop attribute, the element can be used both in the
head element and in the body of the page, subject to the constraints of
the microdata model.
Two categories of links can be created using the link element: links to external resources and hyperlinks. The link types section defines
whether a particular link type is an external resource or a hyperlink. One link
element can create multiple links (of which some might be external resource links and some might be hyperlinks); exactly which and how many links are created depends on the
keywords given in the rel attribute. User agents must process
the links on a per-link basis, not a per-element basis.
Each link created for a link element is handled separately. For
instance, if there are two link elements with rel="stylesheet",
they each count as a separate external resource, and each is affected by its own attributes
independently. Similarly, if a single link element has a rel attribute with the value next stylesheet,
it creates both a hyperlink (for the next keyword) and
an external resource link (for the stylesheet
keyword), and they are affected by other attributes (such as media or title)
differently.
For example, the following link element creates two hyperlinks (to the same page):
< link rel = "author license" href = "/about" > 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.
Hyperlinks created with the link element and its
rel attribute apply to the whole document. This contrasts with
the rel attribute of a and area
elements, which indicates the type of a link whose context is given by the link's location within
the document.
Unlike those created by a and area elements, hyperlinks created by link elements are not displayed as
part of the document by default, in user agents that support the suggested
default rendering. And even if they are force-displayed using CSS, they have no
activation behavior. 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 provide
its own UI for following such hyperlinks.
The exact behavior for links to external resources depends on the exact relationship, as defined for the relevant link type.
The crossorigin
attribute is a CORS settings attribute. It is intended for use with external resource links.
The media attribute
says which media the resource applies to. The value must be a valid media query
list.
Support in all current engines.
The integrity
attribute represents the integrity
metadata for requests which this element is responsible for. The value is text. The
attribute must only be specified on link elements that have a rel attribute that contains the stylesheet, preload, or modulepreload keyword. [SRI]
The hreflang
attribute on the link element has the same semantics as the hreflang attribute on the a
element.
The type attribute
gives the MIME type of the linked resource. It is purely advisory. The value must be
a valid MIME type string.
For external resource links, the type attribute is used as a hint to user agents so that they can
avoid fetching resources they do not support.
The referrerpolicy attribute is a referrer policy
attribute. It is intended for use with external
resource links, where it helps set the referrer policy used when fetching and processing the linked resource.
[REFERRERPOLICY]
The title 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 in a document tree, for which the title attribute defines CSS
style sheet sets.
The title attribute on link
elements differs from the global title 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.
The imagesrcset
attribute may be present, and is a srcset attribute.
The imagesrcset and href attributes (if width
descriptors are not used) together contribute the image
sources to the source set.
If the imagesrcset attribute is present and has any
image candidate strings using a width
descriptor, the imagesizes attribute must also be present, and is a
sizes attribute. The imagesizes attribute
contributes the source size to the source set.
The imagesrcset and imagesizes attributes must only be specified on
link elements that have both a rel attribute that
specifies the preload keyword, as well as an as attribute in the "image" state.
These attributes allow preloading the appropriate resource that is later used by an
img element that has the corresponding values for its srcset and sizes
attributes:
< 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" > Note how we omit the href attribute, as it would only
be relevant for browsers that do not support imagesrcset, and in those cases it would likely cause the
incorrect image to be preloaded.
The imagesrcset attribute can be combined with the
media attribute to preload the appropriate resource
selected from a picture element's sources, for art direction:
< 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 > The sizes attribute
gives the sizes of icons for visual media. Its value, if present, is merely advisory. User agents may use the value to decide which icon(s) to use if multiple icons are
available. If specified, the attribute must have a value that is an unordered set of
unique space-separated tokens which are ASCII case-insensitive. Each value
must be either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers 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 link elements
that have a rel attribute that specifies the icon keyword or the apple-touch-icon keyword.
The apple-touch-icon keyword is a registered extension to the predefined set of link types, but user
agents are not required to support it in any way.
The as attribute
specifies the potential destination for a
preload request for the resource given by the href attribute.
It is an enumerated attribute. Each potential destination is a keyword for this
attribute, mapping to a state of the same name. The attribute must be specified on
link elements that have a rel attribute that
contains the preload keyword. It may be specified on
link elements that have a rel attribute that
contains the modulepreload keyword; in such cases it must
have a value which is a script-like
destination. For other link elements, it must not be specified.
The processing model for how the as attribute is
used is given in an individual link type's fetch and process the linked resource
algorithm.
The attribute does not have a missing value
default or invalid value default, meaning that invalid
or missing values for the attribute map to no state. This is accounted for in the processing
model. For preload links, both conditions are an error; for
modulepreload links, a missing value will be treated as
"script".
The blocking
attribute is a blocking attribute. It is used by link types stylesheet and expect, and it must only be specified on link elements
that have a rel attribute containing those keywords.
The color attribute is
used with the mask-icon link type. The attribute must only be specified on
link elements that have a rel attribute that
contains the mask-icon keyword. The value must be a string that matches the
CSS <color> 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.
This specification does not have any user agent requirements for the color attribute.
The mask-icon keyword is a registered extension to the predefined set of link types, but user
agents are not required to support it in any way.
link elements have an associated explicitly enabled boolean. It is
initially false.
The disabled
attribute is a boolean attribute that is used with the stylesheet link type. The attribute must only be specified on
link elements that have a rel attribute that
contains the stylesheet keyword.
Whenever the disabled attribute is removed, set the
link element's explicitly enabled attribute to true.
Removing the disabled attribute dynamically, e.g.,
using document.querySelector("link").removeAttribute("disabled"), will
fetch and apply the style sheet:
< link disabled rel = "alternate stylesheet" href = "css/pooh" > The fetchpriority attribute is a fetch
priority attribute that is intended for use with external resource links, where it is used to set the priority used when fetching and processing the linked
resource.
There is no reflecting IDL attribute for the color attribute, but this might be added later.
Support in all current engines.
The as IDL
attribute must reflect the as content attribute,
limited to only known values.
The crossOrigin IDL attribute must reflect the
crossorigin content attribute, limited to only
known values.
HTMLLinkElement/referrerPolicy
Support in all current engines.
The referrerPolicy IDL attribute must
reflect the referrerpolicy content
attribute, limited to only known values.
The fetchPriority IDL attribute must
reflect the fetchpriority content
attribute, limited to only known values.
The relList attribute can be used for
feature detection, by calling its supports()
method to check which types of links are supported.
media attributeIf the link is a hyperlink then the media
attribute is purely advisory, and describes for which media the document in question was
designed.
However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must apply the
external resource when the media attribute's value
matches the environment and the other relevant conditions apply, and must not apply
it otherwise.
The default, if the media attribute is
omitted, is "all", meaning that by default links apply to all media.
The external resource might have further restrictions defined within that limit
its applicability. For example, a CSS style sheet might have some @media
blocks. This specification does not override such further restrictions or requirements.
type attributeIf the type attribute is present, then the user agent must
assume that the resource is of the given type (even if that is not a valid MIME type
string, e.g. the empty string). If the attribute is omitted, but the external
resource link 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 MIME type for the
given link relationship, then the UA should not fetch and process the linked
resource; if the UA does support the given MIME type for the given link
relationship, then the UA should fetch and process the linked resource at the
appropriate time as specified for the external resource link's particular type.
If the attribute is omitted, and the external resource link type does not have a
default type defined, but the user agent would fetch and process the linked resource
if the type was known and supported, then the user agent should fetch and process the linked
resource under the assumption that it will be supported.
User agents must not consider the type attribute
authoritative — upon fetching the resource, user agents must not use the type attribute to determine its actual type. Only the actual type
(as defined in the next paragraph) is used to determine whether to apply the resource,
not the aforementioned assumed type.
If the external resource link type defines rules for processing the resource's Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource's Content-Type metadata, and use the resulting computed type of the resource 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 Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.
The stylesheet link type defines rules for
processing the resource's Content-Type metadata.
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.
If a document contains style sheet links labeled as follows:
< link rel = "stylesheet" href = "A" type = "text/plain" >
< link rel = "stylesheet" href = "B" type = "text/css" >
< link rel = "stylesheet" href = "C" > ...then a compliant UA that supported only CSS style sheets would fetch the B and C files, and
skip the A file (since text/plain is not the MIME type for CSS style
sheets).
For files B and C, it would then check the actual types returned by the server. For those that
are sent as text/css, it would apply the styles, but for those labeled as
text/plain, or any other type, it would not.
If one of the two files was returned without a Content-Type metadata, or with a
syntactically incorrect type like Content-Type: "null", then the
default type for stylesheet links would kick in. Since that
default type is text/css, the style sheet would nonetheless be applied.
link elementAll external resource
links have a fetch and process the linked resource algorithm, which takes a
link element el. They also have linked resource fetch setup
steps which take a link element el and request request. Individual link types may provide
their own fetch and process the linked resource algorithm, but unless explicitly
stated, they use the default fetch and process the linked resource algorithm.
Similarly, individual link types may provide their own linked resource fetch setup
steps, but unless explicitly stated, these steps just return true.
The default fetch and process the linked resource, given a link element
el, is as follows:
Let options be the result of creating link options from el.
Let request be the result of creating a link request given options.
If request is null, then return.
Set request's synchronous flag.
Run the linked resource fetch setup steps, given el and request. If the result is false, then return.
Set request's initiator
type to "css" if el's rel attribute contains the keyword stylesheet; "link" otherwise.
Fetch request with processResponseConsumeBody set to the following steps given response response and null, failure, or a byte sequence bodyBytes:
Let success be true.
If any of the following are true:
then set success to false.
Note that content-specific errors, e.g., CSS parse errors or PNG decoding errors, do not affect success.
Otherwise, wait for the link resource's critical subresources to finish loading.
The specification that defines a link type's critical subresources (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 link resource's critical subresources to be fetched and processed, with the expectation that this will be done correctly.
Process the linked resource given el, success, response, and bodyBytes.
To create a link request given a link processing options options:
Let url be the result of encoding-parsing a URL given options's href, relative to options's base URL.
Passing the base URL instead of a document or environment is tracked by issue #9715.
If url is failure, then return null.
Let request be the result of creating a potential-CORS request given url, options's destination, and options's crossorigin.
Set request's policy container to options's policy container.
Set request's integrity metadata to options's integrity.
Set request's cryptographic nonce metadata to options's cryptographic nonce metadata.
Set request's referrer policy to options's referrer policy.
Set request's client to options's environment.
Set request's priority to options's fetch priority.
Return request.
User agents may opt to only try to fetch and process such resources when they are needed, instead of pro-actively fetching all the external resources that are not applied.
Similar to the fetch and process the linked resource algorithm, all external resource links have a process the linked
resource algorithm which takes a link element el, boolean
success, a response response, and a
byte sequence bodyBytes. Individual link types may provide their own
process the linked resource algorithm, but unless explicitly stated, that algorithm
does nothing.
Unless otherwise specified for a given rel keyword, the
element must delay the load event of the element's node document until
all the attempts to fetch and process the linked resource and its critical
subresources 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 delay the
load event.)
Link` headersAll link types that can be external resource
links define a process a link header algorithm, which takes a link
processing options. This algorithm defines whether and how they react to appearing in an
HTTP `Link` response header.
For most link types, this algorithm does nothing. The summary table is a good reference to quickly know whether a link type has defined process a link header steps.
A link processing options is a struct. It has the following items:
link")DocumentDocumentAuto)A link processing options has a base URL and an href rather than a parsed URL because the URL could be a result of the options's source set.
To create link options from element given a link element
el:
Let document be el's node document.
Let options be a new link processing options with
crossorigin
content attributereferrerpolicy
content attributefetchpriority
content attributeIf el has an href attribute, then set
options's href to the value of
el's href attribute.
If el has an integrity attribute,
then set options's integrity to the
value of el's integrity content
attribute.
If el has a type attribute, then set
options's type to the value of
el's type attribute.
Assert: options's href is not the empty string, or options's source set is not null.
A link element with neither an href or an
imagesrcset does not represent a link.
Return options.
To extract links from headers given a header list headers:
Let links be a new list.
Let rawLinkHeaders be the result of getting, decoding, and splitting
`Link` from headers.
For each linkHeader of rawLinkHeaders:
Return links.
To process link headers given a Document doc,
a response response, and a
"pre-media" or "media" phase:
Let links be the result of extracting links from response's header list.
For each linkObject in links:
Let rel be linkObject["relation_type"].
Let attribs be linkObject["target_attributes"].
Let expectedPhase be "media" if either "srcset", "imagesrcset", or "media" exist in
attribs; otherwise "pre-media".
If expectedPhase is not phase, then continue.
If attribs["media"] exists and attribs["media"]
does not match the environment, then
continue.
Let options be a new link processing options with
target_uri"]Apply link options from parsed header attributes to options given attribs and rel. If that returned false, then return.
If attribs["imagesrcset"] exists and attribs["imagesizes"] exists,
then set options's source set to the
result of creating a source set given
linkObject["target_uri"], attribs["imagesrcset"], attribs["imagesizes"], and null.
Run the process a link header steps for rel given options.
To apply link options from parsed header attributes to a link processing options options given attribs and a string rel:
If rel is "preload":
Let destination be the result of translating attribs["as"].
If destination is null, then return false.
Set options's destination to destination.
If attribs["crossorigin"] exists and is an ASCII case-insensitive match for one of
the CORS settings attribute keywords,
then set options's crossorigin to the
CORS settings attribute state corresponding to that keyword.
If attribs["integrity"] exists, then set options's integrity to attribs["integrity"].
If attribs["referrerpolicy"]
exists and is an ASCII case-insensitive match for
some referrer policy, then set options's referrer policy to that referrer policy.
If attribs["nonce"]
exists, then set options's nonce to attribs["nonce"].
If attribs["type"] exists, then set options's type to attribs["type"].
If attribs["fetchpriority"]
exists and is an ASCII case-insensitive match for
a fetch priority attribute keyword, then set options's fetch priority to that fetch priority
attribute keyword.
Return true.
Early hints 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 response with a 103 status code before serving the final response.[RFC8297]
For compatibility reasons early hints are typically delivered over HTTP/2 or above, but for readability we use HTTP/1.1-style notation below.
For example, given the following sequence of responses:
103 Early Hint Link: </image.png>; rel=preload; as=image
200 OK Content-Type: text/html <!DOCTYPE html> ... <img src="/image.png">
the image will start loading before the HTML content arrives.
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.
In addition to the `Link` headers, it is possible that the 103
response contains a Content Security Policy header, which is enforced when processing
the early hint.
For example, given the following sequence of responses:
103 Early Hint Content-Security-Policy: style-src: self; Link: </style.css>; rel=preload; as=style
103 Early Hint Link: </image.png>; rel=preload; as=image
302 Redirect Location: /alternate.html
200 OK Content-Security-Policy: style-src: none; Link: </font.ttf>; rel=preload; as=font
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 Content Security Policy header comes after the request to fetch the style has already been performed, but the style will not be accessible to the document.
To process early hint headers given a response response and an environment reservedEnvironment:
Early-hint `Link` headers are always processed
before `Link` headers from the final response, followed by link elements. This is
equivalent to prepending the contents of the early and final `Link` headers to the Document's head element,
in respective order.
Let earlyPolicyContainer be the result of creating a policy container from a fetch response given response and reservedEnvironment.
This allows the early hint response to include a Content Security Policy which would be enforced when fetching the early hint request.
Let links be the result of extracting links from response's header list.
Let earlyHints be an empty list.
For each linkObject in links:
The moment we receive the early hint link header, we begin fetching earlyRequest. If it comes back before the
Document is created, we set earlyResponse to the response of that fetch and
once the Document is created we commit it (by making it available in the map
of preloaded resources as if it was a link element). If the
Document is created first, the response is
committed as soon as it becomes available.
Let rel be linkObject["relation_type"].
Let options be a new link processing options with
target_uri"]early-hint"Let attribs be linkObject["target_attributes"].
Only the as, crossorigin, integrity, and type
attributes are handled as part of early hint processing. The other ones, in particular blocking, imagesrcset, imagesizes, and media are only applicable once a Document is
created.
Apply link options from parsed header attributes to options given attribs and rel. If that returned false, then return.
Run the process a link header steps for rel given options.
Append options to earlyHints.
Return the following substeps given Document doc: for each options in earlyHints:
If options's on document ready is null, then set options's document to doc.
Otherwise, call options's on document ready with doc.
link
elementInteractive user agents may provide users with a means to follow the hyperlinks created using the link element, somewhere
within their user interface. Such invocations of the follow
the hyperlink algorithm must set the userInvolvement argument to "browser UI". 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
hyperlink created with each link element in the document:
rel attribute)title
attribute).href
attribute).hreflang
attribute).media
attribute).User agents could also include other information, such as the type of the resource (as given by
the type attribute).
meta
elementSupport in all current engines.
Support in all current engines.
itemprop attribute is present: flow content.itemprop attribute is present: phrasing content.charset attribute is present, or if the element's http-equiv attribute is in the Encoding declaration state: in a head element.http-equiv attribute is present but not in the Encoding declaration state: in a head element.http-equiv attribute is present but not in the Encoding declaration state: in a noscript element that is a child of a head element.name attribute is present: where metadata content is expected.itemprop attribute is present: where metadata content is expected.itemprop attribute is present: where phrasing content is expected.name — Metadata name
http-equiv — Pragma directive
content — Value of the element
charset — Character encoding declaration
media — Applicable media
[Exposed =Window ]
interface HTMLMetaElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute DOMString name ;
[CEReactions , Reflect="http-equiv"] attribute DOMString httpEquiv ;
[CEReactions , Reflect ] attribute DOMString content ;
[CEReactions , Reflect ] attribute DOMString media ;
// also has obsolete members
};The meta element represents various kinds of metadata that cannot be
expressed using the title, base, link, style,
and script elements.
The meta element can represent document-level metadata with the name attribute, pragma directives with the http-equiv attribute, and the file's character encoding
declaration when an HTML document is serialized to string form (e.g. for transmission over
the network or for disk storage) with the charset
attribute.
Exactly one of the name, http-equiv, charset,
and itemprop attributes must be specified.
If either name, http-equiv, or itemprop is
specified, then the content attribute must also be
specified. Otherwise, it must be omitted.
The charset
attribute specifies the character encoding used by the document.
This is a character encoding declaration. If the attribute is present, its value must
be an ASCII case-insensitive match for the string "utf-8".
The charset attribute on the
meta element has no effect in XML documents, but is allowed in XML documents in order
to facilitate migration to and from XML.
There must not be more than one meta element with a charset attribute per document.
The content
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.
If a meta element has a name attribute, it sets document metadata. Document metadata
is expressed in terms of name-value pairs, the name attribute
on the meta element giving the name, and the content 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 meta element has no content attribute, then the value part of the metadata
name-value pair is the empty string.
The media attribute
says which media the metadata applies to. The value must be a valid media query list.
Unless the name is theme-color, the media
attribute has no effect on the processing model and must not be used by authors.
Support in all current engines.
This specification defines a few names for the name
attribute of the meta element.
Names are case-insensitive, and must be compared in an ASCII case-insensitive manner.
application-nameThe 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 application-name metadata name must not be used.
Translations of the web application's name may be given, using the lang attribute to specify the language of each name.
There must not be more than one meta element with a given language
and where the name attribute value is an
ASCII case-insensitive match for
application-name per document.
User agents may use the application name in UI in preference to the page's
title, 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.
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:
Let languages be the list of languages.
Let default language be the language of the
Document's document element, if any, and if that language is not
unknown.
If there is a default language, and if it is not the same language as any of the languages in languages, append it to languages.
Let winning language be the first language in languages for which
there is a meta element in the Document where the
name attribute value is an
ASCII case-insensitive match for
application-name and whose
language is the language in question.
If none of the languages have such a meta element, then return;
there's no given application name.
Return the value of the content attribute of the
first meta element in the Document in tree order where the
name attribute value is an
ASCII case-insensitive match for application-name
and whose language is winning language.
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.
authorThe value must be a free-form string giving the name of one of the page's authors.
descriptionThe 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 meta element where the name attribute value
is an ASCII case-insensitive match for
description per document.
generatorThe 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.
Here is what a tool called "Frontweaver" could include in its output, in the page's
head element, to identify itself as the tool used to generate the page:
< meta name = generator content = "Frontweaver 8.2" > keywordsThe value must be a set of comma-separated tokens, each of which is a keyword relevant to the page.
This page about typefaces on British motorways uses a meta element to specify
some keywords that users might use to look for the page:
<!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 >
...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.
To obtain the list of keywords that the author has specified as applicable to the page, the user agent must run the following steps:
Let keywords be an empty list.
For each meta element with a name
attribute and a content attribute and where the name attribute value is an ASCII case-insensitive
match for keywords:
Split the value of the element's content attribute on commas.
Add the resulting tokens, if any, to keywords.
Remove any duplicates from keywords.
Return keywords. This is the list of keywords that the author has specified as applicable to the page.
User agents should not use this information when there is insufficient confidence in the reliability of the value.
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.
referrerThe value must be a referrer policy, which defines the default referrer
policy for the Document. [REFERRERPOLICY]
If any meta element element is inserted into the document, or has its name or content
attributes changed, user agents must run the following algorithm:
If element is not in a document tree, then return.
If element does not have a name
attribute whose value is an ASCII case-insensitive match for "referrer", then return.
If element does not have a content
attribute, or that attribute's value is the empty string, then return.
Let value be the value of element's content attribute, converted to ASCII
lowercase.
If value is one of the values given in the first column of the following table, then set value to the value given in the second column:
| Legacy value | Referrer policy |
|---|---|
never
| no-referrer
|
default
| the default referrer policy |
always
| unsafe-url
|
origin-when-crossorigin
| origin-when-cross-origin
|
If value is a referrer policy, then set element's node document's policy container's referrer policy to policy.
For historical reasons, unlike other standard metadata names, the processing
model for referrer is not responsive to element removals,
and does not use tree order. Only the most-recently-inserted or
most-recently-modified meta element in this state has an effect.
theme-colorThe value must be a string that matches the CSS <color> 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.
Within an HTML document, the media attribute value must
be unique amongst all the meta elements with their name attribute value set to an ASCII
case-insensitive match for theme-color.
This standard itself uses "WHATWG green" as its theme color:
<!DOCTYPE HTML>
< title > HTML Standard</ title >
< meta name = "theme-color" content = "#3c790a" >
...The media attribute may be used to describe the context
in which the provided color should be used.
If we only wanted to use "WHATWG green" as this standard's theme color in dark mode,
we could use the prefers-color-scheme media feature:
<!DOCTYPE HTML>
< title > HTML Standard</ title >
< meta name = "theme-color" content = "#3c790a" media = "(prefers-color-scheme: dark)" >
...To obtain a page's theme color, user agents must run the following steps:
Let candidate elements be the list of all meta elements that
meet the following criteria, in tree order:
the element is in a document tree;
the element has a name attribute, whose value
is an ASCII case-insensitive match for theme-color; and
the element has a content attribute.
For each element in candidate elements:
If element has a media attribute
and the value of element's media
attribute does not match the environment, then
continue.
Let value be the result of stripping leading and trailing ASCII whitespace from the value of
element's content attribute.
Let color be the result of parsing value.
If color is not failure, then return color.
Return nothing (the page has no theme color).
If any meta elements are inserted into the document or removed from the document, or existing meta elements have their
name, content, or
media attributes changed, or if the environment changes
such that any meta element's media
attribute's value may now or may no longer match the
environment, user agents must re-run the above algorithm and apply the result to any
affected UI.
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.
color-schemeTo 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 'color-scheme' value can
be provided in a meta element.
The value must be a string that matches the syntax for the CSS 'color-scheme' property value. It determines the page's supported color-schemes.
There must not be more than one meta element with its name attribute value set to an
ASCII case-insensitive match for color-scheme per document.
The following declaration indicates that the page is aware of and can handle a color scheme with dark background colors and light foreground colors:
< meta name = "color-scheme" content = "dark" > To obtain a page's supported color-schemes, user agents must run the following steps:
Let candidate elements be the list of all meta elements that
meet the following criteria, in tree order:
the element is in a document tree;
the element has a name attribute, whose value
is an ASCII case-insensitive match for color-scheme; and
the element has a content attribute.
For each element in candidate elements:
content attribute.Return null.
If any meta elements are inserted into the document or removed from the document, or existing meta elements have their
name or content
attributes changed, user agents must re-run the above algorithm.
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.
Anyone can create and use their own extensions to the predefined set of metadata names. There is no requirement to register such extensions.
However, a new metadata name should not be created in any of the following cases:
If either the name is a URL, or the value of its accompanying content attribute is a URL; in those cases,
registering it as an extension to the predefined set of
link types is encouraged (rather than creating a new metadata name).
If the name is for something expected to have processing requirements in user agents; in that case it ought to be standardized.
Also, before creating and using a new metadata name, consulting the WHATWG Wiki MetaExtensions page 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. [WHATWGWIKI]
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:
The actual name being defined. The name should not be confusingly similar to any other defined name (e.g. differing only in case).
A short non-normative description of what the metadata name's meaning is, including the format the value is required to be in.
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.
One of the following:
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.
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.
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.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
When the http-equiv attribute is specified on a
meta element, the element is a pragma directive.
The http-equiv attribute is an enumerated
attribute with the following keywords and states:
| Keyword | Conforming | State | Brief description |
|---|---|---|---|
content-language
| No | Content language | Sets the pragma-set default language. |
content-type
| Encoding declaration | An alternative form of setting the charset.
| |
default-style
| Default style | Sets the name of the default CSS style sheet set. | |
refresh
| Refresh | Acts as a timed redirect. | |
set-cookie
| No | Set-Cookie | Has no effect. |
x-ua-compatible
| X-UA-Compatible | In practice, encourages Internet Explorer to more closely follow the specifications. | |
content-security-policy
| Content security policy | Enforces a Content Security
Policy on a Document.
|
When a meta element is inserted
into the document, if its http-equiv 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:
http-equiv="content-language")
This feature is non-conforming. Authors are encouraged to use the lang attribute instead.
This pragma sets the pragma-set default language. Until such a pragma is successfully processed, there is no pragma-set default language.
If the element's content attribute contains a
U+002C COMMA character (,), then return.
Let input be the value of the element's content attribute.
Let position point at the first character of input.
Skip ASCII whitespace within input given position.
Collect a sequence of code points that are not ASCII whitespace from input given position.
Let candidate be the string that resulted from the previous step.
If candidate is the empty string, return.
Set the pragma-set default language to candidate.
If the value consists of multiple space-separated tokens, tokens after the first are ignored.
This pragma is almost, but not quite, entirely unlike the HTTP `Content-Language` header of the same name.
[HTTP]
http-equiv="content-type")
The Encoding declaration state is
just an alternative form of setting the charset
attribute: it is a character encoding declaration. This state's user
agent requirements are all handled by the parsing section of the specification.
For meta elements with an http-equiv
attribute in the Encoding declaration
state, the content attribute must have a value
that is an ASCII case-insensitive match for a string that consists of:
"text/html;", optionally followed by any number of ASCII
whitespace, followed by "charset=utf-8".
A document must not contain both a meta element with an http-equiv attribute in the Encoding declaration state and a
meta element with the charset attribute
present.
The Encoding declaration state may be
used in HTML documents, but elements with an http-equiv attribute in that state must not be used in
XML documents.
http-equiv="default-style")
Support in one engine only.
This pragma sets the name of the default CSS style sheet set.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then return.
Change the preferred CSS style sheet set name with the name being the value
of the element's content attribute.
[CSSOM]
http-equiv="refresh")
This pragma acts as a timed redirect.
A Document object has an associated will declaratively
refresh (a boolean). It is initially false.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then return.
Let input be the value of the element's content attribute.
Run the shared declarative refresh steps with the meta
element's node document, input, and the meta
element.
The shared declarative refresh steps, given a Document object
document, string input, and optionally a meta element
meta, are as follows:
If document's will declaratively refresh is true, then return.
Let position point at the first code point of input.
Skip ASCII whitespace within input given position.
Let time be 0.
Collect a sequence of code points that are ASCII digits from input given position, and let timeString be the result.
If timeString is the empty string, then:
If the code point in input pointed to by position is not U+002E (.), then return.
Otherwise, set time to the result of parsing timeString using the rules for parsing non-negative integers.
Collect a sequence of code points that are ASCII digits and U+002E FULL STOP characters (.) from input given position. Ignore any collected characters.
Let urlRecord be document's URL.
If position is not past the end of input, then:
If the code point in input pointed to by position is not U+003B (;), U+002C (,), or ASCII whitespace, then return.
Skip ASCII whitespace within input given position.
If the code point in input pointed to by position is U+003B (;) or U+002C (,), then advance position to the next code point.
Skip ASCII whitespace within input given position.
If position is not past the end of input, then:
Let urlString be the substring of input from the code point at position to the end of the string.
If the code point in input pointed to by position is U+0055 (U) or U+0075 (u), then advance position to the next code point. Otherwise, jump to the step labeled skip quotes.
If the code point in input pointed to by position is U+0052 (R) or U+0072 (r), then advance position to the next code point. Otherwise, jump to the step labeled parse.
If the code point in input pointed to by position is U+004C (L) or U+006C (l), then advance position to the next code point. Otherwise, jump to the step labeled parse.
Skip ASCII whitespace within input given position.
If the code point in input pointed to by position is U+003D (=), then advance position to the next code point. Otherwise, jump to the step labeled parse.
Skip ASCII whitespace within input given position.
Skip quotes: If the code point in input pointed to by position is U+0027 (') or U+0022 ("), then let quote be that code point, and advance position to the next code point. Otherwise, let quote be the empty string.
Set urlString to the substring of input from the code point at position to the end of the string.
If quote is not the empty string, and there is a code point in urlString equal to quote, then truncate urlString at that code point, so that it and all subsequent code points are removed.
Parse: Set urlRecord to the result of encoding-parsing a URL given urlString, relative to document.
If urlRecord is failure, then return.
If urlRecord's scheme is "javascript", then return.
Set document's will declaratively refresh to true.
Perform one or more of the following steps:
After the refresh has come due (as defined below), if the user has not canceled the
redirect and, if meta is given, document's active sandboxing
flag set does not have the sandboxed automatic features browsing context
flag set, then navigate
document's node navigable to urlRecord using
document, with historyHandling set to "replace".
For the purposes of the previous paragraph, a refresh is said to have come due as soon as the later of the following two conditions occurs:
It is important to use document here, and not meta's
node document, as that might have changed between the initial set of steps and
the refresh coming due and meta is not always given (in case of the HTTP
`Refresh` header).
Provide the user with an interface that, when selected, navigates document's node navigable to urlRecord using document.
Do nothing.
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.
For meta elements with an http-equiv attribute in the Refresh state, the content attribute must have a value consisting either of:
URL",
followed by a U+003D EQUALS SIGN character (=), followed by a valid URL string
that does not start with a literal U+0027 APOSTROPHE (') or U+0022 QUOTATION MARK (")
character.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 URL.
A news organization's front page could include the following markup in the page's
head element, to ensure that the page automatically reloads from the server every
five minutes:
< meta http-equiv = "Refresh" content = "300" > 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:
< meta http-equiv = "Refresh" content = "20; URL=page4.html" > http-equiv="set-cookie")
This pragma is non-conforming and has no effect.
User agents are required to ignore this pragma.
http-equiv="x-ua-compatible")
In practice, this pragma encourages Internet Explorer to more closely follow the specifications.
For meta elements with an http-equiv
attribute in the X-UA-Compatible state, the
content attribute must have a value that is an
ASCII case-insensitive match for the string "IE=edge".
User agents are required to ignore this pragma.
http-equiv="content-security-policy")
This pragma enforces a Content Security
Policy on a Document. [CSP]
If the meta element is not a child of a head element,
return.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then return.
Let policy be the result of executing Content Security Policy's parse
a serialized Content Security Policy algorithm on the meta element's
content attribute's value, with a source of "meta",
and a disposition of "enforce".
Remove all occurrences of the report-uri, frame-ancestors, and sandbox directives from policy.
Enforce the policy policy.
For meta elements with an http-equiv
attribute in the Content security
policy state, the content attribute must have a
value consisting of a valid Content Security
Policy, but must not contain any report-uri,
frame-ancestors, or sandbox directives.
The Content Security Policy given in the content attribute will be enforced upon the current document. [CSP]
At the time of inserting the meta element to the document, it is
possible that some resources have already been fetched. For example, images might be stored in
the list of available images prior to dynamically inserting a meta
element with an http-equiv attribute in the Content security policy state.
Resources that have already been fetched are not guaranteed to be blocked by a Content
Security Policy that's enforced late.
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:
< meta http-equiv = "Content-Security-Policy" content = "script-src 'self'; object-src 'none'" > There must not be more than one meta element with any particular state in the
document at a time.
A character encoding declaration is a mechanism by which the character encoding used to store or transmit a document is specified.
The Encoding standard requires use of the UTF-8 character
encoding and requires use of the "utf-8" encoding label
to identify it. Those requirements necessitate that the document's character encoding
declaration, if it exists, specifies an encoding label using an ASCII
case-insensitive match for "utf-8". Regardless of whether a
character encoding declaration is present or not, the actual character encoding used to encode the document must be
UTF-8. [ENCODING]
To enforce the above rules, authoring tools must default to using UTF-8 for newly-created documents.
The following restrictions also apply:
In addition, due to a number of restrictions on meta elements, there can only be
one meta-based character encoding declaration per document.
If an HTML document does not start with a BOM, and its
encoding is not explicitly given by Content-Type
metadata, and the document is not an iframe srcdoc document, then the encoding must be specified
using a meta element with a charset attribute
or a meta element with an http-equiv
attribute in the Encoding declaration
state.
A character encoding declaration is required (either in the Content-Type metadata 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.
Using non-UTF-8 encodings can have unexpected results on form submission and URL encodings, which use the document's character encoding by default.
If the document is an iframe srcdoc
document, the document must not have a character encoding declaration. (In
this case, the source is already decoded, since it is part of the document that contained the
iframe.)
In XML, the XML declaration should be used for inline character encoding information, if necessary.
In HTML, to declare that the character encoding is UTF-8, the author could
include the following markup near the top of the document (in the head element):
< meta charset = "utf-8" > In XML, the XML declaration would be used instead, at the very top of the markup:
<?xml version="1.0" encoding="utf-8"?> style elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
noscript element that is a child of a head element.media — Applicable media
blocking — Whether the element is potentially render-blocking
title attribute has special semantics on this element: CSS style sheet set name
[Exposed =Window ]
interface HTMLStyleElement : HTMLElement {
[HTMLConstructor ] constructor ();
attribute boolean disabled ;
[CEReactions , Reflect ] attribute DOMString media ;
[SameObject , PutForwards =value , Reflect ] readonly attribute DOMTokenList blocking ;
// also has obsolete members
};
HTMLStyleElement includes LinkStyle ;The style element allows authors to embed CSS style sheets in their documents.
The style element is one of several inputs to the styling processing
model. The element does not represent content for the
user.
Support in all current engines.
The disabled getter steps are:
If this does not have an associated CSS style sheet, return false.
If this's associated CSS style sheet's disabled flag is set, return true.
Return false.
The disabled setter steps are:
If this does not have an associated CSS style sheet, return.
If the given value is true, set this's associated CSS style sheet's disabled flag. Otherwise, unset this's associated CSS style sheet's disabled flag.
Importantly, disabled attribute assignments only take
effect when the style element has an associated CSS style sheet:
const style = document. createElement( 'style' );
style. disabled = true ;
style. textContent = 'body { background-color: red; }' ;
document. body. append( style);
console. log( style. disabled); // false The media attribute
says which media the styles apply to. The value must be a valid media query list.
The user agent must apply the styles when the media attribute's value matches the environment and
the other relevant conditions apply, and must not apply them otherwise.
The styles might be further limited in scope, e.g. in CSS with the use of @media blocks. This specification does not override such further restrictions or
requirements.
The default, if the media
attribute is omitted, is "all", meaning that by default styles apply to all
media.
The blocking
attribute is a blocking attribute.
Support in one engine only.
The title attribute on style elements defines
CSS style sheet sets. If the style element
has no title attribute, then it has no title; the title attribute of ancestors does not apply to the style
element. If the style element is not in a document tree, then the title attribute is ignored. [CSSOM]
The title attribute on style
elements, like the title attribute on link
elements, differs from the global title attribute in that a
style block without a title does not inherit the title of the parent element: it
merely has no title.
The child text content of a style element must be that of a
conformant style sheet.
A style element is implicitly potentially render-blocking if the
element was created by its node document's parser.
The user agent must run the update a style block algorithm whenever
any of the following conditions occur:
The element is popped off the stack of open elements of an HTML parser or XML parser.
The element is not on the stack of open elements of an HTML parser or XML parser, and it becomes connected or disconnected.
The element's children changed steps run.
The update a style block algorithm is as follows:
Let element be the style element.
If element has an associated CSS style sheet, remove the CSS style sheet in question.
If element is not connected, then return.
If element's type attribute is present and
its value is neither the empty string nor an ASCII case-insensitive match for
"text/css", then return.
In particular, a type value with
parameters, such as "text/css; charset=utf-8", will cause this algorithm
to return early.
If the Should element's inline behavior be blocked by Content Security
Policy? algorithm returns "Blocked" when executed upon the
style element, "style", and the style element's
child text content, then return. [CSP]
Create a CSS style sheet with the following properties:
element
The media attribute of element.
This is a reference to the (possibly absent at this time) attribute, rather than a copy of the attribute's current value. CSSOM defines what happens when the attribute is dynamically set, changed, or removed.
The title attribute of element, if
element is in a document tree, or the empty string otherwise.
Again, this is a reference to the attribute.
Unset.
Set.
null
Left at its default value.
Left uninitialized.
This doesn't seem right. Presumably we should be using the element's child text content? Tracked as issue #2997.
If element contributes a script-blocking style sheet, append element to its node document's script-blocking style sheet set.
If element's media attribute's value
matches the environment and element is
potentially render-blocking, then block rendering on
element.
Once the attempts to obtain the style sheet's critical subresources, if any, are complete, or, if the style sheet has no critical subresources, once the style sheet has been parsed and processed, the user agent must run these steps:
Fetching the critical subresources is not well-defined; probably issue #968 is the best resolution for that.
In the meantime, any critical subresource request should have its render-blocking set to whether or not the
style element is currently render-blocking.
Let element be the style element associated with the style sheet
in question.
Let success be true.
If the attempts to obtain any of the style sheet's critical subresources failed for any reason (e.g., DNS error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type), set success to false.
Note that content-specific errors, e.g., CSS parse errors or PNG decoding errors, do not affect success.
Queue an element task on the networking task source given element and the following steps:
If success is true, fire an event
named load at element.
Otherwise, fire an event named error at element.
If element contributes a script-blocking style sheet:
Assert: element's node document's script-blocking style sheet set contains element.
Remove element from its node document's script-blocking style sheet set.
Unblock rendering on element.
The element must delay the load event of the element's node document until all the attempts to obtain the style sheet's critical subresources, if any, are complete.
This specification does not specify a style system, but CSS is expected to be supported by most web browsers. [CSS]
The LinkStyle interface is also implemented by this element. [CSSOM]
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.
<!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 > If the style sheet referenced no other resources (e.g., it was an internal style sheet given by
a style element with no @import rules), then the style rules
must be immediately made available to script; otherwise, the style rules must only be
made available to script once the event loop reaches its update the
rendering step.
An element el in the context of a
Document of an HTML parser or XML parser contributes a
script-blocking style sheet if all of the following are true:
el was created by that Document's parser.
el is either a style element or a link element that
was an external resource link that contributes to the styling
processing model when the el was created by the parser.
el's media attribute's value
matches the environment.
el's style sheet was enabled when the element was created by the parser.
The last time the event loop reached step 1,
el's root was that Document.
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.
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.
It is expected that counterparts to the above rules also apply to
<?xml-stylesheet?> PIs. However, this has not yet been thoroughly
investigated.
A Document has a script-blocking style sheet set, which is an ordered set, initially empty.
A Document document has a style sheet that is blocking
scripts if the following steps return true:
If document's script-blocking style sheet set is not empty, then return true.
If document's node navigable is null, then return false.
Let containerDocument be document's node navigable's container document.
If containerDocument is non-null and containerDocument's script-blocking style sheet set is not empty, then return true.
Return false.
A Document has no style sheet that is blocking scripts if it does not
have a style sheet that is blocking
scripts.
Introduction_to_HTML/Document_and_website_structure#HTML_for_structuring_content
Support in all current engines.
body elementSupport in all current engines.
Support in all current engines.
html element.body element's start tag can be omitted
if the element is empty, or if the first thing inside the body element is not
ASCII whitespace or a comment, except if the
first thing inside the body element is a meta, noscript,
link, script, style, or template element.
body element's end tag can be omitted if the
body element is not immediately followed by a comment.onafterprintonbeforeprintonbeforeunloadonhashchangeonlanguagechangeonmessageonmessageerroronofflineononlineonpageswaponpagehideonpagerevealonpageshowonpopstateonrejectionhandledonstorageonunhandledrejectiononunload[Exposed =Window ]
interface HTMLBodyElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
HTMLBodyElement includes WindowEventHandlers ;The body element represents the contents of the document.
In conforming documents, there is only one body element. The document.body IDL attribute provides scripts with easy access to
a document's body element.
Some DOM operations (for example, parts of the drag and drop model)
are defined in terms of "the body element". This refers to a particular element in
the DOM, as per the definition of the term, and not any arbitrary body element.
The body element exposes as event handler content attributes a number
of the event handlers of the Window object. It also mirrors their
event handler IDL attributes.
The event handlers of the Window object named by the
Window-reflecting body element event handler set, exposed on the
body element, replace the generic event handlers with the same names
normally supported by HTML elements.
Thus, for example, a bubbling error event
dispatched on a child of the body element of a Document would first
trigger the onerror event handler content
attributes of that element, then that of the root html element, and only
then would it trigger the onerror event handler content attribute on the
body element. This is because the event would bubble from the target, to the
body, to the html, to the Document, to the
Window, and the event handler on the
body is watching the Window not the body. A regular event
listener attached to the body using addEventListener(),
however, would be run when the event bubbled through the body and not when it reaches
the Window object.
This page updates an indicator to show whether or not the user is online:
<!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 > article elementSupport in all current engines.
HTMLElement.The article element represents 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.
When article elements are nested, the inner article 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 article elements nested within the article element for the blog
entry.
Author information associated with an article element (q.v. the
address element) does not apply to nested article elements.
When used specifically with content to be redistributed in syndication, the
article element is similar in purpose to the entry element in
Atom. [ATOM]
The schema.org microdata vocabulary can be used to provide the publication date
for an article element, using one of the CreativeWork subtypes.
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
article, 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).
This example shows a blog post using the article element, with some schema.org
annotations:
< 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 > ...</ p >
< footer >
< a itemprop = "discussionUrl" href = "?comments=1" > Show comments...</ a >
</ footer >
</ article > Here is that same blog post, but showing some of the comments:
< 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 > ...</ 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 > Notice the use of footer to give the information for each comment (such as who
wrote it and when): the footer element can appear at the start of its
section when appropriate, such as in this case. (Using header in this case wouldn't
be wrong either; it's mostly a matter of authoring preference.)
In this example, article elements are used to host widgets on a portal page. The
widgets are implemented as customized built-in
elements in order to get specific styling and scripted behavior.
<!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 > section elementSupport in all current engines.
HTMLElement.The section element represents a generic section of a document or
application. A section, in this context, is a thematic grouping of content, typically with a
heading.
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.
Authors are encouraged to use the article element instead of the
section element when it would make sense to syndicate the contents of the
element.
The section 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 div element instead. A general rule is
that the section element is appropriate only if the element's contents would be
listed explicitly in the document's outline.
In the following example, we see an article (part of a larger web page) about apples, containing two short sections.
< 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 > 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 inter-element whitespace.)
<!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 > 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.
< style >
section { border : double medium ; margin : 2 em ; }
section . chapter h2 { font : 2 em Roboto , Helvetica Neue , sans-serif ; }
section . appendix h2 { font : small-caps 2 em 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 > nav elementSupport in all current engines.
HTMLElement.The nav element represents a section of a page that links to other
pages or to parts within the page: a section with navigation links.
Not all groups of links on a page need to be in a nav 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 footer element
alone is sufficient for such cases; while a nav element can be used in such cases, it
is usually unnecessary.
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).
In the following example, there are two nav elements, one for primary navigation
around the site, and one for secondary navigation around the page itself.
< body >
< h1 > The Wiki Center Of Exampland</ h1 >
< nav >
< ul >
< li >< a href = "/" > Home</ a ></ li >
< li >< a href = "/events" > Current Events</ a ></ li >
...more...
</ 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 >
...more...
</ ul >
</ nav >
< div >
< section id = "public" >
< h2 > Public demonstrations</ h2 >
< p > ...more...</ p >
</ section >
< section id = "destroy" >
< h2 > Demolitions</ h2 >
< p > ...more...</ p >
</ section >
...more...
</ 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 > In the following example, the page has several places where links are present, but only one of those places is considered a navigation section.
< 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 >
...more content...
</ div >
< footer >
< p > Posted < time itemprop = "datePublished" datetime = "2009-10-10" > Thursday</ time > .</ p >
</ footer >
</ article >
...more blog posts...
</ 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 > 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.
A nav 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:
< 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 > In this example, nav is used in an email application, to let the user switch
folders:
< 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 > aside elementSupport in all current engines.
HTMLElement.The aside element represents a section of a page that consists of
content that is tangentially related to the content around the aside element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
The element can be used for typographical effects like pull quotes or sidebars, for
advertising, for groups of nav elements, and for other content that is considered
separate from the main content of the page.
It's not appropriate to use the aside element just for
parentheticals, since those are part of the main flow of the document.
The following example shows how an aside is used to mark up background material on Switzerland in a much longer news story on Europe.
< 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 > The following example shows how an aside is used to mark up a pull quote in a longer article.
...
< 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 >
...The following extract shows how aside can be used for blogrolls and other side
content on a blog:
< body >
< header >
< h1 > My wonderful blog</ h1 >
< p > My tagline</ p >
</ header >
< aside >
<!-- 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 -->
< 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 >
<!-- this aside is tangentially related to the page also, it
contains twitter messages from the blog author -->
< 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 >
<!-- this is a blog post -->
< 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 >
<!-- this is also a blog post -->
< h2 > My first post</ h2 >
< p > This is my first post.</ p >
< aside >
<!-- 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 -->
< 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 > h1, h2, h3, h4, h5, and h6
elementsSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
hgroup element.[Exposed =Window ]
interface HTMLHeadingElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};These elements represent headings for their sections.
The semantics and meaning of these elements are defined in the section on headings and outlines.
These elements have a heading level given by the number in their name. The
heading level corresponds to the levels of nested sections. The h1
element is for a top-level section, h2 for a subsection, h3 for a
sub-subsection, and so on.
As far as their respective document outlines (their heading and section structures) are concerned, these two snippets are semantically equivalent:
< 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 > < 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 > 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.
hgroup elementSupport in all current engines.
p elements, followed by one h1, h2,
h3, h4, h5, or h6 element, followed by zero
or more p elements, optionally intermixed with script-supporting
elements.HTMLElement.The hgroup element represents a heading and related content. The
element may be used to group an h1–h6 element with one or more
p elements containing content representing a subheading, alternative title, or
tagline.
Here are some examples of valid headings contained within an hgroup element.
< hgroup >
< h1 > The reality dysfunction</ h1 >
< p > Space is not the only void</ p >
</ hgroup > < hgroup >
< h1 > Dr. Strangelove</ h1 >
< p > Or: How I Learned to Stop Worrying and Love the Bomb</ p >
</ hgroup > header elementSupport in all current engines.
header or footer element
descendants.HTMLElement.The header element represents a group of introductory or navigational
aids.
A header element is intended to usually contain a heading
(an h1–h6 element or an hgroup element), but this is
not required. The header element can also be used to wrap a section's table of
contents, a search form, or any relevant logos.
Here are some sample headers. This first one is for a game:
< header >
< p > Welcome to...</ p >
< h1 > Voidwars!</ h1 >
</ header > The following snippet shows how the element can be used to mark up a specification's header:
< 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 > The header element is not sectioning content; it doesn't
introduce a new section.
In this example, the page has a page heading given by the h1 element, and two
subsections whose headings are given by h2 elements. The content after the
header element is still part of the last subsection started in the
header element, because the header element doesn't take part in the
outline algorithm.
< 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" -->
...footer elementSupport in all current engines.
header or footer element
descendants.HTMLElement.The footer element represents a footer for its nearest ancestor
sectioning content element, or for the body element 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.
When the footer element contains entire sections, they represent appendices, indices, long colophons, verbose license
agreements, and other such content.
Contact information for the author or editor of a section belongs in an
address element, possibly itself inside a footer. Bylines and other
information that could be suitable for both a header or a footer 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.
Footers don't necessarily have to appear at the end of a section, though they usually do.
When there is no ancestor sectioning content element, then it applies to the whole page.
The footer element is not itself sectioning content; it
doesn't introduce a new section.
Here is a page with two footers, one at the top and one at the bottom, with the same content:
< 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 > Here is an example which shows the footer element being used both for a site-wide
footer and for a section footer.
<!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 > 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.
This fragment shows the bottom of a page on a site with a "fat footer":
...
< 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 > address elementSupport in all current engines.
header, footer, or
address element descendants.HTMLElement.The address element represents the contact information for its
nearest article or body element ancestor. If that is the body
element, then the contact information applies to the document as a whole.
For example, a page at the W3C web site related to HTML might include the following contact information:
< 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 > The address element must not be used to represent arbitrary addresses (e.g. postal
addresses), unless those addresses are in fact the relevant contact information. (The
p element is the appropriate element for marking up postal addresses in general.)
The address element must not contain information other than contact
information.
For example, the following is non-conforming use of the
address element:
< ADDRESS > Last Modified: 1999/12/24 23:37:50</ ADDRESS > Typically, the address element would be included along with other information in a
footer element.
The contact information for a node node is a collection of
address elements defined by the first applicable entry from the following list:
article elementbody elementThe contact information consists of all the address elements that have node as an ancestor and do not have another body or
article element ancestor that is a descendant of node.
article elementbody elementThe contact information of node is the same as the contact information of
the nearest article or body element ancestor, whichever is
nearest.
The contact information of node is the same as the contact information of
the body element of the Document.
There is no contact information for node.
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.
In this example the footer contains contact information and a copyright notice.
< footer >
< address >
For more details, contact
< a href = "mailto:[email protected]" > John Smith</ a > .
</ address >
< p >< small > © copyright 2038 Example Corp.</ small ></ p >
</ footer > h1–h6 elements have a heading level, which is
given by getting the element's computed
heading level.
These elements represent headings. The lower a heading's heading level is, the fewer ancestor sections the heading has.
The outline is all headings in a document, in tree order.
The outline 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 heading.
If a document has one or more headings, at least a single heading within the outline should have a heading level of 1.
Each heading following another heading lead in the outline must have a heading level that is less than, equal to, or 1 greater than lead's heading level.
The following example is non-conforming:
< body >
< h1 > Apples</ h1 >
< p > Apples are fruit.</ p >
< section >
< h3 > Taste</ h3 >
< p > They taste lovely.</ p >
</ section >
</ body > It could be written as follows and then it would be conforming:
< body >
< h1 > Apples</ h1 >
< p > Apples are fruit.</ p >
< section >
< h2 > Taste</ h2 >
< p > They taste lovely.</ p >
</ section >
</ body > The headingoffset
content attribute allows authors to offset heading levels for descendants.
If the headingoffset attribute is specified, it must
have a value that is a valid non-negative integer between 0 and 8, inclusive.
The headingreset
content attribute is a boolean attribute. It allows authors to prevent a heading
offset computation from traversing beyond the element with the attribute.
To get an element's computed heading level, given an element element:
Let level be 0.
If element's local name is h1, then set
level to 1.
If element's local name is h2, then set
level to 2.
If element's local name is h3, then set
level to 3.
If element's local name is h4, then set
level to 4.
If element's local name is h5, then set
level to 5.
If element's local name is h6, then set
level to 6.
Assert: level is not 0.
Increment level by the result of getting an element's computed heading offset given element.
If level is greater than 9, then return 9.
Return level.
To get an element's computed heading offset, given an element element, perform the following steps. They return a non-negative integer.
Let offset be 0.
Let inclusiveAncestor be element.
While inclusiveAncestor is not null:
Let nextOffset be 0.
If inclusiveAncestor is an HTML element and
has a headingoffset attribute, then parse its value
using the rules for parsing non-negative integers.
If the result of parsing the value is not an error, then set nextOffset to that value.
Increment offset by nextOffset.
If inclusiveAncestor is an HTML element
and has a headingreset attribute, then return
offset.
Set inclusiveAncestor to the parent node of inclusiveAncestor within the flat tree.
Return offset.
This example shows a combination of headingoffset,
headingreset, and aria-level attributes with comments demonstrating the respective
heading levels. This example illustrates the various combinations and is not a best practice
example.
< body >
< main >
< h1 > This is a heading level 1</ h1 >
< article headingoffset = "1" >
< h1 > This is a heading level 2</ h1 >
< section headingoffset = "1" >
< h1 > This is a heading level 3</ h1 >
< dialog headingreset >
< h1 > This is a heading level 1</ h1 >
</ dialog >
</ section >
</ article >
< h1 aria-level = "2" > This is a heading level 2</ h1 >
</ main >
</ body > The following markup fragment:
< 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 > ...results in 3 document headings:
<h1>HTML: Living Standard</h1>
<h2>Table of contents</h2>.
<h2>First section</h2>.
A rendered view of the outline might look like:
First, here is a document, which is a book with very short chapters and subsections:
<!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 > Its outline could be presented as follows:
A document can contain multiple top-level headings:
<!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 > The document's outline could be presented as follows:
header elements do not influence the outline of a
document:
<!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 > The document's outline could be presented as follows:
The following example is conforming, but not encouraged as it has no heading whose heading level is 1:
<!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 > The document's outline could be presented as follows:
The following example is conforming, but not encouraged as the first heading's heading level is not 1:
<!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 > The document's outline could be presented as follows:
User agents are encouraged to expose page outlines to users to aid in navigation. This is especially true for non-visual media, e.g. screen readers.
For instance, a user agent could map the arrow keys as follows:
This section is non-normative.
| Element | Purpose |
|---|---|
| Example | |
body
| The contents of the document. |
| |
article
| 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. |
| |
section
| A generic section of a document or application. A section, in this context, is a thematic grouping of content, typically with a heading. |
| |
nav
| A section of a page that links to other pages or to parts within the page: a section with navigation links. |
| |
aside
| A section of a page that consists of
content that is tangentially related to the content around the aside element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
|
| |
h1–h6
| A heading |
| |
hgroup
| A heading and related content. The
element may be used to group an h1–h6 element with one or more
p elements containing content representing a subheading, alternative title, or
tagline.
|
| |
header
| A group of introductory or navigational aids. |
| |
footer
| A footer for its nearest ancestor sectioning content element, or for the body element 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. |
|
This section is non-normative.
A section forms part of something else. An article is its own thing.
But how does one know which is which? Mostly the real answer is "it depends on author intent".
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 section
because there'd be lots of other chapters on (maybe) other kinds of apples.
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 articles because that was the whole thing.
A comment on an article is not part of the article on which it is commenting,
therefore it is its own article.
p elementSupport in all current engines.
Support in all current engines.
hgroup element.p element's end tag can be omitted if the
p element is immediately followed by an address, article,
aside, blockquote, details, dialog,
div, dl, fieldset, figcaption,
figure, footer, form, h1, h2,
h3, h4, h5, h6, header,
hgroup, hr, main, menu, nav,
ol, p, pre, search, section,
table, or ul element, or if there is no more content in the parent
element and the parent element is an HTML element that is not
an a, audio, del, ins, map,
noscript, or video element, or an autonomous custom
element.[Exposed =Window ]
interface HTMLParagraphElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The p element represents a paragraph.
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 (¶).
The following examples are conforming HTML fragments:
< 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 > < 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 > < 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 > The p element should not be used when a more specific element is more
appropriate.
The following example is technically correct:
< section >
<!-- ... -->
< p > Last modified: 2001-04-23</ p >
< p > Author: [email protected]</ p >
</ section > However, it would be better marked-up as:
< section >
<!-- ... -->
< footer > Last modified: 2001-04-23</ footer >
< address > Author: [email protected]</ address >
</ section > Or:
< section >
<!-- ... -->
< footer >
< p > Last modified: 2001-04-23</ p >
< address > Author: [email protected]</ address >
</ footer >
</ section > List elements (in particular, ol and ul elements) cannot be children
of p elements. When a sentence contains a bulleted list, therefore, one might wonder
how it should be marked up.
For instance, this fantastic sentence has bullets relating to
and is further discussed below.
The solution is to realize that a paragraph, in HTML terms, is not a logical concept, but a structural one. In the fantastic example above, there are actually five paragraphs as defined by this specification: one before the list, one for each bullet, and one after the list.
The markup for the above example could therefore be:
< 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 > Authors wishing to conveniently style such "logical" paragraphs consisting of multiple
"structural" paragraphs can use the div element instead of the p
element.
Thus for instance the above example could become the following:
< 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 > This example still has five structural paragraphs, but now the author can style just the
div instead of having to consider each part of the example separately.
hr elementSupport in all current engines.
Support in all current engines.
select element inner content elements.select element.[Exposed =Window ]
interface HTMLHRElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The hr element represents a paragraph-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
select element.
The following fictional extract from a project manual shows two sections that use the
hr element to separate topics within the section.
< 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 >
< hr >
< 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 >
< hr >
< p > Radios use the electromagnetic spectrum in the meter range and
longer.</ p >
< hr >
< 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 >
< hr >
< p > Cooking is done by the chefs on a set rotation.</ p >
</ section > There is no need for an hr element between the sections themselves, since the
section elements and the h1 elements imply thematic changes
themselves.
The following extract from Pandora's Star 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 hr element.
< 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 >
< hr >
< 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 > The hr element does not affect the document's
outline.
pre elementSupport in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLPreElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The pre element represents a block of preformatted text, in which
structure is represented by typographic conventions rather than by elements.
In the HTML syntax, a leading newline character immediately following
the pre element start tag is stripped.
Some examples of cases where the pre element could be used:
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.
To represent a block of computer code, the pre element can be used with a
code element; to represent a block of computer output the pre element
can be used with a samp element. Similarly, the kbd element can be used
within a pre element to indicate text that the user is to enter.
This element has rendering requirements involving the bidirectional algorithm.
In the following snippet, a sample of computer code is presented.
< 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 > In the following snippet, samp and kbd elements are mixed in the
contents of a pre element to show a session of Zork I.
< 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 > The following shows a contemporary poem that uses the pre element to preserve its
unusual formatting, which forms an intrinsic part of the poem itself.
< 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 > blockquote elementSupport in all current engines.
Support in all current engines.
cite — Link to the source of the quotation or more information about the edit
[Exposed =Window ]
interface HTMLQuoteElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString cite ;
};The HTMLQuoteElement interface is also used by the q
element.
The blockquote element represents a section that is quoted from
another source.
Content inside a blockquote must be quoted from another source, whose address, if
it has one, may be cited in the cite attribute.
If the cite attribute is present, it must be a
valid URL potentially surrounded by spaces. To obtain the
corresponding citation link, the value of the attribute must be parsed relative to the element's node document. 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.
The content of a blockquote may be abbreviated or may have context added in the
conventional manner for the text's language.
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:
< blockquote >
< p > [Jane] then said she liked [...] fish.</ p >
</ blockquote > Attribution for the quotation, if any, must be placed outside the blockquote
element.
For example, here the attribution is given in a paragraph after the quote:
< 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 > The other examples below show other ways of showing attribution.
Here a blockquote element is used in conjunction with a figure
element and its figcaption to clearly relate a quote to its attribution (which is
not part of the quote and therefore doesn't belong inside the blockquote
itself):
< 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 > This next example shows the use of cite alongside blockquote:
< 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 >
...This example shows how a forum post could use blockquote to show what post a user
is replying to. The article element is used for each post, to mark up the
threading.
< 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 > This example shows the use of a blockquote for short snippets, demonstrating that
one does not have to use p elements inside blockquote elements:
< 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...Examples of how to represent a conversation are shown
in a later section; it is not appropriate to use the cite and blockquote
elements for this purpose.
ol elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.reversed — Number the list backwards
start — Starting value of the list
type — Kind of list marker
[Exposed =Window ]
interface HTMLOListElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute boolean reversed ;
[CEReactions , Reflect , ReflectDefault=1] attribute long start ;
[CEReactions , Reflect ] attribute DOMString type ;
// also has obsolete members
};The ol element represents a list of items, where the items have been
intentionally ordered, such that changing the order would change the meaning of the document.
The items of the list are the li element child nodes of the ol
element, in tree order.
Support in all current engines.
The reversed attribute
is a boolean attribute. 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, ...).
The start attribute, if
present, must be a valid integer. It is used to determine the starting value of the list.
An ol element has a starting value, which is
an integer determined as follows:
If the ol element has a start attribute,
then:
Let parsed be the result of parsing the value of the attribute as an integer.
If parsed is not an error, then return parsed.
If the ol element has a reversed
attribute, then return the number of owned li
elements.
Return 1.
The type 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 referenced by their number/letter). The attribute, if
specified, must have a value that is identical to one of the characters given in the
first cell of one of the rows of the following table. The type 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 decimal state.
| Keyword | State | Description | Examples for values 1-3 and 3999-4001 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
1
(U+0031)
| decimal | Decimal numbers | 1. | 2. | 3. | ... | 3999. | 4000. | 4001. | ... |
a (U+0061)
| lower-alpha | Lowercase latin alphabet | a. | b. | c. | ... | ewu. | ewv. | eww. | ... |
A (U+0041)
| upper-alpha | Uppercase latin alphabet | A. | B. | C. | ... | EWU. | EWV. | EWW. | ... |
i (U+0069)
| lower-roman | Lowercase roman numerals | i. | ii. | iii. | ... | mmmcmxcix. | i̅v̅. | i̅v̅i. | ... |
I (U+0049)
| upper-roman | Uppercase roman numerals | I. | II. | III. | ... | MMMCMXCIX. | I̅V̅. | I̅V̅I. | ... |
User agents should render the items of the list in a manner consistent with the state of the
type attribute of the ol element. Numbers less than
or equal to zero should always use the decimal system regardless of the type attribute.
For CSS user agents, a mapping for this attribute to the 'list-style-type' CSS property is given in the Rendering section (the mapping is straightforward: the states above have the same names as their corresponding CSS values).
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.
Due to [ReflectDefault] the start IDL attribute does not necessarily match the list's starting value, in cases where the start content attribute is omitted and the reversed content attribute is specified.
The following markup shows a list where the order matters, and where the ol
element is therefore appropriate. Compare this list to the equivalent list in the ul
section to see an example of the same items using the ul element.
< 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 > 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 > 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 > ul elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.[Exposed =Window ]
interface HTMLUListElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The ul element represents 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.
The items of the list are the li element child nodes of the ul
element.
The following markup shows a list where the order does not matter, and where the
ul element is therefore appropriate. Compare this list to the equivalent list in the
ol section to see an example of the same items using the ol
element.
< p > I have lived in the following countries:</ p >
< ul >
< li > Norway
< li > Switzerland
< li > United Kingdom
< li > United States
</ ul > 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 > I have lived in the following countries:</ p >
< ul >
< li > Switzerland
< li > Norway
< li > United Kingdom
< li > United States
</ ul > menu elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.[Exposed =Window ]
interface HTMLMenuElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The menu element represents a toolbar consisting of its contents, in
the form of an unordered list of items (represented by li elements), each of
which represents a command that the user can perform or activate.
The menu element is simply a semantic alternative to ul
to express an unordered list of commands (a "toolbar").
In this example, a text-editing application uses a menu element to provide a
series of editing commands:
< 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 > Note that the styling to make this look like a conventional toolbar menu is up to the application.
li elementSupport in all current engines.
Support in all current engines.
ol elements.ul elements.menu elements.li element's end tag can be omitted if the
li element is immediately followed by another li element or if there is
no more content in the parent element.ul or menu element: value — Ordinal value of the list item
[Exposed =Window ]
interface HTMLLIElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute long value ;
// also has obsolete members
};The li element represents a list item. If its parent element is an
ol, ul, or menu 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 li element.
The value attribute, if
present, must be a valid integer. It is used to determine the ordinal
value of the list item, when the li's list owner is an
ol element.
Any element whose computed value of 'display' is 'list-item' has a list owner, which is determined as follows:
If the element is not being rendered, return null; the element has no list owner.
Let ancestor be the element's parent.
If the element has an ol, ul, or menu ancestor, set
ancestor to the closest such ancestor element.
Return the closest inclusive ancestor of ancestor that produces a CSS box.
Such an element will always exist, as at the very least the document element will always produce a CSS box.
To determine the ordinal value of each element owned by a given list owner owner, perform the following steps:
Let i be 1.
If owner is an ol element, let numbering be
owner's starting value. Otherwise, let
numbering be 1.
Loop: If i is greater than the number of list items that owner owns, then return; all of owner's owned list items have been assigned ordinal values.
Let item be the ith of owner's owned list items, in tree order.
If item is an li element that has a value attribute, then:
Let parsed be the result of parsing the value of the attribute as an integer.
If parsed is not an error, then set numbering to parsed.
The ordinal value of item is numbering.
If owner is an ol element, and owner has a reversed attribute, decrement numbering by 1;
otherwise, increment numbering by 1.
Increment i by 1.
Go to the step labeled loop.
The element's value IDL attribute does not directly
correspond to its ordinal value; it simply reflects
the content attribute. For example, given this list:
< ol >
< li > Item 1
< li value = "3" > Item 3
< li > Item 4
</ ol > The ordinal values are 1, 3, and 4, whereas the value IDL attributes return 0, 3, 0 on getting.
The following example, the top ten movies are listed (in reverse order). Note the way the list
is given a title by using a figure element and its figcaption
element.
< 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 > The markup could also be written as follows, using the reversed attribute on the ol element:
< 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 > While it is conforming to include heading elements (e.g. h1) inside
li 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.
dl elementSupport in all current engines.
Support in all current engines.
dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.div elements, optionally intermixed with script-supporting elements.[Exposed =Window ]
interface HTMLDListElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The dl element represents an association list consisting of zero or
more name-value groups (a description list). A name-value group consists of one or more names
(dt elements, possibly as children of a div element child) followed by
one or more values (dd elements, possibly as children of a div element
child), ignoring any nodes other than dt and dd element children, and
dt and dd elements that are children of div element
children. Within a single dl element, there should not be more than one
dt element for each name.
Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.
The values within a group are alternatives; multiple paragraphs forming part of the same value
must all be given within the same dd element.
The order of the list of groups, and of the names and values within each group, may be significant.
In order to annotate groups with microdata attributes, or other global
attributes that apply to whole groups, or just for styling purposes, each group in a
dl element can be wrapped in a div element. This does not change the
semantics of the dl element.
The name-value groups of a dl element dl are determined using the
following algorithm. A name-value group has a name (a list of dt elements, initially
empty) and a value (a list of dd elements, initially empty).
Let groups be an empty list of name-value groups.
Let current be a new name-value group.
Let seenDd be false.
Let child be dl's first child.
Let grandchild be null.
While child is not null:
If child is a div element, then:
Let grandchild be child's first child.
While grandchild is not null:
Process dt or dd for
grandchild.
Set grandchild to grandchild's next sibling.
Otherwise, process dt or dd for
child.
Set child to child's next sibling.
If current is not empty, then append current to groups.
Return groups.
To process dt or dd for a node node means to
follow these steps:
Let groups, current, and seenDd be the same variables as those of the same name in the algorithm that invoked these steps.
If node is a dt element, then:
If seenDd is true, then append current to groups, set current to a new name-value group, and set seenDd to false.
Append node to current's name.
Otherwise, if node is a dd element, then append node to
current's value and set seenDd to true.
When a name-value group has an empty list as name or value, it is often due to
accidentally using dd elements in the place of dt elements and vice
versa. Conformance checkers can spot such mistakes and might be able to advise authors how to
correctly use the markup.
In the following example, one entry ("Authors") is linked to two values ("John" and "Luke").
< dl >
< dt > Authors
< dd > John
< dd > Luke
< dt > Editor
< dd > Frank
</ dl > In the following example, one definition is linked to two terms.
< dl >
< dt lang = "en-US" > < dfn > color</ dfn > </ dt >
< dt lang = "en-GB" > < dfn > colour</ dfn > </ dt >
< 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 > The following example illustrates the use of the dl 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
div element around the groups of dt and dd element, to aid
with styling.
< 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 > The following example shows the dl 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 > 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 > The following snippet shows a dl element being used as a glossary. Note the use
of dfn to indicate the word being defined.
< 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 > This example uses microdata attributes in a dl element, together
with the div element, to annotate the ice cream desserts at a French restaurant.
< 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 > Without the div element the markup would need to use the itemref attribute to link the data in the dd elements
with the item, as follows.
< 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 > The dl element is inappropriate for marking up dialogue. See some examples of how to mark up dialogue.
dt elementSupport in all current engines.
dd or dt elements inside dl elements.dd or dt elements inside div elements that are children of a dl element.header, footer, sectioning content, or heading content descendants.dt element's end tag can be omitted if the
dt element is immediately followed by another dt element or a
dd element.HTMLElement.The dt element represents the term, or name, part of a
term-description group in a description list (dl element).
The dt element itself, when used in a dl element, does
not indicate that its contents are a term being defined, but this can be indicated using the
dfn element.
This example shows a list of frequently asked questions (a FAQ) marked up using the
dt element for questions and the dd element for answers.
< 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 > dd elementSupport in all current engines.
dt or dd elements inside dl elements.dt or dd elements inside div elements that are children of a dl element.dd element's end tag can be omitted if the
dd element is immediately followed by another dd element or a
dt element, or if there is no more content in the parent element.HTMLElement.The dd element represents the description, definition, or value, part
of a term-description group in a description list (dl element).
A dl can be used to define a vocabulary list, like in a dictionary. In the
following example, each entry, given by a dt with a dfn, has several
dds, showing the various parts of the definition.
< 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 > figure elementSupport in all current engines.
figcaption element followed by flow content.figcaption element.HTMLElement.The figure element represents some flow content,
optionally with a caption, that is self-contained (like a complete sentence) and is typically
referenced as a single unit from the main flow of the document.
"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 figure, but an entire sentence made of images would be
fitting.
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.
When a figure 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.
If a figure element is referenced 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.
The first figcaption element child of the element, if any,
represents the caption of the figure element's contents. If there is no child
figcaption element, then there is no caption.
A figure 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
figure and figcaption 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 aside element should be used (and can itself
wrap a figure). For example, a pull quote that repeats content from an
article would be more appropriate in an aside than in a
figure, 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.
This example shows the figure element to mark up a code listing.
< 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< byte> data);
undefined initSelfDestruct();
}</ code ></ pre >
</ figure >
< p > The API is designed to use UTF-8.</ p > Here we see a figure element to mark up a photo that is the main content of the
page (as in a gallery).
<!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 > In this example, we see an image that is not 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 figure would be inappropriate.
< 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.Here, a part of a poem is marked up using figure.
< 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 > In this example, which could be part of a much larger work discussing a castle, nested
figure elements are used to provide both a group caption and individual captions for
each figure in the group:
< 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 > The previous example could also be more succinctly written as follows (using title attributes in place of the nested
figure/figcaption pairs):
< 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 > The figure is sometimes referenced only implicitly from the content:
< 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 > figcaption elementSupport in all current engines.
figure element.HTMLElement.The figcaption element represents a caption or legend for the rest of
the contents of the figcaption element's parent figure element, if any.
The element can contain additional information about the source:
< figcaption >
< p > A duck.</ p >
< p >< small > Photograph courtesy of 🌟 News.</ small ></ p >
</ figcaption > < 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 > main elementSupport in all current engines.
main element.HTMLElement.The main element represents the dominant contents of the
document.
A document must not have more than one main element that does not have the attribute specified.
A hierarchically correct main element is one whose ancestor elements
are limited to html, body, div, form without
an accessible name, and autonomous custom elements. Each main element must be a
hierarchically correct main element.
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 main element is used.
<!DOCTYPE html>
< html lang = "en" >
< title > RPG System 17</ title >
< style >
header , nav , aside , main , footer {
margin : 0.5 em ; border : thin solid ; padding : 0.5 em ;
background : #EFF ; color : black ; box-shadow : 0 0 0.25 em #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 > In the following example, multiple main elements are used and script is used to
make navigation work without a server roundtrip and to set the attribute on those that are not current:
<!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 > search elementNo support in current engines.
HTMLElement.The search element represents 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.
It's not appropriate to use the search 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.
In the following example, the author is including a search form within the
header of the web page:
< 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 > In this example, the author has implemented their web application's search functionality
entirely with JavaScript. There is no use of the form element to perform
server-side submission, but the containing search element semantically identifies
the purpose of the descendant content as representing search capabilities.
< 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 > In the following example, the page has two search features. The first is located in the web page's
header and serves as a global mechanism to search the web site's content. Its purpose is
indicated by its specified title 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.
< 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 > div elementSupport in all current engines.
Support in all current engines.
select element inner content elements.optgroup element inner content elements.option element inner content elements.dl element.dl element: One or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.option element: Zero or more
option element inner content elements.optgroup element: Zero or more
optgroup element inner content elements.select element: Zero or more
select element inner content elements.[Exposed =Window ]
interface HTMLDivElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The div element has no special meaning at all. It represents its
children. It can be used with the class, lang, and title attributes to mark up
semantics common to a group of consecutive elements. It can also be used in a dl
element, wrapping groups of dt and dd elements.
Authors are strongly encouraged to view the div element as an element
of last resort, for when no other element is suitable. Use of more appropriate elements instead of
the div element leads to better accessibility for readers and easier maintainability
for authors.
For example, a blog post would be marked up using article, a chapter using
section, a page's navigation aids using nav, and a group of form
controls using fieldset.
On the other hand, div 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 div 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:
< 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, 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 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 "colour"...</ p >
</ div >
< p > I should say "sidewalk" and "apartment" and "color"!</ p >
</ article > a elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
href attribute: Interactive content.a element descendant, or descendant with the tabindex attribute specified.href — Address of the hyperlink
target — Navigable for hyperlink navigation
download — Whether to download the resource instead of navigating to it, and its filename if so
ping — URLs to ping
rel — Relationship between the location in the document containing the hyperlink and the destination resource
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
href attribute: for authors; for implementers.[Exposed =Window ]
interface HTMLAnchorElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute DOMString target ;
[CEReactions , Reflect ] attribute DOMString download ;
[CEReactions , Reflect ] attribute USVString ping ;
[CEReactions , Reflect ] attribute DOMString rel ;
[SameObject , PutForwards =value , Reflect="rel"] readonly attribute DOMTokenList relList ;
[CEReactions , Reflect ] attribute DOMString hreflang ;
[CEReactions , Reflect ] attribute DOMString type ;
[CEReactions ] attribute DOMString text ;
[CEReactions ] attribute DOMString referrerPolicy ;
// also has obsolete members
};
HTMLAnchorElement includes HTMLHyperlinkElementUtils ;If the a element has an href attribute,
then it represents a hyperlink (a hypertext anchor) labeled by its
contents.
If the a element has no href attribute,
then the element represents a placeholder for where a link might otherwise have been
placed, if it had been relevant, consisting of just the element's contents.
The target, download, ping,
rel, hreflang, type,
and referrerpolicy attributes must be omitted
if the href attribute is not present.
If the itemprop attribute is specified on an a element,
then the href attribute must also be specified.
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 a element:
< 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 > The href, target, download, ping,
and referrerpolicy attributes affect what
happens when users follow hyperlinks or download hyperlinks created using the a
element. The rel, hreflang, and type
attributes may be used to indicate to the user the likely nature of the target resource before the
user follows the link.
a.textSame as textContent.
HTMLAnchorElement/referrerPolicy
Support in all current engines.
The IDL attribute referrerPolicy must reflect the referrerpolicy content attribute, limited to
only known values.
The text
attribute's getter must return this element's descendant text content.
The text attribute's setter must string replace
all with the given value within this element.
The a 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:
< aside class = "advertising" >
< h1 > Advertising</ h1 >
< a href = "https://ad.example.com/?adid=1929&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&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 > 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:
< 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 > em elementSupport in all current engines.
HTMLElement.The em element represents stress emphasis of its contents.
The level of stress that a particular piece of content has is given by its number of ancestor
em elements.
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.
These examples show how changing the stress emphasis changes the meaning. First, a general statement of fact, with no stress:
< p > Cats are cute animals.</ 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 >< em > Cats</ em > are cute animals.</ 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 > Cats < em > are</ em > cute animals.</ p > By moving it to the adjective, the exact nature of the cats is reasserted (maybe someone suggested cats were mean animals):
< p > Cats are < em > cute</ em > animals.</ p > Similarly, if someone asserted that cats were vegetables, someone correcting this might emphasize the last word:
< p > Cats are cute < em > animals</ em > .</ 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 >< em > Cats are cute animals!</ em ></ p > Anger mixed with emphasizing the cuteness could lead to markup such as:
< p >< em > Cats are < em > cute</ em > animals!</ em ></ p > The em 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 i element is more appropriate.
The em element also isn't intended to convey importance; for that purpose, the
strong element is more appropriate.
strong elementSupport in all current engines.
HTMLElement.The strong element represents strong importance, seriousness, or
urgency for its contents.
Importance: the strong 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 hgroup element is appropriate.)
For example, the first word of the previous paragraph is marked up with
strong to distinguish it from the more detailed text in the rest of the
paragraph.
Seriousness: the strong element can be used to mark up a warning
or caution notice.
Urgency: the strong element can be used to denote contents that
the user needs to see sooner than other parts of the document.
The relative level of importance of a piece of content is given by its number of ancestor
strong elements; each strong element increases the importance of its
contents.
Changing the importance of a piece of text with the strong element does not change
the meaning of the sentence.
Here, the word "chapter" and the actual chapter number are mere boilerplate, and the actual
name of the chapter is marked up with strong:
< h1 > Chapter 1: < strong > The Praxis</ strong ></ h1 > In the following example, the name of the diagram in the caption is marked up with
strong, to distinguish it from boilerplate text (before) and the description
(after):
< 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 > In this example, the heading is really "Flowers, Bees, and Honey", but the author has added a
light-hearted addition to the heading. The strong element is thus used to mark up
the first part to distinguish it from the latter part.
< h1 >< strong > Flowers, Bees, and Honey</ strong > and other things I don't understand</ h1 > Here is an example of a warning notice in a game, with the various parts marked up according to how important they are:
< 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 > In this example, the strong element is used to denote the part of the text that
the user is intended to read first.
< 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 > small elementSupport in all current engines.
HTMLElement.The small element represents side comments such as small print.
Small print typically features disclaimers, caveats, legal restrictions, or copyrights. Small print is also sometimes used for attribution, or for satisfying licensing requirements.
The small element does not "de-emphasize" or lower the importance of
text emphasized by the em element or marked as important with the strong
element. To mark text as not emphasized or important, simply do not mark it up with the
em or strong elements respectively.
The small 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
small element: in such a case, the text is not a side comment, it is the main content
of the page.
The small element must not be used for subheadings; for that purpose, use the
hgroup element.
In this example, the small element is used to indicate that value-added tax is
not included in a price of a hotel room:
< 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 > In this second example, the small element is used for a side comment in an
article.
< 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 > 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.
< 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 > In this last example, the small element is marked as being important
small print.
< p >< strong >< small > Continued use of this service will result in a kiss.</ small ></ strong ></ p > s elementSupport in all current engines.
HTMLElement.The s element represents contents that are no longer accurate or no
longer relevant.
The s element is not appropriate when indicating document edits; to
mark a span of text as having been removed from a document, use the del element.
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 > 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 > cite elementSupport in all current engines.
HTMLElement.The cite element represents 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,
etc.). This can be a work that is being quoted or referenced in detail (i.e., a
citation), or it can just be a work that is mentioned in passing.
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 b 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 really needed, the span element can be
used.)
This next example shows a typical use of the cite element:
< 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 > This is correct usage:
< 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 > The following, however, is incorrect usage, as the cite element here is
containing far more than the title of the work:
<!-- 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 > The cite element is a key part of any citation in a bibliography, but it is only
used to mark the title:
< p >< cite > Universal Declaration of Human Rights</ cite > , United Nations,
December 1948. Adopted by General Assembly resolution 217 A (III).</ p > A citation is not a quote (for which the q element
is appropriate).
This is incorrect usage, because cite is not for quotes:
< p >< cite > This is wrong!</ cite > , said Ian.</ p > This is also incorrect usage, because a person is not a work:
< p >< q > This is still wrong!</ q > , said < cite > Ian</ cite > .</ p > The correct usage does not use a cite element:
< p >< q > This is correct</ q > , said Ian.</ p > As mentioned above, the b element might be relevant for marking names as being
keywords in certain kinds of documents:
< p > And then < b > Ian</ b > said < q > this might be right, in a
gossip column, maybe!</ q > .</ p > q elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
HTMLQuoteElement.The q element represents some phrasing
content quoted from another source.
Quotation punctuation (such as quotation marks) that is quoting the contents of the element
must not appear immediately before, after, or inside q elements; they will be
inserted into the rendering by the user agent.
Content inside a q element must be quoted from another source, whose address, if
it has one, may be cited in the cite attribute. The source may be fictional, as when quoting
characters in a novel or screenplay.
If the cite attribute is present, it must be a valid
URL potentially surrounded by spaces. To obtain the corresponding citation
link, the value of the attribute must be parsed
relative to the element's node document. 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.
The q element must not be used in place of quotation marks that do not represent
quotes; for example, it is inappropriate to use the q element for marking up
sarcastic statements.
The use of q elements to mark up quotations is entirely optional; using explicit
quotation punctuation without q elements is just as correct.
Here is a simple example of the use of the q element:
< p > The man said < q > Things that are impossible just take
longer</ q > . I disagreed with him.</ p > Here is an example with both an explicit citation link in the q element, and an
explicit citation outside:
< 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 > In the following example, the quotation itself contains a quotation:
< 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 > In the following example, quotation marks are used instead of the q element:
< p > His best argument was ❝I disagree❞, which
I thought was laughable.</ p > In the following example, there is no quote — the quotation marks are used to name a
word. Use of the q element in this case would be inappropriate.
< p > The word "ineffable" could have been used to describe the disaster
resulting from the campaign's mismanagement.</ p > dfn elementSupport in all current engines.
dfn element descendants.title attribute has special semantics on this element: Full term or expansion of abbreviation
HTMLElement.The dfn element represents the defining instance of a term. The paragraph, description list group, or section that is the nearest ancestor of the dfn
element must also contain the definition(s) for the term given
by the dfn element.
Defining term: if the dfn element has a title 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 Text nodes, and that child element is an abbr element with a
title attribute, then the exact value of that
attribute is the term being defined. Otherwise, it is the descendant text content of
the dfn element that gives the term being defined.
If the title attribute of the dfn element is
present, then it must contain only the term being defined.
The title attribute of ancestor elements does not
affect dfn elements.
An a element that links to a dfn element represents an instance of
the term defined by the dfn element.
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 > The < dfn >< 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 < abbr title = "Garage Door Opener" > GDO</ abbr >
and so Hammond ordered the iris to be opened.</ p > With the addition of an a element, the reference
can be made explicit:
< p > The < dfn id = gdo >< 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 < a href = #gdo > < abbr title = "Garage Door Opener" > GDO</ abbr > </ a >
and so Hammond ordered the iris to be opened.</ p > abbr elementSupport in all current engines.
title attribute has special semantics on this element: Full term or expansion of abbreviation
HTMLElement.The abbr element represents an abbreviation or acronym, optionally
with its expansion. The title 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.
The paragraph below contains an abbreviation marked up with the abbr element.
This paragraph defines the term "Web Hypertext Application
Technology Working Group".
< 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 > An alternative way to write this would be:
< 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 > This paragraph has two abbreviations. Notice how only one is defined; the other, with no
expansion associated with it, does not use the abbr element.
< p > The
< abbr title = "Web Hypertext Application Technology Working Group" > WHATWG</ abbr >
started working on HTML5 in 2004.</ p > This paragraph links an abbreviation to its definition.
< 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 > This paragraph marks up an abbreviation without giving an expansion, possibly as a hook to apply styles for abbreviations (e.g. smallcaps).
< 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 > If an abbreviation is pluralized, the expansion's grammatical number (plural vs singular) must match the grammatical number of the contents of the element.
Here the plural is outside the element, so the expansion is in the singular:
< p > Two < abbr title = "Working Group" > WG</ abbr > s worked on
this specification: the < abbr > WHATWG</ abbr > and the
< abbr > HTMLWG</ abbr > .</ p > Here the plural is inside the element, so the expansion is in the plural:
< p > Two < abbr title = "Working Groups" > WGs</ abbr > worked on
this specification: the < abbr > WHATWG</ abbr > and the
< abbr > HTMLWG</ abbr > .</ p > Abbreviations do not have to be marked up using this element. It is expected to be useful in the following cases:
abbr element with a title attribute is an
alternative to including the expansion inline (e.g. in parentheses).abbr element with a title attribute or include the expansion inline in the text the first
time the abbreviation is used.abbr element
can be used without a title attribute.Providing an expansion in a title attribute once
will not necessarily cause other abbr elements in the same document with the same
contents but without a title attribute to behave as if they had
the same expansion. Every abbr element is independent.
ruby elementSupport in all current engines.
HTMLElement.The ruby 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 furigana.
The content model of ruby elements consists of one or more of the following
sequences:
One or the other of the following:
Phrasing content, but with no ruby elements and with no
ruby element descendants
A single ruby element that itself has no ruby element
descendants
One or the other of the following:
The ruby and rt 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
Requirements for Japanese Text Layout. [JLREQ]
At the time of writing, CSS does not yet provide a way to fully control the
rendering of the HTML ruby element. It is hoped that CSS will be extended to support
the styles described below in due course.
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.
< ruby > B< rt > annotation</ ruby > In this example, notice how each annotation corresponds to a single base character.
< ruby > 君< rt > くん</ ruby >< ruby > 子< rt > し</ ruby > は< ruby > 和< rt > わ</ ruby > して< ruby > 同< rt > どう</ ruby > ぜず。君子は和して同ぜず。
This example can also be written as follows, using one ruby element with two
segments of base text and two annotations (one for each) rather than two back-to-back
ruby elements each with one base text segment and annotation (as in the markup
above):
< ruby > 君< rt > くん</ rt > 子< rt > し</ ruby > は< ruby > 和< rt > わ</ ruby > して< ruby > 同< rt > どう</ ruby > ぜず。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.
< ruby > B< rt > annotation</ rt > B< rt > annotation</ ruby > 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 ruby element.
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.
< ruby > 鬼< rt > き</ rt > 門< rt > もん</ rt ></ ruby > の< ruby > 方< rt > ほう</ rt > 角< rt > がく</ rt ></ ruby > を< ruby > 凝< rt > ぎょう</ rt > 視< rt > し</ rt ></ ruby > する鬼門の方角を凝視する
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.
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.
< ruby > 鬼< rt > き</ rt > 門< rt > もん</ rt ></ ruby > の< ruby > 方< rt > ほう</ rt > 角< rt > がく</ rt ></ ruby > を< ruby > 凝< rt > ぎょう</ rt > 視< rt > し</ rt ></ ruby > するFor more details on Jukugo Ruby rendering, see Appendix F in the Requirements for Japanese Text Layout. [JLREQ]
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.
< ruby > BASE< rt > annotation</ ruby > Here a compound ideographic word has its corresponding katakana given as an annotation.
< ruby > 境界面< rt > インターフェース</ ruby > 境界面
Here a compound ideographic word has its translation in English provided as an annotation.
< ruby lang = "ja" > 編集者< rt lang = "en" > editor</ ruby > 編集者
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.)
In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
< ruby > 紫陽花< rt > あじさい</ ruby > 紫陽花
Sometimes, ruby styles described above are combined.
If this results in two annotations covering the same single base segment, then the annotations can just be placed back to back.
< ruby > BASE< rt > annotation 1< rt > annotation 2</ ruby > < 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 > In this contrived example, some symbols are given names in English and French.
< 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 > In more complicated situations such as the following examples, a nested ruby
element is used to give the inner annotations, and then that whole ruby is then
given an annotation at the "outer" level.
< ruby >< ruby > B< rt > a</ rt > A< rt > n</ rt > S< rt > t</ rt > E< rt > n</ rt ></ ruby >< rt > annotation</ ruby > Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested ruby element gives a mono-ruby phonetic annotation for each base character, while the annotation in the rt element that is a child of the outer ruby element gives the meaning using hiragana.
< ruby >< ruby > 東< rt > とう</ rt > 南< rt > なん</ rt ></ ruby >< rt > たつみ</ rt ></ ruby > の方角東南の方角
This is the same example, but the meaning is given in English instead of Japanese:
< ruby >< ruby > 東< rt > とう</ rt > 南< rt > なん</ rt ></ ruby >< rt lang = en > Southeast</ rt ></ ruby > の方角東南の方角
Within a ruby element that does not have a ruby 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 inter-element whitespace and rp 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). Annotation segments correspond to rt 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 ruby element represents the union of the segments of base
text it contains, along with the mapping from those base text segments to annotation segments.
Segments are described in terms of DOM ranges; annotation segment ranges always
consist of exactly one element. [DOM]
At any particular time, the segmentation and categorization of content of a ruby
element is the result that would be obtained from running the following algorithm:
Let base text segments be an empty list of base text segments, each potentially with a list of base text subsegments.
Let annotation segments be an empty list of annotation segments, each potentially being associated with a base text segment or subsegment.
Let root be the ruby element for which the algorithm is
being run.
If root has a ruby element ancestor, then jump to the
step labeled end.
Let current parent be root.
Let index be 0.
Let start index be null.
Let saved start index be null.
Let current base text be null.
Start mode: If index is greater than or equal to the number of child nodes in current parent, then jump to the step labeled end mode.
If the indexth node in current parent is an
rt or rp element, jump to the step labeled annotation
mode.
Set start index to the value of index.
Base mode: If the indexth node in current
parent is a ruby element, and if current parent is the
same element as root, then push a ruby level and then jump to
the step labeled start mode.
If the indexth node in current parent is an
rt or rp element, then set the current base text and then
jump to the step labeled annotation mode.
Increment index by one.
Base mode post-increment: If index is greater than or equal to the number of child nodes in current parent, then jump to the step labeled end mode.
Jump back to the step labeled base mode.
Annotation mode: If the indexth node in current
parent is an rt element, then push a ruby annotation and jump to
the step labeled annotation mode increment.
If the indexth node in current parent is an
rp element, jump to the step labeled annotation mode increment.
If the indexth node in current parent is not a
Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode.
Annotation mode increment: Let lookahead index be index plus one.
Annotation mode white-space skipper: If lookahead index is equal to the number of child nodes in current parent then jump to the step labeled end mode.
If the lookahead indexth node in current parent is
an rt element or an rp element, then set index to
lookahead index and jump to the step labeled annotation mode.
If the lookahead indexth node in current parent is
not a Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode (without further incrementing
index, so the inter-element whitespace seen so far becomes part
of the next base text segment).
Increment lookahead index by one.
Jump to the step labeled annotation mode white-space skipper.
End mode: If current parent is not the same element as root, then pop a ruby level and jump to the step labeled base mode post-increment.
End: Return base text segments and annotation
segments. Any content of the ruby element not described by segments in either
of those lists is implicitly in an ignored segment.
When the steps above say to set the current base text, it means to run the following steps at that point in the algorithm:
Let text range be a DOM range whose start is the boundary point (current parent, start index) and whose end is the boundary point (current parent, index).
Let new text segment be a base text segment described by the range text range.
Add new text segment to base text segments.
Let current base text be new text segment.
Let start index be null.
When the steps above say to push a ruby level, it means to run the following steps at that point in the algorithm:
Let current parent be the indexth node in current parent.
Let index be 0.
Set saved start index to the value of start index.
Let start index be null.
When the steps above say to pop a ruby level, it means to run the following steps at that point in the algorithm:
Let index be the position of current parent in root.
Let current parent be root.
Increment index by one.
Set start index to the value of saved start index.
Let saved start index be null.
When the steps above say to push a ruby annotation, it means to run the following steps at that point in the algorithm:
Let rt be the rt element that is the indexth node of current parent.
Let annotation range be a DOM range whose start is the boundary point (current parent, index) and whose end is the boundary point (current parent, index plus one) (i.e. that contains only rt).
Let new annotation segment be an annotation segment described by the range annotation range.
If current base text is not null, associate new annotation segment with current base text.
Add new annotation segment to annotation segments.
In this example, each ideograph in the Japanese text 漢字 is annotated with its reading in hiragana.
...
< ruby > 漢< rt > かん</ rt > 字< rt > じ</ rt ></ ruby >
...This might be rendered as:
In this example, each ideograph in the traditional Chinese text 漢字 is annotated with its bopomofo reading.
< ruby > 漢< rt > ㄏㄢˋ</ rt > 字< rt > ㄗˋ</ rt ></ ruby > This might be rendered as:
In this example, each ideograph in the simplified Chinese text 汉字 is annotated with its pinyin reading.
...< ruby > 汉< rt > hàn</ rt > 字< rt > zì</ rt ></ ruby > ...This might be rendered as:
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".
< 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 > rt elementSupport in all current engines.
ruby element.rt element's end tag can be omitted if the
rt element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.HTMLElement.The rt element marks the ruby text component of a ruby annotation. When it is the
child of a ruby element, it doesn't represent
anything itself, but the ruby element uses it as part of determining what it
represents.
An rt element that is not a child of a ruby element
represents the same thing as its children.
rp elementSupport in all current engines.
ruby element, either immediately before or immediately after an rt element.rp element's end tag can be omitted if the
rp element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.HTMLElement.The rp 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.
An rp element that is a child of a ruby
element represents nothing. An rp element
whose parent element is not a ruby element represents its
children.
The example above, in which each ideograph in the text 漢字 is annotated with its phonetic reading, could be expanded to
use rp so that in legacy user agents the readings are in parentheses:
...
< ruby > 漢< rp > （</ rp >< rt > かん</ rt >< rp > ）</ rp > 字< rp > （</ rp >< rt > じ</ rt >< rp > ）</ rp ></ ruby >
...In conforming user agents the rendering would be as above, but in user agents that do not support ruby, the rendering would be:
... 漢（かん）字（じ）...
When there are multiple annotations for a segment, rp 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 rp elements as
well:
< 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 > This would make the example render as follows in non-ruby-capable user agents:
♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.
data elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
value — Machine-readable value
[Exposed =Window ]
interface HTMLDataElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute DOMString value ;
};The data element represents its contents, along with a
machine-readable form of those contents in the value
attribute.
The value attribute
must be present. Its value must be a representation of the element's contents in a
machine-readable format.
When the value is date- or time-related, the more specific time
element can be used instead.
The element can be used for several purposes.
When combined with microformats or the microdata attributes 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 value attribute is
determined by the microformats or microdata vocabulary in use.
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 data-*
attributes can also be useful in such situations.)
Here, a short table has its numeric values encoded using the data 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.
< 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 > time elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
datetime attribute: Phrasing content.datetime — Machine-readable value
[Exposed =Window ]
interface HTMLTimeElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute DOMString dateTime ;
};The time element represents its contents, along with a
machine-readable form of those contents in the datetime
attribute. The kind of content is limited to various kinds of dates, times, time-zone offsets, and
durations, as described below.
The datetime
attribute may be present. If present, its value must be a representation of the element's contents
in a machine-readable format.
A time element that does not have a datetime content attribute must not have any element
descendants.
The datetime value of a time element is the value of the element's
datetime content attribute, if it has one, otherwise the
child text content of the time element.
The datetime value of a time element must match one of the following
syntaxes.
< time > 2011-11</ time > < time > 2011-11-18</ time > < time > 11-18</ time > < time > 14:54</ time > < time > 14:54:39</ time > < time > 14:54:39.929</ time > < time > 2011-11-18T14:54</ time > < time > 2011-11-18T14:54:39</ time > < time > 2011-11-18T14:54:39.929</ time > < time > 2011-11-18 14:54</ time > < time > 2011-11-18 14:54:39</ time > < time > 2011-11-18 14:54:39.929</ time > 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 valid global date and time string is likely more useful.
< time > Z</ time > < time > +0000</ time > < time > +00:00</ time > < time > -0800</ time > < time > -08:00</ time > 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 time zone database. [TZDATABASE]
< time > 2011-11-18T14:54Z</ time > < time > 2011-11-18T14:54:39Z</ time > < time > 2011-11-18T14:54:39.929Z</ time > < time > 2011-11-18T14:54+0000</ time > < time > 2011-11-18T14:54:39+0000</ time > < time > 2011-11-18T14:54:39.929+0000</ time > < time > 2011-11-18T14:54+00:00</ time > < time > 2011-11-18T14:54:39+00:00</ time > < time > 2011-11-18T14:54:39.929+00:00</ time > < time > 2011-11-18T06:54-0800</ time > < time > 2011-11-18T06:54:39-0800</ time > < time > 2011-11-18T06:54:39.929-0800</ time > < time > 2011-11-18T06:54-08:00</ time > < time > 2011-11-18T06:54:39-08:00</ time > < time > 2011-11-18T06:54:39.929-08:00</ time > < time > 2011-11-18 14:54Z</ time > < time > 2011-11-18 14:54:39Z</ time > < time > 2011-11-18 14:54:39.929Z</ time > < time > 2011-11-18 14:54+0000</ time > < time > 2011-11-18 14:54:39+0000</ time > < time > 2011-11-18 14:54:39.929+0000</ time > < time > 2011-11-18 14:54+00:00</ time > < time > 2011-11-18 14:54:39+00:00</ time > < time > 2011-11-18 14:54:39.929+00:00</ time > < time > 2011-11-18 06:54-0800</ time > < time > 2011-11-18 06:54:39-0800</ time > < time > 2011-11-18 06:54:39.929-0800</ time > < time > 2011-11-18 06:54-08:00</ time > < time > 2011-11-18 06:54:39-08:00</ time > < time > 2011-11-18 06:54:39.929-08:00</ time > 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 valid local date and time string combined with that geographic location is likely more useful.
< time > 2011-W47</ time > < time > 2011</ time > < time > 0001</ time > < time > PT4H18M3S</ time > < time > 4h 18m 3s</ time > The machine-readable equivalent of the element's contents must be obtained from the element's datetime value by using the following algorithm:
If parsing a month string from the element's datetime value returns a month, that is the machine-readable equivalent; return.
If parsing a date string from the element's datetime value returns a date, that is the machine-readable equivalent; return.
If parsing a yearless date string from the element's datetime value returns a yearless date, that is the machine-readable equivalent; return.
If parsing a time string from the element's datetime value returns a time, that is the machine-readable equivalent; return.
If parsing a local date and time string from the element's datetime value returns a local date and time, that is the machine-readable equivalent; return.
If parsing a time-zone offset string from the element's datetime value returns a time-zone offset, that is the machine-readable equivalent; return.
If parsing a global date and time string from the element's datetime value returns a global date and time, that is the machine-readable equivalent; return.
If parsing a week string from the element's datetime value returns a week, that is the machine-readable equivalent; return.
If the element's datetime value consists of only ASCII digits, 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.
If parsing a duration string from the element's datetime value returns a duration, that is the machine-readable equivalent; return.
There is no machine-readable equivalent.
The algorithms referenced above are intended to be designed such that for any arbitrary string s, 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.
The time 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 time element:
< 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 > Here, a fictional microdata vocabulary based on the Atom vocabulary is used with the
time element to mark up a blog post's publication date.
< 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 > In this example, another article's publication date is marked up using time, this
time using the schema.org microdata vocabulary:
< 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 > In the following snippet, the time element is used to encode a date in the
ISO8601 format, for later processing by a script:
< p > Our first date was < time datetime = "2006-09-23" > a Saturday</ time > .</ p > In this second snippet, the value includes a time:
< p > We stopped talking at < time datetime = "2006-09-24T05:00-07:00" > 5am the next morning</ time > .</ p > A script loaded by the page (and thus privy to the page's internal convention of marking up
dates and times using the time element) could scan through the page and look at all
the time elements therein to create an index of dates and times.
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":
Today is < time datetime = "2011-11-18" > Friday</ time > .In this example, a specific time in the Pacific Standard Time timezone is specified:
Your next meeting is at < time datetime = "2011-11-18T15:00-08:00" > 3pm</ time > .code elementSupport in all current engines.
HTMLElement.The code element represents 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.
There is no formal way to indicate the language of computer code being marked up. Authors who
wish to mark code elements with the language used, e.g. so that syntax highlighting
scripts can use the right rules, can use the class attribute, e.g.
by adding a class prefixed with "language-" to the element.
The following example shows how the element can be used in a paragraph to mark up element names and computer code, including punctuation.
< 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 > The following example shows how a block of code could be marked up using the pre
and code elements.
< pre >< code class = "language-pascal" > var i: Integer;
begin
i := 1;
end.</ code ></ pre > A class is used in that example to indicate the language used.
See the pre element for more details.
var elementSupport in all current engines.
HTMLElement.The var element represents 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.
In the paragraph below, the letter "n" is being used as a variable in prose:
< 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 > For mathematics, in particular for anything beyond the simplest of expressions, MathML is more
appropriate. However, the var element can still be used to refer to specific
variables that are then mentioned in MathML expressions.
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 var.
< 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 > Here, the equation describing mass-energy equivalence is used in a sentence, and the
var element is used to mark the variables and constants in that equation:
< 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 > samp elementSupport in all current engines.
HTMLElement.The samp element represents sample or quoted output from another
program or computing system.
See the pre and kbd elements for more details.
This element can be contrasted with the output element, which can be
used to provide immediate output in a web application.
This example shows the samp element being used
inline:
< p > The computer said < samp > Too much cheese in tray
two</ samp > but I didn't know what that meant.</ p > This second example shows a block of sample output from a console program. Nested
samp and kbd elements allow for the styling of specific elements
of the sample output using a style sheet. There's also a few parts of the samp that
are annotated with even more detailed markup, to enable very precise styling. To achieve this,
span elements are used.
< 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 > This third example shows a block of input and its respective output. The example uses
both code and samp elements.
< pre >
< code class = "language-javascript" > console.log(2.3 + 2.4)</ code >
< samp > 4.699999999999999</ samp >
</ pre > kbd elementSupport in all current engines.
HTMLElement.The kbd element represents user input (typically keyboard input,
although it may also be used to represent other input, such as voice commands).
When the kbd element is nested inside a samp element, it represents
the input as it was echoed by the system.
When the kbd element contains a samp element, it represents
input based on system output, for example invoking a menu item.
When the kbd element is nested inside another kbd element, it
represents an actual key or other single unit of input as appropriate for the input mechanism.
Here the kbd element is used to indicate keys to press:
< p > To make George eat an apple, press < kbd >< kbd > Shift</ kbd > + < kbd > F3</ kbd ></ kbd ></ p > In this second example, the user is told to pick a particular menu item. The outer
kbd element marks up a block of input, with the inner kbd elements
representing each individual step of the input, and the samp elements inside them
indicating that the steps are input based on something being displayed by the system, in this
case menu labels:
< p > To make George eat an apple, select
< kbd >< kbd >< samp > File</ samp ></ kbd > |< kbd >< samp > Eat Apple...</ samp ></ kbd ></ kbd >
</ p > Such precision isn't necessary; the following is equally fine:
< p > To make George eat an apple, select < kbd > File | Eat Apple...</ kbd ></ p > sub and sup elementsSupport in all current engines.
Support in all current engines.
sub element: for authors; for implementers.sup element: for authors; for implementers.HTMLElement.The sup element represents a superscript and the sub
element represents a subscript.
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 sub and sup elements to be used in the name of the LaTeX
document preparation system. In general, authors should use these elements only if the
absence of those elements would change the meaning of the content.
In certain languages, superscripts are part of the typographical conventions for some abbreviations.
< 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 > The sub element can be used inside a var element, for variables that
have subscripts.
Here, the sub element is used to represent the subscript that identifies the
variable in a family of variables:
< 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 > Mathematical expressions often use subscripts and superscripts. Authors are encouraged to use
MathML for marking up mathematics, but authors may opt to use sub and
sup if detailed mathematical markup is not desired. [MATHML]
< var > E</ var > =< var > m</ var >< var > c</ var >< sup > 2</ sup > f(< var > x</ var > , < var > n</ var > ) = log< sub > 4</ sub >< var > x</ var >< sup >< var > n</ var ></ sup > i elementSupport in all current engines.
HTMLElement.The i element represents 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.
Terms in languages different from the main text should be annotated with lang attributes (or, in XML, lang attributes in the XML namespace).
The examples below show uses of the i element:
< 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 > In the following example, a dream sequence is marked up using
i elements.
< 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 > Authors can use the class attribute on the i
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.
Authors are encouraged to consider whether other elements might be more applicable than the
i element, for instance the em element for marking up stress emphasis,
or the dfn element to mark up the defining instance of a term.
Style sheets can be used to format i elements, just like any other
element can be restyled. Thus, it is not the case that content in i elements will
necessarily be italicized.
b elementSupport in all current engines.
HTMLElement.The b element represents 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.
The following example shows a use of the b element to highlight key words without
marking them up as important:
< p > The < b > frobonitor</ b > and < b > barbinator</ b > components are fried.</ p > In the following example, objects in a text adventure are highlighted as being special by use
of the b element.
< p > You enter a small room. Your < b > sword</ b > glows
brighter. A < b > rat</ b > scurries past the corner wall.</ p > Another case where the b element is appropriate is in marking up the lede (or
lead) sentence or paragraph. The following example shows how a BBC article about
kittens adopting a rabbit as their own could be marked up:
< 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 >
[...]As with the i element, authors can use the class
attribute on the b 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.
The b element should be used as a last resort when no other element is more
appropriate. In particular, headings should use the h1 to h6 elements,
stress emphasis should use the em element, importance should be denoted with the
strong element, and text marked or highlighted should use the mark
element.
The following would be incorrect usage:
< p >< b > WARNING!</ b > Do not frob the barbinator!</ p > In the previous example, the correct element to use would have been strong, not
b.
Style sheets can be used to format b elements, just like any other
element can be restyled. Thus, it is not the case that content in b elements will
necessarily be boldened.
u elementSupport in all current engines.
HTMLElement.The u element represents 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.
In most cases, another element is likely to be more appropriate: for marking stress emphasis,
the em element should be used; for marking key words or phrases either the
b element or the mark element should be used, depending on the context;
for marking book titles, the cite element should be used; for labeling text with explicit textual annotations, the
ruby element should be used; for technical terms, taxonomic designation,
transliteration, a thought, or for labeling ship names in Western texts, the i
element should be used.
The default rendering of the u element in visual presentations
clashes with the conventional rendering of hyperlinks (underlining). Authors are encouraged to
avoid using the u element where it could be confused for a hyperlink.
In this example, a u element is used to mark a word as misspelt:
< p > The < u > see</ u > is full of fish.</ p > mark elementSupport in all current engines.
HTMLElement.The mark element represents a run of text in one document marked or
highlighted for reference 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.
This example shows how the mark element can be used to bring attention to a
particular part of a quotation:
< p lang = "en-US" > Consider the following quote:</ p >
< blockquote lang = "en-GB" >
< p > Look around and you will find, no-one's really
< mark > colour</ mark > blind.</ p >
</ blockquote >
< 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 > (If the goal was to mark the element as misspelt, however, the u element,
possibly with a class, would be more appropriate.)
Another example of the mark 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 > 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 > In the following snippet, a paragraph of text refers to a specific part of a code fragment.
< 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 > This is separate from syntax highlighting, for which span is more
appropriate. Combining both, one would get:
< 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 > This is another example showing the use of mark 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 mark elements in quotes to render in italics.
< 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 > Note, incidentally, the distinction between the em element in this example, which
is part of the original text being quoted, and the mark element, which is
highlighting a part for comment.
The following example shows the difference between denoting the importance of a span
of text (strong) as opposed to denoting the relevance of a span of text
(mark). 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.
< 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 > bdi elementSupport in all current engines.
dir global attribute has special semantics on this element.HTMLElement.The bdi element represents a span of text that is to be isolated from
its surroundings for the purposes of bidirectional text formatting. [BIDI]
The dir global attribute defaults to auto on this element (it never inherits from the parent element like
with other elements).
This element has rendering requirements involving the bidirectional algorithm.
This element is especially useful when embedding user-generated content with an unknown directionality.
In this example, usernames are shown along with the number of posts that the user has
submitted. If the bdi 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").
< ul >
< li > User < bdi > jcranmer</ bdi > : 12 posts.
< li > User < bdi > hober</ bdi > : 5 posts.
< li > User < bdi > إيان</ bdi > : 3 posts.
</ ul > bdi element, the username acts as expected.bdi element were to be replaced by a b 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.bdo elementSupport in all current engines.
dir global attribute has special semantics on this element.HTMLElement.The bdo element represents explicit text directionality formatting
control for its children. It allows authors to override the Unicode bidirectional algorithm by
explicitly specifying a direction override. [BIDI]
Authors must specify the dir attribute on this element, with the
value ltr to specify a left-to-right override and with the value rtl to
specify a right-to-left override. The auto value must not be specified.
This element has rendering requirements involving the bidirectional algorithm.
span elementSupport in all current engines.
Support in all current engines.
option element: Zero or more
option element inner content elements, except div
elements.[Exposed =Window ]
interface HTMLSpanElement : HTMLElement {
[HTMLConstructor ] constructor ();
};The span element doesn't mean anything on its own, but can be useful when used
together with the global attributes, e.g. class,
lang, or dir. It
represents its children.
In this example, a code fragment is marked up using span elements and class attributes so that its keywords and identifiers can be
color-coded from CSS:
< pre >< code class = "lang-c" >< span class = "keyword" > for</ span > (< span class = "ident" > j</ span > = 0; < span class = "ident" > j</ span > < 256; < span class = "ident" > j</ span > ++) {
< span class = "ident" > i_t3</ span > = (< span class = "ident" > i_t3</ span > & 0x1ffff) | (< span class = "ident" > j</ span > << 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 > br elementSupport in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLBRElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};The br element represents a line break.
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.
br elements must be used only for line breaks that are actually part of the
content, as in poems or addresses.
The following example is correct usage of the br element:
< p > P. Sherman< br >
42 Wallaby Way< br >
Sydney</ p > br elements must not be used for separating thematic groups in a paragraph.
The following examples are non-conforming, as they abuse the br element:
< p >< a ...> 34 comments.</ a >< br >
< a ...> Add a comment.</ a ></ p > < p >< label > Name: < input name = "name" ></ label >< br >
< label > Address: < input name = "address" ></ label ></ p > Here are alternatives to the above, which are correct:
< p >< a ...> 34 comments.</ a ></ p >
< p >< a ...> Add a comment.</ a ></ p > < p >< label > Name: < input name = "name" ></ label ></ p >
< p >< label > Address: < input name = "address" ></ label ></ p > If a paragraph consists of nothing but a single br element, it
represents a placeholder blank line (e.g. as in a template). Such blank lines must not be used for
presentation purposes.
Any content inside br elements must not be considered part of the surrounding
text.
This element has rendering requirements involving the bidirectional algorithm.
wbr elementSupport in all current engines.
HTMLElement.The wbr element represents a line break opportunity.
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 wbr element.
< 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 > Any content inside wbr elements must not be considered part of the surrounding
text.
var wbr = document. createElement( "wbr" );
wbr. textContent = "This is wrong" ;
document. body. appendChild( wbr); This element has rendering requirements involving the bidirectional algorithm.
This section is non-normative.
| Element | Purpose | Example |
|---|---|---|
a
| Hyperlinks | |
em
| Stress emphasis | |
strong
| Importance | |
small
| Side comments | |
s
| Inaccurate text | |
cite
| Titles of works | |
q
| Quotations | |
dfn
| Defining instance | |
abbr
| Abbreviations | |
ruby, rt, rp
| Ruby annotations | |
data
| Machine-readable equivalent | |
time
| Machine-readable equivalent of date- or time-related data | |
code
| Computer code | |
var
| Variables | |
samp
| Computer output | |
kbd
| User input | |
sub
| Subscripts | |
sup
| Superscripts | |
i
| Alternative voice | |
b
| Keywords | |
u
| Annotations | |
mark
| Highlight | |
bdi
| Text directionality isolation | |
bdo
| Text directionality formatting | |
span
| Other | |
br
| Line break | |
wbr
| Line breaking opportunity | |
Links are a conceptual construct, created by a, area,
form, and link elements, that represent
a connection between two resources, one of which is the current Document. There are
three kinds of links in HTML:
These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent. All external resource links have a fetch and process the linked resource algorithm which describes how the resource is obtained.
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 navigate to those resources, e.g. to visit them in a browser or download them.
These are links to resources within the current document, used to give those resources special meaning or behavior.
For link elements with an href attribute and a
rel attribute, links must be created for the keywords of the
rel attribute, as defined for those keywords in the link types section.
Similarly, for a and area elements with an href attribute and a rel attribute, links must be created for the keywords of the
rel attribute as defined for those keywords in the link types section. Unlike link elements, however,
a and area elements with an href
attribute that either do not have a rel attribute, or
whose rel attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
This implied hyperlink has no special meaning (it has no link type)
beyond linking the element's node document to the resource given by the element's href attribute.
Similarly, for form elements with a rel
attribute, links must be created for the keywords of the rel
attribute as defined for those keywords in the link types section.
form elements that do not have a rel attribute,
or whose rel attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.
a and area elementsThe href
attribute on a and area elements must have a value that is a valid
URL potentially surrounded by spaces.
The href attribute on a and
area elements is not required; when those elements do not have href attributes they do not create hyperlinks.
The target
attribute, if present, must be a valid navigable target name or keyword. It gives the
name of the navigable that will be used. User agents use this
name when following hyperlinks.
The download
attribute, if present, indicates that the author intends the hyperlink to be used for downloading a resource. 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.
Support in all current engines.
The ping 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 set of space-separated tokens, each of which must be a valid non-empty
URL whose scheme is an HTTP(S)
scheme. The value is used by the user agent for hyperlink
auditing.
The rel attribute on a and area
elements controls what kinds of links the elements create. The attribute's value must be an
unordered set of unique space-separated tokens. The allowed
keywords and their meanings are defined below.
rel's supported tokens are the keywords defined in HTML link types which are allowed on a and area
elements, impact the processing model, and are supported by the user agent. The possible supported tokens are noreferrer, noopener, and opener. rel's supported tokens must only include the tokens from this
list that the user agent implements the processing model for.
The rel 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.
The hreflang
attribute on a elements that create hyperlinks, if
present, gives the language of the linked resource. It is purely advisory. The value must be a
valid BCP 47 language tag. [BCP47] 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.
The type
attribute, if present, gives the MIME type of the linked resource. It is purely
advisory. The value must be a valid MIME type string. User agents must
not consider the type attribute authoritative —
upon fetching the resource, user agents must not use metadata included in the link to the resource
to determine its type.
The referrerpolicy attribute is a referrer
policy attribute. Its purpose is to set the referrer policy used when
following hyperlinks. [REFERRERPOLICY]
When an a or area element's activation behavior is
invoked, the user agent may allow the user to indicate a preference regarding whether the
hyperlink is to be used for navigation or whether the resource it
specifies is to be downloaded.
In the absence of a user preference, the default should be navigation if the element has no
download attribute, and should be to download the
specified resource if it does.
The activation behavior of an a or area element
element given an event event is:
If element has no href attribute,
then return.
Let hyperlinkSuffix be null.
If element is an a element, and event's target is an img with an ismap attribute specified, then:
Let x and y be 0.
If event's isTrusted attribute is
initialized to true, then set x to the distance in CSS
pixels from the left edge of the image to the location of the click, and set
y to the distance in CSS pixels from the top edge of the
image to the location of the click.
If x is negative, set x to 0.
If y is negative, set y to 0.
Set hyperlinkSuffix to the concatenation of U+003F (?), the value of x expressed as a base-ten integer using ASCII digits, U+002C (,), and the value of y expressed as a base-ten integer using ASCII digits.
Let userInvolvement be event's user navigation involvement.
If the user has expressed a preference to download the hyperlink, then set
userInvolvement to "browser UI".
That is, if the user has expressed a specific preference for downloading, this
no longer counts as merely "activation".
If element has a download
attribute, or if the user has expressed a preference to download the hyperlink, then download the hyperlink created by element with
hyperlinkSuffix set to hyperlinkSuffix and
userInvolvement set to
userInvolvement.
Otherwise, follow the hyperlink created by element with hyperlinkSuffix set to hyperlinkSuffix and userInvolvement set to userInvolvement.
a and area elementsinterface mixin HTMLHyperlinkElementUtils {
[CEReactions , ReflectSetter ] stringifier attribute USVString href ;
readonly attribute USVString origin ;
[CEReactions ] attribute USVString protocol ;
[CEReactions ] attribute USVString username ;
[CEReactions ] attribute USVString password ;
[CEReactions ] attribute USVString host ;
[CEReactions ] attribute USVString hostname ;
[CEReactions ] attribute USVString port ;
[CEReactions ] attribute USVString pathname ;
[CEReactions ] attribute USVString search ;
[CEReactions ] attribute USVString hash ;
};hyperlink.toString()hyperlink.hrefSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL.
Can be set, to change the URL.
hyperlink.originSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's origin.
hyperlink.protocolSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's scheme.
Can be set, to change the URL's scheme.
hyperlink.usernameSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's username.
Can be set, to change the URL's username.
hyperlink.passwordSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's password.
Can be set, to change the URL's password.
hyperlink.hostSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's host and port (if different from the default port for the scheme).
Can be set, to change the URL's host and port.
hyperlink.hostnameSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's host.
Can be set, to change the URL's host.
hyperlink.portSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's port.
Can be set, to change the URL's port.
hyperlink.pathnameSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's path.
Can be set, to change the URL's path.
hyperlink.searchSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's query (includes leading "?" if
non-empty).
Can be set, to change the URL's query (ignores leading "?").
hyperlink.hashSupport in all current engines.
Support in all current engines.
Returns the hyperlink's URL's fragment (includes leading "#" if
non-empty).
Can be set, to change the URL's fragment (ignores leading "#").
An element implementing the HTMLHyperlinkElementUtils mixin has an associated url (null or a URL). It is initially null.
An element implementing the HTMLHyperlinkElementUtils mixin has the following
extract an origin steps:
An element implementing the HTMLHyperlinkElementUtils mixin has an associated set the url algorithm, which runs these steps:
Set this element's url to null.
If this element's href content attribute is
absent, then return.
Let url be the result of encoding-parsing a URL given this
element's href content attribute's value, relative to
this element's node document.
If url is not failure, then set this element's url to url.
When elements implementing the HTMLHyperlinkElementUtils mixin are created, the
user agent must set the url.
The HTML element insertion steps for a and area
elements, given insertedNode, are:
If insertedNode is not connected, then return.
Consider speculative loads given insertedNode's node document.
The HTML element removing steps for a and area elements,
given removedNode and oldParent, are:
If oldParent is not connected, then return.
Consider speculative loads given oldParent's node document.
The HTML element moving steps for a and area elements,
given movedNode, are:
Consider speculative loads given movedNode's node document.
The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used for all a and area
elements:
If namespace is not null, then return.
If oldValue equals value, then return.
If localName is href, then set the url given element.
This is only observable for blob: URLs as
parsing them involves a Blob URL Store lookup.
If localName is href, referrerpolicy, or rel, then consider speculative loads given
element's node document.
An element implementing the HTMLHyperlinkElementUtils mixin has an associated
reinitialize url algorithm, which runs these
steps:
If the element's url is non-null, its scheme is "blob", and it has an
opaque path, then terminate these steps.
To update href, set the element's href content attribute's value to the element's url, serialized.
The href getter steps are:
If url is null and this has no href content attribute, return the empty string.
Otherwise, if url is null, return this's href content attribute's value.
Return url, serialized.
The origin getter steps are:
Return the serialization of this's url's origin.
The protocol getter steps are:
The protocol setter steps are:
Basic URL parse the given value, followed by ":", with this's url as
url and scheme start state as
state override.
Because the URL parser ignores multiple consecutive colons, providing a value
of "https:" (or even "https::::") is the same as
providing a value of "https".
The username getter steps are:
The username setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the username, given url and the given value.
The password getter steps are:
If url is null, then return the empty string.
Return url's password.
The password setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the password, given url and the given value.
The host getter steps are:
If url or url's host is null, return the empty string.
If url's port is null, return url's host, serialized.
Return url's host, serialized, followed by ":" and url's port, serialized.
The host setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and host state as state override.
The hostname getter steps are:
If url or url's host is null, return the empty string.
Return url's host, serialized.
The hostname setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and hostname state as state override.
The port getter steps are:
If url or url's port is null, return the empty string.
Return url's port, serialized.
The port setter steps are:
If url is null or url cannot have a username/password/port, then return.
If the given value is the empty string, then set url's port to null.
Otherwise, basic URL parse the given value, with url as url and port state as state override.
The pathname getter steps are:
If url is null, then return the empty string.
Return the result of URL path serializing url.
The pathname setter steps are:
If url is null or url has an opaque path, then return.
Set url's path to the empty list.
Basic URL parse the given value, with url as url and path start state as state override.
The search getter steps are: